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

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__/no-raw-openspec-status-in-skills.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Repo-level invariant: OpenSpec workflow skills (.pi/skills/openspec-*)
+ * MUST invoke `.pi/skills/openspec-shared/scripts/effective-status.sh`
+ * instead of calling `openspec status --json` directly. The wrapper
+ * applies the dashboard's local-design-evidence override (R1/R2/R3) so
+ * skill-driven prompts and dashboard session-card buttons cannot
+ * disagree about a change's next-ready artifact.
+ *
+ * If this test fails: replace the offending `openspec status ... --json`
+ * line with:
+ *
+ *   .pi/skills/openspec-shared/scripts/effective-status.sh "<name>"
+ *
+ * See change: fix-openspec-design-detection.
+ */
+import { describe, it, expect } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import url from "node:url";
+
+/**
+ * Regex catches `openspec status ... --json` invocations. We deliberately
+ * accept whitespace flexibility but reject only the `--json` flavor (the
+ * human-readable `openspec status --change "<name>"` form is allowed
+ * because it doesn't drive logic).
+ */
+const RAW_STATUS_RE = /\bopenspec\s+status\b[^\n]*--json\b/;
+
+/** Per-line opt-out marker. */
+const OPT_OUT_MARKER = "ban:openspec-status-ok";
+
+/** Skills the wrapper exists to serve — these MUST go through it. */
+const GOVERNED_SKILLS = [
+  "openspec-continue-change",
+  "openspec-ff-change",
+  "openspec-apply-change",
+  "openspec-verify-change",
+];
+
+describe("OpenSpec workflow skills must use effective-status.sh", () => {
+  it("no raw `openspec status --json` outside the wrapper script", async () => {
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(here, "..", "..", "..", "..");
+    const skillsRoot = path.resolve(repoRoot, ".pi", "skills");
+
+    const violations: Array<{ file: string; line: number; text: string }> = [];
+
+    for (const skill of GOVERNED_SKILLS) {
+      const skillFile = path.join(skillsRoot, skill, "SKILL.md");
+      let content: string;
+      try {
+        content = await fs.readFile(skillFile, "utf-8");
+      } catch {
+        // Skill not present in this checkout — fine, skip.
+        continue;
+      }
+      const lines = content.split(/\r?\n/);
+      lines.forEach((line, idx) => {
+        if (!RAW_STATUS_RE.test(line)) return;
+        if (line.includes(OPT_OUT_MARKER)) return;
+        violations.push({
+          file: path.relative(repoRoot, skillFile),
+          line: idx + 1,
+          text: line.trim(),
+        });
+      });
+    }
+
+    if (violations.length > 0) {
+      const msg =
+        `Raw \`openspec status --json\` invocations found in OpenSpec skills.\n` +
+        `Replace each with the wrapper that applies the dashboard's design override:\n` +
+        `  .pi/skills/openspec-shared/scripts/effective-status.sh "<name>"\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);
+  });
+});