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

[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: b792fcc678ff98d7b885c9cee0cbaf110770c9ab

Thanks @varshaprasad96. I checked the complete current diff after your import-formatting update and verified the moved helpers against main.

Review findings:

• One warning requires an author change: the move drops an existing public openshell_cli::run re-export.
• One non-blocking visibility suggestion is included inline.
• Otherwise the extraction preserves behavior, error text, credential handling, provisioning flow, output formatting, and Git environment scrubbing; no security regression was found.

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

Tests: Review was code-only as required. Existing behavioral tests remain intact, but the suite does not currently assert the lost public re-export.

E2E: No test:* label is required for this behavior-preserving CLI-only move. CI mirror authorization should wait until the blocking review finding is fixed on a new head.

Next state: gator:in-review

[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: d47b76b546c0058b73130a5ff37c5f4e4a49fa23

Thanks @varshaprasad96. I checked the new head after your response about preserving the public API. The parse_secret_material_env_pairs re-export is restored, PolicyGetView::includes_policy is narrowed to pub(crate), and the complete extraction was independently re-reviewed.

Review findings:

• No blocking findings remain. The moved implementations, public compatibility surface, error text, credential/environment handling, provisioning behavior, output formatting, and Git environment scrubbing remain equivalent.

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

Tests: Review was code-only as required. Existing unit and integration coverage remains in place.

E2E: No test:* label is required for this behavior-preserving CLI-only move. The copy-pr validation gate must be authorized for this new head.

Next state: gator:watch-pipeline

[johntmyers]

/ok to test d47b76b

[johntmyers]

gator-agent

Monitoring Complete

Monitoring is complete because this PR has merged.

Final status: The final head d47b76b546c0058b73130a5ff37c5f4e4a49fa23 had no blocking review findings, maintainer approval was present, and the required Branch Checks, Helm Lint, and DCO gates passed. E2E labels were not required for this behavior-preserving CLI-only refactor.

I removed the active gator:* label because there is nothing left for gator to monitor on this PR.