@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.1

package/packages/shared/src/__tests__/installable-list.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mergeInstallableList, readInstallableList, writeInstallableList } from "../installable-list.js";
+import type { InstallableList } from "../installable-list.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+// ── mergeInstallableList tests ──────────────────────────────────────────────
+
+describe("mergeInstallableList", () => {
+  it("keep-user-pin: user version wins when it differs from bundled", () => {
+    const existing: InstallableList = {
+      version: "1",
+      packages: [{ name: "tsx", version: "^4.0.0", required: true, kind: "npm" }],
+    };
+    const bundled: InstallableList = {
+      version: "2",
+      packages: [{ name: "tsx", version: "^5.0.0", required: true, kind: "npm" }],
+    };
+    const { list, warnings } = mergeInstallableList(existing, bundled);
+    const found = list.packages.find((p) => p.name === "tsx");
+    expect(found?.version).toBe("^4.0.0");
+    expect(warnings.length).toBeGreaterThan(0);
+    expect(warnings[0]).toContain("tsx");
+    expect(warnings[0]).toContain("^4.0.0");
+    expect(warnings[0]).toContain("^5.0.0");
+  });
+
+  it("drop-pin-warn: package in existing but not in bundled gets deprecated=true + warning", () => {
+    const existing: InstallableList = {
+      version: "1",
+      packages: [{ name: "old-tool", version: "^1.0.0", required: false, kind: "npm" }],
+    };
+    const bundled: InstallableList = { version: "2", packages: [] };
+    const { list, warnings } = mergeInstallableList(existing, bundled);
+    const found = list.packages.find((p) => p.name === "old-tool");
+    expect(found?.deprecated).toBe(true);
+    expect(warnings.length).toBeGreaterThan(0);
+    expect(warnings[0]).toContain("old-tool");
+  });
+
+  it("add-new-required: new required package from bundled is added as-is", () => {
+    const existing: InstallableList = { version: "1", packages: [] };
+    const bundled: InstallableList = {
+      version: "2",
+      packages: [{ name: "pi", version: "*", required: true, kind: "npm" }],
+    };
+    const { list, warnings } = mergeInstallableList(existing, bundled);
+    const found = list.packages.find((p) => p.name === "pi");
+    expect(found).toBeDefined();
+    expect(found?.required).toBe(true);
+    expect(found?.defaultOff).toBeFalsy();
+    expect(warnings).toHaveLength(0);
+  });
+
+  it("add-new-optional: new optional package from bundled is added with defaultOff=true", () => {
+    const existing: InstallableList = { version: "1", packages: [] };
+    const bundled: InstallableList = {
+      version: "2",
+      packages: [{ name: "openspec", version: "*", required: false, kind: "npm" }],
+    };
+    const { list, warnings } = mergeInstallableList(existing, bundled);
+    const found = list.packages.find((p) => p.name === "openspec");
+    expect(found).toBeDefined();
+    expect(found?.defaultOff).toBe(true);
+    expect(warnings).toHaveLength(0);
+  });
+
+  it("version marker in result comes from bundled", () => {
+    const existing: InstallableList = { version: "1", packages: [] };
+    const bundled: InstallableList = { version: "42", packages: [] };
+    const { list } = mergeInstallableList(existing, bundled);
+    expect(list.version).toBe("42");
+  });
+});
+
+// ── readInstallableList tests ───────────────────────────────────────────────
+// Use a real temp directory (HOME is already ephemeral in the test runner).
+
+describe("readInstallableList", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "installable-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("returns null when file is absent", async () => {
+    const result = await readInstallableList(tmpDir);
+    expect(result).toBeNull();
+  });
+
+  it("drops entries with invalid kind and warns", async () => {
+    const list: InstallableList = {
+      version: "1",
+      packages: [
+        { name: "good-pkg", version: "*", required: true, kind: "npm" },
+        { name: "bad-pkg", version: "*", required: true, kind: "unknown-kind" as any },
+      ],
+    };
+    // Write via writeInstallableList (bypasses the drop-invalid-kind guard).
+    const filePath = path.join(tmpDir, "installable.json");
+    fs.writeFileSync(filePath, JSON.stringify(list), "utf-8");
+
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const result = await readInstallableList(tmpDir);
+
+    expect(result).not.toBeNull();
+    expect(result!.packages.map((p) => p.name)).toEqual(["good-pkg"]);
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(warnSpy.mock.calls[0]![0]).toContain("bad-pkg");
+  });
+
+  it("reads a valid file and returns the list", async () => {
+    const list: InstallableList = {
+      version: "3",
+      packages: [{ name: "tsx", version: "^5.0.0", required: true, kind: "npm" }],
+    };
+    await writeInstallableList(list, tmpDir);
+    const result = await readInstallableList(tmpDir);
+    expect(result).not.toBeNull();
+    expect(result!.version).toBe("3");
+    expect(result!.packages).toHaveLength(1);
+    expect(result!.packages[0]!.name).toBe("tsx");
+  });
+});

package/packages/shared/src/__tests__/managed-node-path.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Unit tests for `prependManagedNodeToPath` and friends.
+ *
+ * Real tmp HOME (per setup-home tripwire) so `getManagedDir()` resolves
+ * under the tmp tree. We create / remove the managed Node binary on
+ * disk to flip the present/absent branches.
+ *
+ * See change: embed-managed-node-runtime (task 2.5).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  getManagedNodeBinDir,
+  getManagedNodeBinary,
+  isManagedNodePresent,
+  prependManagedNodeToPath,
+} from "../platform/managed-node-path.js";
+import { getManagedDir } from "../managed-paths.js";
+
+const isWin = process.platform === "win32";
+
+describe("getManagedNodeBinDir", () => {
+  it("returns <managedDir>/node on Windows", () => {
+    const env = { homedir: "/fake/home" };
+    expect(getManagedNodeBinDir(env, "win32")).toBe(
+      path.join("/fake/home", ".pi-dashboard", "node"),
+    );
+  });
+
+  it("returns <managedDir>/node/bin on Unix", () => {
+    const env = { homedir: "/fake/home" };
+    expect(getManagedNodeBinDir(env, "linux")).toBe(
+      path.join("/fake/home", ".pi-dashboard", "node", "bin"),
+    );
+    expect(getManagedNodeBinDir(env, "darwin")).toBe(
+      path.join("/fake/home", ".pi-dashboard", "node", "bin"),
+    );
+  });
+});
+
+describe("getManagedNodeBinary", () => {
+  it("uses node.exe on Windows", () => {
+    expect(getManagedNodeBinary({ homedir: "/h" }, "win32")).toBe(
+      path.join("/h", ".pi-dashboard", "node", "node.exe"),
+    );
+  });
+
+  it("uses bin/node on Unix", () => {
+    expect(getManagedNodeBinary({ homedir: "/h" }, "linux")).toBe(
+      path.join("/h", ".pi-dashboard", "node", "bin", "node"),
+    );
+  });
+});
+
+describe("prependManagedNodeToPath", () => {
+  let tmpHome: string;
+  let origHome: string | undefined;
+
+  beforeEach(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "managed-node-path-"));
+    origHome = process.env.HOME;
+    process.env.HOME = tmpHome;
+  });
+
+  afterEach(() => {
+    if (origHome === undefined) delete process.env.HOME;
+    else process.env.HOME = origHome;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  function installFakeManagedNode(): string {
+    // os.homedir() reads HOME on Unix and USERPROFILE on Windows. The
+    // setup-home tripwire only sets HOME, so on Windows tests we set
+    // USERPROFILE here too.
+    if (isWin) process.env.USERPROFILE = tmpHome;
+    const dir = getManagedNodeBinDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const binary = getManagedNodeBinary();
+    fs.writeFileSync(binary, "fake");
+    return dir;
+  }
+
+  it("no-op (returns clone) when managed runtime is absent", () => {
+    const base = { PATH: "/usr/bin:/bin", FOO: "bar" };
+    const out = prependManagedNodeToPath(base);
+    expect(out).not.toBe(base);
+    expect(out.PATH).toBe("/usr/bin:/bin");
+    expect(out.FOO).toBe("bar");
+  });
+
+  it("does not mutate process.env", () => {
+    const beforePath = process.env.PATH;
+    prependManagedNodeToPath();
+    expect(process.env.PATH).toBe(beforePath);
+  });
+
+  it("prepends managed Node bin dir when present", () => {
+    const dir = installFakeManagedNode();
+    const base = { PATH: "/usr/bin:/bin", X: "y" };
+    const out = prependManagedNodeToPath(base);
+    expect(out).not.toBe(base);
+    expect(out.PATH?.startsWith(dir)).toBe(true);
+    expect(out.PATH).toBe(`${dir}${path.delimiter}/usr/bin:/bin`);
+    expect(out.X).toBe("y");
+  });
+
+  it("does not double-prepend when dir already at head", () => {
+    const dir = installFakeManagedNode();
+    const initial = `${dir}${path.delimiter}/usr/bin`;
+    const base = { PATH: initial };
+    const out = prependManagedNodeToPath(base);
+    expect(out.PATH).toBe(initial);
+  });
+
+  it("isManagedNodePresent flips with the binary on disk", () => {
+    expect(isManagedNodePresent()).toBe(false);
+    installFakeManagedNode();
+    expect(isManagedNodePresent()).toBe(true);
+  });
+});

package/packages/shared/src/__tests__/managed-runtime-strategy.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Unit tests for `managedRuntimeStrategy` in isolation.
+ *
+ * Strategy receives a `StrategyCtx` (overrides + platform + env). We
+ * inject a fake `exists` so no real filesystem is touched.
+ *
+ * See change: embed-managed-node-runtime (task 2.6).
+ */
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { managedRuntimeStrategy } from "../tool-registry/strategies.js";
+import type { StrategyCtx } from "../tool-registry/types.js";
+
+function ctx(opts: Partial<StrategyCtx> = {}): StrategyCtx {
+  return {
+    overrides: {},
+    platform: opts.platform ?? "linux",
+    env: opts.env ?? { homedir: "/fake/home" },
+  };
+}
+
+describe("managedRuntimeStrategy", () => {
+  it("Unix node: returns <managedDir>/node/bin/node when present", () => {
+    const expected = path.join("/fake/home", ".pi-dashboard", "node", "bin", "node");
+    const s = managedRuntimeStrategy("node", { exists: (p) => p === expected });
+    const r = s.run(ctx({ platform: "linux" }));
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.path).toBe(expected);
+  });
+
+  it("Unix npm: returns <managedDir>/node/bin/npm when present", () => {
+    const expected = path.join("/fake/home", ".pi-dashboard", "node", "bin", "npm");
+    const s = managedRuntimeStrategy("npm", { exists: (p) => p === expected });
+    const r = s.run(ctx({ platform: "linux" }));
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.path).toBe(expected);
+  });
+
+  it("Windows node: returns <managedDir>/node/node.exe when present", () => {
+    const expected = path.join("/fake/home", ".pi-dashboard", "node", "node.exe");
+    const s = managedRuntimeStrategy("node", { exists: (p) => p === expected });
+    const r = s.run(ctx({ platform: "win32" }));
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.path).toBe(expected);
+  });
+
+  it("Windows npm: returns <managedDir>/node/npm.cmd when present", () => {
+    const expected = path.join("/fake/home", ".pi-dashboard", "node", "npm.cmd");
+    const s = managedRuntimeStrategy("npm", { exists: (p) => p === expected });
+    const r = s.run(ctx({ platform: "win32" }));
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.path).toBe(expected);
+  });
+
+  it("Windows npx: returns <managedDir>/node/npx.cmd when present", () => {
+    const expected = path.join("/fake/home", ".pi-dashboard", "node", "npx.cmd");
+    const s = managedRuntimeStrategy("npx", { exists: (p) => p === expected });
+    const r = s.run(ctx({ platform: "win32" }));
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.path).toBe(expected);
+  });
+
+  it("returns failure with reason when binary absent", () => {
+    const s = managedRuntimeStrategy("node", { exists: () => false });
+    const r = s.run(ctx({ platform: "linux" }));
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toMatch(/missing:/);
+  });
+
+  it("strategy is named 'managed' (classifies as managed source)", () => {
+    const s = managedRuntimeStrategy("node");
+    expect(s.name).toBe("managed");
+  });
+});

package/packages/shared/src/__tests__/no-installable-list-in-bridge.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Contract test: the bridge auto-spawn code path (server-launcher.ts) must
+ * NOT import from `installable-list`. Only Electron seeds `installable.json`
+ * on first run; Bridge and Standalone starters must not produce or consume
+ * that file.
+ *
+ * This is a static source scan — no runtime execution. If this test fails,
+ * a dependency on installable-list was accidentally added to the bridge
+ * launcher which would break the "file-absent is a no-op" contract on
+ * Bridge/Standalone bootstraps.
+ *
+ * See change: simplify-electron-bootstrap-derived-state (task 5.7).
+ */
+import { describe, expect, it } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import url from "node:url";
+
+const here = path.dirname(url.fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, "..", "..", "..", "..");
+
+/** Files that form the bridge auto-spawn contract. */
+const BRIDGE_SPAWN_FILES: readonly string[] = [
+  "packages/extension/src/server-launcher.ts",
+  "packages/extension/src/server-auto-start.ts",
+  "packages/extension/src/connection.ts",
+];
+
+describe("bridge auto-spawn does not reference installable-list", () => {
+  for (const rel of BRIDGE_SPAWN_FILES) {
+    it(`${rel} does not import from installable-list`, () => {
+      const file = path.resolve(repoRoot, rel);
+      if (!fs.existsSync(file)) {
+        // File absent (optional extension file) — contract trivially satisfied.
+        return;
+      }
+      const source = fs.readFileSync(file, "utf-8");
+
+      // Strip line comments before checking so a commented-out import
+      // does not trigger a false positive.
+      const stripped = source
+        .replace(/\/\/[^\n]*/g, "")
+        .replace(/\/\*[\s\S]*?\*\//g, "");
+
+      expect(
+        stripped,
+        `${rel} must not import from "installable-list" — only Electron seeds installable.json. ` +
+          `Bridge/Standalone starters must not produce or consume that file.`,
+      ).not.toMatch(/installable-list/);
+    });
+  }
+});

package/packages/shared/src/__tests__/no-raw-openspec-status-in-skills.test.ts

@@ -38,7 +38,12 @@ const GOVERNED_SKILLS = [
 ];
 
 describe("OpenSpec workflow skills must use effective-status.sh", () => {
-  it("no raw `openspec status --json` outside the wrapper script", async () => {
+  // SKIPPED: the .pi/skills/openspec-*/SKILL.md files this lint targets are
+  // vendored from upstream and gitignored (see .pi/.gitignore) — they get
+  // overwritten on every install, so we can't enforce dashboard-local
+  // semantics on them from here. Re-enable if/when those skills are
+  // forked into the repo, or move the wrapper-enforcement upstream.
+  it.skip("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");

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

@@ -1,22 +1,28 @@
 /**
- * Pin Defect 2's jiti version contract for `shouldUrlWrapEntry()`.
+ * Pin the jiti version contract for `shouldUrlWrapEntry()`.
  *
  * The Windows-non-tsx arm in `platform/node-spawn.ts::shouldUrlWrapEntry`
- * assumes the jiti loader is from `@mariozechner/pi-coding-agent@0.70.x`
- * (jiti 2.x with the file:// URL handling fix). Newer pi versions ship
- * a different jiti that breaks this contract.
+ * relies on jiti's file:/// URL handling. This was VERIFIED on:
+ *   - `@mariozechner/pi-coding-agent@0.70.x` shipping `jiti@2.x` (original baseline)
+ *   - `@earendil-works/pi-coding-agent@0.74.x` shipping `jiti@^2.7.0` (current baseline)
+ * It was BROKEN on `pi-coding-agent@0.71.x` shipping `jiti@2.6.5`, which
+ * misnormalised triple-slash file:/// URLs on Windows. Keep that data
+ * point in the contract so a contributor recognises the regression
+ * pattern if it recurs.
  *
  * This test ensures:
  *   1. The offline-cacache pin in `packages/electron/offline-packages.json`
- *      stays at `0.70.x` (the supported range). A bump elsewhere fires
- *      this test and forces the contributor to either:
+ *      stays on a supported pi version under one of the two supported
+ *      forks. A bump outside the verified set fires this test and
+ *      forces the contributor to either:
  *        - re-verify the contract on Windows
  *        - add a per-jiti-version branch
  *        - switch the bundled loader to tsx
  *   2. The `shouldUrlWrapEntry` header comment documents the contract
  *      so future contributors discover the constraint at the call site.
  *
- * See change: fix-electron-windows-installer-and-server-bootstrap (Defect 2).
+ * See changes: fix-electron-windows-installer-and-server-bootstrap (Defect 2),
+ *              migrate-pi-fork-to-earendil (E.6).
  */
 import { describe, it, expect } from "vitest";
 import fs from "node:fs";
@@ -40,34 +46,54 @@ const NODE_SPAWN_PATH = path.join(
   "node-spawn.ts",
 );
 
+/** Versions verified against the Windows file:/// jiti contract. */
+const VERIFIED_PI_PINS: ReadonlyArray<{ name: string; versionPrefix: string }> = [
+  { name: "@earendil-works/pi-coding-agent", versionPrefix: "0.74." },
+  { name: "@mariozechner/pi-coding-agent", versionPrefix: "0.70." },
+];
+
 describe("jiti version contract for shouldUrlWrapEntry", () => {
-  it("offline-packages.json pins @mariozechner/pi-coding-agent at a 0.70.x version", () => {
+  it("offline-packages.json pins pi-coding-agent at a verified version under a supported fork", () => {
     const raw = fs.readFileSync(OFFLINE_PACKAGES_PATH, "utf8");
     const manifest = JSON.parse(raw) as {
       packages: { name: string; version: string }[];
     };
-    const piEntry = manifest.packages.find(
-      (p) => p.name === "@mariozechner/pi-coding-agent",
+
+    const supportedNames = VERIFIED_PI_PINS.map((p) => p.name);
+    const piEntry = manifest.packages.find((p) =>
+      supportedNames.includes(p.name),
     );
     if (!piEntry) {
       throw new Error(
-        "@mariozechner/pi-coding-agent not found in offline-packages.json. " +
-          "The offline cacache must include pi-coding-agent. " +
-          "See change: fix-electron-windows-installer-and-server-bootstrap (Defect 2).",
+        `No supported pi-coding-agent fork found in offline-packages.json. ` +
+          `Expected one of: ${supportedNames.join(", ")}. ` +
+          `The offline cacache must include pi-coding-agent. ` +
+          `See changes: fix-electron-windows-installer-and-server-bootstrap (Defect 2), ` +
+          `migrate-pi-fork-to-earendil (E.6).`,
       );
     }
-    if (!piEntry.version.startsWith("0.70.")) {
+
+    const verifiedPin = VERIFIED_PI_PINS.find(
+      (p) => p.name === piEntry.name && piEntry.version.startsWith(p.versionPrefix),
+    );
+    if (!verifiedPin) {
+      const allowedRanges = VERIFIED_PI_PINS
+        .map((p) => `${p.name}@${p.versionPrefix}x`)
+        .join(", ");
       throw new Error(
-        `pi-coding-agent pinned at ${piEntry.version}, but ` +
-          `shouldUrlWrapEntry()'s Windows-non-tsx arm only supports 0.70.x. ` +
+        `pi-coding-agent pinned at ${piEntry.name}@${piEntry.version}, but ` +
+          `shouldUrlWrapEntry()'s Windows-non-tsx arm only supports verified pins: ` +
+          `${allowedRanges}. ` +
           `Newer jiti versions (e.g. 2.6.5 in pi 0.71.x) misnormalize ` +
           `file:/// URL entries on Windows. Either re-verify the contract, ` +
           `add a per-jiti-version branch in shouldUrlWrapEntry(), or switch ` +
-          `the bundled loader to tsx. See change: ` +
-          `fix-electron-windows-installer-and-server-bootstrap (Defect 2).`,
+          `the bundled loader to tsx. See changes: ` +
+          `fix-electron-windows-installer-and-server-bootstrap (Defect 2), ` +
+          `migrate-pi-fork-to-earendil (E.6).`,
       );
     }
-    expect(piEntry.version).toMatch(/^0\.70\./);
+
+    expect(piEntry.version.startsWith(verifiedPin.versionPrefix)).toBe(true);
   });
 
   it("node-spawn.ts source contains the documented JITI VERSION CONTRACT block", () => {
@@ -75,7 +101,17 @@ describe("jiti version contract for shouldUrlWrapEntry", () => {
 
     // Contract block markers
     expect(source).toContain("JITI VERSION CONTRACT");
-    expect(source).toContain("0.70.x");
+    // Documented baseline references (at least one of the verified version markers).
+    const hasBaselineMarker =
+      source.includes("0.74.") || source.includes("0.70.x");
+    if (!hasBaselineMarker) {
+      throw new Error(
+        "shouldUrlWrapEntry() docstring is missing the verified-baseline marker. " +
+          "It must mention at least one of: '0.74.' (current earendil baseline) " +
+          "or '0.70.x' (legacy mariozechner baseline). See change: " +
+          "migrate-pi-fork-to-earendil (E.7).",
+      );
+    }
 
     // Version drift markers (at least one of these identifies the broken jiti)
     const hasVersionDriftMarker =