@blackbelt-technology/pi-agent-dashboard 0.4.0 → 0.4.1

package/packages/shared/src/__tests__/no-hardcoded-node-modules-paths.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Repo-level invariant: build-time scripts (CI workflows, Dockerfiles,
+ * shell scripts, root-level CJS helpers) MUST NOT hardcode
+ * `node_modules/electron` or `node_modules/node-pty` paths. Instead, they
+ * MUST resolve through the tool registry — either via the shared shell
+ * wrapper at `packages/shared/bin/pi-dashboard-resolve-tool.cjs`, or
+ * (for postinstall paths that run before the shared package is built)
+ * via `require.resolve("<pkg>/package.json")` matching the registry's
+ * `bare-import` strategy semantics.
+ *
+ * This invariant exists because npm workspace hoisting moves these
+ * packages between `packages/<workspace>/node_modules/<pkg>/` (nested)
+ * and `<repoRoot>/node_modules/<pkg>/` (hoisted) depending on the
+ * workspaces config and npm version. The v0.4.0 release crisis was
+ * caused exactly by this: `cd packages/electron/node_modules/electron`
+ * stopped working after `f51e352` switched workspace cross-refs to
+ * plain semver.
+ *
+ * If this test fails, replace the offending substring with one of:
+ *
+ *   # Shell / YAML / Dockerfile (build-time, has access to repo source):
+ *   ELECTRON_DIR=$(node packages/shared/bin/pi-dashboard-resolve-tool.cjs electron)
+ *   cd "$ELECTRON_DIR" && ...
+ *
+ *   # CJS root postinstall (runs DURING npm install — must inline):
+ *   const ptyPkg = require.resolve("node-pty/package.json");
+ *   const prebuildsDir = path.join(path.dirname(ptyPkg), "prebuilds");
+ *
+ * See change: register-build-time-tools.
+ */
+import { describe, expect, it } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import url from "node:url";
+
+/** Banned substrings (after comment-stripping). */
+const PATTERNS: readonly { re: RegExp; suggestion: string }[] = [
+  {
+    re: /node_modules\/electron(?:\/|\b)/,
+    suggestion:
+      "Use `node packages/shared/bin/pi-dashboard-resolve-tool.cjs electron`",
+  },
+  {
+    re: /node_modules\/node-pty(?:\/|\b)/,
+    suggestion:
+      'Use `require.resolve("node-pty/package.json")` (mirrors the registry\'s bare-import strategy)',
+  },
+];
+
+/**
+ * Files explicitly allowed to contain the banned substrings. Each entry
+ * is a repo-relative path matched exactly. Add an entry only when the
+ * substring appears as a non-path token (e.g. an argument to
+ * `require.resolve`, a comment quoting an example, or this lint file
+ * itself). Document the reason inline.
+ */
+const ALLOWLIST: readonly string[] = [
+  // The lint file itself contains every banned substring as test data.
+  "packages/shared/src/__tests__/no-hardcoded-node-modules-paths.test.ts",
+  // Root postinstall — uses `require.resolve("node-pty/package.json")`,
+  // which contains "node-pty" as an argument string but not as a
+  // hardcoded path. Allowlisted because it must run before the shared
+  // package is unpacked. See file header for full reasoning.
+  "scripts/fix-pty-permissions.cjs",
+  // Sister postinstall script (workspace-scoped) — same rationale.
+  "packages/server/scripts/fix-pty-permissions.cjs",
+];
+
+/**
+ * Repo-relative file list to scan.
+ *
+ * The scope is intentionally narrow: only the build-time sites that the
+ * `register-build-time-tools` change migrated, plus the postinstall
+ * scripts that mirror the registry's `bare-import` semantics. Bundle /
+ * Docker entrypoint scripts (`bundle-server.sh`, `docker-make.sh`,
+ * `test-electron-install-inner.sh`, etc.) are NOT in scope: those
+ * operate on a known WORKDIR with deterministic node_modules layout
+ * inside the build image and are not affected by host-side hoisting.
+ */
+const SCAN_FILES: readonly string[] = [
+  ".github/workflows/publish.yml",
+  ".github/workflows/ci.yml",
+  "packages/electron/scripts/Dockerfile.build",
+  "scripts/fix-pty-permissions.cjs",
+  "packages/server/scripts/fix-pty-permissions.cjs",
+];
+
+interface Violation {
+  file: string;
+  line: number;
+  col: number;
+  text: string;
+  suggestion: string;
+}
+
+/**
+ * Strip a single line's trailing comment for YAML / shell / JS-style
+ * line comments. Preserves substring matches inside strings as actual
+ * content (we don't try to parse string literals — keeping it simple).
+ *
+ * Specifically:
+ *   - `# ...` (YAML, shell): everything from a `#` not preceded by a
+ *     non-space alphanumeric is dropped. Matches GitHub Actions /
+ *     bash conventions.
+ *   - `// ...` (JS): everything from `//` to end of line is dropped.
+ *
+ * This is intentionally simple. False positives only matter if a banned
+ * pattern appears INSIDE a string literal (which would still be the
+ * bug we want to catch); false negatives only matter for inline
+ * comments (`echo foo  # comment node_modules/electron`), which we
+ * exclude correctly.
+ */
+function stripLineComment(line: string): string {
+  // JS-style first.
+  const jsIdx = line.indexOf("//");
+  if (jsIdx >= 0) line = line.slice(0, jsIdx);
+  // Shell/YAML `#` — only when preceded by whitespace or start-of-line.
+  const hashMatch = line.match(/(^|\s)#/);
+  if (hashMatch && typeof hashMatch.index === "number") {
+    line = line.slice(0, hashMatch.index);
+  }
+  return line;
+}
+
+describe("no hardcoded node_modules/<dep> paths in build-time files", () => {
+  it("only allowlisted files reference node_modules/electron or node_modules/node-pty", () => {
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(here, "..", "..", "..", "..");
+
+    const violations: Violation[] = [];
+    const allowSet = new Set(
+      ALLOWLIST.map((p) => path.resolve(repoRoot, p).replace(/\\/g, "/")),
+    );
+
+    for (const rel of SCAN_FILES) {
+      const file = path.resolve(repoRoot, rel);
+      if (!fs.existsSync(file)) continue;
+      const normalized = file.replace(/\\/g, "/");
+      if (allowSet.has(normalized)) continue;
+
+      const content = fs.readFileSync(file, "utf-8");
+      const lines = content.split(/\r?\n/);
+
+      lines.forEach((rawLine, idx) => {
+        const stripped = stripLineComment(rawLine);
+        for (const { re, suggestion } of PATTERNS) {
+          const m = stripped.match(re);
+          if (!m) continue;
+          const col = rawLine.indexOf(m[0]);
+          violations.push({
+            file: path.relative(repoRoot, file),
+            line: idx + 1,
+            col: col >= 0 ? col + 1 : 1,
+            text: rawLine.trim(),
+            suggestion,
+          });
+        }
+      });
+    }
+
+    if (violations.length > 0) {
+      const msg =
+        `Hardcoded \`node_modules/<dep>\` path(s) found in build-time files.\n` +
+        `These break under npm workspace hoisting changes (see v0.4.0 release crisis).\n` +
+        `Use the tool registry instead. See change: register-build-time-tools.\n\n` +
+        `Offenders (${violations.length}):\n` +
+        violations
+          .map(
+            (v) =>
+              `  ${v.file}:${v.line}:${v.col}  ${v.text}\n      → ${v.suggestion}`,
+          )
+          .join("\n");
+      expect(violations, msg).toEqual([]);
+    }
+  });
+});

package/packages/shared/src/__tests__/no-raw-node-import.test.ts

@@ -0,0 +1,146 @@
+/**
+ * Repo-level invariant: any source file that passes an argv to Node
+ * with `--import` or `--loader` MUST wrap the following positions
+ * (loader and entry script) in `file://` URLs via `toFileUrl(...)` or
+ * `pathToFileURL(...).href`. Raw OS paths on Windows drives whose
+ * letter collides with URL-scheme parsing (e.g. `B:\`) crash Node with
+ * `ERR_UNSUPPORTED_ESM_URL_SCHEME`.
+ *
+ * If this test fails, migrate the offending file to use
+ * `spawnNodeScript` or wrap the entry/loader with `toFileUrl` from
+ * `@blackbelt-technology/pi-dashboard-shared/platform/node-spawn.js`.
+ *
+ * See change: fix-windows-entry-script-url.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import url from "node:url";
+
+/** Files allowed to reference --import / --loader with raw identifiers. */
+const ALLOWLIST: readonly string[] = [
+  "packages/shared/src/platform/node-spawn.ts",
+  // resolve-jiti.ts returns a file:// URL to callers; it does not itself
+  // build a `["--import", X, Y]` argv. Allowlisted as the documented
+  // source of loader URLs referenced in server spawn call sites.
+  "packages/shared/src/resolve-jiti.ts",
+];
+
+/** Per-line opt-out for intentional usages (e.g. comment examples). */
+const OPT_OUT_MARKER = "ban:raw-node-import-ok";
+
+/**
+ * Detect argv arrays containing `"--import"` or `"--loader"` followed by
+ * a bare identifier (not a string literal and not a wrapped call).
+ *
+ * We match the argv-literal shape:
+ *   ["--import", X, Y]
+ *   args: ["--import", X, Y, ...]
+ *
+ * Then check that both X and Y are either:
+ *   - a string literal starting with "file:" (already a URL)
+ *   - a call expression to toFileUrl(...) or pathToFileURL(...).href
+ *   - the identifier resolveJitiImport() / resolveJitiFromAnchor() (which
+ *     are documented to return file:// URLs — allowlisted by name)
+ *
+ * Anything else is flagged.
+ */
+const IMPORT_ARGV_RE =
+  /["']--(?:import|loader)["']\s*,\s*([^,\]]+?)\s*,\s*([^,\]]+?)(?:\s*,|\s*\])/g;
+
+const URL_LOOKING_RE =
+  /^(?:["']file:|toFileUrl\s*\(|pathToFileURL\s*\([^)]*\)\s*\.href|resolveJitiImport\s*\(|resolveJitiFromAnchor\s*\()/;
+
+/** Recursively walk a directory, yielding .ts / .tsx files. */
+async function* walk(dir: string): AsyncGenerator<string> {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === "__tests__") continue;
+      yield* walk(full);
+    } else if (entry.isFile() && /\.(ts|tsx|mts|cts)$/.test(entry.name)) {
+      yield full;
+    }
+  }
+}
+
+describe("no raw paths passed to node --import / --loader", () => {
+  it("only URL-wrapped or allowlisted argv positions follow --import / --loader", async () => {
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(here, "..", "..", "..", "..");
+    const packagesDir = path.resolve(repoRoot, "packages");
+
+    const allowSet = new Set(
+      ALLOWLIST.map((p) => path.resolve(repoRoot, p).replace(/\\/g, "/")),
+    );
+
+    const violations: Array<{ file: string; line: number; text: string }> = [];
+
+    for (const pkg of await fs.readdir(packagesDir, { withFileTypes: true })) {
+      if (!pkg.isDirectory()) continue;
+      const srcDir = path.join(packagesDir, pkg.name, "src");
+      try {
+        await fs.access(srcDir);
+      } catch {
+        continue;
+      }
+      for await (const file of walk(srcDir)) {
+        const normalized = file.replace(/\\/g, "/");
+        if (allowSet.has(normalized)) continue;
+
+        const content = await fs.readFile(file, "utf-8");
+        const lines = content.split(/\r?\n/);
+
+        // Walk each line and check for the argv pattern. Track byte
+        // offsets so we can compute line numbers for multi-line matches.
+        let offset = 0;
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i]!;
+          // Fast path: only inspect lines that mention --import or --loader.
+          if (!line.includes("--import") && !line.includes("--loader")) {
+            offset += line.length + 1;
+            continue;
+          }
+          if (line.includes(OPT_OUT_MARKER)) {
+            offset += line.length + 1;
+            continue;
+          }
+          // Check the current line alone (we allow argv to be on one line;
+          // multi-line argv arrays are a rare style and would still trip
+          // the quick search above).
+          IMPORT_ARGV_RE.lastIndex = 0;
+          let m: RegExpExecArray | null;
+          while ((m = IMPORT_ARGV_RE.exec(line)) !== null) {
+            const loaderArg = m[1]!.trim();
+            const entryArg = m[2]!.trim();
+            const loaderOk = URL_LOOKING_RE.test(loaderArg);
+            const entryOk = URL_LOOKING_RE.test(entryArg);
+            if (!loaderOk || !entryOk) {
+              violations.push({
+                file: path.relative(repoRoot, file),
+                line: i + 1,
+                text: line.trim(),
+              });
+            }
+          }
+          offset += line.length + 1;
+        }
+      }
+    }
+
+    if (violations.length > 0) {
+      const msg =
+        `Raw filesystem paths passed to node --import / --loader found.\n` +
+        `Migrate each call site to use spawnNodeScript() or wrap the\n` +
+        `loader/entry with toFileUrl(...) from:\n` +
+        `  import { toFileUrl, spawnNodeScript } from\n` +
+        `    "@blackbelt-technology/pi-dashboard-shared/platform/node-spawn.js";\n\n` +
+        `Offenders (${violations.length}):\n` +
+        violations
+          .map((v) => `  ${v.file}:${v.line}  ${v.text}`)
+          .join("\n");
+      expect(violations, msg).toEqual([]);
+    }
+  });
+});

package/packages/shared/src/__tests__/node-spawn.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Tests for `platform/node-spawn.ts` — the canonical helper for
+ * constructing `node --import <loader> <entry>` argv.
+ *
+ * See change: fix-windows-entry-script-url.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { toFileUrl, spawnNodeScript, isTsxLoader, shouldUrlWrapEntry } from "../platform/node-spawn.js";
+import * as execModule from "../platform/exec.js";
+
+describe("toFileUrl", () => {
+  it("returns a file:// URL input unchanged (idempotent)", () => {
+    expect(toFileUrl("file:///C:/foo.ts")).toBe("file:///C:/foo.ts");
+    expect(toFileUrl("file:///usr/local/bin/cli.js")).toBe("file:///usr/local/bin/cli.js");
+  });
+
+  it("wraps Windows B:\\ drive-letter paths on any host OS", () => {
+    expect(toFileUrl("B:\\Dev\\cli.ts")).toBe("file:///B:/Dev/cli.ts");
+  });
+
+  it("wraps Windows C:\\ drive-letter paths on any host OS", () => {
+    expect(toFileUrl("C:\\Users\\x\\cli.ts")).toBe("file:///C:/Users/x/cli.ts");
+  });
+
+  it("wraps forward-slash Windows paths", () => {
+    expect(toFileUrl("B:/Dev/cli.ts")).toBe("file:///B:/Dev/cli.ts");
+  });
+
+  it("wraps POSIX absolute paths", () => {
+    expect(toFileUrl("/usr/local/bin/cli.js")).toBe("file:///usr/local/bin/cli.js");
+  });
+
+  it("handles uppercase and lowercase drive letters identically", () => {
+    expect(toFileUrl("b:\\Dev\\cli.ts")).toBe("file:///b:/Dev/cli.ts");
+    expect(toFileUrl("Z:\\foo.ts")).toBe("file:///Z:/foo.ts");
+  });
+});
+
+describe("isTsxLoader", () => {
+  it("returns true for loader URLs containing /tsx/", () => {
+    expect(isTsxLoader("file:///home/x/node_modules/tsx/dist/esm/index.mjs")).toBe(true);
+    expect(isTsxLoader("file:///C:/project/node_modules/tsx/dist/esm/index.mjs")).toBe(true);
+  });
+
+  it("returns true for raw paths with /tsx/ segment", () => {
+    expect(isTsxLoader("/home/x/node_modules/tsx/dist/esm/index.mjs")).toBe(true);
+  });
+
+  it("returns true for Windows raw paths with \\tsx\\ segment", () => {
+    expect(isTsxLoader("C:\\project\\node_modules\\tsx\\dist\\esm\\index.mjs")).toBe(true);
+  });
+
+  it("returns false for jiti loader", () => {
+    expect(isTsxLoader("file:///home/x/node_modules/@mariozechner/jiti/lib/jiti-register.mjs")).toBe(false);
+    expect(isTsxLoader("/home/x/node_modules/@mariozechner/jiti/lib/jiti-register.mjs")).toBe(false);
+  });
+
+  it("returns false for undefined / empty", () => {
+    expect(isTsxLoader(undefined)).toBe(false);
+    expect(isTsxLoader("")).toBe(false);
+  });
+});
+
+describe("spawnNodeScript", () => {
+  it("URL-wraps both loader and entry when loader is NOT tsx (jiti/default)", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    spawnNodeScript({
+      nodeBin: "C:\\Program Files\\nodejs\\node.exe",
+      loader: "B:\\jiti\\register.mjs",
+      entry: "B:\\Dev\\cli.ts",
+      args: ["start", "--dev"],
+    });
+
+    expect(spawnSpy).toHaveBeenCalledTimes(1);
+    const [bin, argv] = spawnSpy.mock.calls[0]!;
+    expect(bin).toBe("C:\\Program Files\\nodejs\\node.exe");
+    // On Linux host: entry stays raw even with a Windows-styled path
+    // (shouldUrlWrapEntry consults process.platform, which is Linux).
+    // The Windows-wrapped branch is exercised separately via shouldUrlWrapEntry.
+    expect(argv).toEqual([
+      "--import",
+      "file:///B:/jiti/register.mjs",
+      "B:\\Dev\\cli.ts",
+      "start",
+      "--dev",
+    ]);
+
+    spawnSpy.mockRestore();
+  });
+
+  it("URL-wraps loader but passes RAW entry when loader is tsx", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    spawnNodeScript({
+      nodeBin: "/usr/bin/node",
+      loader: "/home/u/node_modules/tsx/dist/esm/index.mjs",
+      entry: "/home/u/repo/packages/server/src/cli.ts",
+      args: ["start"],
+    });
+
+    const [, argv] = spawnSpy.mock.calls[0]!;
+    expect(argv).toEqual([
+      "--import",
+      "file:///home/u/node_modules/tsx/dist/esm/index.mjs",
+      "/home/u/repo/packages/server/src/cli.ts",  // RAW, not URL
+      "start",
+    ]);
+    spawnSpy.mockRestore();
+  });
+
+  it("defaults nodeBin to process.execPath when omitted", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    spawnNodeScript({
+      entry: "/usr/local/cli.ts",
+    });
+
+    const [bin] = spawnSpy.mock.calls[0]!;
+    expect(bin).toBe(process.execPath);
+    spawnSpy.mockRestore();
+  });
+
+  it("omits --import when no loader is provided", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    spawnNodeScript({
+      entry: "B:\\Dev\\cli.ts",
+      args: ["help"],
+    });
+
+    const [, argv] = spawnSpy.mock.calls[0]!;
+    // No loader → shouldUrlWrapEntry returns false on Linux host → raw entry.
+    expect(argv).toEqual(["B:\\Dev\\cli.ts", "help"]);
+    spawnSpy.mockRestore();
+  });
+
+  it("passes spawnOptions through to exec.spawn unchanged", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    const opts = { detached: true, stdio: ["ignore", 1, 2] as ("ignore" | number)[], env: { FOO: "bar" } };
+    spawnNodeScript({
+      entry: "/usr/local/cli.ts",
+      spawnOptions: opts,
+    });
+
+    const [, , passedOpts] = spawnSpy.mock.calls[0]!;
+    expect(passedOpts).toBe(opts);
+    spawnSpy.mockRestore();
+  });
+
+  it("accepts a loader that is already a file:// URL without double-wrapping", () => {
+    const spawnSpy = vi
+      .spyOn(execModule, "spawn")
+      .mockImplementation(() => ({ unref: () => {} } as unknown as ReturnType<typeof execModule.spawn>));
+
+    spawnNodeScript({
+      loader: "file:///C:/jiti/register.mjs",
+      entry: "B:\\Dev\\cli.ts",
+    });
+
+    const [, argv] = spawnSpy.mock.calls[0]!;
+    // On Linux host with non-tsx loader: entry stays raw.
+    expect(argv).toEqual([
+      "--import",
+      "file:///C:/jiti/register.mjs",
+      "B:\\Dev\\cli.ts",
+    ]);
+    spawnSpy.mockRestore();
+  });
+});
+
+describe("shouldUrlWrapEntry", () => {
+  it("returns false for tsx loader on any platform", () => {
+    const tsxLoader = "file:///home/u/node_modules/tsx/dist/esm/index.mjs";
+    expect(shouldUrlWrapEntry(tsxLoader, "linux")).toBe(false);
+    expect(shouldUrlWrapEntry(tsxLoader, "darwin")).toBe(false);
+    expect(shouldUrlWrapEntry(tsxLoader, "win32")).toBe(false);
+  });
+
+  it("returns false for non-tsx loader on POSIX (jiti MUST get raw entry)", () => {
+    const jiti = "file:///home/u/node_modules/@mariozechner/jiti/lib/jiti-register.mjs";
+    expect(shouldUrlWrapEntry(jiti, "linux")).toBe(false);
+    expect(shouldUrlWrapEntry(jiti, "darwin")).toBe(false);
+  });
+
+  it("returns true for non-tsx loader on Windows (drive letters need file://)", () => {
+    const jiti = "file:///C:/node_modules/@mariozechner/jiti/lib/jiti-register.mjs";
+    expect(shouldUrlWrapEntry(jiti, "win32")).toBe(true);
+  });
+
+  it("returns false when no loader is provided, regardless of platform", () => {
+    // Without a loader, Node's default resolver handles the entry; the URL
+    // wrap was historically used for Windows drive-letter collision, but
+    // if we were to spawn without a loader we'd still default to raw on POSIX.
+    // On Windows without a loader, callers should wrap themselves.
+    expect(shouldUrlWrapEntry(undefined, "linux")).toBe(false);
+    expect(shouldUrlWrapEntry(undefined, "darwin")).toBe(false);
+  });
+});

package/packages/shared/src/__tests__/resolve-tool-cli.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Unit tests for the shell-callable resolver wrapper at
+ * `packages/shared/bin/pi-dashboard-resolve-tool.cjs`.
+ *
+ * We spawn the wrapper as a child process (matching its real-world use)
+ * and assert stdout/stderr/exit-code per the spec scenarios in
+ *   openspec/changes/register-build-time-tools/specs/tool-registry/spec.md
+ *
+ * See change: register-build-time-tools.
+ */
+import { describe, expect, it } from "vitest";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import url from "node:url";
+
+const here = path.dirname(url.fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, "..", "..", "..", "..");
+const SCRIPT = path.join(
+  repoRoot,
+  "packages",
+  "shared",
+  "bin",
+  "pi-dashboard-resolve-tool.cjs",
+);
+
+function run(args: string[]) {
+  return spawnSync(process.execPath, [SCRIPT, ...args], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    // Isolate from any user override file so tests are deterministic.
+    env: {
+      ...process.env,
+      // Point HOME at /tmp so ~/.pi/dashboard/tool-overrides.json is
+      // (almost certainly) absent, keeping the resolver in the
+      // bare-import branch.
+      HOME: "/tmp/pi-dashboard-resolve-tool-test",
+    },
+  });
+}
+
+describe("pi-dashboard-resolve-tool.cjs", () => {
+  it("prints absolute path to stdout for `electron`", () => {
+    const r = run(["electron"]);
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toMatch(/[\\/]node_modules[\\/]electron$/);
+    expect(r.stderr).toBe("");
+  });
+
+  it("prints absolute path to stdout for `node-pty`", () => {
+    const r = run(["node-pty"]);
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toMatch(/[\\/]node_modules[\\/]node-pty$/);
+    expect(r.stderr).toBe("");
+  });
+
+  it("emits JSON Resolution shape with --json", () => {
+    const r = run(["electron", "--json"]);
+    expect(r.status).toBe(0);
+    const parsed = JSON.parse(r.stdout);
+    expect(parsed.name).toBe("electron");
+    expect(parsed.ok).toBe(true);
+    expect(parsed.path).toMatch(/electron$/);
+    expect(parsed.source).toBe("bare-import");
+    expect(Array.isArray(parsed.tried)).toBe(true);
+    // First strategy attempted is `override`, then `bare-import`.
+    expect(parsed.tried.map((t: { strategy: string }) => t.strategy)).toEqual([
+      "override",
+      "bare-import",
+    ]);
+    expect(typeof parsed.resolvedAt).toBe("number");
+  });
+
+  it("exits 1 with stderr when tool name is unknown", () => {
+    const r = run(["nonexistent-tool"]);
+    expect(r.status).toBe(1);
+    expect(r.stdout).toBe("");
+    expect(r.stderr).toContain("nonexistent-tool");
+    expect(r.stderr).toContain("not registered");
+  });
+
+  it("exits 1 with stderr when --json is passed for unknown tool", () => {
+    const r = run(["nonexistent-tool", "--json"]);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain("not registered");
+  });
+
+  it("exits 1 with usage message when no tool name given", () => {
+    const r = run([]);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain("usage:");
+    expect(r.stderr).toContain("registered:");
+  });
+
+  it("strategy chain order in --json mirrors definitions.ts", () => {
+    // Both build-time tools share the same chain shape: override → bare-import.
+    for (const tool of ["electron", "node-pty"]) {
+      const r = run([tool, "--json"]);
+      expect(r.status).toBe(0);
+      const parsed = JSON.parse(r.stdout);
+      expect(
+        parsed.tried.map((t: { strategy: string }) => t.strategy),
+      ).toEqual(["override", "bare-import"]);
+    }
+  });
+});