refactor(cli): improve snapshot command metadata

[cv]

Summary

Improve the oclif shape for sandbox snapshot commands by adding examples and making the parent command a strict adapter. This keeps public snapshot help stable while allowing unknown snapshot subcommands to fail before reaching the snapshot action.

Stack Navigation

• Position: 16 of 60
• Previous PR: #2907 — refactor(cli): tighten policy and channel parser validation
• Next PR: #2909 — refactor(cli): require skill install path in oclif

Changes

• Added examples for the snapshot parent plus create, list, and restore subcommands.
• Made the parent sandbox:snapshot command strict and sandbox-arg aware.
• Routed nemoclaw <name> snapshot --help through the parent adapter while preserving public usage text.
• Added adapter and CLI coverage for parent usage and unknown snapshot subcommands.

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

• New Features

  • Added usage examples and clearer help documentation for snapshot commands.

• Bug Fixes

  • Help flag now shows snapshot usage instead of being treated as an argument.
  • Invalid snapshot subcommands are rejected earlier (extra/unknown args now error).
  • Installer: tightened non-interactive check to fail fast when stdin is not a TTY.

• Tests

  • Added tests verifying snapshot help display and invalid-subcommand error handling.

[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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8f9279a4-bbc8-40d5-8c64-57f4f688ea6b

📥 Commits

Reviewing files that changed from the base of the PR and between 8b1d8a9 and 6184e41.

📒 Files selected for processing (1)

• src/lib/legacy-oclif-dispatch.ts

---

📝 Walkthrough

Walkthrough

Snapshot CLI was converted to a strict oclif command with explicit args parsing and examples; help flags are intercepted and not forwarded as positional snapshot subcommand args. Tests were added for the new parsing/dispatch behavior. The installer TTY acceptance check was tightened.

Changes

Snapshot Command Flow

Layer / File(s)	Summary
Data Shape / CLI Schema src/lib/snapshot-cli-commands.ts	SnapshotCommand now static strict = true, declares static args = { sandboxName }, and adds static examples.
Core Implementation src/lib/snapshot-cli-commands.ts	run() uses this.parse(SnapshotCommand) and calls sandboxSnapshot(args.sandboxName, []) (does not forward sub-arguments).
Dispatch Guard src/lib/legacy-oclif-dispatch.ts	resolveSandboxOclifDispatch adds an early branch for "snapshot": if subcommand is missing or --help/-h, return { kind: "oclif", commandId: "sandbox:snapshot", args: [sandboxName] } to avoid forwarding help flags.
Tests / Documentation src/lib/snapshot-cli-commands.test.ts, test/cli.test.ts	Adds tests asserting SnapshotCommand.run(["alpha"], ...) dispatches sandboxSnapshot("alpha", []), that unknown subcommands (e.g., bogus) error before dispatch, and that alpha snapshot --help shows public snapshot examples.

Installer TTY Acceptance

Layer / File(s)	Summary
Script Behavior scripts/install.sh	In main(), tighten acceptance gating: if NON_INTERACTIVE != 1 and stdin is not a TTY (! -t 0), the installer errors (removes prior /dev/tty fallback).
Comments scripts/install.sh	Adjusted explanatory comments to match the new gating behavior.

sequenceDiagram
    participant User as CLI user
    participant Oclif as oclif command
    participant Dispatcher as legacy oclif dispatch
    participant Sandbox as sandbox:snapshot action

    User->>Oclif: run "alpha snapshot [--help|subcmd]"
    Oclif->>Dispatcher: resolve dispatch for snapshot
    alt no subcmd or --help/-h
        Dispatcher->>Sandbox: oclif dispatch with args [sandboxName]
    else explicit subcommand (e.g., create/list/restore)
        Dispatcher->>Sandbox: oclif dispatch with subcommand handling
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

I am a rabbit, quick and spry,
I caught the help flag as it flew by.
Snapshots tidy, args made right,
No stray flags in the night. 🐇📸

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'refactor(cli): improve snapshot command metadata' directly aligns with the main changeset, which adds examples and improves the oclif UX for snapshot commands across multiple files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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-ux-snapshot-commands

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/install.sh`:
- Around line 1628-1630: The current guard incorrectly rejects piped interactive
installs by requiring stdin to be a TTY; update the conditional around
NON_INTERACTIVE to allow cases where /dev/tty exists (the documented fallback)
so interactive piped installs can prompt. Concretely, change the if that checks
[ "${NON_INTERACTIVE:-}" != "1" ] && [ ! -t 0 ] to also allow when /dev/tty is
present (e.g. [ ! -t 0 ] && [ ! -e /dev/tty ]), leaving the existing error
message and references to --yes-i-accept-third-party-software /
NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE untouched; this ensures code paths that
open /dev/tty for prompts remain reachable during curl ... | bash flows.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 6941f1b6-3dca-4ac2-83eb-334d1937af11

📥 Commits

Reviewing files that changed from the base of the PR and between 0f44fc2 and 8b1d8a9.

📒 Files selected for processing (1)

• scripts/install.sh

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Piped install now hard-fails against the documented default flow

At Line 1628, this condition rejects all curl ... | bash runs unless NON_INTERACTIVE=1 (or equivalent) is pre-set. That conflicts with the usage text at Line 483-484 and effectively makes the existing /dev/tty fallback paths unreachable for interactive piped installs.

Suggested minimal fix

-  if [ "${NON_INTERACTIVE:-}" != "1" ] && [ ! -t 0 ]; then
-    error "Interactive third-party software acceptance requires a TTY. Re-run in a terminal or pass --yes-i-accept-third-party-software (or set NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1)."
-  fi
+  if [ "${NON_INTERACTIVE:-}" != "1" ] && [ ! -t 0 ]; then
+    if { exec 3</dev/tty; } 2>/dev/null; then
+      exec 3<&-
+    else
+      error "Interactive third-party software acceptance requires a TTY. Re-run in a terminal or pass --yes-i-accept-third-party-software (or set NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1)."
+    fi
+  fi

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if [ "${NON_INTERACTIVE:-}" != "1" ] && [ ! -t 0 ]; then
	error "Interactive third-party software acceptance requires a TTY. Re-run in a terminal or pass --yes-i-accept-third-party-software (or set NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1)."
	fi
	if [ "${NON_INTERACTIVE:-}" != "1" ] && [ ! -t 0 ]; then
	if { exec 3</dev/tty; } 2>/dev/null; then
	exec 3<&-
	else
	error "Interactive third-party software acceptance requires a TTY. Re-run in a terminal or pass --yes-i-accept-third-party-software (or set NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE=1)."
	fi
	fi

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/install.sh` around lines 1628 - 1630, The current guard incorrectly
rejects piped interactive installs by requiring stdin to be a TTY; update the
conditional around NON_INTERACTIVE to allow cases where /dev/tty exists (the
documented fallback) so interactive piped installs can prompt. Concretely,
change the if that checks [ "${NON_INTERACTIVE:-}" != "1" ] && [ ! -t 0 ] to
also allow when /dev/tty is present (e.g. [ ! -t 0 ] && [ ! -e /dev/tty ]),
leaving the existing error message and references to
--yes-i-accept-third-party-software / NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE
untouched; this ensures code paths that open /dev/tty for prompts remain
reachable during curl ... | bash flows.

[prekshivyas]

LGTM after rebase. Snapshot work is clean (5 files / +67 / -13).

• SnapshotCommand parent flips strict=false → strict=true with explicit Args.string for sandboxName, replacing the hand-rolled if (!sandboxName) error. <name> snapshot bogus now rejected with Unexpected argument: bogus instead of silently dispatched. Tested.
• legacy-oclif-dispatch.ts adds a help intercept routing snapshot --help (and bare snapshot) through the parent adapter, preserving public help text without leaking sandbox:snapshot command-id. Tested.
• Examples added to all four snapshot commands.

One scope-drift nit (non-blocking but worth flagging for description hygiene):

scripts/install.sh removes the /dev/tty fallback from the license-acceptance check. Was: skip license error if NON_INTERACTIVE=1 OR stdin TTY OR /dev/tty openable. Now: skip only if NON_INTERACTIVE=1 OR stdin TTY. The inline comment explains the rationale (curl|bash mode leaves partial install on decline) and installer-hash-check PASSed, so the hash file was updated. But the change isn't mentioned in the human-written PR body — only CodeRabbit's auto-summary surfaced it. Consider pulling that line into the description before merge so the squash-merge commit message reflects what landed. No new test for the fail-fast path; if any user is on a curl|bash flow that relied on /dev/tty fallback, this will now fail fast (which is the intended fix per the comment).

CI: pr.yaml mostly green; pr-self-hosted builds and wsl-e2e/macos-e2e/checks still in flight at review time. src/nemoclaw.ts untouched — cumulative ~16-orphan debt unchanged.