@blackbelt-technology/pi-agent-dashboard 0.5.0 → 0.5.2

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 =

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

@@ -180,6 +180,57 @@ describe("spawnNodeScript", () => {
   });
 });
 
+describe("buildNodeImportArgvParts", () => {
+  // Pure helper shared by spawnNodeScript and restart-helper.ts so the
+  // `--import` argv shape lives in exactly one place.
+  it("POSIX + jiti: entry passed RAW (jiti rejects file:// URL entries)", async () => {
+    const { buildNodeImportArgvParts } = await import("../platform/node-spawn.js");
+    const parts = buildNodeImportArgvParts({
+      loader: "/usr/lib/jiti/lib/jiti-register.mjs",
+      entry: "/srv/cli.ts",
+      args: ["start", "--port", "8000"],
+      platform: "linux",
+    });
+    expect(parts[0]).toBe("--import");
+    expect(parts[1]).toMatch(/^file:\/\//);
+    expect(parts[2]).toBe("/srv/cli.ts"); // RAW
+    expect(parts.slice(3)).toEqual(["start", "--port", "8000"]);
+  });
+
+  it("Windows + jiti: entry URL-wrapped", async () => {
+    const { buildNodeImportArgvParts } = await import("../platform/node-spawn.js");
+    const parts = buildNodeImportArgvParts({
+      loader: "B:\\Dev\\jiti\\lib\\jiti-register.mjs",
+      entry: "B:\\srv\\cli.ts",
+      args: ["start"],
+      platform: "win32",
+    });
+    expect(parts[1]).toBe("file:///B:/Dev/jiti/lib/jiti-register.mjs");
+    expect(parts[2]).toBe("file:///B:/srv/cli.ts");
+  });
+
+  it("tsx loader: entry RAW on any platform", async () => {
+    const { buildNodeImportArgvParts } = await import("../platform/node-spawn.js");
+    const parts = buildNodeImportArgvParts({
+      loader: "/x/tsx/dist/esm/index.mjs",
+      entry: "C:\\srv\\cli.ts",
+      args: [],
+      platform: "win32",
+    });
+    expect(parts[2]).toBe("C:\\srv\\cli.ts"); // RAW (tsx rejects file:// entries)
+  });
+
+  it("omits args when none supplied", async () => {
+    const { buildNodeImportArgvParts } = await import("../platform/node-spawn.js");
+    const parts = buildNodeImportArgvParts({
+      loader: "/x/jiti/lib/jiti-register.mjs",
+      entry: "/srv/cli.ts",
+      platform: "linux",
+    });
+    expect(parts).toEqual(["--import", `file://${"/x/jiti/lib/jiti-register.mjs"}`, "/srv/cli.ts"]);
+  });
+});
+
 describe("shouldUrlWrapEntry", () => {
   it("returns false for tsx loader on any platform", () => {
     const tsxLoader = "file:///home/u/node_modules/tsx/dist/esm/index.mjs";

package/packages/shared/src/__tests__/openspec-groups-types.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Type-level tests for OpenSpec change-grouping shared types.
+ *
+ * Asserts:
+ *   - `OpenSpecGroup` shape compiles.
+ *   - `OpenSpecChange.groupId?: string | null` is optional.
+ *   - `OpenSpecGroupsFile` shape compiles.
+ *   - `OPENSPEC_GROUPS_SCHEMA_VERSION` is the literal `1`.
+ *   - `BrowserOpenSpecGroupsUpdateMessage` is a member of `ServerToBrowserMessage`
+ *     (otherwise esbuild would dead-code-eliminate the consumer switch arm).
+ *   - REST request/response shapes for the five `/api/openspec/groups*` routes compile.
+ *
+ * See change: add-openspec-change-grouping (tasks 1.1–1.7).
+ */
+import { describe, it, expect } from "vitest";
+import type {
+  OpenSpecGroup,
+  OpenSpecChange,
+  OpenSpecGroupsFile,
+} from "../types.js";
+import { OPENSPEC_GROUPS_SCHEMA_VERSION } from "../types.js";
+import type {
+  ServerToBrowserMessage,
+  BrowserOpenSpecGroupsUpdateMessage,
+} from "../browser-protocol.js";
+import type {
+  GetOpenSpecGroupsResponse,
+  CreateOpenSpecGroupRequest,
+  CreateOpenSpecGroupResponse,
+  UpdateOpenSpecGroupRequest,
+  UpdateOpenSpecGroupResponse,
+  DeleteOpenSpecGroupResponse,
+  SetOpenSpecGroupAssignmentRequest,
+  SetOpenSpecGroupAssignmentResponse,
+} from "../rest-api.js";
+
+// Type-level assertion: if the type does NOT extend the union, this will fail to compile.
+type AssertExtends<T, U> = T extends U ? true : never;
+
+// 1.5 — broadcast variant lives in the union.
+type _GroupsUpdateInBrowserUnion = AssertExtends<
+  BrowserOpenSpecGroupsUpdateMessage,
+  ServerToBrowserMessage
+>;
+
+// 1.1 — group shape.
+type _GroupShape = AssertExtends<
+  { id: string; name: string; color?: string; order: number },
+  OpenSpecGroup
+>;
+
+// 1.2 — `groupId?` is optional on `OpenSpecChange`.
+type _ChangeGroupIdOptional = AssertExtends<
+  { name: string; status: "in-progress"; completedTasks: 0; totalTasks: 0; artifacts: [] },
+  OpenSpecChange
+>;
+// And it accepts a string when present.
+type _ChangeWithGroupId = AssertExtends<
+  {
+    name: string;
+    status: "in-progress";
+    completedTasks: 0;
+    totalTasks: 0;
+    artifacts: [];
+    groupId: "ui";
+  },
+  OpenSpecChange
+>;
+
+// 1.4 — file shape.
+type _FileShape = AssertExtends<
+  {
+    schemaVersion: 1;
+    groups: OpenSpecGroup[];
+    assignments: Record<string, string>;
+  },
+  OpenSpecGroupsFile
+>;
+
+// 1.6 — REST shapes (compile-time only).
+const _getResp: GetOpenSpecGroupsResponse = {
+  success: true,
+  data: { schemaVersion: 1, groups: [], assignments: {} },
+};
+const _createReq: CreateOpenSpecGroupRequest = { name: "UI", color: "#3b82f6" };
+const _createResp: CreateOpenSpecGroupResponse = {
+  success: true,
+  data: { id: "ui", name: "UI", color: "#3b82f6", order: 0 },
+};
+const _updateReq: UpdateOpenSpecGroupRequest = { name: "Frontend" };
+const _updateResp: UpdateOpenSpecGroupResponse = {
+  success: true,
+  data: { id: "ui", name: "Frontend", order: 0 },
+};
+const _deleteResp: DeleteOpenSpecGroupResponse = { success: true };
+const _putReq: SetOpenSpecGroupAssignmentRequest = { changeName: "add-foo", groupId: "ui" };
+const _putReqNull: SetOpenSpecGroupAssignmentRequest = { changeName: "add-foo", groupId: null };
+const _putResp: SetOpenSpecGroupAssignmentResponse = { success: true };
+
+// Suppress unused-locals for compile-time-only declarations.
+void _getResp;
+void _createReq;
+void _createResp;
+void _updateReq;
+void _updateResp;
+void _deleteResp;
+void _putReq;
+void _putReqNull;
+void _putResp;
+
+describe("OpenSpec change-grouping shared types", () => {
+  it("OPENSPEC_GROUPS_SCHEMA_VERSION is the literal 1", () => {
+    expect(OPENSPEC_GROUPS_SCHEMA_VERSION).toBe(1);
+  });
+
+  it("openspec_groups_update is reachable in a runtime switch over ServerToBrowserMessage", () => {
+    // Runtime check that the discriminant survives type-narrowing — mirrors
+    // the prompt-message regression guard in browser-protocol-types.test.ts.
+    const sample: ServerToBrowserMessage = {
+      type: "openspec_groups_update",
+      cwd: "/tmp/foo",
+      groups: [],
+      assignments: {},
+    };
+    let hit = false;
+    switch (sample.type) {
+      case "openspec_groups_update":
+        hit = true;
+        break;
+      default:
+        break;
+    }
+    expect(hit).toBe(true);
+  });
+});

package/packages/shared/src/__tests__/publish-workflow-contract.test.ts

@@ -128,6 +128,102 @@ describe("publish.yml — electron job dependency-graph contract", () => {
 // single source of truth is the `prepare` job's computed `is_prerelease`
 // output. See change: eliminate-bash-on-windows-runners (D6).
 
+// ── Lockfile-regen contract ──────────────────────────────────────────────
+// The `prepare` job MUST regenerate package-lock.json with the bumped
+// versions (between sync-versions.js and the git commit) so consumers'
+// `npm ci` doesn't fall back to stale registry tarballs via strict
+// prerelease semver. See change: fix-release-lockfile-drift.
+
+/**
+ * Parse the `steps:` block of a single job into an array of `{ run }`
+ * entries. We only care about the `run:` field for this contract; the
+ * step delimiter is any `      - ` line (6-space indent + dash + space).
+ * Multi-line `run: |` blocks fold into a single `run` string.
+ */
+function parseJobSteps(jobBlock: string): Array<{ run: string }> {
+  const lines = jobBlock.split("\n");
+  const steps: Array<{ run: string }> = [];
+  let i = 0;
+  // Find the `    steps:` line.
+  while (i < lines.length && !/^    steps:\s*$/.test(lines[i])) i++;
+  i++;
+  let current: { run: string } | null = null;
+  let inRunBlock = false;
+  let runBlockIndent = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    // New step delimiter: `      - ` at 6-space indent.
+    if (/^      - /.test(line)) {
+      if (current) steps.push(current);
+      current = { run: "" };
+      inRunBlock = false;
+      // Inline `- run: foo` form.
+      const inlineRun = line.match(/^      -\s+run:\s+(.*)$/);
+      if (inlineRun) current.run = inlineRun[1];
+      i++;
+      continue;
+    }
+    if (current) {
+      // Block scalar `        run: |`.
+      const blockStart = line.match(/^        run:\s*\|?\s*$/);
+      const inlineKey = line.match(/^        run:\s+(.+)$/);
+      if (blockStart) {
+        inRunBlock = true;
+        runBlockIndent = 10; // body lines start at ≥ 10-space indent
+        i++;
+        continue;
+      }
+      if (inlineKey) {
+        current.run += (current.run ? "\n" : "") + inlineKey[1];
+        i++;
+        continue;
+      }
+      if (inRunBlock) {
+        // Body line of a `run: |` block. Stop when we hit a less-indented
+        // line (next key at 8-space indent, or the next step at 6-space).
+        if (line.length === 0) {
+          current.run += "\n";
+          i++;
+          continue;
+        }
+        const indent = line.length - line.trimStart().length;
+        if (indent < runBlockIndent) {
+          inRunBlock = false;
+          continue; // re-process this line as a key
+        }
+        current.run += (current.run ? "\n" : "") + line.slice(runBlockIndent);
+        i++;
+        continue;
+      }
+    }
+    i++;
+  }
+  if (current) steps.push(current);
+  return steps;
+}
+
+describe("publish.yml — prepare job lockfile-regen contract", () => {
+  const yaml = fs.readFileSync(WORKFLOW_PATH, "utf8");
+  const prepareBlock = extractJobBlock(yaml, "prepare");
+  const prepareSteps = parseJobSteps(prepareBlock);
+
+  it("prepare job regenerates lockfile after version bump (fix-release-lockfile-drift)", () => {
+    const syncIdx = prepareSteps.findIndex((s) => /sync-versions\.js/.test(s.run || ""));
+    const regenIdx = prepareSteps.findIndex((s) =>
+      /npm install --package-lock-only/.test(s.run || ""),
+    );
+    const commitIdx = prepareSteps.findIndex((s) =>
+      /git commit -m "chore\(release\)/.test(s.run || ""),
+    );
+    expect(syncIdx, "sync-versions.js step missing").toBeGreaterThanOrEqual(0);
+    expect(
+      regenIdx,
+      "lockfile regen step missing — see change fix-release-lockfile-drift",
+    ).toBeGreaterThan(syncIdx);
+    expect(commitIdx, "git commit step missing").toBeGreaterThan(regenIdx);
+  });
+});
+
 describe("publish.yml — prerelease safety contract", () => {
   const yaml = fs.readFileSync(WORKFLOW_PATH, "utf8");
   const prepareBlock = extractJobBlock(yaml, "prepare");

package/packages/shared/src/__tests__/recommended-extensions.test.ts

@@ -8,13 +8,14 @@ import {
 } from "../recommended-extensions.js";
 
 describe("RECOMMENDED_EXTENSIONS manifest", () => {
-	it("contains exactly the five expected entries", () => {
+	it("contains exactly the six expected entries", () => {
 		const ids = RECOMMENDED_EXTENSIONS.map((e) => e.id).sort();
 		expect(ids).toEqual(
 			[
 				"pi-anthropic-messages",
 				"pi-agent-browser",
 				"pi-flows",
+				"pi-memory-honcho",
 				"pi-web-access",
 				"tintinweb-pi-subagents",
 			].sort(),
@@ -62,7 +63,12 @@ describe("RECOMMENDED_EXTENSIONS manifest", () => {
 	it("npm-sourced entries use the npm: prefix", () => {
 		const npmEntries = RECOMMENDED_EXTENSIONS.filter((e) => e.source.startsWith("npm:"));
 		expect(npmEntries.map((e) => e.id).sort()).toEqual(
-			["pi-agent-browser", "pi-web-access", "tintinweb-pi-subagents"].sort(),
+			[
+				"pi-agent-browser",
+				"pi-memory-honcho",
+				"pi-web-access",
+				"tintinweb-pi-subagents",
+			].sort(),
 		);
 	});
 
@@ -105,7 +111,9 @@ describe("getRecommendedByStatus", () => {
 
 	it("filters by optional", () => {
 		const optional = getRecommendedByStatus("optional");
-		expect(optional.map((e) => e.id)).toEqual(["pi-agent-browser"]);
+		expect(optional.map((e) => e.id).sort()).toEqual(
+			["pi-agent-browser", "pi-memory-honcho"].sort(),
+		);
 	});
 });