refactor(cli): pass lifecycle typed options

[cv]

Summary

Stop rebuilding argv strings in lifecycle oclif adapters and pass typed option objects from the parsed oclif result into action facades.

Stack Navigation

• Position: 35 of 60
• Previous PR: #2927 — refactor(cli): use oclif flag relationships
• Next PR: #2929 — refactor(cli): parse durations with oclif flags

Changes

• Added typed lifecycle option shapes and compatibility normalizers for destroy, rebuild, gc, and upgrade-sandboxes.
• Updated lifecycle command classes to pass typed options instead of reconstructed legacy argv arrays.
• Kept action-level compatibility with existing internal argv callers.
• Replaced a gc source-shape assertion with behavior-level option normalization coverage.

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

Release Notes

• Refactor

  • Internal improvements to command option handling for enhanced type safety and consistency across sandbox management operations.

• Tests

  • Added test coverage for option normalization utilities to ensure robust handling of configuration flags.

[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

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

The PR refactors sandbox lifecycle actions to accept typed options objects instead of CLI argument arrays. It introduces lifecycle-options.ts with four option interfaces and normalizer functions for backward compatibility, then updates all action files, CLI commands, and wrappers to use normalized options derived from either structured objects or string arrays of flags.

Changes

Lifecycle Options Refactoring

Layer / File(s)	Summary
Type Definitions & Normalizers src/lib/lifecycle-options.ts	Defines DestroySandboxOptions, RebuildSandboxOptions, GarbageCollectImagesOptions, and UpgradeSandboxesOptions interfaces. Each normalizer function accepts string[] | TypedOptions and converts flag strings (e.g., --force, --yes, --verbose, --dry-run, --auto, --check) to typed boolean fields, or returns the options object unchanged.
Core Action Functions src/lib/sandbox-destroy-action.ts, src/lib/sandbox-rebuild-action.ts, src/lib/maintenance-actions.ts, src/lib/upgrade-sandboxes-action.ts	Each action now accepts options: string[] | TypedOptions and normalizes it via the appropriate normalizer. Behavior gates (skipConfirm, dryRun, verbose, etc.) derive from normalized option fields instead of direct flag inspection.
Runtime & Global Wrappers src/lib/sandbox-runtime-actions.ts, src/lib/global-cli-actions.ts	Function signatures updated to accept options: string[] | TypedOptions and forward them to underlying actions. Type assertions for dynamic require() calls updated to reflect the new parameter shape.
CLI Command Classes src/lib/destroy-cli-command.ts, src/lib/rebuild-cli-command.ts, src/lib/maintenance-cli-commands.ts	CLI commands updated to construct and pass typed options objects { force, yes, verbose, ... } to action functions instead of building legacy string arrays. DestroyCliCommand and RebuildCliCommand now extend NemoClawCommand instead of Command.
Tests & Option Normalization Coverage src/lib/lifecycle-options.test.ts, test/image-cleanup.test.ts	New test file verifies normalization preserves typed objects and correctly maps flag arrays. Existing test updated to focus on option normalization for garbage-collect operations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Hops of joy, this refactoring dance,
From string arrays to options true,
Type-safe flags in every stance,
A backward-compat encore, too!
Lifecycle flows now cleanly brew. 🌱

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.56% 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 clearly and concisely describes the main refactoring: replacing legacy argv string reconstruction with typed option objects for lifecycle CLI commands.
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-first-lifecycle-options

---

_{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).