refactor(cli): extract public argv normalizer

[cv]

Summary

Start the post-UX architecture cleanup by extracting public argv normalization out of src/nemoclaw.ts. The top-level entrypoint still owns registry recovery and user-facing routing errors, but command classification now lives in a focused helper with unit coverage.

Stack Navigation

• Position: 23 of 60
• Previous PR: #2915 — docs: sync oclif UX command reference
• Next PR: #2917 — refactor(cli): rename oclif dispatch module

Changes

• Added src/lib/cli-argv-normalizer.ts for root/global/sandbox argv normalization and typo suggestions.
• Replaced duplicated command-shape parsing in src/nemoclaw.ts with the normalizer.
• Added unit coverage for root help, global commands, explicit sandbox actions, implicit connect, and suggestions.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• Tests

  • Added comprehensive test suite for CLI argument normalization and command suggestions

• Refactor

  • Reorganized CLI argument parsing and command routing
  • Enhanced command suggestions with improved typo detection using similarity matching
  • Improved handling of help requests across root, global commands, and sandbox contexts
  • Streamlined sandbox action dispatching with explicit connect action support

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: a44ac2c8-9a0d-48b4-8df9-24adc8a25248

📥 Commits

Reviewing files that changed from the base of the PR and between 3224350 and 4efce12.

📒 Files selected for processing (1)

• src/nemoclaw.ts

---

📝 Walkthrough

Walkthrough

A new CLI argv normalizer module is introduced that formalizes the parsing of command-line arguments into a discriminated union type (NormalizedArgv), covering root help, dump commands, global commands, and sandbox actions. The main entry point is refactored to dispatch through this centralizer, and a helper function for command suggestion via edit distance is provided and used in both modules.

Changes

CLI Argument Normalization

Layer / File(s)	Summary
Data Shape src/lib/cli-argv-normalizer.ts (lines 1–25)	Exported discriminated union NormalizedArgv with variants rootHelp, dumpCommands, global, and sandbox. NormalizeArgvOptions provides configuration for global commands and sandbox connect flag detection.
Core Implementation src/lib/cli-argv-normalizer.ts (lines 26–88)	normalizeArgv parses argv into one of the four normalized kinds; editDistance computes Levenshtein distance; suggestCommand finds the closest non-flag command match.
Tests src/lib/cli-argv-normalizer.test.ts	Vitest suite verifying normalization of help, dump, global, sandbox, and connect scenarios, plus command suggestion with typo correction and flag-like filtering.
Integration src/nemoclaw.ts (lines 83–254)	main refactored to call normalizeArgv and dispatch on the result kind; suggestGlobalCommand simplified to delegate to the shared suggestCommand helper.

Sequence Diagram

sequenceDiagram
    participant CLI as CLI Input
    participant NormAr as Argv Normalizer
    participant Main as Main Dispatcher
    participant GCmd as Global Command<br/>Handler
    participant SBx as Sandbox Action<br/>Handler

    CLI->>NormAr: argv: string[]
    activate NormAr
    alt Empty or --help
        NormAr-->>NormAr: { kind: "rootHelp" }
    else --dump-commands
        NormAr-->>NormAr: { kind: "dumpCommands" }
    else Known global command
        NormAr-->>NormAr: { kind: "global", command, args }
    else Sandbox invocation
        NormAr-->>NormAr: { kind: "sandbox",<br/>sandboxName, action,<br/>actionArgs, connectHelpRequested }
    end
    NormAr-->>Main: NormalizedArgv
    deactivate NormAr

    activate Main
    alt kind = "rootHelp" | "dumpCommands"
        Main->>Main: Handle early
    else kind = "global"
        Main->>GCmd: Dispatch command
        activate GCmd
        GCmd-->>Main: Result
        deactivate GCmd
    else kind = "sandbox"
        alt connectHelpRequested
            Main->>Main: Show connect help
        else
            Main->>SBx: Execute action
            activate SBx
            SBx-->>Main: Result
            deactivate SBx
        end
    end
    deactivate Main

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A normalizer hops along the argv trail,
Bundling chaos into kinds both great and small—
Global commands leap, sandbox actions stir,
Help and dumps parse clean, no more a whir,
Edit distances whisper typos' gentle call! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/oclif-arch-normalize-argv

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cjagwani]

Approved as part of stack from #2886 (auto-approve: CI green, no scope/behavior flags).