refactor(cli): group pure domain helpers

src/lib/commands/sandbox/logs.ts

@@ -4,8 +4,8 @@
 import { Args, Command, Flags } from "@oclif/core";
 
 import { logsSinceDurationFlag } from "../../duration-flags";
-import type { SandboxLogsOptions } from "../../sandbox-logs-options";
-import { DEFAULT_SANDBOX_LOG_LINES } from "../../sandbox-logs-options";
+import type { SandboxLogsOptions } from "../../domain/sandbox/log-options";
+import { DEFAULT_SANDBOX_LOG_LINES } from "../../domain/sandbox/log-options";
 import { showSandboxLogs } from "../../sandbox-runtime-actions";
 
 type SandboxLogsRuntimeBridge = {

src/lib/coverage-hotspots.test.ts

@@ -6,7 +6,7 @@ import os from "node:os";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 
-import { parseDuration } from "./duration";
+import { parseDuration } from "./domain/duration";
 import { parseGatewayTokenArgs, runGatewayTokenCommand } from "./gateway-token-command";
 import { resolveDefaultSandboxName, runStartCommand, runStopCommand } from "./services-command";
 import { getVersion } from "./version";

test/duration.test.ts → src/lib/domain/duration.test.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { describe, it, expect } from "vitest";
-import { parseDuration, MAX_SECONDS, DEFAULT_SECONDS } from "../src/lib/duration.js";
+import { parseDuration, MAX_SECONDS, DEFAULT_SECONDS } from "./duration";
 
 describe("parseDuration", () => {
   it("parses minutes", () => {

src/lib/lifecycle-options.test.ts → src/lib/domain/lifecycle/options.test.ts

@@ -8,7 +8,7 @@ import {
   normalizeGarbageCollectImagesOptions,
   normalizeRebuildSandboxOptions,
   normalizeUpgradeSandboxesOptions,
-} from "./lifecycle-options";
+} from "./options";
 
 describe("lifecycle option normalization", () => {
   it("preserves typed destroy options and still accepts compatibility argv", () => {

src/lib/maintenance-image-helpers.test.ts → src/lib/domain/maintenance/images.test.ts

@@ -7,7 +7,7 @@ import {
   findOrphanedSandboxImages,
   getRegisteredImageTags,
   parseSandboxImageRows,
-} from "./maintenance-image-helpers";
+} from "./images";
 
 describe("maintenance image helpers", () => {
   it("parses Docker image rows and fills missing sizes", () => {

src/lib/upgrade-sandboxes-helpers.test.ts → src/lib/domain/maintenance/upgrade.test.ts

@@ -8,7 +8,7 @@ import {
   shouldSkipUpgradeConfirmation,
   splitRebuildableSandboxes,
   type SandboxVersionCheck,
-} from "./upgrade-sandboxes-helpers";
+} from "./upgrade";
 
 describe("upgrade sandboxes helpers", () => {
   it("detects upgrade confirmation bypass modes", () => {

src/lib/upgrade-sandboxes-helpers.ts → src/lib/domain/maintenance/upgrade.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import type { UpgradeSandboxesOptions } from "./lifecycle-options";
+import type { UpgradeSandboxesOptions } from "../lifecycle/options";
 
 export type SandboxVersionCheck = {
   isStale: boolean;

src/lib/policy-channel-helpers.test.ts → src/lib/domain/policy-channel.test.ts

@@ -7,7 +7,7 @@ import {
   parseCustomPolicySource,
   parsePolicyAddArgs,
   shouldSkipPolicyConfirmation,
-} from "./policy-channel-helpers";
+} from "./policy-channel";
 
 describe("policy channel helpers", () => {
   it("parses custom policy source flags", () => {

src/lib/sandbox-destroy-helpers.test.ts → src/lib/domain/sandbox/destroy.test.ts

@@ -8,7 +8,7 @@ import {
   isMissingSandboxDeleteOutput,
   shouldCleanupGatewayAfterDestroy,
   shouldStopHostServicesAfterDestroy,
-} from "./sandbox-destroy-helpers";
+} from "./destroy";
 
 describe("sandbox destroy helpers", () => {
   it("detects missing sandbox delete output", () => {

src/lib/sandbox-destroy-helpers.ts → src/lib/domain/sandbox/destroy.ts

@@ -3,7 +3,11 @@
 
 /* v8 ignore start -- pure helper tests exercise this module; orchestration coverage still runs through dist. */
 
-import { stripAnsi } from "./openshell";
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+function stripAnsi(value = ""): string {
+  return String(value).replace(ANSI_RE, "");
+}
 
 export type SpawnLikeResult = {
   status: number | null;

src/lib/sandbox-logs-helpers.test.ts → src/lib/domain/sandbox/logs.test.ts

@@ -11,7 +11,7 @@ import {
   exitCodeFromSignal,
   getLogsProbeTimeoutMs,
   normalizeSandboxLogsOptions,
-} from "./sandbox-logs-helpers";
+} from "./logs";
 
 describe("sandbox logs helpers", () => {
   it("normalizes boolean and partial logs options", () => {

src/lib/sandbox-logs-helpers.ts → src/lib/domain/sandbox/logs.ts

@@ -5,8 +5,8 @@
 
 import os from "node:os";
 
-import type { SandboxLogsOptions } from "./sandbox-logs-options";
-import { DEFAULT_SANDBOX_LOG_LINES } from "./sandbox-logs-options";
+import type { SandboxLogsOptions } from "./log-options";
+import { DEFAULT_SANDBOX_LOG_LINES } from "./log-options";
 
 export const DEFAULT_LOGS_PROBE_TIMEOUT_MS = 5000;
 export const LOGS_PROBE_TIMEOUT_ENV = "NEMOCLAW_LOGS_PROBE_TIMEOUT_MS";

src/lib/duration-flags.ts

@@ -3,7 +3,7 @@
 
 import { Errors, Flags } from "@oclif/core";
 
-import { parseDuration } from "./duration";
+import { parseDuration } from "./domain/duration";
 
 const LOGS_SINCE_DURATION_RE = /^[1-9]\d*(?:ms|s|m|h|d)$/i;
 

src/lib/global-cli-actions.ts

@@ -5,7 +5,7 @@ import { runDeployAction as executeDeployAction } from "./deploy-action";
 import {
   type GarbageCollectImagesOptions,
   type UpgradeSandboxesOptions,
-} from "./lifecycle-options";
+} from "./domain/lifecycle/options";
 import {
   backupAll as executeBackupAllAction,
   garbageCollectImages as executeGarbageCollectImagesAction,

src/lib/maintenance-actions.ts

@@ -7,9 +7,9 @@ import { prompt as askPrompt } from "./credentials";
 import {
   type GarbageCollectImagesOptions,
   normalizeGarbageCollectImagesOptions,
-} from "./lifecycle-options";
+} from "./domain/lifecycle/options";
 import { dockerListImagesFormat, dockerRmi } from "./docker";
-import { findOrphanedSandboxImages, parseSandboxImageRows } from "./maintenance-image-helpers";
+import { findOrphanedSandboxImages, parseSandboxImageRows } from "./domain/maintenance/images";
 import { captureOpenshell } from "./openshell-runtime";
 import * as registry from "./registry";
 import { parseLiveSandboxNames } from "./runtime-recovery";

src/lib/policy-channel-actions.ts

@@ -13,7 +13,7 @@ import { recoverNamedGatewayRuntime } from "./gateway-runtime-action";
 const { isNonInteractive } = require("./onboard") as { isNonInteractive: () => boolean };
 const onboardProviders = require("./onboard-providers");
 import * as policies from "./policies";
-import { parsePolicyAddArgs } from "./policy-channel-helpers";
+import { parsePolicyAddArgs } from "./domain/policy-channel";
 import * as registry from "./registry";
 import { runOpenshell } from "./openshell-runtime";
 import { rebuildSandbox } from "./sandbox-runtime-actions";

src/lib/sandbox-destroy-action.ts

@@ -10,7 +10,7 @@ import { prompt as askPrompt } from "./credentials";
 import {
   type DestroySandboxOptions,
   normalizeDestroySandboxOptions,
-} from "./lifecycle-options";
+} from "./domain/lifecycle/options";
 import * as onboardSession from "./onboard-session";
 import type { Session } from "./onboard-session";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "./openshell-timeouts";
@@ -26,7 +26,7 @@ import {
   getSandboxDeleteOutcome,
   shouldCleanupGatewayAfterDestroy,
   shouldStopHostServicesAfterDestroy,
-} from "./sandbox-destroy-helpers";
+} from "./domain/sandbox/destroy";
 import { G, R, YW } from "./terminal-style";
 
 type DockerRmi = (tag: string, opts?: { ignoreError?: boolean }) => { status: number | null };

src/lib/sandbox-logs-action.ts

@@ -14,8 +14,8 @@ import {
   getLogsProbeTimeoutMs,
   normalizeSandboxLogsOptions,
   type LogProbeResult,
-} from "./sandbox-logs-helpers";
-import type { SandboxLogsOptions } from "./sandbox-logs-options";
+} from "./domain/sandbox/logs";
+import type { SandboxLogsOptions } from "./domain/sandbox/log-options";
 
 /* v8 ignore next -- process exit mapping is covered through CLI subprocess log tests. */
 function exitWithSpawnResult(result: LogProbeResult) {

src/lib/sandbox-rebuild-action.ts

@@ -8,7 +8,7 @@ import { prompt as askPrompt } from "./credentials";
 import {
   normalizeRebuildSandboxOptions,
   type RebuildSandboxOptions,
-} from "./lifecycle-options";
+} from "./domain/lifecycle/options";
 
 const { hydrateCredentialEnv } = require("./onboard") as {
   hydrateCredentialEnv: (name: string) => string | null;
@@ -26,7 +26,7 @@ import * as policies from "./policies";
 import * as registry from "./registry";
 import { resolveOpenshell } from "./resolve-openshell";
 import { parseLiveSandboxNames } from "./runtime-recovery";
-import { getSandboxDeleteOutcome } from "./sandbox-destroy-helpers";
+import { getSandboxDeleteOutcome } from "./domain/sandbox/destroy";
 import { removeSandboxRegistryEntry } from "./sandbox-destroy-action";
 import { executeSandboxCommand } from "./sandbox-process-recovery-action";
 import {

src/lib/sandbox-runtime-actions.ts

@@ -3,9 +3,9 @@
 
 /* v8 ignore start -- transitional action facade until implementations leave src/nemoclaw.ts. */
 
-import type { DestroySandboxOptions, RebuildSandboxOptions } from "./lifecycle-options";
+import type { DestroySandboxOptions, RebuildSandboxOptions } from "./domain/lifecycle/options";
 import type { SandboxConnectOptions } from "./sandbox-connect-action";
-import type { SandboxLogsOptions } from "./sandbox-logs-options";
+import type { SandboxLogsOptions } from "./domain/sandbox/log-options";
 
 export async function connectSandbox(
   sandboxName: string,

src/lib/shields.ts

@@ -21,7 +21,7 @@ const {
   parseCurrentPolicy,
   PERMISSIVE_POLICY_PATH,
 } = require("./policies");
-const { parseDuration, MAX_SECONDS, DEFAULT_SECONDS } = require("./duration");
+const { parseDuration, MAX_SECONDS, DEFAULT_SECONDS } = require("./domain/duration");
 const { appendAuditEntry } = require("./shields-audit");
 const { resolveAgentConfig } = require("./sandbox-config");
 

src/lib/upgrade-sandboxes-action.ts

@@ -8,7 +8,7 @@ import { prompt as askPrompt } from "./credentials";
 import {
   normalizeUpgradeSandboxesOptions,
   type UpgradeSandboxesOptions,
-} from "./lifecycle-options";
+} from "./domain/lifecycle/options";
 import { captureOpenshell } from "./openshell-runtime";
 import * as registry from "./registry";
 import { parseLiveSandboxNames } from "./runtime-recovery";
@@ -19,7 +19,7 @@ import {
   classifyUpgradeableSandboxes,
   shouldSkipUpgradeConfirmation,
   splitRebuildableSandboxes,
-} from "./upgrade-sandboxes-helpers";
+} from "./domain/maintenance/upgrade";
 
 // ── Upgrade sandboxes (#1904) ────────────────────────────────────
 // Detect sandboxes running stale agent versions and offer to rebuild them.

test/image-cleanup.test.ts

@@ -12,8 +12,8 @@ import {
   removeSandboxImage,
   removeSandboxRegistryEntry,
 } from "../src/lib/sandbox-destroy-action";
-import { getSandboxDeleteOutcome } from "../src/lib/sandbox-destroy-helpers";
-import { normalizeGarbageCollectImagesOptions } from "../src/lib/lifecycle-options";
+import { getSandboxDeleteOutcome } from "../src/lib/domain/sandbox/destroy";
+import { normalizeGarbageCollectImagesOptions } from "../src/lib/domain/lifecycle/options";
 import { help as renderRootHelp } from "../src/lib/root-help-action";
 
 const ROOT = path.resolve(import.meta.dirname, "..");

test/shields.test.ts

@@ -76,29 +76,29 @@ describe("shields — unit logic", () => {
     // Since the CJS require resolution issue makes direct import flaky,
     // test the TypeScript duration module instead.
     it("parses minutes", async () => {
-      const { parseDuration } = await import("../src/lib/duration.js");
+      const { parseDuration } = await import("../src/lib/domain/duration.js");
       expect(parseDuration("5m")).toBe(300);
       expect(parseDuration("30m")).toBe(1800);
     });
 
     it("parses seconds", async () => {
-      const { parseDuration } = await import("../src/lib/duration.js");
+      const { parseDuration } = await import("../src/lib/domain/duration.js");
       expect(parseDuration("90s")).toBe(90);
     });
 
     it("treats bare numbers as seconds", async () => {
-      const { parseDuration } = await import("../src/lib/duration.js");
+      const { parseDuration } = await import("../src/lib/domain/duration.js");
       expect(parseDuration("300")).toBe(300);
     });
 
     it("rejects durations exceeding 30 minutes", async () => {
-      const { parseDuration } = await import("../src/lib/duration.js");
+      const { parseDuration } = await import("../src/lib/domain/duration.js");
       expect(() => parseDuration("31m")).toThrow("exceeds maximum");
       expect(() => parseDuration("1h")).toThrow("exceeds maximum");
     });
 
     it("rejects invalid input", async () => {
-      const { parseDuration } = await import("../src/lib/duration.js");
+      const { parseDuration } = await import("../src/lib/domain/duration.js");
       expect(() => parseDuration("abc")).toThrow("Invalid duration");
     });
   });