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

package/packages/shared/src/__tests__/bootstrap/families/h-home-drift.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Family H — HOME drift scenarios.
+ *
+ * H1: home-drift-git-bash  — Windows: $HOME=/c/Users/R set by Git Bash,
+ *     USERPROFILE=C:\Users\R, os.homedir()=C:\Users\R. All paths must
+ *     canonicalize to the same settings.json location.
+ * H2: home-symlink         — posix: homedir is a symlink (common with
+ *     filevault / dotfile managers). Today the harness does not
+ *     simulate symlinks (memfs limitation), so H2 is documented and
+ *     covered by scenarios-skipped.ts. This file adds a placeholder
+ *     test documenting the invariant.
+ *
+ * These scenarios exercise `registerBridgeExtension`'s homedir
+ * resolution. They don't touch ToolRegistry (bridge registration is
+ * an independent resolution problem per design §2).
+ */
+import { describe, expect, it } from "vitest";
+import { withFakeEnv } from "../harness.js";
+import * as fixtures from "../fixtures/index.js";
+import { register, SKIPPED_SCENARIOS, cellKey } from "../scenarios.js";
+
+const H = [
+  { platform: "win32", dash: "managed", pi: "present-valid", settings: "valid", env: "home-drift" },
+] as const;
+for (const cell of H) {
+  register(cell, "families/h-home-drift.test.ts");
+  SKIPPED_SCENARIOS.delete(cellKey(cell));
+}
+
+describe("Family H — HOME drift", () => {
+  it("H1 — Git Bash \\$HOME vs USERPROFILE both reach same canonical homedir", async () => {
+    // This test documents the EXPECTED behavior. Full enforcement
+    // lives in `single-dashboard-per-home` (Layer 0 canonicalization).
+    // Here we only verify that `registerBridgeExtension` accepts an
+    // explicit homedir and uses it over env vars.
+    const canonicalHome = "C:\\Users\\R";
+    await withFakeEnv(
+      {
+        platform: "win32",
+        homedir: canonicalHome,
+        env: {
+          // Simulated drift: $HOME disagrees with USERPROFILE. The
+          // explicit `{ homedir }` argument SHOULD win over env vars.
+          HOME: "/c/Users/R",
+          USERPROFILE: canonicalHome,
+        },
+        fs: fixtures.settingsJson({
+          homedir: canonicalHome,
+          platform: "win32",
+          packages: [],
+        }),
+      },
+      (ctx) => {
+        // Harness provides the fake homedir to registerBridgeExtension
+        // via the new opts arg. We don't actually call it here (it
+        // uses real fs) — instead we assert the settings.json path
+        // the harness reports matches the canonical homedir.
+        const settings = ctx.readSettings();
+        expect(settings).not.toBeNull();
+        expect(settings).toEqual({ packages: [] });
+      },
+    );
+  });
+});

package/packages/shared/src/__tests__/bootstrap/families/i-malformed-settings.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Family I — settings.json shape variants.
+ *
+ * I1: malformed-settings     — broken JSON in settings.json.
+ * I2: settings-other-packages — settings contains unrelated extensions
+ *     that MUST be preserved across bridge registration.
+ *
+ * Bridge-registration semantics live in `registerBridgeExtension`,
+ * which uses node:fs directly. The harness can only assert input
+ * (fake settings.json shape visible via readSettings) — full round-trip
+ * asserting preservation lands when bridge-register is refactored
+ * to accept an injectable fs (future task, cross-proposal).
+ */
+import { describe, expect, it } from "vitest";
+import { withFakeEnv } from "../harness.js";
+import * as fixtures from "../fixtures/index.js";
+import { register, SKIPPED_SCENARIOS, cellKey } from "../scenarios.js";
+
+const I = [
+  { platform: "linux", dash: "managed", pi: "present-valid", settings: "malformed", env: "normal" },
+] as const;
+for (const cell of I) {
+  register(cell, "families/i-malformed-settings.test.ts");
+  SKIPPED_SCENARIOS.delete(cellKey(cell));
+}
+
+describe("Family I — settings.json variants", () => {
+  it("I1 — malformed JSON surfaces as null from readSettings", async () => {
+    const homedir = "/home/r";
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir,
+        fs: fixtures.settingsJson({
+          homedir,
+          platform: "linux",
+          malformed: true,
+        }),
+      },
+      (ctx) => {
+        // readSettings returns null for malformed JSON — tolerant
+        // fallback behavior. Consumers (registerBridgeExtension)
+        // treat null as "start fresh".
+        expect(ctx.readSettings()).toBeNull();
+      },
+    );
+  });
+
+  it("I2 — settings with unrelated packages is preserved in fixture", async () => {
+    const homedir = "/home/r";
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir,
+        fs: fixtures.settingsJson({
+          homedir,
+          platform: "linux",
+          packages: [
+            "/home/r/.pi/extensions/custom-pkg",
+            "/home/r/.pi/extensions/another-pkg",
+          ],
+        }),
+      },
+      (ctx) => {
+        const settings = ctx.readSettings();
+        expect(settings).toEqual({
+          packages: [
+            "/home/r/.pi/extensions/custom-pkg",
+            "/home/r/.pi/extensions/another-pkg",
+          ],
+        });
+        // Full round-trip preservation test: pending bridge-register
+        // fs injection. Asserted at input side only for now.
+      },
+    );
+  });
+});

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

@@ -0,0 +1,19 @@
+/**
+ * Family-test barrel — imports every family file for its registration
+ * side-effects so `cube.test.ts` can sweep a fully-populated
+ * REGISTERED_SCENARIOS map.
+ *
+ * Each family file registers at module top-level via `register(cell, tag)`.
+ * When a new family file is added, import it here.
+ */
+import "./a-electron.test.js";
+import "./b-npm-global.test.js";
+import "./c-dev-monorepo.test.js";
+import "./d-overrides.test.js";
+import "./e-stale-partial.test.js";
+import "./f-cwd-variants.test.js";
+import "./g-windows-specifics.test.js";
+import "./h-home-drift.test.js";
+import "./i-malformed-settings.test.js";
+import "./j-path-gui-minimal.test.js";
+import "./k-dashboard-absent.test.js";

package/packages/shared/src/__tests__/bootstrap/families/j-path-gui-minimal.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Family J — minimal PATH (GUI-launched processes).
+ *
+ * J1: path-gui-minimal — PATH contains only /usr/bin (no /usr/local/bin,
+ *     no ~/.npm). Typical of GUI-launched processes on macOS/Linux.
+ *     Resolution should still succeed via npm-global strategy, which
+ *     uses `npm root -g` not PATH.
+ */
+import { describe, expect, it } from "vitest";
+import { withFakeEnv } from "../harness.js";
+import { registerDefaultTools } from "../../../tool-registry/definitions.js";
+import * as fixtures from "../fixtures/index.js";
+import { snapshotTrail } from "../assertions.js";
+import { register, SKIPPED_SCENARIOS, cellKey } from "../scenarios.js";
+
+const J = [
+  // Use "absent" dash axis — the dashboard itself isn't relevant; we
+  // only care about pi resolution.
+  { platform: "linux", dash: "absent", pi: "present-valid", settings: "empty", env: "normal" },
+] as const;
+for (const cell of J) {
+  register(cell, "families/j-path-gui-minimal.test.ts");
+  SKIPPED_SCENARIOS.delete(cellKey(cell));
+}
+
+describe("Family J — minimal PATH", () => {
+  it("J1 — GUI-launched minimal PATH: pi does NOT resolve on posix (limitation)", async () => {
+    const homedir = "/home/r";
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir,
+        // The minimal PATH a macOS GUI-launched app sees by default.
+        env: { PATH: "/usr/bin" },
+        // pi + openspec live in /usr/local/bin, NOT in PATH.
+        fs: fixtures.npmGlobalUnix({
+          root: "/usr/lib/node_modules",
+          binDir: "/usr/local/bin",
+        }),
+        npmRootGlobal: "/usr/lib/node_modules",
+      },
+      (ctx) => {
+        const registry = ctx.createRegistry();
+        registerDefaultTools(registry, ctx.createStrategyDeps());
+        const res = registry.resolve("pi");
+        // On Unix, the pi chain is override → managed-bin → where.
+        // npm-g strategy is NOT in the Unix pi chain; with PATH missing
+        // `/usr/local/bin`, `where` can't find pi either. This is a
+        // real limitation worth locking in via snapshot — if a future
+        // change adds npm-g to the Unix pi chain, this test surfaces
+        // it loudly.
+        expect(res.ok).toBe(false);
+        expect(snapshotTrail(res, ctx)).toMatchSnapshot();
+
+        // Same limitation for openspec on Unix.
+        const os = registry.resolve("openspec");
+        expect(os.ok).toBe(false);
+      },
+    );
+  });
+});

package/packages/shared/src/__tests__/bootstrap/families/k-dashboard-absent.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Family K — dashboard absent.
+ *
+ * K1: no dashboard anywhere; pi present. Registry behaves normally for
+ *     pi. The dashboard itself isn't registered in ToolRegistry (it's
+ *     the package this code is part of), so "dashboard absent" is
+ *     observable only at the dependency-detector level — out of scope
+ *     for this family.
+ *
+ * Kept as a minimal registration + assertion so the cell appears in
+ * the cube.
+ */
+import { describe, expect, it } from "vitest";
+import { withFakeEnv } from "../harness.js";
+import { registerDefaultTools } from "../../../tool-registry/definitions.js";
+import * as fixtures from "../fixtures/index.js";
+import { register, SKIPPED_SCENARIOS, cellKey } from "../scenarios.js";
+
+const K = [
+  { platform: "linux", dash: "absent", pi: "present-valid", settings: "valid", env: "normal" },
+] as const;
+for (const cell of K) {
+  register(cell, "families/k-dashboard-absent.test.ts");
+  SKIPPED_SCENARIOS.delete(cellKey(cell));
+}
+
+describe("Family K — dashboard absent", () => {
+  it("pi still resolves when no dashboard binary is installed", async () => {
+    const homedir = "/home/r";
+    await withFakeEnv(
+      {
+        platform: "linux",
+        homedir,
+        fs: fixtures.managedInstall({ homedir, platform: "linux" }),
+      },
+      (ctx) => {
+        const registry = ctx.createRegistry();
+        registerDefaultTools(registry, ctx.createStrategyDeps());
+        const res = registry.resolve("pi");
+        expect(res.ok).toBe(true);
+        expect(res.source).toBe("managed");
+        // "Dashboard absence" is not observable at the registry level —
+        // the dashboard isn't a registered tool. The observation
+        // happens at `dependency-detector.ts:detectPiDashboardCli()`
+        // via `which pi-dashboard`. Covered by dependency-detector
+        // unit tests, not this harness.
+      },
+    );
+  });
+});

package/packages/shared/src/__tests__/bootstrap/families/l-instance-coordination.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Family L — Instance coordination (per-HOME advisory lock).
+ *
+ * Covers the scenarios enumerated in
+ * `openspec/changes/single-dashboard-per-home/design.md §10`:
+ *
+ *   L1  no prior dashboard              → acquire
+ *   L2  healthy dashboard same port     → attach
+ *   L3  healthy dashboard diff port     → attach via metadata URL
+ *   L4  stale lock (PID dead)           → steal + start
+ *   L5  stale PID + port free           → steal + clean + start
+ *   L6  stale PID + port taken by       → identity mismatch error
+ *       unrelated process
+ *   L7  mDNS disabled                   → lock still works (same as L2)
+ *   L9  multi-user                      → separate HOMEs, separate locks
+ *   L10 HOME symlink                    → realpath canonicalization
+ *   L11 identity mismatch               → error, no attach, no start
+ *   L12 corrupt metadata                → treat as stale, steal
+ *
+ * L8 (concurrent launch) and L13 (permission denied) live in integration
+ * tests (`concurrent-launch.test.ts`, `crash-recovery.test.ts`) because
+ * they require real processes / real filesystems.
+ *
+ * Note: this family does NOT use the cube enumeration. The 5-axis cube
+ * does not model lock state; adding it would 4x the cell count. Family L
+ * is registered as a separate enumeration here (design decision: the
+ * simpler option from design §Precondition item 2b).
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  acquireOrAttach,
+  readMetadata,
+  writeMetadataAtomic,
+  canonicalHomedir,
+  getLockPath,
+  InstanceLockMismatchError,
+  type LockMetadata,
+} from "../../../../../server/src/home-lock.js";
+
+let tmpHome: string;
+let lockPath: string;
+let metaPath: string;
+
+beforeEach(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-family-l-"));
+  lockPath = path.join(tmpHome, ".pi", "dashboard", "server.lock");
+  metaPath = `${lockPath}.meta.json`;
+});
+
+afterEach(() => {
+  try { fs.rmSync(tmpHome, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+const baseCfg = (over: Partial<Parameters<typeof acquireOrAttach>[0]> = {}) => ({
+  httpPort: 8000,
+  piPort: 9999,
+  version: "0.0.0-test",
+  hooks: {
+    lockPath, metaPath, staleMs: 500,
+    probeHealth: async () => ({ running: false }),
+    isProcessAlive: () => false,
+    ...(over.hooks ?? {}),
+  },
+  ...over,
+});
+
+describe("Family L — instance coordination", () => {
+  it("L1 — no prior dashboard: acquires cleanly", async () => {
+    const r = await acquireOrAttach(baseCfg());
+    expect(r.mode).toBe("acquired");
+    if (r.mode === "acquired") await r.release();
+  });
+
+  it("L2 — healthy dashboard same port: attaches", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "live-1" }));
+    expect(first.mode).toBe("acquired");
+
+    const second = await acquireOrAttach(baseCfg({
+      hooks: {
+        lockPath, metaPath, staleMs: 500,
+        isProcessAlive: () => true,
+        probeHealth: async () => ({ running: true, identity: "live-1", pid: process.pid }),
+      },
+    }));
+    expect(second.mode).toBe("attach");
+    if (first.mode === "acquired") await first.release();
+  });
+
+  it("L3 — healthy dashboard on different port: attaches via metadata URL", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "live-3", httpPort: 8765 }));
+    expect(first.mode).toBe("acquired");
+
+    // New caller asks for port 9001, but lock meta says live on 8765.
+    const second = await acquireOrAttach(baseCfg({
+      httpPort: 9001,
+      hooks: {
+        lockPath, metaPath, staleMs: 500,
+        isProcessAlive: () => true,
+        // Probe only returns alive for the correct port (8765).
+        probeHealth: async (port) =>
+          port === 8765
+            ? { running: true, identity: "live-3", pid: process.pid }
+            : { running: false },
+      },
+    }));
+    expect(second.mode).toBe("attach");
+    if (second.mode === "attach") {
+      expect(second.meta.httpPort).toBe(8765);
+      expect(second.meta.url).toContain("8765");
+    }
+    if (first.mode === "acquired") await first.release();
+  });
+
+  it("L4 — stale lock, PID dead: steals + starts", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "dead-holder" }));
+    expect(first.mode).toBe("acquired");
+    // Don't release — simulate crash.
+    await new Promise(r => setTimeout(r, 50));
+
+    const second = await acquireOrAttach(baseCfg({
+      hooks: {
+        lockPath, metaPath, staleMs: 1,
+        isProcessAlive: () => false,
+        probeHealth: async () => ({ running: false }),
+      },
+    }));
+    expect(second.mode).toBe("acquired");
+    if (second.mode === "acquired") await second.release();
+  });
+
+  it("L5 — stale PID + port free: clean steal", async () => {
+    // Write stale metadata manually, with no active lockfile yet.
+    fs.mkdirSync(path.dirname(metaPath), { recursive: true });
+    const staleMeta: LockMetadata = {
+      pid: 1, ppid: 0, httpPort: 8000, piPort: 9999,
+      startedAt: 0, identity: "ghost", version: "0", url: "http://localhost:8000", hostname: "h",
+    };
+    writeMetadataAtomic(staleMeta, metaPath);
+
+    const r = await acquireOrAttach(baseCfg());
+    expect(r.mode).toBe("acquired");
+    if (r.mode === "acquired") {
+      expect(r.meta.identity).not.toBe("ghost");
+      await r.release();
+    }
+  });
+
+  it("L6 — stale PID + port taken by unrelated process: identity mismatch", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "legit" }));
+    expect(first.mode).toBe("acquired");
+
+    // Simulate: lock is alive-ish, but health returns a different identity
+    // (port commandeered by something else with same pid reuse).
+    await expect(
+      acquireOrAttach(baseCfg({
+        hooks: {
+          lockPath, metaPath, staleMs: 500,
+          isProcessAlive: () => true,
+          probeHealth: async () => ({ running: true, identity: "hostile-squatter" }),
+        },
+      })),
+    ).rejects.toBeInstanceOf(InstanceLockMismatchError);
+
+    if (first.mode === "acquired") await first.release();
+  });
+
+  it("L7 — mDNS disabled: lock path unaffected (parity with L2)", async () => {
+    // mDNS is orthogonal to the lock; exercise the same L2 flow to document
+    // that lock acquisition does NOT depend on mDNS discovery.
+    const first = await acquireOrAttach(baseCfg({ identity: "no-mdns" }));
+    expect(first.mode).toBe("acquired");
+
+    const second = await acquireOrAttach(baseCfg({
+      hooks: {
+        lockPath, metaPath, staleMs: 500,
+        isProcessAlive: () => true,
+        probeHealth: async () => ({ running: true, identity: "no-mdns", pid: process.pid }),
+      },
+    }));
+    expect(second.mode).toBe("attach");
+    if (first.mode === "acquired") await first.release();
+  });
+
+  it("L9 — multi-user: two HOMEs, two locks, no interference", async () => {
+    const homeA = fs.mkdtempSync(path.join(os.tmpdir(), "pi-user-a-"));
+    const homeB = fs.mkdtempSync(path.join(os.tmpdir(), "pi-user-b-"));
+    try {
+      const lockA = path.join(homeA, ".pi", "dashboard", "server.lock");
+      const metaA = `${lockA}.meta.json`;
+      const lockB = path.join(homeB, ".pi", "dashboard", "server.lock");
+      const metaB = `${lockB}.meta.json`;
+
+      const a = await acquireOrAttach({
+        httpPort: 8000, piPort: 9999, version: "t",
+        hooks: { lockPath: lockA, metaPath: metaA, staleMs: 500 },
+      });
+      const b = await acquireOrAttach({
+        httpPort: 8001, piPort: 9998, version: "t",
+        hooks: { lockPath: lockB, metaPath: metaB, staleMs: 500 },
+      });
+      expect(a.mode).toBe("acquired");
+      expect(b.mode).toBe("acquired");
+      if (a.mode === "acquired") await a.release();
+      if (b.mode === "acquired") await b.release();
+    } finally {
+      fs.rmSync(homeA, { recursive: true, force: true });
+      fs.rmSync(homeB, { recursive: true, force: true });
+    }
+  });
+
+  it("L10 — HOME symlink: realpath canonicalizes to the same lock", async () => {
+    const real = fs.mkdtempSync(path.join(os.tmpdir(), "pi-real-home-"));
+    const link = path.join(os.tmpdir(), `pi-link-home-${Date.now()}-${Math.random()}`);
+    fs.symlinkSync(real, link);
+    try {
+      // Both paths resolve via realpath → same canonical HOME.
+      expect(fs.realpathSync(link)).toBe(fs.realpathSync(real));
+      // canonicalHomedir() uses os.homedir() so we can't mock without
+      // globals; the invariant is tested via fs.realpathSync equivalence.
+      expect(typeof canonicalHomedir()).toBe("string");
+    } finally {
+      try { fs.unlinkSync(link); } catch { /* ignore */ }
+      fs.rmSync(real, { recursive: true, force: true });
+    }
+  });
+
+  it("L11 — identity mismatch: throws, no attach, no start", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "me" }));
+    expect(first.mode).toBe("acquired");
+
+    await expect(
+      acquireOrAttach(baseCfg({
+        hooks: {
+          lockPath, metaPath, staleMs: 500,
+          isProcessAlive: () => true,
+          probeHealth: async () => ({ running: true, identity: "not-me", pid: 99999 }),
+        },
+      })),
+    ).rejects.toBeInstanceOf(InstanceLockMismatchError);
+
+    // Verify no new metadata has been written with a different identity
+    const meta = readMetadata(metaPath);
+    expect(meta?.identity).toBe("me");
+
+    if (first.mode === "acquired") await first.release();
+  });
+
+  it("L12 — corrupt metadata: treated as stale, steal", async () => {
+    const first = await acquireOrAttach(baseCfg({ identity: "intact" }));
+    expect(first.mode).toBe("acquired");
+
+    // Corrupt the metadata file.
+    fs.writeFileSync(metaPath, "{broken json");
+    await new Promise(r => setTimeout(r, 50));
+
+    const second = await acquireOrAttach(baseCfg({
+      hooks: {
+        lockPath, metaPath, staleMs: 1,
+        isProcessAlive: () => false,
+        probeHealth: async () => ({ running: false }),
+      },
+    }));
+    expect(second.mode).toBe("acquired");
+    if (second.mode === "acquired") {
+      expect(second.meta.identity).not.toBe("intact");
+      await second.release();
+    }
+  });
+});

package/packages/shared/src/__tests__/bootstrap/fixtures/dev-monorepo.ts

@@ -0,0 +1,58 @@
+/**
+ * Fixture: dev monorepo layout (what developers see running from source).
+ *
+ * <root>/
+ *   node_modules/
+ *     @mariozechner/pi-coding-agent/dist/cli.js
+ *     openspec/dist/cli.js
+ *     tsx/dist/cli.mjs
+ *   packages/
+ *     shared/    server/    extension/    electron/
+ *
+ * Used for Family C scenarios (bare-import resolves pi via workspace
+ * node_modules).
+ */
+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 DevMonorepoSpec {
+  root: string;
+  platform: NodeJS.Platform;
+  pi?: PiVersionSpec;
+  openspec?: string;
+}
+
+export function devMonorepo(spec: DevMonorepoSpec): FsRecord {
+  const p = spec.platform === "win32" ? win32 : posix;
+  const nodeModules = p.join(spec.root, "node_modules");
+  const out: Record<string, string> = {};
+
+  // Root package.json (workspace)
+  out[p.join(spec.root, "package.json")] = JSON.stringify({
+    name: "pi-agent-dashboard-root",
+    private: true,
+    workspaces: ["packages/*"],
+  });
+
+  // Workspace packages
+  for (const pkg of ["shared", "server", "extension", "electron", "client"]) {
+    out[p.join(spec.root, "packages", pkg, "package.json")] = JSON.stringify({
+      name: `@blackbelt-technology/pi-dashboard-${pkg}`,
+      version: "0.4.0",
+    });
+  }
+
+  // Hoisted deps
+  const piDir = p.join(nodeModules, "@mariozechner", "pi-coding-agent");
+  out[p.join(piDir, "package.json")] = piPackageJson(spec.pi);
+  out[p.join(piDir, "dist", "cli.js")] = "#!/usr/bin/env node";
+
+  const osDir = p.join(nodeModules, "openspec");
+  out[p.join(osDir, "package.json")] = openspecPackageJson(spec.openspec ?? "0.4.1");
+  out[p.join(osDir, "dist", "cli.js")] = "#!/usr/bin/env node";
+  out[p.join(osDir, "dist", "index.js")] = "module.exports = {};";
+
+  return out;
+}