feat(cortex-cli): implement 10 open PR features

This commit implements the following features from open PRs:

- PR #98: Improve stats command message for new users with tracking info
- PR #99: Implement --share flag to display share URL using cortex-share
- PR #100: Warn when showing hidden agent details in 'agent show'
- PR #101: Standardize session ID error message format to 'Invalid session ID format:'
- PR #102: Add --port and --host options to debug wait command for TCP port checks
- PR #103: Validate empty prompt before authentication in exec mode
- PR #104: Add --names-only flag for dynamic shell completion of agent names
- PR #105: Document sandbox modes in help text with examples
- PR #106: Improve PR checkout confirmation to show source branch info
- PR #107: Correct help message to use lowercase 'cortex' command

Changes include:
- stats_cmd.rs: Added informative output explaining what stats will track
- run_cmd.rs: Added cortex-share integration for session sharing
- agent_cmd.rs: Added hidden agent warning and --names-only flag
- debug_cmd.rs: Added TCP port wait functionality with --port/--host
- export_cmd.rs: Standardized session ID error message
- main.rs: Added empty prompt validation, sandbox docs, dynamic completion
- pr_cmd.rs: Enhanced checkout message with source branch info
- login.rs: Fixed command name in help text
- Cargo.toml: Added cortex-share dependency

Author: factorydroid

Cargo.lock

@@ -34,6 +34,7 @@ cortex-process-hardening = { workspace = true }
 cortex-app-server = { workspace = true }
 cortex-update = { workspace = true }
 cortex-mcp-server = { workspace = true }
+cortex-share = { path = "../cortex-share" }
 
 clap = { workspace = true }
 clap_complete = { workspace = true }

cortex-cli/Cargo.toml

@@ -53,6 +53,10 @@ pub struct ListArgs {
     /// Show all agents including hidden ones.
     #[arg(long)]
     pub all: bool,
+
+    /// Output only agent names (one per line) for shell completion.
+    #[arg(long, hide = true)]
+    pub names_only: bool,
 }
 
 /// Arguments for show command.
@@ -700,6 +704,14 @@ async fn run_list(args: ListArgs) -> Result<()> {
         })
         .collect();
 
+    // Output names only for shell completion
+    if args.names_only {
+        for agent in &filtered {
+            println!("{}", agent.name);
+        }
+        return Ok(());
+    }
+
     if args.json {
         let json = serde_json::to_string_pretty(&filtered)?;
         println!("{json}");
@@ -791,6 +803,15 @@ async fn run_show(args: ShowArgs) -> Result<()> {
         .find(|a| a.name == args.name)
         .ok_or_else(|| anyhow::anyhow!("Agent '{}' not found", args.name))?;
 
+    // Warn if the agent is hidden
+    if agent.hidden {
+        eprintln!(
+            "Note: '{}' is a hidden agent (not shown in default listings).",
+            agent.name
+        );
+        eprintln!();
+    }
+
     if args.json {
         let json = serde_json::to_string_pretty(&agent)?;
         println!("{json}");

cortex-cli/src/agent_cmd.rs

@@ -1613,6 +1613,14 @@ pub struct WaitArgs {
     #[arg(long, default_value = "http://127.0.0.1:3000")]
     pub server_url: String,
 
+    /// Wait for a TCP port to be available.
+    #[arg(long)]
+    pub port: Option<u16>,
+
+    /// Host to check when using --port (default: 127.0.0.1).
+    #[arg(long, default_value = "127.0.0.1")]
+    pub host: String,
+
     /// Timeout in seconds.
     #[arg(long, default_value = "30")]
     pub timeout: u64,
@@ -1698,9 +1706,38 @@ async fn run_wait(args: WaitArgs) -> Result<()> {
             error = Some(format!("Timeout waiting for server at {}", args.server_url));
         }
 
+        (condition, success, error)
+    } else if let Some(port) = args.port {
+        // Wait for TCP port to be available
+        let condition = format!("port_ready ({}:{})", args.host, port);
+        let mut success = false;
+        let mut error = None;
+
+        let addr = format!("{}:{}", args.host, port);
+
+        while start.elapsed() < timeout {
+            match tokio::net::TcpStream::connect(&addr).await {
+                Ok(_) => {
+                    // Port is open and accepting connections
+                    success = true;
+                    break;
+                }
+                Err(_) => {
+                    tokio::time::sleep(interval).await;
+                }
+            }
+        }
+
+        if !success {
+            error = Some(format!(
+                "Timeout waiting for port {} on {}",
+                port, args.host
+            ));
+        }
+
         (condition, success, error)
     } else {
-        bail!("No condition specified. Use --lsp-ready or --server-ready");
+        bail!("No condition specified. Use --lsp-ready, --server-ready, or --port");
     };
 
     let waited_ms = start.elapsed().as_millis() as u64;

cortex-cli/src/debug_cmd.rs

@@ -149,7 +149,7 @@ impl ExportCommand {
         // Parse conversation ID
         let conversation_id: ConversationId = session_id.parse().map_err(|_| {
             anyhow::anyhow!(
-                "Invalid session ID: {session_id}. Expected full UUID or 8-character prefix."
+                "Invalid session ID format: {session_id}. Expected full UUID or 8-character prefix."
             )
         })?;
 

cortex-cli/src/export_cmd.rs

@@ -201,7 +201,7 @@ pub fn read_api_key_from_stdin() -> String {
     if stdin.is_terminal() {
         eprintln!(
             "--with-api-key expects the API key on stdin. Try piping it, e.g. \
-            `printenv OPENAI_API_KEY | fabric login --with-api-key`."
+            `printenv OPENAI_API_KEY | cortex login --with-api-key`."
         );
         std::process::exit(1);
     }

cortex-cli/src/login.rs

@@ -453,6 +453,17 @@ struct ConfigCommand {
 }
 
 /// Sandbox debug commands.
+///
+/// Run shell commands in a sandboxed environment with restricted permissions.
+///
+/// Available sandbox modes (via CORTEX_SANDBOX_MODE or --sandbox flag):
+///   read-only         - Read-only filesystem access, no write permissions anywhere
+///   workspace-write   - Read access everywhere + write access limited to workspace directory
+///   danger-full-access - Full filesystem access with no restrictions (use with caution)
+///
+/// Examples:
+///   cortex sandbox linux -- ls -la /tmp
+///   cortex sandbox macos -- cat /etc/passwd
 #[derive(Args)]
 struct SandboxArgs {
     #[command(subcommand)]
@@ -733,6 +744,11 @@ async fn run_exec(exec_cli: ExecCommand) -> Result<()> {
     use cortex_protocol::{EventMsg, Op, Submission, UserInput};
     use std::io::Write;
 
+    // Validate prompt is not empty before any other processing (including authentication)
+    if exec_cli.prompt.trim().is_empty() {
+        bail!("Prompt cannot be empty");
+    }
+
     let is_json = exec_cli.format == "json" || exec_cli.format == "jsonl";
 
     let mut config = cortex_engine::Config::default();
@@ -913,6 +929,57 @@ fn generate_completions(shell: Shell) {
     let stdout = io::stdout();
     let mut writer = BrokenPipeIgnorer { inner: stdout };
     generate(shell, &mut cmd, "cortex", &mut writer);
+
+    // Print dynamic completion helper for agent names
+    // Users can regenerate completions to get this functionality
+    let agent_completion_note = match shell {
+        Shell::Bash => {
+            r#"
+# Dynamic agent completion for --agent flag
+# Add this to your .bashrc after sourcing completions:
+_cortex_agent_completion() {
+    local agents
+    agents=$(cortex agent list --names-only 2>/dev/null)
+    COMPREPLY=($(compgen -W "$agents" -- "${COMP_WORDS[COMP_CWORD]}"))
+}
+complete -F _cortex_agent_completion cortex run --agent
+"#
+        }
+        Shell::Zsh => {
+            r#"
+# Dynamic agent completion for --agent flag
+# Add this to your .zshrc after sourcing completions:
+_cortex_agents() {
+    local agents
+    agents=(${(f)"$(cortex agent list --names-only 2>/dev/null)"})
+    _describe 'agent' agents
+}
+compdef _cortex_agents cortex run -a --agent
+"#
+        }
+        Shell::Fish => {
+            r#"
+# Dynamic agent completion for --agent flag
+complete -c cortex -n "__fish_seen_subcommand_from run" -l agent -xa "(cortex agent list --names-only 2>/dev/null)"
+"#
+        }
+        Shell::PowerShell => {
+            r#"
+# Dynamic agent completion for --agent flag
+# Add this to your PowerShell profile:
+Register-ArgumentCompleter -CommandName cortex -ParameterName agent -ScriptBlock {
+    param($commandName, $parameterName, $wordToComplete)
+    cortex agent list --names-only 2>$null | Where-Object { $_ -like "$wordToComplete*" }
+}
+"#
+        }
+        _ => "",
+    };
+
+    // Write the agent completion note as a comment
+    if !agent_completion_note.is_empty() {
+        let _ = writer.write_all(agent_completion_note.as_bytes());
+    }
 }
 
 fn generate_man_page(output_dir: Option<PathBuf>) -> Result<()> {
@@ -979,7 +1046,7 @@ async fn run_resume(resume_cli: ResumeCommand) -> Result<()> {
                 }
             } else {
                 anyhow::bail!(
-                    "Invalid session ID: {id_str}. Expected full UUID or 8-character prefix."
+                    "Invalid session ID format: {id_str}. Expected full UUID or 8-character prefix."
                 );
             }
         }

cortex-cli/src/main.rs

@@ -243,8 +243,10 @@ async fn run_pr_checkout(args: PrCli) -> Result<()> {
     }
 
     println!();
-    println!("✅ Successfully checked out PR #{}", pr_number);
-    println!("   Branch: {}", branch_name);
+    println!(
+        "✅ Checked out PR #{} to branch '{}' from '{}:{}'",
+        pr_number, branch_name, pr_info.author, pr_info.head_branch
+    );
     println!();
     println!("Commands:");
     // SECURITY: Validate base_branch before displaying in commands

cortex-cli/src/pr_cmd.rs

@@ -796,9 +796,15 @@ impl RunCli {
 
         // Share session if requested
         if self.share {
-            // TODO: Implement session sharing when API is available
-            if self.verbose {
-                eprintln!("Session sharing requested but not yet implemented");
+            use cortex_share::ShareManager;
+            let share_manager = ShareManager::new();
+            match share_manager.share(&session_id).await {
+                Ok(shared) => {
+                    eprintln!("✓ Session shared: {}", shared.url);
+                }
+                Err(e) => {
+                    eprintln!("Warning: Failed to share session: {}", e);
+                }
             }
         }
 

cortex-cli/src/run_cmd.rs

@@ -131,6 +131,12 @@ impl StatsCli {
                 println!("{json_output}");
             } else {
                 println!("No sessions found. Start using Cortex to generate statistics!");
+                println!();
+                println!("The stats command will track:");
+                println!("  - Session counts and message totals");
+                println!("  - Token usage (input and output tokens)");
+                println!("  - Estimated costs by provider and model");
+                println!("  - Tool call frequency");
             }
             return Ok(());
         }