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

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(),
+		);
 	});
 });
 

package/packages/shared/src/__tests__/server-launcher.test.ts

@@ -0,0 +1,227 @@
+/**
+ * Unit tests for `launchDashboardServer`.
+ *
+ * Mocks the test seams (`_resolveJiti`, `_spawnNodeScript`,
+ * `_isDashboardRunning`, `_fs`, `_sleep`, `_now`) so the launcher's
+ * orchestration logic is exercised without spawning a real child or
+ * touching the filesystem.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { EventEmitter } from "node:events";
+import {
+  launchDashboardServer,
+  JitiNotFoundError,
+  PortConflictError,
+  EarlyExitError,
+} from "../server-launcher.js";
+import type { ChildProcess } from "node:child_process";
+import type { spawnNodeScript } from "../platform/node-spawn.js";
+import type { isDashboardRunning } from "../server-identity.js";
+
+const spawnSpy = (impl: () => ChildProcess) =>
+  vi.fn<typeof spawnNodeScript>(impl as unknown as typeof spawnNodeScript);
+const probeSpy = <T>(impl: () => Promise<T>) =>
+  vi.fn<typeof isDashboardRunning>(impl as unknown as typeof isDashboardRunning);
+
+interface FakeChildOpts {
+  pid?: number | null;
+  exitCode?: number | null;
+}
+
+function makeFakeChild(opts: FakeChildOpts = {}): ChildProcess {
+  const ee = new EventEmitter() as unknown as ChildProcess & {
+    pid: number | undefined;
+    exitCode: number | null;
+    signalCode: NodeJS.Signals | null;
+    unref: () => void;
+  };
+  ee.pid = (opts.pid ?? 12345) as number | undefined;
+  ee.exitCode = opts.exitCode ?? null;
+  ee.signalCode = null;
+  ee.unref = vi.fn();
+  return ee;
+}
+
+function baseOpts(overrides: Partial<Parameters<typeof launchDashboardServer>[0]> = {}) {
+  return {
+    cliPath: "/srv/cli.ts",
+    stdio: "ignore" as const,
+    healthTimeoutMs: 5000,
+    port: 8000,
+    _resolveJiti: () => "file:///loader/jiti-register.mjs",
+    _spawnNodeScript: spawnSpy(() => makeFakeChild()),
+    _isDashboardRunning: probeSpy(async () => ({ running: true, pid: 99 })),
+    _sleep: () => Promise.resolve(),
+    _pollIntervalMs: 1,
+    ...overrides,
+  };
+}
+
+describe("launchDashboardServer — happy path", () => {
+  it("returns childPid + reportedPid + healthOk on first health-ok poll", async () => {
+    const result = await launchDashboardServer(baseOpts());
+    expect(result.childPid).toBe(12345);
+    expect(result.reportedPid).toBe(99);
+    expect(result.healthOk).toBe(true);
+  });
+
+  it("delegates argv to spawnNodeScript with loader + entry + args", async () => {
+    const spy = spawnSpy(() => makeFakeChild());
+    await launchDashboardServer(baseOpts({
+      _spawnNodeScript: spy,
+      extraArgs: ["--port", "8000", "--pi-port", "9999"],
+    }));
+    expect(spy).toHaveBeenCalledOnce();
+    const call = spy.mock.calls[0]![0]!;
+    expect(call.loader).toBe("file:///loader/jiti-register.mjs");
+    expect(call.entry).toBe("/srv/cli.ts");
+    expect(call.args).toEqual(["--port", "8000", "--pi-port", "9999"]);
+    expect(call.spawnOptions?.detached).toBe(true);
+    expect(call.spawnOptions?.windowsHide).toBe(true);
+    expect(call.spawnOptions?.stdio).toBe("ignore");
+  });
+});
+
+describe("launchDashboardServer — jiti resolution", () => {
+  it("throws JitiNotFoundError when resolveJiti returns null (no spawn)", async () => {
+    const spawn = spawnSpy(() => makeFakeChild());
+    await expect(launchDashboardServer(baseOpts({
+      _resolveJiti: () => null,
+      _spawnNodeScript: spawn,
+    }))).rejects.toBeInstanceOf(JitiNotFoundError);
+    expect(spawn).not.toHaveBeenCalled();
+  });
+});
+
+describe("launchDashboardServer — readiness termination", () => {
+  it("throws PortConflictError when probe reports portConflict", async () => {
+    await expect(launchDashboardServer(baseOpts({
+      _isDashboardRunning: async () => ({ running: false, portConflict: true }),
+    }))).rejects.toBeInstanceOf(PortConflictError);
+  });
+
+  it("throws EarlyExitError when child exits during poll", async () => {
+    const child = makeFakeChild();
+    let calls = 0;
+    const spawnFn = spawnSpy(() => child);
+    const probe = probeSpy(async () => {
+      calls++;
+      if (calls === 1) {
+        // Mid-poll, child crashes.
+        (child as unknown as { exitCode: number }).exitCode = 7;
+      }
+      return { running: false };
+    });
+    await expect(launchDashboardServer(baseOpts({
+      _spawnNodeScript: spawnFn,
+      _isDashboardRunning: probe,
+    }))).rejects.toBeInstanceOf(EarlyExitError);
+  });
+
+  it("throws readiness-timeout Error after healthTimeoutMs elapses", async () => {
+    let now = 1000;
+    await expect(launchDashboardServer(baseOpts({
+      healthTimeoutMs: 100,
+      _now: () => { now += 60; return now; }, // each poll advances 60ms — 2 polls past deadline
+      _isDashboardRunning: async () => ({ running: false }),
+    }))).rejects.toThrow(/readiness timeout/);
+  });
+
+  it("port-conflict beats timeout (probe order respected)", async () => {
+    let now = 1000;
+    await expect(launchDashboardServer(baseOpts({
+      healthTimeoutMs: 100,
+      _now: () => { now += 200; return now; },
+      _isDashboardRunning: async () => ({ running: false, portConflict: true }),
+    }))).rejects.toBeInstanceOf(PortConflictError);
+  });
+});
+
+describe("launchDashboardServer — log-file stdio", () => {
+  it("mkdirs parent, opens append fd, writes header, passes fd, closes parent's copy", async () => {
+    const calls: string[] = [];
+    const fsStub = {
+      mkdirSync: vi.fn((p: any) => { calls.push(`mkdir:${p}`); }),
+      openSync: vi.fn((p: any, mode: any) => { calls.push(`open:${p}:${mode}`); return 42; }),
+      writeSync: vi.fn((fd: number, s: any) => { calls.push(`write:${fd}:${String(s).slice(0, 20)}…`); return s.length; }),
+      closeSync: vi.fn((fd: number) => { calls.push(`close:${fd}`); }),
+    };
+    const spawn = spawnSpy(() => makeFakeChild());
+    await launchDashboardServer(baseOpts({
+      stdio: { logFile: "/var/log/dashboard/server.log" },
+      starter: "Standalone",
+      _fs: fsStub as any,
+      _spawnNodeScript: spawn,
+    }));
+    expect(fsStub.mkdirSync).toHaveBeenCalledWith("/var/log/dashboard", { recursive: true });
+    expect(fsStub.openSync).toHaveBeenCalledWith("/var/log/dashboard/server.log", "a");
+    expect(fsStub.writeSync).toHaveBeenCalledOnce();
+    expect(String(fsStub.writeSync.mock.calls[0]![1])).toContain("Standalone launch");
+    // Spawn received [ignore, fd, fd]:
+    const stdio = spawn.mock.calls[0]![0]!.spawnOptions!.stdio as Array<unknown>;
+    expect(stdio).toEqual(["ignore", 42, 42]);
+    // Parent fd closed AFTER spawn:
+    expect(fsStub.closeSync).toHaveBeenCalledWith(42);
+    const closeIdx = calls.findIndex((c) => c.startsWith("close:42"));
+    const writeIdx = calls.findIndex((c) => c.startsWith("write:42"));
+    expect(closeIdx).toBeGreaterThan(writeIdx);
+  });
+});
+
+describe("launchDashboardServer — env merge", () => {
+  it("caller env keys override buildSpawnEnv defaults", async () => {
+    const spawn = spawnSpy(() => makeFakeChild());
+    await launchDashboardServer(baseOpts({
+      _spawnNodeScript: spawn,
+      env: { DASHBOARD_STARTER: "Bridge", CUSTOM_KEY: "x" },
+    }));
+    const env = spawn.mock.calls[0]![0]!.spawnOptions!.env as Record<string, string>;
+    expect(env.DASHBOARD_STARTER).toBe("Bridge");
+    expect(env.CUSTOM_KEY).toBe("x");
+  });
+
+  it("starter option becomes DASHBOARD_STARTER when env does not supply it", async () => {
+    const spawn = spawnSpy(() => makeFakeChild());
+    await launchDashboardServer(baseOpts({
+      _spawnNodeScript: spawn,
+      starter: "Electron",
+    }));
+    const env = spawn.mock.calls[0]![0]!.spawnOptions!.env as Record<string, string>;
+    expect(env.DASHBOARD_STARTER).toBe("Electron");
+  });
+
+  it("explicit env.DASHBOARD_STARTER wins over starter option", async () => {
+    const spawn = spawnSpy(() => makeFakeChild());
+    await launchDashboardServer(baseOpts({
+      _spawnNodeScript: spawn,
+      starter: "Electron",
+      env: { DASHBOARD_STARTER: "Bridge" },
+    }));
+    const env = spawn.mock.calls[0]![0]!.spawnOptions!.env as Record<string, string>;
+    expect(env.DASHBOARD_STARTER).toBe("Bridge");
+  });
+});
+
+describe("launchDashboardServer — entry URL-wrapping", () => {
+  // The launcher delegates to spawnNodeScript, which uses
+  // `shouldUrlWrapEntry(loader, platform)`. We verify the launcher
+  // simply forwards the raw entry; the URL-wrap behaviour itself is
+  // pinned by node-spawn-jiti-contract.test.ts.
+  it("forwards `cliPath` verbatim to spawnNodeScript (URL-wrapping owned downstream)", async () => {
+    const spawn = spawnSpy(() => makeFakeChild());
+    await launchDashboardServer(baseOpts({
+      _spawnNodeScript: spawn,
+      cliPath: "/posix/cli.ts",
+    }));
+    expect(spawn.mock.calls[0]![0]!.entry).toBe("/posix/cli.ts");
+  });
+
+  it("forwards Windows-style `cliPath` verbatim too", async () => {
+    const spawn = spawnSpy(() => makeFakeChild());
+    await launchDashboardServer(baseOpts({
+      _spawnNodeScript: spawn,
+      cliPath: "C:\\srv\\cli.ts",
+    }));
+    expect(spawn.mock.calls[0]![0]!.entry).toBe("C:\\srv\\cli.ts");
+  });
+});

package/packages/shared/src/bootstrap-install.ts

@@ -213,7 +213,7 @@ export async function bootstrapInstallDefaults(
   progress?: ProgressCallback,
 ): Promise<BootstrapInstallResult> {
   return bootstrapInstall({
-    packages: ["@earendil-works/pi-coding-agent", "@fission-ai/openspec", "tsx"],
+    packages: ["@earendil-works/pi-coding-agent", "@fission-ai/openspec"],
     progress,
   });
 }

package/packages/shared/src/browser-protocol.ts

@@ -9,6 +9,7 @@ import type {
   ImageContent,
   FileEntry,
   OpenSpecData,
+  OpenSpecGroup,
   ModelInfo,
   PiSessionInfo,
   ExtensionUiModule,
@@ -96,6 +97,19 @@ export interface BrowserOpenSpecUpdateMessage {
   data: OpenSpecData;
 }
 
+/**
+ * Per-repo OpenSpec change-grouping update. Broadcast after every successful
+ * write to `<cwd>/openspec/groups/groups.json`, debounced 100 ms per cwd.
+ * Full payload (no incremental delta) so client logic stays simple.
+ * See change: add-openspec-change-grouping.
+ */
+export interface BrowserOpenSpecGroupsUpdateMessage {
+  type: "openspec_groups_update";
+  cwd: string;
+  groups: OpenSpecGroup[];
+  assignments: Record<string, string>;
+}
+
 export interface BrowserModelsListMessage {
   type: "models_list";
   sessionId: string;
@@ -386,6 +400,18 @@ export interface BootstrapStateSnapshot {
     upgradeDashboard?: boolean;
   };
   bridgeRegistrationError?: string;
+  /**
+   * Legacy `@mariozechner/pi-coding-agent` installs detected on disk.
+   * Surfaced by the client as a one-click cleanup banner. Empty array
+   * means no legacy installs found. Pi was renamed to
+   * `@earendil-works/pi-coding-agent` at v0.74 — the legacy scope can
+   * collide with the new scope's `bin/pi` symlink.
+   */
+  legacyPiInstalls?: Array<{
+    scope: "npm-global" | "npx-cache" | "managed";
+    path: string;
+    version: string | null;
+  }>;
 }
 
 /**
@@ -514,6 +540,7 @@ export type ServerToBrowserMessage =
   | BrowserUiDismissMessage
   | BrowserFilesListMessage
   | BrowserOpenSpecUpdateMessage
+  | BrowserOpenSpecGroupsUpdateMessage
   | BrowserModelsListMessage
   | SessionsListBrowserMessage
   | ResumeResultBrowserMessage