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

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/__tests__/tool-registry-definitions.test.ts

@@ -104,7 +104,7 @@ describe("pi binary definition", () => {
 });
 
 describe("pi-coding-agent module definition", () => {
-  it("probes both @mariozechner and @oh-my-pi alias names", () => {
+  it("probes both @earendil-works (preferred) and @mariozechner (legacy fallback) alias names", () => {
     const r = freshRegistry({ exists: () => false });
     const res = r.resolve("pi-coding-agent");
     const names = res.tried.map((t) => t.strategy);

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

@@ -213,7 +213,7 @@ export async function bootstrapInstallDefaults(
   progress?: ProgressCallback,
 ): Promise<BootstrapInstallResult> {
   return bootstrapInstall({
-    packages: ["@mariozechner/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,
@@ -22,6 +23,14 @@ import type { EditorInstanceStatus } from "./editor-types.js";
 export interface SessionAddedMessage {
   type: "session_added";
   session: DashboardSession;
+  /**
+   * Echoed `requestId` from the originating browser `spawn_session` /
+   * `resume_session` (when known). Lets the client auto-select / dismiss
+   * placeholder by exact correlation, replacing the cwd-FIFO heuristic.
+   * Absent for server-initiated spawns (auto-resume, headless reload).
+   * See change: spawn-correlation-token.
+   */
+  spawnRequestId?: string;
 }
 
 export interface SessionUpdatedMessage {
@@ -88,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;
@@ -118,6 +140,24 @@ export interface ResumeResultBrowserMessage {
   sessionId: string;
   success: boolean;
   message: string;
+  /** Echoed from input `resume_session.requestId` when provided. */
+  requestId?: string;
+  /**
+   * For `mode: "fork"` only — populated once the new fork's bridge has
+   * registered and been correlated. Absent for `mode: "continue"` (the
+   * sessionId is unchanged across the respawn).
+   * See change: spawn-correlation-token.
+   */
+  newSessionId?: string;
+  /**
+   * Optional structured failure classifier. Known values:
+   *   - `"FORK_EMPTY_SESSION"`: fork attempted on a session whose
+   *     `sessionFile` does not exist on disk yet (e.g., freshly spawned,
+   *     no messages persisted).
+   * Old clients that don't read this field still get the human-readable
+   * `message`. See change: fix-fork-empty-session-silent-timeout.
+   */
+  code?: string;
 }
 
 export interface SpawnResultBrowserMessage {
@@ -125,6 +165,10 @@ export interface SpawnResultBrowserMessage {
   cwd: string;
   success: boolean;
   message: string;
+  /** Echoed from input `spawn_session.requestId` when provided. */
+  requestId?: string;
+  /** Spawned process PID when known (headless strategies); informational. */
+  pid?: number;
 }
 
 /**
@@ -356,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;
+  }>;
 }
 
 /**
@@ -484,6 +540,7 @@ export type ServerToBrowserMessage =
   | BrowserUiDismissMessage
   | BrowserFilesListMessage
   | BrowserOpenSpecUpdateMessage
+  | BrowserOpenSpecGroupsUpdateMessage
   | BrowserModelsListMessage
   | SessionsListBrowserMessage
   | ResumeResultBrowserMessage
@@ -665,6 +722,12 @@ export interface ResumeSessionBrowserMessage {
   mode: "continue" | "fork";
   /** When forking, optionally fork from a specific session entry instead of the latest */
   entryId?: string;
+  /**
+   * Client-minted UUIDv4 used to correlate `resume_result` and (for fork mode)
+   * the eventual `session_added` for the new session. Optional for back-compat.
+   * See change: spawn-correlation-token.
+   */
+  requestId?: string;
   /**
    * Placement intent for the resumed session in the cwd's sessionOrder:
    *   - "front" (default): move to top of alive tier (Resume button, REST,
@@ -699,6 +762,13 @@ export interface SpawnSessionBrowserMessage {
    * add-folder-task-checker-and-spawn-attach.
    */
   attachProposal?: string;
+  /**
+   * Client-minted UUIDv4 used to correlate `spawn_result` and the eventual
+   * `session_added` (which echoes it as `spawnRequestId`). Optional for
+   * back-compat with older clients.
+   * See change: spawn-correlation-token.
+   */
+  requestId?: string;
 }
 
 export interface AttachProposalBrowserMessage {

package/packages/shared/src/changelog-types.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared types for the pi changelog display feature.
+ *
+ * Server parses `CHANGELOG.md` files installed alongside core packages
+ * and the client renders the result via `WhatsNewDialog`. These types
+ * are the wire contract between the two halves.
+ *
+ * See change: pi-update-whats-new-panel.
+ */
+
+/**
+ * One bullet point under a release section. Preserves the original
+ * markdown prose verbatim so issue/PR links and inline code formatting
+ * survive intact for the client renderer.
+ */
+export interface ChangelogBullet {
+  /**
+   * Original markdown text of the bullet, with the leading `- `
+   * removed and any continuation lines joined with `\n`. Inline
+   * markdown (links, code spans, emphasis) is preserved exactly as
+   * written so the client can hand it to a markdown renderer.
+   */
+  text: string;
+  /**
+   * Issue / PR references mined from the prose via the canonical
+   * `([#NNN](URL))` pattern pi uses at end-of-bullet. May be empty
+   * when no such pattern is found. Order matches occurrence order.
+   * The `text` field still contains the link in its original form.
+   */
+  issues: { num: number; url: string }[];
+}
+
+/**
+ * One release entry parsed from a Keep-a-Changelog-style markdown
+ * document. Typed sub-section arrays are populated only when the
+ * corresponding H3 heading is present in the source.
+ */
+export interface ChangelogRelease {
+  /**
+   * Version string lifted from the `## [<version>] - <date>` H2
+   * heading. The bracket contents are taken verbatim so versions
+   * like `0.4.3-rc.1` survive.
+   */
+  version: string;
+  /**
+   * Date string lifted from the H2 heading. Set to `null` when the
+   * date token is missing or fails to parse as a YYYY-MM-DD-ish form.
+   * Parser tolerance is intentional — pi has shipped rare entries
+   * with date ranges or missing dates.
+   */
+  date: string | null;
+  /** Bullets under `### Breaking Changes`, in source order. */
+  breaking: ChangelogBullet[];
+  /**
+   * Union of bullets under `### New Features` and `### Added`. Pi
+   * uses both labels at different times for the same concept, so
+   * we merge them. Source order is preserved within each sub-section
+   * and the two sub-sections are concatenated in source order.
+   */
+  features: ChangelogBullet[];
+  /** Bullets under `### Changed`. */
+  changed: ChangelogBullet[];
+  /** Bullets under `### Fixed`. */
+  fixed: ChangelogBullet[];
+  /**
+   * Full markdown text from the release's H2 line up to (but not
+   * including) the next H2 line. Retained as a fallback render path
+   * when the typed arrays don't capture the content (e.g. an
+   * unrecognized H3 heading).
+   */
+  raw: string;
+}
+
+/**
+ * Response shape for `GET /api/pi-core/changelog`. Always wraps the
+ * filtered release list in this envelope so the client gets the
+ * derived `hasBreaking` flag and the GitHub link in one round-trip.
+ */
+export interface ChangelogResponse {
+  /** Package the changelog was parsed for. */
+  pkg: string;
+  /**
+   * Lower bound of the version range, EXCLUSIVE. Echoes the request
+   * query param. Releases at or below this version are filtered out.
+   */
+  from: string;
+  /**
+   * Upper bound of the version range, INCLUSIVE. Echoes the request
+   * query param. Releases above this version are filtered out.
+   */
+  to: string;
+  /**
+   * Filtered release list, ordered with the latest version FIRST.
+   * Empty when no releases exist in `(from, to]` or when the
+   * CHANGELOG could not be located.
+   */
+  releases: ChangelogRelease[];
+  /**
+   * Convenience flag derived from `releases.some(r => r.breaking.length > 0)`.
+   * Lets the client render the warning icon without re-walking the array.
+   */
+  hasBreaking: boolean;
+  /**
+   * Public URL to the full CHANGELOG on GitHub, derived from the
+   * package's `repository` field. `null` when the repository is not
+   * GitHub-hosted or is unparseable.
+   */
+  changelogUrl: string | null;
+  /** ISO timestamp at which the parser produced this response. */
+  parsedAt: string;
+}