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

package/packages/shared/src/__tests__/no-direct-platform-branch.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Repo-level invariant: `process.platform === "<os>"` branches (and the
+ * inverse `!==` form) MUST NOT appear outside the canonical platform
+ * primitive locations. All OS-specific behaviour lives under
+ * `packages/shared/src/platform/**` (and `packages/electron/src/platform/**`
+ * for Electron-specific primitives) plus a small documented allowlist.
+ *
+ * If this test fails, either:
+ *   (a) Move the platform-aware logic into a platform/* primitive that
+ *       takes an optional `platform: NodeJS.Platform` parameter, OR
+ *   (b) Add an opt-out marker `// platform-branch-ok` on the same line
+ *       for a genuine, localised OS probe (e.g. a top-level env fingerprint).
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import url from "node:url";
+
+/**
+ * Files / directory-prefixes where platform branches are allowed.
+ *
+ * Each entry is a repo-relative path using forward slashes. Entries
+ * ending in `/` match any file under that directory (prefix match);
+ * entries without a trailing slash must match exactly.
+ *
+ * Every entry has a one-line reason and a follow-up owner.
+ */
+const ALLOWLIST: readonly string[] = [
+  // Canonical platform primitives — the whole POINT is platform branching.
+  "packages/shared/src/platform/",
+  // Electron-specific platform primitives.
+  "packages/electron/src/platform/",
+
+  // ── Seed allowlist (documented follow-ups, out of scope for this change)
+
+  // Extension's pgid/ps scanner — platform-aware but uses `_platform` test
+  // hooks rather than shared primitives; consolidating into
+  // shared/platform/process-scan.ts is a separate change.
+  "packages/extension/src/process-scanner.ts",
+
+  // Electron dependency detection predates the tool-registry; migration
+  // to ToolRegistry.resolve is a separate change.
+  "packages/electron/src/lib/dependency-detector.ts",
+
+  // Electron top-level bootstrap: process.platform printed in log output,
+  // legitimate observability use.
+  "packages/electron/src/main.ts",
+
+  // Electron doctor: reports process.platform to the user.
+  "packages/electron/src/lib/doctor.ts",
+
+  // Electron forge config: build-time darwin special-case.
+  "packages/electron/forge.config.ts",
+
+  // Server process-manager: one domain branch in spawnHeadless picking
+  // Unix "sh -c tail -f" wrapper vs Windows direct node.exe spawn.
+  // The wrapper is genuinely Unix-only (sh+tail); splitting the headless
+  // mechanism into two is tracked as a follow-up.
+  "packages/server/src/process-manager.ts",
+
+  // Server editor registry: selects per-OS process patterns from a data
+  // table. Genuine data-lookup branching, benign.
+  "packages/server/src/editor-registry.ts",
+
+  // Server tunnel: surfaces process.platform in a response body.
+  "packages/server/src/tunnel.ts",
+
+  // Server browse: returns process.platform in BrowseResult for the
+  // client path-picker (protocol surface).
+  "packages/server/src/browse.ts",
+
+  // Client session-grouping: reads process.platform in a comment-only
+  // doc reference and uses inferPlatform heuristic; no actual branch.
+  "packages/client/src/lib/session-grouping.ts",
+
+  // ── Follow-up: migrate to electron/src/platform/ per deferred
+  // consolidate-platform-handlers (18→13 file refactor).
+
+  // App menu: darwin detection for role:appMenu (Electron convention).
+  "packages/electron/src/lib/app-menu.ts",
+  // Bundled node: win32 binary name suffix; data-lookup branch.
+  "packages/electron/src/lib/bundled-node.ts",
+  // Server lifecycle: win32 managed-tsx.cmd + which/where probes.
+  "packages/electron/src/lib/server-lifecycle.ts",
+  // Tray icon: platform-specific asset selection; will move to
+  // electron/src/platform/tray-icon.ts in deferred consolidation.
+  "packages/electron/src/lib/tray.ts",
+
+  // Server editor PID registry: per-OS process pattern matching for
+  // orphan detection on boot. Genuine data-table branching.
+  "packages/server/src/editor-pid-registry.ts",
+  // Electron dependency installer: Windows npm is npm.cmd (batch wrapper);
+  // spawn('npm') without .cmd extension fails ENOENT on Windows. The branch
+  // routes around this by preferring bundled node+npm-cli.js on Windows.
+  // Follow-up: migrate to a platform/exec npm-resolver primitive.
+  "packages/electron/src/lib/dependency-installer.ts",
+  // fix-pty-permissions: Windows short-circuit (no chmod needed).
+  "packages/server/src/fix-pty-permissions.ts",
+  // package-manager-wrapper: comment-only reference; no runtime branch.
+  "packages/server/src/package-manager-wrapper.ts",
+  // terminal-manager: win32 branch for node-pty spawnOptions; will move
+  // to platform/terminal in deferred consolidation.
+  "packages/server/src/terminal-manager.ts",
+];
+
+const PLATFORM_BRANCH_RE = /process\.platform\s*(===|!==)\s*["'](win32|linux|darwin)["']/;
+
+const OPT_OUT_MARKER = "platform-branch-ok";
+
+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;
+    }
+  }
+}
+
+/** Check if a repo-relative normalised path is covered by the allowlist. */
+function isAllowed(relPath: string, allow: readonly string[]): boolean {
+  for (const entry of allow) {
+    if (entry.endsWith("/")) {
+      if (relPath.startsWith(entry)) return true;
+    } else {
+      if (relPath === entry) return true;
+    }
+  }
+  return false;
+}
+
+describe("no direct process.platform branches outside platform/**", () => {
+  it("only allowlisted files contain process.platform === \"<os>\" branches", async () => {
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(here, "..", "..", "..", "..");
+    const packagesDir = path.resolve(repoRoot, "packages");
+
+    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 relPath = path.relative(repoRoot, file).replace(/\\/g, "/");
+        if (isAllowed(relPath, ALLOWLIST)) continue;
+
+        const content = await fs.readFile(file, "utf-8");
+        const lines = content.split(/\r?\n/);
+        lines.forEach((line, idx) => {
+          if (!PLATFORM_BRANCH_RE.test(line)) return;
+          if (line.includes(OPT_OUT_MARKER)) return;
+          violations.push({ file: relPath, line: idx + 1, text: line.trim() });
+        });
+      }
+    }
+
+    if (violations.length > 0) {
+      const msg =
+        `Direct process.platform branches found outside the allowlist.\n` +
+        `Move the logic into a platform/* primitive or add a ` +
+        `\`// ${OPT_OUT_MARKER}\` comment on the line with a justification.\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__/no-direct-process-kill.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Repo-level invariant: `process.kill(...)` MUST NOT be called directly
+ * outside `packages/shared/src/platform/`. All termination / liveness must
+ * go through the platform helpers (`isProcessAlive`, `killProcess`,
+ * `killPidWithGroup`) so that Windows tree-kill (taskkill /F /T /PID) and
+ * POSIX process-group semantics are applied uniformly.
+ *
+ * If this test fails, migrate the offending file's call to:
+ *   import { isProcessAlive, killProcess, killPidWithGroup }
+ *     from "@blackbelt-technology/pi-dashboard-shared/platform/process.js";
+ *
+ * See change: route-kill-paths-through-platform.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import url from "node:url";
+
+/** Files or directories allowed to call `process.kill(...)` directly. */
+const ALLOWLIST_DIRS: readonly string[] = [
+  "packages/shared/src/platform",
+];
+
+/**
+ * Regex catches any textual reference to `process.kill(...)`. We match on
+ * whole-word `process` to avoid flagging `childProcess.kill(...)`, which
+ * is the `ChildProcess#kill()` instance method, not the global
+ * `process.kill`. Calls on `ChildProcess` instances are banned separately
+ * via code review / type-guided refactors, not this lint.
+ */
+const PROCESS_KILL_RE = /(?:^|[^.\w])process\.kill\s*\(/;
+
+/**
+ * Per-line opt-out marker. Use for embedded scripts that run in a
+ * separate Node process (e.g. the `node -e` orchestrator string in
+ * restart-helper.ts):
+ *   const orchestrator = `process.kill(pid, 0);` // ban:process-kill-ok
+ */
+const OPT_OUT_MARKER = "ban:process-kill-ok";
+
+/** Recursively walk a directory, yielding all .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 direct process.kill outside packages/shared/src/platform/", () => {
+  it("only allowlisted paths call process.kill directly", async () => {
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(here, "..", "..", "..", "..");
+    const packagesDir = path.resolve(repoRoot, "packages");
+
+    const violations: Array<{ file: string; line: number; text: string }> = [];
+    const allowPrefixes = ALLOWLIST_DIRS.map((p) =>
+      path.resolve(repoRoot, p).replace(/\\/g, "/") + "/",
+    );
+
+    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 (allowPrefixes.some((prefix) => normalized.startsWith(prefix))) continue;
+
+        const content = await fs.readFile(file, "utf-8");
+        const lines = content.split(/\r?\n/);
+        lines.forEach((line, idx) => {
+          if (!PROCESS_KILL_RE.test(line)) return;
+          if (line.includes(OPT_OUT_MARKER)) return;
+          violations.push({
+            file: path.relative(repoRoot, file),
+            line: idx + 1,
+            text: line.trim(),
+          });
+        });
+      }
+    }
+
+    if (violations.length > 0) {
+      const msg =
+        `Direct process.kill(...) calls found outside packages/shared/src/platform/.\n` +
+        `Migrate each to a platform helper:\n` +
+        `  import { isProcessAlive, killProcess, killPidWithGroup }\n` +
+        `    from "@blackbelt-technology/pi-dashboard-shared/platform/process.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__/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([]);
+    }
+  });
+});