refactor(cli): extract upgrade sandbox helpers

[cv]

Summary

Extract pure upgrade sandbox classification helpers from the subprocess-heavy upgrade action module.

Stack Navigation

• Position: 48 of 60
• Previous PR: #2962 — refactor(cli): extract maintenance image helpers
• Next PR: #2964 — refactor(cli): extract sandbox destroy helpers

Changes

• Added upgrade-sandboxes-helpers.ts for confirmation bypass, stale/unknown classification, and rebuildable/stopped splitting.
• Updated upgradeSandboxes to call the extracted helpers while keeping OpenShell and rebuild orchestration in the action module.
• Added direct helper coverage for stale, unknown, current, running, and stopped sandbox cases.

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

• Refactor

  • Refactored the sandbox upgrade workflow by introducing modular helper functions that improve code organization, maintainability, and readability while preserving all existing behavior and functionality.

• Tests

  • Added comprehensive test suite covering upgrade confirmation handling, sandbox version classification, and the intelligent grouping of sandboxes by their rebuild state and configuration.

[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: 4e0e53d0-9c9b-4ae0-bb66-ceb7418df21d

📥 Commits

Reviewing files that changed from the base of the PR and between f8f4013 and 402d9bb.

📒 Files selected for processing (3)

• src/lib/upgrade-sandboxes-action.ts
• src/lib/upgrade-sandboxes-helpers.test.ts
• src/lib/upgrade-sandboxes-helpers.ts

---

📝 Walkthrough

Walkthrough

This PR introduces three modular helper functions that encapsulate sandbox version classification, upgrade confirmation skipping, and rebuild grouping logic. The upgrade-sandboxes-action is refactored to delegate logic to these helpers. Overall behavior remains unchanged, with code organized for better testability and reusability.

Changes

Sandbox Upgrade Helpers Extraction

Layer / File(s)	Summary
Type Definitions src/lib/upgrade-sandboxes-helpers.ts	New types: SandboxVersionCheck, UpgradeSandboxCandidate, and UpgradeClassification define the data structures for version checks and upgrade classifications.
Core Helper Functions src/lib/upgrade-sandboxes-helpers.ts	Three functions implemented: shouldSkipUpgradeConfirmation() checks auto/yes flags; classifyUpgradeableSandboxes() classifies sandboxes into stale/unknown; splitRebuildableSandboxes() partitions stale sandboxes by running state.
Integration in Action src/lib/upgrade-sandboxes-action.ts	Inline skip logic, classification loop, and rebuild grouping logic replaced with calls to the new helpers, reducing duplication and improving maintainability.
Helper Tests src/lib/upgrade-sandboxes-helpers.test.ts	Three test cases verify confirmation bypass detection, sandbox classification with running state, and split logic for rebuildable versus stopped sandboxes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• NVIDIA/NemoClaw#2897: Directly refactors upgrade-sandboxes-action to use the new helper functions introduced in this PR.

Suggested labels

v0.0.34

Suggested reviewers

• prekshivyas

Poem

🐰 Logic scattered far and wide,
Now bundled up with helper pride!
Stale and unknown, running true,
Modular code hops right on through. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.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 clearly describes the main change: extracting helper functions from the upgrade-sandboxes action into a new dedicated module. It accurately reflects the primary refactoring work.
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/retry-upgrade-sandbox-helpers

---

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

[prekshivyas]

LGTM. Same pattern as #2962 — three pure helpers extracted from upgradeSandboxes into upgrade-sandboxes-helpers.ts:

• shouldSkipUpgradeConfirmation — wraps the auto-or-yes check.
• classifyUpgradeableSandboxes — replaces the inline classification for-loop, with checkVersion injected as a dep (clean DI for test).
• splitRebuildableSandboxes — replaces the two .filter() calls.

Inline blocks fully replaced; behavior verbatim. The checkVersion injection point is a strict improvement over the previous direct call — same default, but testable.

+59 lines of direct unit tests covering confirmation bypass (auto/yes/check), classification (stale/running, stale/stopped, unknown, current), and rebuildable/stopped split.

CI: pr.yaml fully green (lint/dco/check-hash/legacy-path-guard/macos-e2e/changes/checks PASS); test-e2e-ollama-proxy + pr-self-hosted builds still in flight at review time. No failures.