auth: Enable Tokio I/O for login runtime

Author: davidabram

cli/src/app.rs

@@ -105,6 +105,7 @@ impl std::error::Error for ClassifiedError {}
 #[derive(Clone, Debug, Eq, PartialEq)]
 enum Command {
     Help,
+    HelpText { name: String, text: String },
     Auth(services::auth_command::AuthRequest),
     Completion(services::completion::CompletionRequest),
     Config(services::config::ConfigSubcommand),
@@ -117,9 +118,10 @@ enum Command {
 }
 
 impl Command {
-    fn name(&self) -> &'static str {
+    fn name(&self) -> &str {
         match self {
             Self::Help => "help",
+            Self::HelpText { name, .. } => name.as_str(),
             Self::Auth(_) => services::auth_command::NAME,
             Self::Completion(_) => services::completion::NAME,
             Self::Config(_) => services::config::NAME,
@@ -294,11 +296,22 @@ where
         Err(error) => {
             // Handle --help specially - user explicitly requested help
             if error.kind() == clap::error::ErrorKind::DisplayHelp {
+                if let Some((name, text)) = render_subcommand_help_from_args(&args_vec) {
+                    return Ok(Command::HelpText { name, text });
+                }
+
                 // Return Help command for successful output
                 return Ok(Command::Help);
             }
             // Handle missing subcommand as validation error, not help display
             if error.kind() == clap::error::ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand {
+                if args_vec.get(1).map(String::as_str) == Some(services::auth_command::NAME) {
+                    return Ok(Command::HelpText {
+                        name: services::auth_command::NAME.to_string(),
+                        text: cli_schema::auth_help_text(),
+                    });
+                }
+
                 // This means a required subcommand was not provided
                 return Err(ClassifiedError::parse(
                     "Missing required subcommand. Try: run 'sce --help' to see valid commands.",
@@ -350,6 +363,25 @@ fn classify_clap_error(error: &clap::Error) -> ClassifiedError {
     }
 }
 
+fn render_subcommand_help_from_args(args: &[String]) -> Option<(String, String)> {
+    let command_name = args.get(1)?.clone();
+    let command_path = args[1..]
+        .iter()
+        .take_while(|arg| !arg.starts_with('-'))
+        .map(String::as_str)
+        .collect::<Vec<_>>();
+
+    if command_path.is_empty() {
+        return None;
+    }
+
+    if command_path.as_slice() == [services::auth_command::NAME] {
+        return Some((command_name, cli_schema::auth_help_text()));
+    }
+
+    cli_schema::render_help_for_path(&command_path).map(|text| (command_name, text))
+}
+
 /// Clean up clap error messages to match our error message style.
 fn clean_clap_error_message(message: &str, kind: clap::error::ErrorKind) -> String {
     use clap::error::ErrorKind;
@@ -603,6 +635,7 @@ fn convert_hooks_subcommand(
 fn dispatch(command: &Command) -> Result<String, ClassifiedError> {
     match command {
         Command::Help => Ok(command_surface::help_text()),
+        Command::HelpText { text, .. } => Ok(text.clone()),
         Command::Auth(request) => services::auth_command::run_auth_subcommand(*request)
             .map_err(|error| ClassifiedError::runtime(error.to_string())),
         Command::Completion(request) => Ok(services::completion::render_completion(*request)),
@@ -700,6 +733,68 @@ mod tests {
         assert!(stdout.contains("Usage:"));
     }
 
+    #[test]
+    fn bare_auth_writes_auth_help_to_stdout() {
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        let code = run_with_dependency_check_and_streams(
+            vec!["sce".to_string(), "auth".to_string()],
+            || Ok(()),
+            &mut stdout,
+            &mut stderr,
+        );
+        assert_eq!(code, ExitCode::SUCCESS);
+        assert!(stderr.is_empty());
+
+        let stdout = String::from_utf8(stdout).expect("stdout should be utf-8");
+        assert!(stdout.contains("Usage: auth <COMMAND>"));
+        assert!(stdout.contains("login"));
+        assert!(stdout.contains("status"));
+        assert!(stdout.contains("sce auth status"));
+    }
+
+    #[test]
+    fn auth_help_writes_auth_specific_help_to_stdout() {
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        let code = run_with_dependency_check_and_streams(
+            vec!["sce".to_string(), "auth".to_string(), "--help".to_string()],
+            || Ok(()),
+            &mut stdout,
+            &mut stderr,
+        );
+        assert_eq!(code, ExitCode::SUCCESS);
+        assert!(stderr.is_empty());
+
+        let stdout = String::from_utf8(stdout).expect("stdout should be utf-8");
+        assert!(stdout.contains("Authenticate with `WorkOS` device authorization flow"));
+        assert!(stdout.contains("Usage: auth <COMMAND>"));
+        assert!(stdout.contains("sce auth login"));
+    }
+
+    #[test]
+    fn auth_login_help_writes_nested_auth_help_to_stdout() {
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        let code = run_with_dependency_check_and_streams(
+            vec![
+                "sce".to_string(),
+                "auth".to_string(),
+                "login".to_string(),
+                "--help".to_string(),
+            ],
+            || Ok(()),
+            &mut stdout,
+            &mut stderr,
+        );
+        assert_eq!(code, ExitCode::SUCCESS);
+        assert!(stderr.is_empty());
+
+        let stdout = String::from_utf8(stdout).expect("stdout should be utf-8");
+        assert!(stdout.contains("Start login flow and store credentials"));
+        assert!(stdout.contains("--format <FORMAT>"));
+    }
+
     #[test]
     fn parse_failure_keeps_stdout_empty_and_reports_stderr() {
         let mut stdout = Vec::new();
@@ -1121,6 +1216,20 @@ mod tests {
         );
     }
 
+    #[test]
+    fn parser_routes_bare_auth_to_auth_help_text() {
+        let command = parse_command(vec!["sce".to_string(), "auth".to_string()])
+            .expect("bare auth should parse to help text");
+
+        match command {
+            Command::HelpText { name, text } => {
+                assert_eq!(name, crate::services::auth_command::NAME);
+                assert!(text.contains("Usage: auth <COMMAND>"));
+            }
+            other => panic!("expected auth help text, got {other:?}"),
+        }
+    }
+
     #[test]
     fn parser_routes_sync_json_format() {
         let command = parse_command(vec![

cli/src/cli_schema.rs

@@ -2,7 +2,7 @@
 //!
 //! This module defines the complete command-line interface using clap derive macros.
 
-use clap::{Parser, Subcommand, ValueEnum};
+use clap::{CommandFactory, Parser, Subcommand, ValueEnum};
 use std::path::PathBuf;
 
 /// Shared Context Engineering CLI
@@ -35,6 +35,27 @@ impl Cli {
     }
 }
 
+pub fn render_help_for_path(path: &[&str]) -> Option<String> {
+    let mut command = Cli::command();
+
+    for segment in path {
+        command = command.find_subcommand_mut(segment)?.clone();
+    }
+
+    let mut buffer = Vec::new();
+    command
+        .write_long_help(&mut buffer)
+        .expect("help rendering should write to memory");
+
+    Some(String::from_utf8(buffer).expect("help output should be valid UTF-8"))
+}
+
+pub fn auth_help_text() -> String {
+    let base = render_help_for_path(&["auth"]).expect("auth help should be renderable");
+
+    format!("{base}\nExamples:\n  sce auth login\n  sce auth status\n  sce auth logout\n")
+}
+
 #[derive(Subcommand, Debug, Clone, PartialEq, Eq)]
 pub enum Commands {
     /// Authenticate with `WorkOS` device authorization flow
@@ -343,6 +364,25 @@ mod tests {
         }
     }
 
+    #[test]
+    fn auth_help_text_lists_supported_subcommands() {
+        let help = auth_help_text();
+
+        assert!(help.contains("Usage: auth <COMMAND>"));
+        assert!(help.contains("login"));
+        assert!(help.contains("logout"));
+        assert!(help.contains("status"));
+        assert!(help.contains("sce auth status"));
+    }
+
+    #[test]
+    fn render_help_for_auth_login_path_is_specific_to_login() {
+        let help = render_help_for_path(&["auth", "login"]).expect("auth login help should render");
+
+        assert!(help.contains("Start login flow and store credentials"));
+        assert!(help.contains("--format <FORMAT>"));
+    }
+
     #[test]
     fn parse_version_command() {
         let cli = Cli::try_parse_from(["sce", "version"]).expect("version should parse");

cli/src/services/auth_command.rs

@@ -115,6 +115,7 @@ fn shared_runtime() -> Result<&'static tokio::runtime::Runtime> {
     }
 
     let runtime = tokio::runtime::Builder::new_current_thread()
+        .enable_io()
         .enable_time()
         .build()
         .context("failed to create auth command runtime. Try: rerun the command; if the issue persists, verify the local Tokio runtime environment.")?;
@@ -296,6 +297,7 @@ mod tests {
     use anyhow::{anyhow, Result};
     use serde_json::Value;
     use std::path::{Path, PathBuf};
+    use tokio::net::TcpListener;
 
     use super::{
         build_authenticated_status_report, render_login_result, render_logout_result,
@@ -597,6 +599,17 @@ mod tests {
         assert_eq!(preserved, "runtime failed. Try: rerun the command.");
     }
 
+    #[test]
+    fn shared_runtime_enables_tokio_io_for_auth_login_flow() -> Result<()> {
+        let runtime = super::shared_runtime()?;
+        let listener = runtime.block_on(async { TcpListener::bind("127.0.0.1:0").await })?;
+
+        let local_addr = listener.local_addr()?;
+        assert!(local_addr.port() > 0);
+
+        Ok(())
+    }
+
     #[test]
     fn dispatcher_preserves_actionable_errors() {
         let error = run_auth_subcommand_with(