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

package/packages/shared/src/__tests__/bootstrap/fixtures/electron-layout.ts

@@ -0,0 +1,84 @@
+/**
+ * Fixture: Electron packaged resources layout.
+ *
+ * macOS:   /Applications/PI Dashboard.app/Contents/Resources/server/...
+ * Linux:   /usr/lib/pi-dashboard/resources/server/...
+ * Windows: C:\Program Files\PI Dashboard\resources\server\...
+ * AppImage: /tmp/.mount_PIxxxx/resources/server/... (temp, unstable)
+ *
+ * The bundled extension lives alongside at
+ * `<resourcesPath>/server/packages/extension/`.
+ */
+import posix from "node:path/posix";
+import win32 from "node:path/win32";
+import type { FsRecord } from "../harness.js";
+
+export interface ElectronLayoutSpec {
+  platform: NodeJS.Platform;
+  /** If true, simulate AppImage temp-mount path. */
+  appimage?: boolean;
+}
+
+function resourcesRoot(spec: ElectronLayoutSpec): string {
+  if (spec.appimage) {
+    return "/tmp/.mount_PIxxxx/resources";
+  }
+  switch (spec.platform) {
+    case "darwin":
+      return "/Applications/PI Dashboard.app/Contents/Resources";
+    case "win32":
+      return "C:\\Program Files\\PI Dashboard\\resources";
+    default:
+      return "/usr/lib/pi-dashboard/resources";
+  }
+}
+
+export function electronPackaged(spec: ElectronLayoutSpec): FsRecord {
+  const p = spec.platform === "win32" ? win32 : posix;
+  const resources = resourcesRoot(spec);
+  const serverDir = p.join(resources, "server");
+  const extensionDir = p.join(serverDir, "packages", "extension");
+  const out: Record<string, string> = {};
+
+  // Bundled server package.json
+  out[p.join(serverDir, "package.json")] = JSON.stringify({
+    name: "@blackbelt-technology/pi-agent-dashboard-root",
+    version: "0.4.0",
+    private: true,
+  });
+
+  // Bundled server CLI source
+  out[p.join(serverDir, "packages", "server", "package.json")] = JSON.stringify({
+    name: "@blackbelt-technology/pi-dashboard-server",
+    version: "0.4.0",
+  });
+  out[p.join(serverDir, "packages", "server", "src", "cli.ts")] = "// cli";
+
+  // Bundled bridge extension
+  out[p.join(extensionDir, "package.json")] = JSON.stringify({
+    name: "@blackbelt-technology/pi-dashboard-extension",
+    version: "0.4.0",
+  });
+  out[p.join(extensionDir, "src", "bridge.ts")] = "// bridge";
+
+  // Bundled Node.js (minimal)
+  const nodeBin = spec.platform === "win32"
+    ? p.join(resources, "node", "bin", "node.exe")
+    : p.join(resources, "node", "bin", "node");
+  out[nodeBin] = "\x7fELF"; // binary-ish marker
+
+  return out;
+}
+
+/** Returns the resolved `resourcesPath` + extension path for assertions. */
+export function electronPaths(spec: ElectronLayoutSpec): {
+  resources: string;
+  serverDir: string;
+  extensionDir: string;
+} {
+  const p = spec.platform === "win32" ? win32 : posix;
+  const resources = resourcesRoot(spec);
+  const serverDir = p.join(resources, "server");
+  const extensionDir = p.join(serverDir, "packages", "extension");
+  return { resources, serverDir, extensionDir };
+}

package/packages/shared/src/__tests__/bootstrap/fixtures/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Barrel export for bootstrap fixtures. Import as `import * as fixtures`.
+ */
+export * from "./pi-versions.js";
+export * from "./managed-install.js";
+export * from "./npm-global-layout.js";
+export * from "./electron-layout.js";
+export * from "./dev-monorepo.js";
+export * from "./settings-json.js";

package/packages/shared/src/__tests__/bootstrap/fixtures/managed-install.ts

@@ -0,0 +1,85 @@
+/**
+ * Fixture: managed install at `<homedir>/.pi-dashboard/`.
+ *
+ * Produces the fs layout a user gets after running the Electron wizard
+ * or proposal-2's CLI first-run bootstrap: node_modules/@mariozechner/
+ * pi-coding-agent + node_modules/.bin shims.
+ */
+import posix from "node:path/posix";
+import win32 from "node:path/win32";
+import type { FsRecord } from "../harness.js";
+import { openspecPackageJson, piPackageJson, type PiVersionSpec } from "./pi-versions.js";
+
+export interface ManagedInstallSpec {
+  homedir: string;
+  platform: NodeJS.Platform;
+  pi?: PiVersionSpec | false;
+  openspec?: string | false;
+  tsx?: string | false;
+  /**
+   * If `true`, write just the package.json for pi — no `dist/cli.js`.
+   * Simulates an install that was interrupted mid-extract (scenario E2).
+   */
+  piPartial?: boolean;
+}
+
+export function managedInstall(spec: ManagedInstallSpec): FsRecord {
+  const p = spec.platform === "win32" ? win32 : posix;
+  const out: Record<string, string> = {};
+  const managedDir = p.join(spec.homedir, ".pi-dashboard");
+  const nodeModules = p.join(managedDir, "node_modules");
+  const binDir = p.join(nodeModules, ".bin");
+
+  out[p.join(managedDir, "package.json")] = JSON.stringify({
+    name: "pi-dashboard-managed",
+    private: true,
+    type: "module",
+  });
+
+  if (spec.pi !== false) {
+    const piSpec = spec.pi ?? {};
+    const piDir = p.join(nodeModules, "@mariozechner", "pi-coding-agent");
+    out[p.join(piDir, "package.json")] = piPackageJson(piSpec);
+    if (!spec.piPartial) {
+      out[p.join(piDir, "dist", "cli.js")] = "#!/usr/bin/env node\n// pi cli stub";
+      // bin shim
+      if (spec.platform === "win32") {
+        out[p.join(binDir, "pi.cmd")] = "@node %~dp0\\..\\@mariozechner\\pi-coding-agent\\dist\\cli.js %*";
+      } else {
+        out[p.join(binDir, "pi")] = "#!/bin/sh\nexec node ../@mariozechner/pi-coding-agent/dist/cli.js \"$@\"";
+      }
+    }
+  }
+
+  if (spec.openspec !== false) {
+    const v = spec.openspec ?? "0.4.1";
+    const dir = p.join(nodeModules, "openspec");
+    out[p.join(dir, "package.json")] = openspecPackageJson(v);
+    out[p.join(dir, "dist", "cli.js")] = "#!/usr/bin/env node";
+    out[p.join(dir, "dist", "index.js")] = "module.exports = {};";
+    if (spec.platform === "win32") {
+      out[p.join(binDir, "openspec.cmd")] = "@node %~dp0\\..\\openspec\\dist\\cli.js %*";
+    } else {
+      out[p.join(binDir, "openspec")] = "#!/bin/sh\nexec node ../openspec/dist/cli.js \"$@\"";
+    }
+  }
+
+  if (spec.tsx !== false) {
+    const v = spec.tsx ?? "4.20.0";
+    const dir = p.join(nodeModules, "tsx");
+    out[p.join(dir, "package.json")] = JSON.stringify({
+      name: "tsx",
+      version: v,
+      main: "dist/cli.mjs",
+      bin: { tsx: "dist/cli.mjs" },
+    });
+    out[p.join(dir, "dist", "cli.mjs")] = "#!/usr/bin/env node";
+    if (spec.platform === "win32") {
+      out[p.join(binDir, "tsx.cmd")] = "@node %~dp0\\..\\tsx\\dist\\cli.mjs %*";
+    } else {
+      out[p.join(binDir, "tsx")] = "#!/bin/sh\nexec node ../tsx/dist/cli.mjs \"$@\"";
+    }
+  }
+
+  return out;
+}

package/packages/shared/src/__tests__/bootstrap/fixtures/npm-global-layout.ts

@@ -0,0 +1,122 @@
+/**
+ * Fixture: global npm install layout.
+ *
+ * Posix:   /usr/lib/node_modules/<pkg>/...
+ * Windows: %APPDATA%\Roaming\npm\node_modules\<pkg>\...
+ *          with pi.cmd / openspec.cmd shims in %APPDATA%\Roaming\npm\
+ *
+ * For the "%ProgramFiles%\nodejs" variant on Windows, see
+ * `npmGlobalWindowsProgramFiles` — npm is installed there when users pick
+ * "Add to PATH" during Node.js installer.
+ */
+import posix from "node:path/posix";
+import win32 from "node:path/win32";
+import type { FsRecord } from "../harness.js";
+import { openspecPackageJson, piPackageJson, type PiVersionSpec } from "./pi-versions.js";
+
+interface PosixSpec {
+  pi?: PiVersionSpec | false;
+  openspec?: string | false;
+  /** Install root; defaults to `/usr/lib/node_modules`. */
+  root?: string;
+  binDir?: string;
+}
+
+interface WindowsSpec {
+  pi?: PiVersionSpec | false;
+  openspec?: string | false;
+  dashboard?: boolean;
+  /** Where %APPDATA%\Roaming\npm lives. */
+  npmDir?: string;
+}
+
+/**
+ * Unix global npm install. Root defaults to `/usr/lib/node_modules`,
+ * binaries at `/usr/local/bin`.
+ */
+export function npmGlobalUnix(spec: PosixSpec = {}): FsRecord {
+  const p = posix;
+  const root = spec.root ?? "/usr/lib/node_modules";
+  const binDir = spec.binDir ?? "/usr/local/bin";
+  const out: Record<string, string> = {};
+
+  if (spec.pi !== false) {
+    const piSpec = spec.pi ?? {};
+    const piDir = p.join(root, "@mariozechner", "pi-coding-agent");
+    out[p.join(piDir, "package.json")] = piPackageJson(piSpec);
+    out[p.join(piDir, "dist", "cli.js")] = "#!/usr/bin/env node";
+    out[p.join(binDir, "pi")] = "#!/bin/sh\nexec node ...";
+  }
+
+  if (spec.openspec !== false) {
+    // openspec tool definition uses package `@fission-ai/openspec`
+    // with entry `bin/openspec.js` (see definitions.ts).
+    const dir = p.join(root, "@fission-ai", "openspec");
+    out[p.join(dir, "package.json")] = JSON.stringify({
+      name: "@fission-ai/openspec",
+      version: spec.openspec ?? "0.4.1",
+      bin: { openspec: "bin/openspec.js" },
+    });
+    out[p.join(dir, "bin", "openspec.js")] = "#!/usr/bin/env node";
+    out[p.join(binDir, "openspec")] = "#!/bin/sh\nexec node ...";
+  }
+
+  return out;
+}
+
+/**
+ * Windows AppData\Roaming\npm layout — the default for MSI installs of
+ * Node.js. `npmDir` overrides the location.
+ */
+export function npmGlobalWindowsAppData(
+  homedir: string,
+  spec: WindowsSpec = {},
+): FsRecord {
+  const p = win32;
+  const npmDir = spec.npmDir ?? p.join(homedir, "AppData", "Roaming", "npm");
+  const nodeModules = p.join(npmDir, "node_modules");
+  const out: Record<string, string> = {};
+
+  if (spec.pi !== false) {
+    const piSpec = spec.pi ?? {};
+    const piDir = p.join(nodeModules, "@mariozechner", "pi-coding-agent");
+    out[p.join(piDir, "package.json")] = piPackageJson(piSpec);
+    out[p.join(piDir, "dist", "cli.js")] = "#!/usr/bin/env node";
+    out[p.join(npmDir, "pi.cmd")] = "@node %~dp0\\node_modules\\@mariozechner\\pi-coding-agent\\dist\\cli.js %*";
+  }
+
+  if (spec.openspec !== false) {
+    const dir = p.join(nodeModules, "@fission-ai", "openspec");
+    out[p.join(dir, "package.json")] = JSON.stringify({
+      name: "@fission-ai/openspec",
+      version: spec.openspec ?? "0.4.1",
+      bin: { openspec: "bin/openspec.js" },
+    });
+    out[p.join(dir, "bin", "openspec.js")] = "#!/usr/bin/env node";
+    out[p.join(npmDir, "openspec.cmd")] = "@node %~dp0\\node_modules\\@fission-ai\\openspec\\bin\\openspec.js %*";
+  }
+
+  if (spec.dashboard) {
+    const dir = p.join(nodeModules, "@blackbelt-technology", "pi-agent-dashboard");
+    out[p.join(dir, "package.json")] = JSON.stringify({
+      name: "@blackbelt-technology/pi-agent-dashboard",
+      version: "0.4.0",
+      bin: { "pi-dashboard": "packages/server/dist/cli.js" },
+    });
+    out[p.join(dir, "packages", "server", "dist", "cli.js")] = "#!/usr/bin/env node";
+    out[p.join(npmDir, "pi-dashboard.cmd")] = "@node %~dp0\\node_modules\\@blackbelt-technology\\pi-agent-dashboard\\packages\\server\\dist\\cli.js %*";
+  }
+
+  return out;
+}
+
+/**
+ * Windows %ProgramFiles%\nodejs\node_modules layout — picked when Node
+ * installer chose "install as system tool."
+ */
+export function npmGlobalWindowsProgramFiles(spec: WindowsSpec = {}): FsRecord {
+  return npmGlobalWindowsAppData("C:\\Program Files\\nodejs_", {
+    ...spec,
+    npmDir: "C:\\Program Files\\nodejs",
+  });
+}

package/packages/shared/src/__tests__/bootstrap/fixtures/pi-versions.ts

@@ -0,0 +1,36 @@
+/**
+ * Fixture: stamp a specific version into a pi-coding-agent package.json.
+ * Returns the package.json JSON string ready for FsRecord insertion.
+ */
+export interface PiVersionSpec {
+  name?: string;
+  version?: string;
+  bin?: Record<string, string>;
+  main?: string;
+}
+
+export function piPackageJson(spec: PiVersionSpec = {}): string {
+  return JSON.stringify(
+    {
+      name: spec.name ?? "@mariozechner/pi-coding-agent",
+      version: spec.version ?? "0.6.3",
+      main: spec.main ?? "dist/cli.js",
+      bin: spec.bin ?? { pi: "dist/cli.js" },
+    },
+    null,
+    2,
+  );
+}
+
+export function openspecPackageJson(version = "0.4.1"): string {
+  return JSON.stringify(
+    {
+      name: "openspec",
+      version,
+      main: "dist/index.js",
+      bin: { openspec: "dist/cli.js" },
+    },
+    null,
+    2,
+  );
+}

package/packages/shared/src/__tests__/bootstrap/fixtures/settings-json.ts

@@ -0,0 +1,39 @@
+/**
+ * Fixture: `<homedir>/.pi/agent/settings.json` — pi's extension registry.
+ *
+ * Supports:
+ *   - valid { packages: [...] }
+ *   - empty/missing (return no entry)
+ *   - malformed (broken JSON)
+ *   - extra non-dashboard packages (preservation test)
+ */
+import posix from "node:path/posix";
+import win32 from "node:path/win32";
+import type { FsRecord } from "../harness.js";
+
+export interface SettingsJsonSpec {
+  homedir: string;
+  platform: NodeJS.Platform;
+  packages?: readonly string[];
+  /** If true, write broken JSON instead of a valid object. */
+  malformed?: boolean;
+  /** If true, omit the file entirely. */
+  missing?: boolean;
+}
+
+export function settingsJsonPath(homedir: string, platform: NodeJS.Platform): string {
+  const p = platform === "win32" ? win32 : posix;
+  return p.join(homedir, ".pi", "agent", "settings.json");
+}
+
+export function settingsJson(spec: SettingsJsonSpec): FsRecord {
+  if (spec.missing) return {};
+  const out: Record<string, string> = {};
+  const path = settingsJsonPath(spec.homedir, spec.platform);
+  if (spec.malformed) {
+    out[path] = "{broken json here";
+    return out;
+  }
+  out[path] = JSON.stringify({ packages: spec.packages ?? [] }, null, 2) + "\n";
+  return out;
+}

package/packages/shared/src/__tests__/bootstrap/harness.smoke.test.ts

@@ -0,0 +1,220 @@
+/**
+ * Smoke tests — validate the harness itself, not any real scenario.
+ * Full scenario families (A–K) land in later tasks.
+ */
+import { describe, expect, it } from "vitest";
+import { withFakeEnv, layer, toMemfsPath } from "./harness.js";
+import {
+  registerDefaultTools,
+} from "../../tool-registry/definitions.js";
+import { registerBridgeExtension } from "../../bridge-register.js";
+
+describe("harness smoke", () => {
+  it("withFakeEnv runs callback with HarnessContext (posix)", async () => {
+    const result = await withFakeEnv(
+      {
+        platform: "linux",
+        homedir: "/home/robson",
+        env: { PATH: "/usr/bin:/usr/local/bin" },
+        fs: { "/home/robson/.pi/config": "x" },
+      },
+      (ctx) => {
+        expect(ctx.platform).toBe("linux");
+        expect(ctx.homedir).toBe("/home/robson");
+        expect(ctx.pathEntries).toEqual(["/usr/bin", "/usr/local/bin"]);
+        expect(ctx.fs.existsSync("/home/robson/.pi/config")).toBe(true);
+        return 42;
+      },
+    );
+    expect(result).toBe(42);
+  });
+
+  it("withFakeEnv supports win32 paths via translation", async () => {
+    await withFakeEnv(
+      {
+        platform: "win32",
+        homedir: "C:\\Users\\Robert",
+        env: { PATH: "C:\\Windows\\System32;C:\\Program Files\\nodejs" },
+        fs: {
+          "C:\\Users\\Robert\\.pi-dashboard\\node_modules\\.bin\\pi.cmd":
+            "@node pi",
+        },
+      },
+      (ctx) => {
+        expect(ctx.pathEntries).toEqual([
+          "C:\\Windows\\System32",
+          "C:\\Program Files\\nodejs",
+        ]);
+        // existsSync via the wrapped fs should accept win32-style paths
+        expect(
+          ctx.fs.existsSync(
+            "C:\\Users\\Robert\\.pi-dashboard\\node_modules\\.bin\\pi.cmd",
+          ),
+        ).toBe(true);
+      },
+    );
+  });
+
+  it("toMemfsPath translates Windows paths to posix keys", () => {
+    expect(toMemfsPath("C:\\Users\\Robert\\.pi")).toBe("/C:/Users/Robert/.pi");
+    expect(toMemfsPath("/already/posix")).toBe("/already/posix");
+  });
+
+  it("which() walks fake PATH and finds binaries with .cmd on win32", async () => {
+    await withFakeEnv(
+      {
+        platform: "win32",
+        homedir: "C:\\Users\\R",
+        env: { PATH: "C:\\bin" },
+        fs: { "C:\\bin\\pi.cmd": "@echo off" },
+      },
+      (ctx) => {
+        const deps = ctx.createStrategyDeps();
+        expect(deps.which("pi")).toBe("C:\\bin\\pi.cmd");
+        expect(deps.which("nonexistent")).toBe(null);
+      },
+    );
+  });
+
+  it("which() on posix finds binary without extension", async () => {
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir: "/home/r",
+        env: { PATH: "/usr/local/bin" },
+        fs: { "/usr/local/bin/pi": "#!/bin/sh\nexec node pi.js" },
+      },
+      (ctx) => {
+        const deps = ctx.createStrategyDeps();
+        expect(deps.which("pi")).toBe("/usr/local/bin/pi");
+      },
+    );
+  });
+
+  it("resolveModule() walks node_modules ancestor chain", async () => {
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir: "/home/r",
+        fs: {
+          "/home/r/project/src/index.ts": "x",
+          "/home/r/project/node_modules/@mariozechner/pi/package.json":
+            JSON.stringify({ name: "@mariozechner/pi", main: "dist/cli.js" }),
+          "/home/r/project/node_modules/@mariozechner/pi/dist/cli.js":
+            "#!/usr/bin/env node",
+        },
+      },
+      (ctx) => {
+        const deps = ctx.createStrategyDeps();
+        const resolved = deps.resolveModule(
+          "@mariozechner/pi",
+          "/home/r/project/src/index.ts",
+        );
+        expect(resolved).toBe(
+          "/home/r/project/node_modules/@mariozechner/pi/dist/cli.js",
+        );
+      },
+    );
+  });
+
+  it("resolveModule() returns null when package absent", async () => {
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir: "/home/r",
+        fs: { "/home/r/project/src/index.ts": "x" },
+      },
+      (ctx) => {
+        const deps = ctx.createStrategyDeps();
+        expect(
+          deps.resolveModule("@mariozechner/pi", "/home/r/project/src/index.ts"),
+        ).toBe(null);
+      },
+    );
+  });
+
+  it("layer() merges fs records (later overrides earlier)", () => {
+    const merged = layer(
+      { "/a": "1", "/b": "2" },
+      { "/b": "3", "/c": "4" },
+    );
+    expect(merged).toEqual({ "/a": "1", "/b": "3", "/c": "4" });
+  });
+
+  it("createRegistry wires env and platform through to strategies (linux, managed bin)", async () => {
+    // On Unix, pi resolves via <managedBin>/pi (the `.bin` shim).
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir: "/home/r",
+        fs: {
+          "/home/r/.pi-dashboard/node_modules/.bin/pi":
+            "#!/usr/bin/env node",
+        },
+      },
+      (ctx) => {
+        const registry = ctx.createRegistry();
+        const deps = ctx.createStrategyDeps();
+        registerDefaultTools(registry, deps);
+        const res = registry.resolve("pi");
+        expect(res.ok).toBe(true);
+        expect(res.source).toBe("managed");
+        expect(res.path).toBe("/home/r/.pi-dashboard/node_modules/.bin/pi");
+      },
+    );
+  });
+
+  it("createRegistry resolves pi via managed module on win32", async () => {
+    // On Windows, pi's chain includes managedModuleStrategy for
+    // pi-coding-agent — finds dist/cli.js directly.
+    await withFakeEnv(
+      {
+        platform: "win32",
+        homedir: "C:\\Users\\R",
+        fs: {
+          "C:\\Users\\R\\.pi-dashboard\\node_modules\\@mariozechner\\pi-coding-agent\\dist\\cli.js":
+            "#!/usr/bin/env node",
+        },
+      },
+      (ctx) => {
+        const registry = ctx.createRegistry();
+        const deps = ctx.createStrategyDeps();
+        registerDefaultTools(registry, deps);
+        const res = registry.resolve("pi");
+        expect(res.ok).toBe(true);
+        expect(res.source).toBe("managed");
+      },
+    );
+  });
+
+  it("readSettings returns null when settings.json absent", async () => {
+    await withFakeEnv(
+      { platform: "linux", homedir: "/home/r", fs: {} },
+      (ctx) => {
+        expect(ctx.readSettings()).toBe(null);
+      },
+    );
+  });
+
+  it("bridge registration writes settings.json under fake HOME", async () => {
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir: "/home/r",
+        fs: {
+          "/opt/extension/package.json": JSON.stringify({ name: "ext" }),
+        },
+      },
+      (ctx) => {
+        // Register bridge using the homedir override, but the real
+        // implementation uses `node:fs` — which means this assertion
+        // verifies the API signature compiles. Actual fake-fs bridge
+        // writes land in a follow-up task (bridge-register needs to
+        // accept an injectable fs impl; out of scope for smoke).
+        expect(() =>
+          registerBridgeExtension("/opt/extension", { homedir: "/tmp/nope" }),
+        ).not.toThrow();
+      },
+    );
+  });
+});