Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions src/commands/internal/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Internal commands

Hidden `nemoclaw internal ...` commands are compatibility entrypoints for repo-owned scripts and migration helpers. They are not a public API.

Keep command files thin:

```text
src/commands/internal/<area>/<verb>.ts
-> parse flags/args
-> call src/lib/actions/<area>/<verb>.ts
```

Behavior belongs in `src/lib/actions/**`, pure decisions belong in `src/lib/domain/**`, and process/filesystem/Docker/OpenShell boundaries belong in `src/lib/adapters/**`.
2 changes: 1 addition & 1 deletion src/commands/internal/dev/npm-link-or-shim.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

import { Flags } from "@oclif/core";

import { runNpmLinkOrShim } from "../../../lib/actions/dev-shim";
import { runNpmLinkOrShim } from "../../../lib/actions/dev/npm-link-or-shim";
import { NemoClawCommand } from "../../../lib/cli/nemoclaw-oclif-command";

export default class InternalDevNpmLinkOrShimCommand extends NemoClawCommand {
Expand Down
2 changes: 1 addition & 1 deletion src/commands/internal/installer/normalize-env.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

import { Command, Flags } from "@oclif/core";

import { normalizeInstallerEnv } from "../../../lib/actions/installer-plan";
import { normalizeInstallerEnv } from "../../../lib/actions/installer/plan";

export default class InternalInstallerNormalizeEnvCommand extends Command {
static hidden = true;
Expand Down
2 changes: 1 addition & 1 deletion src/commands/internal/installer/plan.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

import { Command, Flags } from "@oclif/core";

import { buildInstallerPlan } from "../../../lib/actions/installer-plan";
import { buildInstallerPlan } from "../../../lib/actions/installer/plan";

export default class InternalInstallerPlanCommand extends Command {
static hidden = true;
Expand Down
2 changes: 1 addition & 1 deletion src/commands/internal/uninstall/classify-shim.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

import { Args, Command, Flags } from "@oclif/core";

import { classifyShimPath } from "../../../lib/actions/uninstall-plan";
import { classifyShimPath } from "../../../lib/actions/uninstall/plan";

export default class InternalUninstallClassifyShimCommand extends Command {
static hidden = true;
Expand Down
2 changes: 1 addition & 1 deletion src/commands/internal/uninstall/plan.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

import { Command, Flags } from "@oclif/core";

import { buildHostUninstallPlan } from "../../../lib/actions/uninstall-plan";
import { buildHostUninstallPlan } from "../../../lib/actions/uninstall/plan";

export default class InternalUninstallPlanCommand extends Command {
static hidden = true;
Expand Down
2 changes: 1 addition & 1 deletion src/commands/internal/uninstall/run-plan.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

import { Command, Flags } from "@oclif/core";

import { runUninstallPlan } from "../../../lib/actions/uninstall-run-plan";
import { runUninstallPlan } from "../../../lib/actions/uninstall/run-plan";

export default class InternalUninstallRunPlanCommand extends Command {
static hidden = true;
Expand Down
26 changes: 26 additions & 0 deletions src/lib/actions/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Actions

Actions orchestrate CLI workflows. They may compose domain helpers, adapters, state modules, and user-facing output, but they should stay independent of oclif command classes.

Preferred layout for migrated workflows:

```text
src/lib/actions/<area>/<verb>.ts
src/lib/actions/<area>/<verb>.test.ts
```

Examples:

```text
dns/index.ts # internal dns fix-coredns/setup-proxy orchestration
dev/npm-link-or-shim.ts # prepare-time dev shim orchestration
installer/plan.ts # deterministic installer planning
uninstall/plan.ts # host uninstall planning
uninstall/run-plan.ts # uninstall plan application
sandbox/*.ts # public sandbox workflows
```

Use `src/lib/domain/**` for pure decisions and `src/lib/adapters/**` for process/filesystem/network boundaries.
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ import os from "node:os";
import path from "node:path";
import { describe, expect, it, vi } from "vitest";

import { DEV_SHIM_MARKER } from "../domain/dev-shim";
import { runNpmLinkOrShim } from "./dev-shim";
import { DEV_SHIM_MARKER } from "../../domain/dev/npm-link-or-shim";
import { runNpmLinkOrShim } from "./npm-link-or-shim";

function setupRepo(): { binPath: string; homeDir: string; repoDir: string; tmpDir: string } {
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-dev-shim-action-"));
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import {
buildDevShimContents,
classifyDevShim,
pathContainsDirectory,
} from "../domain/dev-shim";
} from "../../domain/dev/npm-link-or-shim";

export type ProcessResult = Pick<SpawnSyncReturns<string>, "stderr" | "stdout" | "status">;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@

import { describe, expect, it, vi } from "vitest";

import { runFixCoreDns, runSetupDnsProxy } from "../../../dist/lib/actions/dns.js";
import type { CommandResult } from "./dns";
import { runFixCoreDns, runSetupDnsProxy } from "../../../../dist/lib/actions/dns/index.js";
import type { CommandResult } from "./index";

function ok(stdout = ""): CommandResult {
return { status: 0, stdout, stderr: "" };
Expand Down
6 changes: 3 additions & 3 deletions src/lib/actions/dns.ts → src/lib/actions/dns/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ import fs from "node:fs";
import os from "node:os";
import path from "node:path";

import { dockerSpawnSync } from "../adapters/docker/exec";
import { dockerSpawnSync } from "../../adapters/docker/exec";
import {
buildCoreDnsPatchJson,
dockerHostRuntime,
isSafeDnsUpstream,
resolveCoreDnsUpstream,
selectOpenshellClusterContainer,
type ContainerRuntime,
} from "../domain/dns/coredns";
} from "../../domain/dns/coredns";
import {
buildDnsProxyPython,
buildDnsReadyProbePython,
Expand All @@ -24,7 +24,7 @@ import {
parseVethGateway,
selectSandboxNamespace,
selectSandboxPod,
} from "../domain/dns/setup-proxy";
} from "../../domain/dns/setup-proxy";

export type CommandResult = Pick<SpawnSyncReturns<string>, "stderr" | "stdout" | "status">;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import path from "node:path";

import { describe, expect, it } from "vitest";

import { buildInstallerPlan, normalizeInstallerEnv } from "./installer-plan";
import { buildInstallerPlan, normalizeInstallerEnv } from "./plan";

const writableState = {
exists: (targetPath: string) => targetPath !== "/missing",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@ import {
pathWithPrependedEntries,
type NpmLinkTargetState,
type NpmLinkTargetWritableResult,
} from "../domain/installer/npm";
} from "../../domain/installer/npm";
import {
installerProviderHelpValues,
normalizeInstallerProvider,
type InstallerProvider,
} from "../domain/installer/provider";
import { resolveInstallerVersion, resolveInstallRef, type InstallerRefEnv } from "../domain/installer/ref";
import { checkInstallerRuntime, type RuntimeCheckResult } from "../domain/installer/version";
} from "../../domain/installer/provider";
import { resolveInstallerVersion, resolveInstallRef, type InstallerRefEnv } from "../../domain/installer/ref";
import { checkInstallerRuntime, type RuntimeCheckResult } from "../../domain/installer/version";

export interface InstallerPlanEnv extends InstallerRefEnv {
NEMOCLAW_PROVIDER?: string | undefined;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ import os from "node:os";
import path from "node:path";
import { describe, expect, it } from "vitest";

import { buildHostUninstallPlan, classifyShimPath } from "./uninstall-plan";
import { flattenUninstallPlan } from "../domain/uninstall/plan";
import { flattenUninstallPlan } from "../../domain/uninstall/plan";
import { buildHostUninstallPlan, classifyShimPath } from "./plan";

describe("uninstall plan actions", () => {
it("classifies an on-disk dev shim", () => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@
/* v8 ignore start -- covered by source-level unit tests; CLI coverage tracks dist integration. */
import fs from "node:fs";

import { defaultUninstallPaths } from "../domain/uninstall/paths";
import { buildUninstallPlan, type UninstallPlan, type UninstallPlanOptions } from "../domain/uninstall/plan";
import { classifyNemoclawShim, type ShimClassification } from "../domain/uninstall/shims";
import { defaultUninstallPaths } from "../../domain/uninstall/paths";
import { buildUninstallPlan, type UninstallPlan, type UninstallPlanOptions } from "../../domain/uninstall/plan";
import { classifyNemoclawShim, type ShimClassification } from "../../domain/uninstall/shims";

export interface FileSystemDeps {
lstatSync?: typeof fs.lstatSync;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

import { describe, expect, it, vi } from "vitest";

import { buildRunPlan, runUninstallPlan, type RunResult } from "./uninstall-run-plan";
import { buildRunPlan, runUninstallPlan, type RunResult } from "./run-plan";

function ok(stdout = ""): RunResult {
return { status: 0, stdout, stderr: "" };
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@ import fs from "node:fs";
import os from "node:os";
import path from "node:path";

import { dockerSpawnSync } from "../adapters/docker/exec";
import { defaultUninstallPaths, NEMOCLAW_OLLAMA_MODELS, NEMOCLAW_PROVIDERS, type UninstallPaths } from "../domain/uninstall/paths";
import { buildUninstallPlan, type UninstallPlan } from "../domain/uninstall/plan";
import { classifyShimPath, type FileSystemDeps } from "./uninstall-plan";
import { dockerSpawnSync } from "../../adapters/docker/exec";
import { defaultUninstallPaths, NEMOCLAW_OLLAMA_MODELS, NEMOCLAW_PROVIDERS, type UninstallPaths } from "../../domain/uninstall/paths";
import { buildUninstallPlan, type UninstallPlan } from "../../domain/uninstall/plan";
import { classifyShimPath, type FileSystemDeps } from "./plan";

export interface RunResult {
status: number | null;
Expand Down
8 changes: 8 additions & 0 deletions src/lib/adapters/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Adapters

Adapters isolate process, filesystem, Docker, OpenShell, and other host-boundary calls from action and domain logic.

Use adapters when code needs to cross a boundary that is hard to unit test directly. Actions can depend on adapters, but domain helpers should stay pure and receive already-collected inputs.
21 changes: 21 additions & 0 deletions src/lib/domain/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# Domain helpers

Domain modules contain pure policy and decision logic. They should not import oclif, spawn processes, read host state directly, or call Docker/OpenShell.

Preferred layout:

```text
src/lib/domain/<area>/<topic>.ts
src/lib/domain/<area>/<topic>.test.ts
```

Flat files are acceptable for small cross-cutting helpers, but workflow-specific logic should live under an area directory that matches the command/action stack when practical:

```text
src/commands/internal/<area>/<verb>.ts
src/lib/actions/<area>/<verb>.ts
src/lib/domain/<area>/<topic>.ts
```
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import {
buildDevShimContents,
classifyDevShim,
pathContainsDirectory,
} from "./dev-shim";
} from "./npm-link-or-shim";

describe("dev shim domain helpers", () => {
it("classifies absent, managed, and foreign shims", () => {
Expand Down
File renamed without changes.
51 changes: 35 additions & 16 deletions src/lib/nim.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,21 @@ describe("nim", () => {
});

describe("detectGpu", () => {
function withGenericLinuxFirmware(fn: () => void): void {
const fs = require("fs");
const origReadFileSync = fs.readFileSync;
fs.readFileSync = (p: string, ...args: unknown[]) => {
if (p === "/sys/class/dmi/id/product_name") return "Generic Linux Workstation";
if (p === "/sys/firmware/devicetree/base/model") return "";
return origReadFileSync(p, ...args);
};
try {
fn();
} finally {
fs.readFileSync = origReadFileSync;
}
}

it("returns object or null", () => {
const gpu = nim.detectGpu();
if (gpu !== null) {
Expand Down Expand Up @@ -330,15 +345,17 @@ describe("nim", () => {
const { nimModule, restore } = loadNimWithMockedRunner(runCapture);

try {
expect(nimModule.detectGpu()).toMatchObject({
type: "nvidia",
name: "NVIDIA Jetson AGX Orin",
count: 1,
totalMemoryMB: 32768,
perGpuMB: 32768,
nimCapable: true,
unifiedMemory: true,
spark: false,
withGenericLinuxFirmware(() => {
expect(nimModule.detectGpu()).toMatchObject({
type: "nvidia",
name: "NVIDIA Jetson AGX Orin",
count: 1,
totalMemoryMB: 32768,
perGpuMB: 32768,
nimCapable: true,
unifiedMemory: true,
spark: false,
});
});
} finally {
restore();
Expand All @@ -356,13 +373,15 @@ describe("nim", () => {
const { nimModule, restore } = loadNimWithMockedRunner(runCapture);

try {
expect(nimModule.detectGpu()).toMatchObject({
type: "nvidia",
name: "NVIDIA Xavier",
totalMemoryMB: 4096,
nimCapable: false,
unifiedMemory: true,
spark: false,
withGenericLinuxFirmware(() => {
expect(nimModule.detectGpu()).toMatchObject({
type: "nvidia",
name: "NVIDIA Xavier",
totalMemoryMB: 4096,
nimCapable: false,
unifiedMemory: true,
spark: false,
});
});
} finally {
restore();
Expand Down
2 changes: 1 addition & 1 deletion test/npm-link-or-shim.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import os from "node:os";
import path from "node:path";
import { describe, it, expect } from "vitest";

import { DEV_SHIM_MARKER } from "../src/lib/domain/dev-shim";
import { DEV_SHIM_MARKER } from "../src/lib/domain/dev/npm-link-or-shim";

const repoRoot = path.join(import.meta.dirname, "..");
const scriptUnderTest = path.join(repoRoot, "scripts", "npm-link-or-shim.sh");
Expand Down
Loading
Loading