Add a stub debug subcommand to uv pip announcing its intentional absence (#16966)

## Summary

Inform users who encounter #16879 that `uv pip debug` is currently
intentionally not implemented.

## Test Plan

Added an integration test for the warning, ran the test suite.

Author: EliteTK

crates/uv-cli/src/lib.rs

@@ -1009,6 +1009,9 @@ pub enum PipCommand {
         after_long_help = ""
     )]
     Check(PipCheckArgs),
+    /// Display debug information (unsupported)
+    #[command(hide = true)]
+    Debug(PipDebugArgs),
 }
 
 #[derive(Subcommand)]
@@ -2756,6 +2759,21 @@ pub struct PipTreeArgs {
     pub compat_args: compat::PipGlobalCompatArgs,
 }
 
+#[derive(Args)]
+pub struct PipDebugArgs {
+    #[arg(long, hide = true)]
+    pub platform: Option<String>,
+
+    #[arg(long, hide = true)]
+    pub python_version: Option<String>,
+
+    #[arg(long, hide = true)]
+    pub implementation: Option<String>,
+
+    #[arg(long, hide = true)]
+    pub abi: Option<String>,
+}
+
 #[derive(Args)]
 pub struct BuildArgs {
     /// The directory from which distributions should be built, or a source

crates/uv/src/lib.rs

@@ -12,7 +12,7 @@ use std::str::FromStr;
 use std::sync::atomic::Ordering;
 
 use anstream::eprintln;
-use anyhow::{Result, bail};
+use anyhow::{Result, anyhow, bail};
 use clap::error::{ContextKind, ContextValue};
 use clap::{CommandFactory, Parser};
 use futures::FutureExt;
@@ -1060,6 +1060,11 @@ async fn run(mut cli: Cli) -> Result<ExitStatus> {
                 globals.preview,
             )
         }
+        Commands::Pip(PipNamespace {
+            command: PipCommand::Debug(_),
+        }) => Err(anyhow!(
+            "pip's `debug` is unsupported (consider using `uvx pip debug` instead)"
+        )),
         Commands::Cache(CacheNamespace {
             command: CacheCommand::Clean(args),
         })

crates/uv/tests/it/common/mod.rs

@@ -1104,6 +1104,14 @@ impl TestContext {
         command
     }
 
+    /// Create a `pip debug` command for testing.
+    pub fn pip_debug(&self) -> Command {
+        let mut command = Self::new_command();
+        command.arg("pip").arg("debug");
+        self.add_shared_options(&mut command, true);
+        command
+    }
+
     /// Create a `uv help` command with options shared across scenarios.
     #[allow(clippy::unused_self)]
     pub fn help(&self) -> Command {

crates/uv/tests/it/main.rs

@@ -72,6 +72,7 @@ mod pip_show;
 #[cfg(all(feature = "python", feature = "pypi"))]
 mod pip_sync;
 
+mod pip_debug;
 mod pip_tree;
 mod pip_uninstall;
 

crates/uv/tests/it/pip_debug.rs

@@ -0,0 +1,16 @@
+use crate::common::{TestContext, uv_snapshot};
+
+#[test]
+fn debug_warn() {
+    let context = TestContext::new("3.12");
+
+    uv_snapshot!(context.pip_debug(), @r"
+    success: false
+    exit_code: 2
+    ----- stdout -----
+
+    ----- stderr -----
+    error: pip's `debug` is unsupported (consider using `uvx pip debug` instead)
+    "
+    );
+}