fix(hosts): gate host aliases on docker/vm drivers (#4516)

[yimoj]

Summary

Host-alias commands (hosts-list / hosts-add / hosts-remove) still assumed the legacy k3s gateway container openshell-cluster-nemoclaw and the Kubernetes Sandbox custom resource. Docker- and vm-driver sandboxes run per-sandbox direct containers with no gateway cluster container and no Sandbox CR, so the commands failed before reading aliases with No such container: openshell-cluster-nemoclaw. This gates those commands on direct-container drivers with an actionable message instead of targeting a container that does not exist.

Related Issue

Fixes #4516

Changes

• src/lib/actions/sandbox/host-aliases.ts: read the sandbox openshellDriver from the registry and fail fast with an actionable unsupported-runtime message for the docker and vm direct-container drivers, before any docker exec ... kubectl call. Legacy k3s behavior (kubernetes / unrecorded driver) is preserved unchanged. The message is explicit that OpenShell exposes no persistent host-alias API for these drivers and that a one-time /etc/hosts edit would not survive a restart/rebuild — so we do not pretend durability.
• test/cli.test.ts: added a parameterized regression test (docker + vm) proving the commands exit non-zero with the unsupported message and never invoke the legacy gateway container, including the --dry-run preview path. Extended the test SandboxEntry type with openshellDriver.

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
• npm run 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)

Ran locally: npm run typecheck:cli (pass), the full test/cli.test.ts CLI project — 172/172 passing (single-worker run; the shared host could not sustain the fully parallel npm test, but the affected cli project is green), the plugin pre-commit Vitest hook (pass on commit), codex review (no actionable findings), plus a manual reproduction through the built CLI confirming docker/vm drivers are gated and the legacy k3s path still patches the Sandbox resource for unrecorded drivers. Full npm test and prek will run in CI.

---

Signed-off-by: Yimo Jiang yimoj@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Host-alias commands now validate OpenShell driver compatibility and return clear, actionable errors when used with unsupported drivers (docker, vm). Commands fail fast and do not attempt legacy gateway edits or produce misleading previews.
  • --dry-run correctly fails on incompatible driver configurations and does not emit a host-alias JSON preview.

• Tests

  • Added tests covering host-alias commands and --dry-run to verify immediate failure and absence of legacy gateway operations for unsupported drivers.

[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: 421388dd-94b2-408a-8315-ee8451e83f8b

📥 Commits

Reviewing files that changed from the base of the PR and between af1a06d and 3ccabf9.

📒 Files selected for processing (1)

• test/cli.test.ts

---

📝 Walkthrough

Walkthrough

Host-alias CLI commands (alpha hosts-list, alpha hosts-add, alpha hosts-remove) now validate the sandbox's OpenShell driver and fail immediately with a clear error for direct-container drivers (docker, vm) instead of attempting legacy gateway operations. Tests exercise the gating and fixture support.

Changes

Host-alias driver gating

Layer / File(s)	Summary
Driver validation helpers and integration src/lib/actions/sandbox/host-aliases.ts	DIRECT_CONTAINER_DRIVERS added. normalizeDriver and assertLegacyGatewayHostAliasSupport fetch sandbox.openshellDriver via registry.getSandbox and throw HostAliasesCommandError for unsupported drivers. listSandboxHostAliases, addSandboxHostAlias, and removeSandboxHostAlias call the assertion before any legacy gateway operations.
Test fixture and command gating validation test/cli.test.ts	SandboxEntry fixture adds optional openshellDriver field. New parameterized test for docker and vm asserts hosts-list/add/remove fail early with driver-specific unsupported messages, --dry-run also fails without emitting a hostAliases JSON patch preview, and the legacy Docker gateway path is never invoked.

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers:

• cv

"A rabbit sniffs the code at night,
If driver runs direct, we stop the fight.
No legacy chase, no phantom container call,
Commands nap early—no needless sprawl.
Hooray for clearer errors, short and bright!"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% 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 'fix(hosts): gate host aliases on docker/vm drivers' directly summarizes the main change: preventing host-alias commands from failing on docker/vm drivers by adding driver gating logic.
Linked Issues check	✅ Passed	The PR fully addresses all coding requirements from issue #4516: it adds driver gating for docker/vm, fails fast with actionable errors before attempting unsupported operations, and preserves k3s/kubernetes behavior.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to addressing issue #4516: driver gating logic in host-aliases.ts and regression tests in cli.test.ts; no unrelated modifications detected.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{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 `@src/lib/actions/sandbox/host-aliases.ts`:
- Around line 84-88: The code currently swallows any errors from
registry.getSandbox by wrapping the lookup in a broad try/catch and defaulting
driver to null; remove that catch so registry lookup failures surface instead of
silently degrading behavior. Replace the try/catch around
normalizeDriver(registry.getSandbox(sandboxName)?.openshellDriver) with explicit
handling: call registry.getSandbox(sandboxName) first, if it returns null set
driver = null, otherwise pass its openshellDriver into normalizeDriver and let
exceptions from registry or normalizeDriver propagate to the caller (or handle
them at a higher system boundary); reference normalizeDriver,
registry.getSandbox, openshellDriver and the driver variable when making the
change.

🪄 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: 8b9b3c78-4301-457e-b005-9e46c8ddd706

📥 Commits

Reviewing files that changed from the base of the PR and between df7d054 and a5e5120.

📒 Files selected for processing (2)

• src/lib/actions/sandbox/host-aliases.ts
• test/cli.test.ts

[wscurran]

✨
Related open issues:

• #4516 [Ubuntu 24.04][CLI] hosts alias commands fail on Docker-driver sandbox with missing legacy container

[cjagwani]

Approving. Targeted fix for #4516 — gates list/add/remove on docker/vm drivers with an actionable error before any docker exec openshell-cluster-nemoclaw attempt. The fall-through preserves the legacy k3s path for unknown/null drivers, which is the right backwards-compat choice.

Test coverage is solid: parameterized across both direct-container drivers, asserts the --dry-run path is gated too, and proves no docker exec is even attempted (via dockerLog never created). Error message is honest about why (no Sandbox CR + no persistent host-alias API + /etc/hosts wouldn't survive restart).