refactor(cli): extract shared helpers into commands/common module

[varshaprasad96]

Summary

Extract ~950 lines of shared helper functions, types, and parsing utilities from the monolithic run.rs (10,138 lines) into a new commands/common.rs module. This is PR 1 of 6 in the incremental CLI refactor tracked by #2304.

Related Issue

Part of #2304

Changes

• Create commands/mod.rs and commands/common.rs module scaffolding
• Move formatting/display helpers: phase_name, format_epoch_ms, format_elapsed, format_timestamp, print_yaml_line, print_sandbox_policy, short_hash, non_empty_or, format_timestamp_ms, format_optional_epoch_ms, truncate_status_field, truncate_display, format_setting_value
• Move parsing utilities: parse_env_pairs, parse_key_value_pairs, parse_secret_material_env_pairs, parse_credential_*, parse_cli_setting_value, parse_duration_to_ms
• Move shared types: PolicyGetView, ProvisioningStep, ProvisioningDisplay
• Move provisioning event handlers, sandbox header, confirm helpers, git env scrubbing
• Re-export only the 4 items consumed by main.rs and integration tests via pub use in run.rs
• Use pub(crate) mod commands to keep the module crate-internal

Testing

• cargo fmt and cargo clippy pass with zero warnings
• All 362 unit tests pass identically on both baseline and refactored branches
• CLI --help output byte-identical across all subcommands (gateway, sandbox, provider, service, settings, policy, inference)
• Integration tests pass

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• No behavioral changes — pure structural refactor

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[2000krysztof]

I'm curious about the decision for placing common.rs under commands/ rather than at the top level of src/. Since run.rs (which is at the parent level) imports from it, and the utilities seem fairly general-purpose, I'm wondering if src/common.rs might be cleaner?

[varshaprasad96]

@2000krysztof - common.rs is intentionally under commands/ because it's specifically shared helpers for the command modules, not general-purpose crate utilities. The plan in #2304 (#2304 (comment)) calls for decomposing run.rs into commands/gateway.rs, commands/sandbox.rs, commands/provider.rs, etc. common.rs holds the helpers shared across those command modules (CLI parsing, provisioning display, policy views, formatting).

The fact that run.rs currently imports from commands/common is a transitional state, run.rs still contains all the command functions that haven't been extracted yet (PRs 2–6). Once the migration completes, run.rs shrinks to a minimal re-export shim or goes away entirely.

Placing it at src/common.rs would make it a peer of auth.rs, ssh.rs, tls.rs which are infrastructure modules, a different layer than command-specific helpers.

[2000krysztof]

Makes sense, thanks for the explanation. Looks good to me.

[johntmyers]

gator-agent

Blocked

Head SHA: 258c301b8aa6a57744e940deaf37af1f204b27a0

Gator is blocked because this PR currently has merge conflicts with main. DCO and the vouch gate pass, and the refactor is scoped by #2304, but independent code review and CI authorization should wait for a conflict-free head.

Next action: @varshaprasad96, please update the branch from main and resolve the conflicts. Gator will review the new head and then decide whether any test label or /ok to test <sha> action is needed.

[varshaprasad96]

The PR has been rebased with main, and the checks have been passing locally.

[johntmyers]

gator-agent

PR Review Status

Validation: This behavior-preserving CLI refactor is project-valid under maintainer-scoped issue #2304 and its approved incremental command-module plan.
Head SHA: f0b695a8b87ad415766438f0df83940fa6976627

Thanks @varshaprasad96. I confirmed the rebased head is now mergeable and independently checked the complete diff after your update.

Review findings:

• No blocking findings remain. The moved implementations and error text are preserved, the existing run:: compatibility surface remains intact, and the credential/environment helpers do not change behavior.

Docs: Not needed because this is a structural refactor with no user-facing command, output, configuration, or workflow change.

Tests: Existing unit and integration coverage continues to exercise the preserved interfaces; review was code-only as required.

E2E: No test:* label is required for this behavior-preserving CLI-only move. The copy-pr validation gate still needs authorization for this head.

Next state: gator:watch-pipeline

[johntmyers]

/ok to test f0b695a

[johntmyers]

@varshaprasad96 some checks need to be fixed then we can get ready to merge