refactor(cli): move dev shim install behind internal command

scripts/npm-link-or-shim.sh

@@ -2,87 +2,34 @@
 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 #
-# Dev-install helper invoked by `npm install` via the package.json `prepare`
-# script. Runs `npm link` so the local checkout exposes the `nemoclaw` CLI,
-# and on failure falls back to a user-local wrapper at ~/.local/bin/nemoclaw.
-# The wrapper preserves the Node directory that was on PATH at install time
-# so the shim still works in shells where Node is provisioned via nvm and
-# may not be on a fresh login PATH (matches scripts/install.sh's wrapper).
+# Dev-install helper invoked by `npm install` via package.json `prepare`.
+# The implementation lives in TypeScript behind an internal oclif command;
+# this wrapper exists so existing prepare scripts and manual invocations keep
+# working from source checkouts.
 
 set -eu
 
-SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd -- "$SCRIPT_DIR/.." && pwd)"
-BIN_PATH="$REPO_ROOT/bin/nemoclaw.js"
-SHIM_DIR="${HOME}/.local/bin"
-SHIM_PATH="$SHIM_DIR/nemoclaw"
-SHIM_MARKER="# NemoClaw dev-shim - managed by scripts/npm-link-or-shim.sh"
-
 if [ -n "${NEMOCLAW_INSTALLING:-}" ]; then
   exit 0
 fi
-export NEMOCLAW_INSTALLING=1
-
-if [ ! -x "$BIN_PATH" ]; then
-  printf '[nemoclaw] cannot expose CLI: %s is missing or not executable\n' "$BIN_PATH" >&2
-  exit 0
-fi
-
-LINK_LOG="$(mktemp -t nemoclaw-link.XXXXXX.log 2>/dev/null || mktemp)"
-trap 'rm -f "$LINK_LOG"' EXIT
 
-if (cd "$REPO_ROOT" && npm link >"$LINK_LOG" 2>&1); then
-  exit 0
-fi
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd -- "$SCRIPT_DIR/.." && pwd)"
+CLI_JS="${NEMOCLAW_CLI_JS:-$REPO_ROOT/dist/nemoclaw.js}"
+NODE_BIN="${NEMOCLAW_NODE:-${NODE:-}}"
 
-printf '[nemoclaw] npm link failed; falling back to user-local shim.\n' >&2
-if [ -s "$LINK_LOG" ]; then
-  sed 's/^/[nemoclaw]   /' "$LINK_LOG" >&2
+if [ -z "$NODE_BIN" ]; then
+  NODE_BIN="$(command -v node 2>/dev/null || true)"
 fi
 
-NODE_PATH="$(command -v node 2>/dev/null || true)"
-if [ -z "$NODE_PATH" ] || [ ! -x "$NODE_PATH" ]; then
-  printf '[nemoclaw] cannot create shim: node is not on PATH\n' >&2
+if [ -z "$NODE_BIN" ] || [ ! -x "$NODE_BIN" ]; then
+  printf '[nemoclaw] cannot expose CLI: node is not available\n' >&2
   exit 1
 fi
-NODE_DIR="$(cd -- "$(dirname -- "$NODE_PATH")" && pwd)"
-
-if [ -e "$SHIM_PATH" ] || [ -L "$SHIM_PATH" ]; then
-  if ! grep -qFx "$SHIM_MARKER" "$SHIM_PATH" 2>/dev/null; then
-    printf '[nemoclaw] %s already exists and is not managed by NemoClaw; not overwriting.\n' "$SHIM_PATH" >&2
-    printf "[nemoclaw] Move it aside and re-run 'npm install' to install the dev shim.\n" >&2
-    exit 1
-  fi
-fi
-
-mkdir -p "$SHIM_DIR"
-
-# Write to a sibling tempfile and rename so a mid-write failure (disk full,
-# etc.) cannot leave an unrecognisable partial shim that the marker check
-# would later refuse to overwrite.
-SHIM_TMP="$(mktemp "$SHIM_DIR/nemoclaw.tmp.XXXXXX")"
-trap 'rm -f "$LINK_LOG" "$SHIM_TMP"' EXIT
 
-cat >"$SHIM_TMP" <<EOF
-#!/usr/bin/env bash
-$SHIM_MARKER
-export PATH="$NODE_DIR:\$PATH"
-exec "$BIN_PATH" "\$@"
-EOF
-chmod +x "$SHIM_TMP"
-mv -f "$SHIM_TMP" "$SHIM_PATH"
-
-if [ ! -x "$SHIM_PATH" ]; then
-  printf '[nemoclaw] shim creation failed: %s is not executable after write\n' "$SHIM_PATH" >&2
-  exit 1
+if [ ! -f "$CLI_JS" ]; then
+  printf '[nemoclaw] skipping dev shim: %s is missing. Run npm run build:cli and retry.\n' "$CLI_JS" >&2
+  exit 0
 fi
 
-printf '[nemoclaw] Created user-local shim at %s -> %s\n' "$SHIM_PATH" "$BIN_PATH" >&2
-
-case ":${PATH:-}:" in
-  *":$SHIM_DIR:"*) ;;
-  *)
-    printf '[nemoclaw] %s is not on PATH. Add it to your shell profile, e.g.:\n' "$SHIM_DIR" >&2
-    printf "[nemoclaw]   echo 'export PATH=\"%s:\$PATH\"' >> ~/.bashrc\n" "$SHIM_DIR" >&2
-    ;;
-esac
+exec "$NODE_BIN" "$CLI_JS" internal dev npm-link-or-shim --repo-root "$REPO_ROOT"

src/commands/internal/dev/npm-link-or-shim.ts

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Flags } from "@oclif/core";
+
+import { runNpmLinkOrShim } from "../../../lib/actions/dev-shim";
+import { NemoClawCommand } from "../../../lib/cli/nemoclaw-oclif-command";
+
+export default class InternalDevNpmLinkOrShimCommand extends NemoClawCommand {
+  static hidden = true;
+  static strict = true;
+  static summary = "Internal: link the checkout CLI or create a dev shim";
+  static description = "Run npm link, falling back to a user-local NemoClaw development shim.";
+  static usage = ["internal dev npm-link-or-shim [--repo-root <path>]"];
+  static examples = ["<%= config.bin %> internal dev npm-link-or-shim"];
+  static flags = {
+    help: Flags.help({ char: "h" }),
+    "repo-root": Flags.string({ description: "Repository root to expose", hidden: true }),
+  };
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(InternalDevNpmLinkOrShimCommand);
+    const result = runNpmLinkOrShim({ repoRoot: flags["repo-root"] ?? this.config.root });
+    if (result.status !== 0) process.exit(result.status);
+  }
+}

src/lib/actions/dev-shim.test.ts

@@ -0,0 +1,123 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from "node:fs";
+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";
+
+function setupRepo(): { binPath: string; homeDir: string; repoDir: string; tmpDir: string } {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-dev-shim-action-"));
+  const repoDir = path.join(tmpDir, "repo");
+  const homeDir = path.join(tmpDir, "home");
+  const binPath = path.join(repoDir, "bin", "nemoclaw.js");
+  fs.mkdirSync(path.dirname(binPath), { recursive: true });
+  fs.mkdirSync(homeDir, { recursive: true });
+  fs.writeFileSync(binPath, "#!/usr/bin/env node\n", { mode: 0o755 });
+  return { binPath, homeDir, repoDir, tmpDir };
+}
+
+function failingNpm() {
+  return vi.fn(() => ({ status: 1, stdout: "", stderr: "npm error code EACCES\n" }));
+}
+
+describe("runNpmLinkOrShim", () => {
+  it("returns without side effects during prepare recursion", () => {
+    const { homeDir, repoDir } = setupRepo();
+    const run = failingNpm();
+
+    const result = runNpmLinkOrShim({ env: { HOME: homeDir, NEMOCLAW_INSTALLING: "1" }, repoRoot: repoDir }, { run });
+
+    expect(result.status).toBe(0);
+    expect(run).not.toHaveBeenCalled();
+  });
+
+  it("does not create a shim when npm link succeeds", () => {
+    const { homeDir, repoDir } = setupRepo();
+    const result = runNpmLinkOrShim(
+      { env: { HOME: homeDir }, repoRoot: repoDir },
+      { run: () => ({ status: 0, stdout: "", stderr: "" }) },
+    );
+
+    expect(result.status).toBe(0);
+    expect(fs.existsSync(path.join(homeDir, ".local", "bin", "nemoclaw"))).toBe(false);
+  });
+
+  it("creates a managed shim after npm link fails", () => {
+    const { binPath, homeDir, repoDir } = setupRepo();
+    const errors: string[] = [];
+
+    const result = runNpmLinkOrShim(
+      { env: { HOME: homeDir, PATH: "/usr/bin" }, repoRoot: repoDir },
+      {
+        commandPath: () => process.execPath,
+        logError: (message) => errors.push(message),
+        run: failingNpm(),
+      },
+    );
+
+    const shimPath = path.join(homeDir, ".local", "bin", "nemoclaw");
+    expect(result.status).toBe(0);
+    expect(fs.existsSync(shimPath)).toBe(true);
+    expect((fs.statSync(shimPath).mode & 0o111) !== 0).toBe(true);
+    const shim = fs.readFileSync(shimPath, "utf-8");
+    expect(shim).toContain(DEV_SHIM_MARKER);
+    expect(shim).toContain(`exec "${binPath}" "$@"`);
+    expect(errors.join("\n")).toContain("npm link failed");
+    expect(errors.join("\n")).toContain("Created user-local shim");
+  });
+
+  it("refuses to overwrite a foreign shim", () => {
+    const { homeDir, repoDir } = setupRepo();
+    const shimPath = path.join(homeDir, ".local", "bin", "nemoclaw");
+    fs.mkdirSync(path.dirname(shimPath), { recursive: true });
+    fs.writeFileSync(shimPath, "user-script\n", { mode: 0o755 });
+    const errors: string[] = [];
+
+    const result = runNpmLinkOrShim(
+      { env: { HOME: homeDir }, repoRoot: repoDir },
+      { commandPath: () => process.execPath, logError: (message) => errors.push(message), run: failingNpm() },
+    );
+
+    expect(result.status).toBe(1);
+    expect(fs.readFileSync(shimPath, "utf-8")).toBe("user-script\n");
+    expect(errors.join("\n")).toContain("not managed by NemoClaw");
+  });
+
+  it("refreshes an existing managed shim", () => {
+    const { binPath, homeDir, repoDir } = setupRepo();
+    const shimPath = path.join(homeDir, ".local", "bin", "nemoclaw");
+    fs.mkdirSync(path.dirname(shimPath), { recursive: true });
+    fs.writeFileSync(shimPath, `#!/usr/bin/env bash\n${DEV_SHIM_MARKER}\nexec /old/stale "$@"\n`, {
+      mode: 0o755,
+    });
+
+    const result = runNpmLinkOrShim(
+      { env: { HOME: homeDir }, repoRoot: repoDir },
+      { commandPath: () => process.execPath, logError: vi.fn(), run: failingNpm() },
+    );
+
+    expect(result.status).toBe(0);
+    const refreshed = fs.readFileSync(shimPath, "utf-8");
+    expect(refreshed).toContain(`exec "${binPath}" "$@"`);
+    expect(refreshed).not.toContain("/old/stale");
+  });
+
+  it("fails clearly when the shim directory cannot be created", () => {
+    const { homeDir, repoDir } = setupRepo();
+    fs.writeFileSync(path.join(homeDir, ".local"), "not-a-directory\n");
+    const errors: string[] = [];
+
+    const result = runNpmLinkOrShim(
+      { env: { HOME: homeDir }, repoRoot: repoDir },
+      { commandPath: () => process.execPath, logError: (message) => errors.push(message), run: failingNpm() },
+    );
+
+    expect(result.status).toBe(1);
+    expect(errors.join("\n")).toContain("shim creation failed");
+    expect(fs.readFileSync(path.join(homeDir, ".local"), "utf-8")).toBe("not-a-directory\n");
+  });
+});