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

package/packages/shared/src/__tests__/openspec-poller-specs-override.test.ts

@@ -0,0 +1,284 @@
+/**
+ * Verifies `buildOpenSpecData`'s specs-artifact override behavior.
+ * Invariants: promote-only, specs-only, never demote, isComplete only
+ * promoted to true (never demoted from CLI true), no-factory call site
+ * is verbatim back-compat.
+ *
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+import { describe, expect, it } from "vitest";
+import { buildOpenSpecData } from "../openspec-poller.js";
+import type { SpecsEvidenceProbe } from "../openspec-specs-evidence.js";
+
+function specsProbe(satisfied: boolean, calls?: { count: number }): SpecsEvidenceProbe {
+  return {
+    hasAnySpecFile: () => {
+      if (calls) calls.count++;
+      return satisfied;
+    },
+  };
+}
+
+const listResult = {
+  changes: [
+    { name: "x", status: "in-progress", completedTasks: 1, totalTasks: 3 },
+  ],
+};
+
+describe("buildOpenSpecData specs override", () => {
+  it("promotes specs ready→done when probe satisfies", () => {
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [
+            { id: "proposal", status: "done" },
+            { id: "design", status: "done" },
+            { id: "specs", status: "ready" },
+            { id: "tasks", status: "ready" },
+          ],
+          isComplete: false,
+        },
+      ],
+    ]);
+    const data = buildOpenSpecData(
+      listResult,
+      statusResults,
+      undefined, // no design probe
+      () => specsProbe(true),
+    );
+    const x = data.changes[0];
+    expect(x.artifacts.find((a) => a.id === "specs")!.status).toBe("done");
+  });
+
+  it("does NOT promote when probe says not satisfied", () => {
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [{ id: "specs", status: "ready" }],
+        },
+      ],
+    ]);
+    const data = buildOpenSpecData(
+      listResult,
+      statusResults,
+      undefined,
+      () => specsProbe(false),
+    );
+    expect(data.changes[0].artifacts.find((a) => a.id === "specs")!.status).toBe("ready");
+  });
+
+  it("never promotes blocked → done", () => {
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [{ id: "specs", status: "blocked" }],
+        },
+      ],
+    ]);
+    const data = buildOpenSpecData(
+      listResult,
+      statusResults,
+      undefined,
+      () => specsProbe(true),
+    );
+    expect(data.changes[0].artifacts.find((a) => a.id === "specs")!.status).toBe("blocked");
+  });
+
+  it("never demotes done → ready (CLI says done; we trust it)", () => {
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [{ id: "specs", status: "done" }],
+        },
+      ],
+    ]);
+    const data = buildOpenSpecData(
+      listResult,
+      statusResults,
+      undefined,
+      () => specsProbe(false),
+    );
+    expect(data.changes[0].artifacts.find((a) => a.id === "specs")!.status).toBe("done");
+  });
+
+  it("only mutates specs — other artifact statuses pass through", () => {
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [
+            { id: "proposal", status: "ready" },
+            { id: "design", status: "blocked" },
+            { id: "specs", status: "ready" },
+            { id: "tasks", status: "ready" },
+          ],
+        },
+      ],
+    ]);
+    const data = buildOpenSpecData(
+      listResult,
+      statusResults,
+      undefined,
+      () => specsProbe(true),
+    );
+    const arts = data.changes[0].artifacts;
+    expect(arts.find((a) => a.id === "proposal")!.status).toBe("ready");
+    expect(arts.find((a) => a.id === "design")!.status).toBe("blocked");
+    expect(arts.find((a) => a.id === "specs")!.status).toBe("done");
+    expect(arts.find((a) => a.id === "tasks")!.status).toBe("ready");
+  });
+
+  it("re-derives isComplete=true when all artifacts done after override", () => {
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [
+            { id: "proposal", status: "done" },
+            { id: "design", status: "done" },
+            { id: "specs", status: "ready" },
+            { id: "tasks", status: "done" },
+          ],
+          isComplete: false,
+        },
+      ],
+    ]);
+    const data = buildOpenSpecData(
+      listResult,
+      statusResults,
+      undefined,
+      () => specsProbe(true),
+    );
+    expect(data.changes[0].isComplete).toBe(true);
+  });
+
+  it("does NOT promote isComplete when any non-specs artifact is not done", () => {
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [
+            { id: "proposal", status: "done" },
+            { id: "design", status: "ready" },
+            { id: "specs", status: "ready" },
+            { id: "tasks", status: "blocked" },
+          ],
+          isComplete: false,
+        },
+      ],
+    ]);
+    const data = buildOpenSpecData(
+      listResult,
+      statusResults,
+      undefined,
+      () => specsProbe(true),
+    );
+    expect(data.changes[0].isComplete).toBe(false);
+  });
+
+  it("never demotes CLI isComplete=true to false", () => {
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [{ id: "specs", status: "ready" }],
+          isComplete: true,
+        },
+      ],
+    ]);
+    const data = buildOpenSpecData(
+      listResult,
+      statusResults,
+      undefined,
+      () => specsProbe(false),
+    );
+    expect(data.changes[0].isComplete).toBe(true);
+  });
+
+  it("no-factory call site preserves today's behavior verbatim", () => {
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [
+            { id: "specs", status: "ready" },
+            { id: "tasks", status: "blocked" },
+          ],
+          isComplete: false,
+        },
+      ],
+    ]);
+    // Both probe params omitted — must match pre-change behavior verbatim.
+    const data = buildOpenSpecData(listResult, statusResults);
+    expect(data.changes[0].artifacts.find((a) => a.id === "specs")!.status).toBe("ready");
+    expect(data.changes[0].isComplete).toBe(false);
+  });
+
+  it("specs probe factory receives the change name", () => {
+    const seen: string[] = [];
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [{ id: "specs", status: "ready" }],
+        },
+      ],
+    ]);
+    buildOpenSpecData(listResult, statusResults, undefined, (changeName) => {
+      seen.push(changeName);
+      return specsProbe(false);
+    });
+    expect(seen).toContain("x");
+  });
+
+  it("specs probe is NOT consulted when CLI says specs is already done", () => {
+    const calls = { count: 0 };
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [{ id: "specs", status: "done" }],
+        },
+      ],
+    ]);
+    buildOpenSpecData(listResult, statusResults, undefined, () => specsProbe(true, calls));
+    expect(calls.count).toBe(0);
+  });
+
+  it("design and specs overrides compose: both ready, both promoted, isComplete becomes true", () => {
+    const statusResults = new Map<string, any>([
+      [
+        "x",
+        {
+          artifacts: [
+            { id: "proposal", status: "done" },
+            { id: "design", status: "ready" },
+            { id: "specs", status: "ready" },
+            { id: "tasks", status: "done" },
+          ],
+          isComplete: false,
+        },
+      ],
+    ]);
+    const data = buildOpenSpecData(
+      listResult,
+      statusResults,
+      // Design probe satisfies.
+      () => ({
+        hasDesignFile: () => true,
+        hasDesignDirWithMd: () => false,
+        tasksHasCheckboxes: () => false,
+      }),
+      // Specs probe satisfies.
+      () => specsProbe(true),
+    );
+    const arts = data.changes[0].artifacts;
+    expect(arts.find((a) => a.id === "design")!.status).toBe("done");
+    expect(arts.find((a) => a.id === "specs")!.status).toBe("done");
+    expect(data.changes[0].isComplete).toBe(true);
+  });
+});

package/packages/shared/src/__tests__/openspec-specs-evidence.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Tests for the local-specs-evidence override that protects against
+ * cache staleness on multi-spec changes.
+ * See change: fix-openspec-specs-mtime-gate-blind-spot.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdirSync, rmSync, writeFileSync, symlinkSync, chmodSync } from "node:fs";
+import { mkdtempSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import {
+  evaluateLocalSpecsSatisfaction,
+  createFsSpecsEvidenceProbe,
+  type SpecsEvidenceProbe,
+} from "../openspec-specs-evidence.js";
+
+/** In-memory probe stub. */
+function probe(hasAny: boolean): SpecsEvidenceProbe {
+  return { hasAnySpecFile: () => hasAny };
+}
+
+describe("evaluateLocalSpecsSatisfaction", () => {
+  it("returns true when probe reports a spec file present", () => {
+    expect(evaluateLocalSpecsSatisfaction("/c", probe(true))).toBe(true);
+  });
+
+  it("returns false when probe reports no spec file", () => {
+    expect(evaluateLocalSpecsSatisfaction("/c", probe(false))).toBe(false);
+  });
+});
+
+describe("createFsSpecsEvidenceProbe", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(path.join(os.tmpdir(), "specs-evidence-"));
+  });
+
+  afterEach(() => {
+    try {
+      rmSync(tmp, { recursive: true, force: true });
+    } catch {
+      // best-effort cleanup
+    }
+  });
+
+  it("(a) specs/<cap>/spec.md exists → true", () => {
+    mkdirSync(path.join(tmp, "specs", "cap-a"), { recursive: true });
+    writeFileSync(path.join(tmp, "specs", "cap-a", "spec.md"), "## ADDED Requirements\n");
+    expect(createFsSpecsEvidenceProbe().hasAnySpecFile(tmp)).toBe(true);
+  });
+
+  it("(b) empty specs/ directory → false", () => {
+    mkdirSync(path.join(tmp, "specs"), { recursive: true });
+    expect(createFsSpecsEvidenceProbe().hasAnySpecFile(tmp)).toBe(false);
+  });
+
+  it("(c) specs/ does not exist → false (no throw)", () => {
+    // tmp deliberately has no specs/
+    expect(() => createFsSpecsEvidenceProbe().hasAnySpecFile(tmp)).not.toThrow();
+    expect(createFsSpecsEvidenceProbe().hasAnySpecFile(tmp)).toBe(false);
+  });
+
+  it("(d) deep layout specs/<cap>/sub/file.md → true", () => {
+    mkdirSync(path.join(tmp, "specs", "cap-a", "sub"), { recursive: true });
+    writeFileSync(path.join(tmp, "specs", "cap-a", "sub", "file.md"), "deep");
+    expect(createFsSpecsEvidenceProbe().hasAnySpecFile(tmp)).toBe(true);
+  });
+
+  it("(e) flat layout specs/cap.md → true", () => {
+    mkdirSync(path.join(tmp, "specs"), { recursive: true });
+    writeFileSync(path.join(tmp, "specs", "cap.md"), "flat");
+    expect(createFsSpecsEvidenceProbe().hasAnySpecFile(tmp)).toBe(true);
+  });
+
+  it("only counts *.md files (other extensions ignored)", () => {
+    mkdirSync(path.join(tmp, "specs", "cap-a"), { recursive: true });
+    writeFileSync(path.join(tmp, "specs", "cap-a", "notes.txt"), "not a spec");
+    writeFileSync(path.join(tmp, "specs", "cap-a", "schema.json"), "{}");
+    expect(createFsSpecsEvidenceProbe().hasAnySpecFile(tmp)).toBe(false);
+  });
+
+  it("(f) symlinked .md outside specs is NOT counted by virtue of being inside specs anyway when symlinked-in", () => {
+    // Create a sibling .md outside specs/, then symlink it INTO specs/. fs.readdirSync with
+    // withFileTypes returns Dirent.isFile() = false for symlinks; .isSymbolicLink() = true.
+    // Since the probe only treats `.isFile()` as a hit, symlinks are correctly ignored.
+    writeFileSync(path.join(tmp, "outside.md"), "outside the specs tree");
+    mkdirSync(path.join(tmp, "specs", "cap-a"), { recursive: true });
+    try {
+      symlinkSync(
+        path.join(tmp, "outside.md"),
+        path.join(tmp, "specs", "cap-a", "linked.md"),
+      );
+    } catch {
+      // skip on platforms that don't allow symlinks (e.g. Windows without admin)
+      return;
+    }
+    expect(createFsSpecsEvidenceProbe().hasAnySpecFile(tmp)).toBe(false);
+  });
+
+  it("(g) probe never throws on permission errors", () => {
+    // Deny read on specs/. POSIX-only; on Windows chmod is a no-op so we just
+    // assert no throw under the platform's actual semantics.
+    mkdirSync(path.join(tmp, "specs", "cap-a"), { recursive: true });
+    writeFileSync(path.join(tmp, "specs", "cap-a", "spec.md"), "x");
+    try {
+      chmodSync(path.join(tmp, "specs"), 0o000);
+    } catch {
+      // chmod may not be supported on this fs/platform; skip the unreadable case
+    }
+    let result: boolean | "threw" = "threw";
+    try {
+      result = createFsSpecsEvidenceProbe().hasAnySpecFile(tmp);
+    } catch {
+      // restore perms before failing
+      try {
+        chmodSync(path.join(tmp, "specs"), 0o755);
+      } catch {
+        /* ignore */
+      }
+      throw new Error("probe threw on unreadable specs/ — must be defensive");
+    }
+    // restore perms so afterEach cleanup can rm -rf
+    try {
+      chmodSync(path.join(tmp, "specs"), 0o755);
+    } catch {
+      /* ignore */
+    }
+    // result is implementation-defined (true if readable, false if not), but
+    // MUST NOT throw. Both valid outcomes are accepted.
+    expect(typeof result).toBe("boolean");
+  });
+
+  it("short-circuits on first match (does not enumerate further siblings)", () => {
+    // Indirect proof: deeply nested tree with hundreds of empty dirs plus one
+    // spec.md at the root of specs/. Should still return true quickly.
+    mkdirSync(path.join(tmp, "specs"), { recursive: true });
+    writeFileSync(path.join(tmp, "specs", "cap-a.md"), "first");
+    for (let i = 0; i < 50; i++) {
+      mkdirSync(path.join(tmp, "specs", `empty-${i}`), { recursive: true });
+    }
+    expect(createFsSpecsEvidenceProbe().hasAnySpecFile(tmp)).toBe(true);
+  });
+});

package/packages/shared/src/__tests__/platform/is-appimage-self-hit.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Unit tests for isAppImageSelfHit — pure helper that flags candidate
+ * binary paths as the running Electron AppImage launcher (self-hit).
+ *
+ * See change: fix-electron-appimage-cli-self-detection (D1).
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { isAppImageSelfHit } from "../../platform/binary-lookup.js";
+
+describe("isAppImageSelfHit", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "appimage-self-hit-"));
+  });
+
+  afterEach(() => {
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch { /* ignore */ }
+  });
+
+  it("returns false when no env vars are set and execPath is unrelated", () => {
+    const candidate = path.join(tmpDir, "unrelated-binary");
+    fs.writeFileSync(candidate, "#!/bin/sh\n");
+    const result = isAppImageSelfHit(candidate, {
+      execPath: "/totally/different/electron",
+      appDir: undefined,
+      appImage: undefined,
+    });
+    expect(result).toBe(false);
+  });
+
+  it("matches when candidate lives under APPDIR", () => {
+    // Synthesize a fake AppImage mount layout under tmpDir.
+    const appDir = path.join(tmpDir, "mount_PI-Das");
+    fs.mkdirSync(appDir, { recursive: true });
+    const candidate = path.join(appDir, "pi-dashboard");
+    fs.writeFileSync(candidate, "#!/bin/sh\n");
+
+    const result = isAppImageSelfHit(candidate, {
+      execPath: "/some/other/electron",
+      appDir,
+      appImage: undefined,
+    });
+    expect(result).toBe(true);
+  });
+
+  it("does NOT match when APPDIR is set but candidate is outside it", () => {
+    const appDir = path.join(tmpDir, "mount_PI-Das");
+    fs.mkdirSync(appDir, { recursive: true });
+    const candidate = path.join(tmpDir, "other-place", "pi-dashboard");
+    fs.mkdirSync(path.dirname(candidate), { recursive: true });
+    fs.writeFileSync(candidate, "#!/bin/sh\n");
+
+    const result = isAppImageSelfHit(candidate, {
+      execPath: "/some/other/electron",
+      appDir,
+      appImage: undefined,
+    });
+    expect(result).toBe(false);
+  });
+
+  it("matches when realpath of candidate equals realpath of APPIMAGE", () => {
+    const appImage = path.join(tmpDir, "PI-Dashboard.AppImage");
+    fs.writeFileSync(appImage, "AppImage payload");
+
+    const symlink = path.join(tmpDir, "alias-link");
+    fs.symlinkSync(appImage, symlink);
+
+    const result = isAppImageSelfHit(symlink, {
+      execPath: "/some/other/electron",
+      appDir: undefined,
+      appImage,
+    });
+    expect(result).toBe(true);
+  });
+
+  it("matches when realpath of candidate equals realpath of execPath", () => {
+    const exec = path.join(tmpDir, "electron-binary");
+    fs.writeFileSync(exec, "Electron");
+
+    const symlink = path.join(tmpDir, "fake-pi-dashboard");
+    fs.symlinkSync(exec, symlink);
+
+    const result = isAppImageSelfHit(symlink, {
+      execPath: exec,
+      appDir: undefined,
+      appImage: undefined,
+    });
+    expect(result).toBe(true);
+  });
+
+  it("does NOT match when execPath is unrelated to candidate", () => {
+    const candidate = path.join(tmpDir, "real-cli");
+    fs.writeFileSync(candidate, "#!/bin/sh\n");
+
+    const exec = path.join(tmpDir, "electron-binary");
+    fs.writeFileSync(exec, "Electron");
+
+    const result = isAppImageSelfHit(candidate, {
+      execPath: exec,
+      appDir: undefined,
+      appImage: undefined,
+    });
+    expect(result).toBe(false);
+  });
+
+  it("falls back to literal compare for broken-symlink / ENOENT candidates", () => {
+    // Candidate path does not exist on disk.
+    const candidate = path.join(tmpDir, "ghost");
+    const exec = candidate; // exact-string match — should still match
+
+    expect(() =>
+      isAppImageSelfHit(candidate, {
+        execPath: exec,
+        appDir: undefined,
+        appImage: undefined,
+      }),
+    ).not.toThrow();
+
+    const result = isAppImageSelfHit(candidate, {
+      execPath: exec,
+      appDir: undefined,
+      appImage: undefined,
+    });
+    expect(result).toBe(true);
+  });
+
+  it("does not throw when APPDIR points at a non-existent directory", () => {
+    const candidate = path.join(tmpDir, "real-cli");
+    fs.writeFileSync(candidate, "#!/bin/sh\n");
+    const ghostAppDir = path.join(tmpDir, "does-not-exist");
+
+    expect(() =>
+      isAppImageSelfHit(candidate, {
+        execPath: "/unrelated",
+        appDir: ghostAppDir,
+        appImage: undefined,
+      }),
+    ).not.toThrow();
+  });
+
+  it("falls back to reading process.env / process.execPath when opts is omitted", () => {
+    const savedAppDir = process.env.APPDIR;
+    const savedAppImage = process.env.APPIMAGE;
+    try {
+      // Construct a self-hit relative to the current process.execPath.
+      // realpath(candidate) === realpath(process.execPath) → matches.
+      const result = isAppImageSelfHit(process.execPath);
+      // process.execPath always exists, so this should match.
+      expect(result).toBe(true);
+    } finally {
+      if (savedAppDir === undefined) delete process.env.APPDIR;
+      else process.env.APPDIR = savedAppDir;
+      if (savedAppImage === undefined) delete process.env.APPIMAGE;
+      else process.env.APPIMAGE = savedAppImage;
+    }
+  });
+});

package/packages/shared/src/__tests__/plugin-bridge-register-extended.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Task 9.3: Bridge auto-register extended tests.
+ * Verifies: write on boot, remove on disable, preserve user entries,
+ * surface path-mismatch conflicts.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  registerPluginBridge,
+  deregisterPluginBridge,
+  listManagedBridges,
+} from "../plugin-bridge-register.js";
+
+let tmpDir: string;
+let homedir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "bridge-ext-test-"));
+  homedir = tmpDir;
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function settingsPath() {
+  return path.join(homedir, ".pi", "agent", "settings.json");
+}
+
+function readSettings(): Record<string, unknown> {
+  return JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+}
+
+describe("bridge auto-register boot + disable lifecycle", () => {
+  it("registers bridge on first boot", () => {
+    const result = registerPluginBridge("openspec", "/opt/dashboard/openspec/bridge.js", { homedir });
+    expect(result.type).toBe("ok");
+    const managed = listManagedBridges({ homedir });
+    expect(managed["dashboard-openspec"]).toBe("/opt/dashboard/openspec/bridge.js");
+  });
+
+  it("deregisters bridge on disable", () => {
+    registerPluginBridge("openspec", "/opt/dashboard/openspec/bridge.js", { homedir });
+    deregisterPluginBridge("openspec", { homedir });
+    const managed = listManagedBridges({ homedir });
+    expect(Object.keys(managed)).toHaveLength(0);
+  });
+
+  it("preserves user-owned packages array", () => {
+    fs.mkdirSync(path.join(homedir, ".pi", "agent"), { recursive: true });
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({
+        packages: ["/user/my-extension", "/user/another"],
+      }),
+    );
+    registerPluginBridge("demo", "/demo/bridge.js", { homedir });
+    const settings = readSettings();
+    expect(settings.packages).toEqual(["/user/my-extension", "/user/another"]);
+  });
+
+  it("surfaces path-mismatch conflict without overwriting", () => {
+    registerPluginBridge("openspec", "/old/bridge.js", { homedir });
+    const result = registerPluginBridge("openspec", "/new/bridge.js", { homedir });
+    expect(result.type).toBe("conflict");
+    // Original path preserved
+    const managed = listManagedBridges({ homedir });
+    expect(managed["dashboard-openspec"]).toBe("/old/bridge.js");
+  });
+});