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

package/packages/server/src/__tests__/editor-pid-registry.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect } from "vitest";
+import { mkdtempSync, mkdirSync, readFileSync, existsSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import os from "node:os";
+import path from "node:path";
+import {
+  createEditorPidRegistry,
+  isDashboardOwnedCodeServer,
+  type PersistedEditorEntry,
+} from "../editor-pid-registry.js";
+
+function tempPidFile(): string {
+  const dir = mkdtempSync(join(tmpdir(), "editor-pid-reg-"));
+  return join(dir, "editor-pids.json");
+}
+
+function readEntries(file: string): PersistedEditorEntry[] {
+  if (!existsSync(file)) return [];
+  return JSON.parse(readFileSync(file, "utf-8")).entries ?? [];
+}
+
+const VALID_CMDLINE = `/usr/local/bin/code-server --auth none --bind-addr 127.0.0.1:63584 --user-data-dir ${path.join(os.homedir(), ".pi", "dashboard", "editors", "abc123def456")} /Users/me/project`;
+
+const UNRELATED_CMDLINE = "/usr/local/bin/code-server --user-data-dir /Users/me/.config/Code";
+
+describe("isDashboardOwnedCodeServer", () => {
+  it("returns true for a dashboard-owned code-server cmdline", () => {
+    expect(isDashboardOwnedCodeServer(VALID_CMDLINE)).toBe(true);
+  });
+
+  it("returns false for an unrelated code-server", () => {
+    expect(isDashboardOwnedCodeServer(UNRELATED_CMDLINE)).toBe(false);
+  });
+
+  it("returns false for null cmdline", () => {
+    expect(isDashboardOwnedCodeServer(null)).toBe(false);
+  });
+
+  it("returns false when --user-data-dir is missing", () => {
+    expect(isDashboardOwnedCodeServer("/usr/local/bin/code-server --bind-addr 127.0.0.1:1234")).toBe(false);
+  });
+});
+
+describe("createEditorPidRegistry — register/remove/persist", () => {
+  it("register writes an entry to the JSON file", () => {
+    const file = tempPidFile();
+    const reg = createEditorPidRegistry({ pidFilePath: file });
+    reg.register({ id: "editor-aaa", pid: 5961, port: 63584, cwd: "/projects/app", dataDir: "/data" });
+    expect(reg.size()).toBe(1);
+    const entries = readEntries(file);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({ id: "editor-aaa", pid: 5961, port: 63584, cwd: "/projects/app", dataDir: "/data" });
+    expect(entries[0].spawnedAt).toBeDefined();
+  });
+
+  it("remove deletes the entry from the JSON file", () => {
+    const file = tempPidFile();
+    const reg = createEditorPidRegistry({ pidFilePath: file });
+    reg.register({ id: "editor-aaa", pid: 1, port: 1, cwd: "/a", dataDir: "/d" });
+    reg.register({ id: "editor-bbb", pid: 2, port: 2, cwd: "/b", dataDir: "/d2" });
+    reg.remove("editor-aaa");
+    expect(reg.size()).toBe(1);
+    const entries = readEntries(file);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].id).toBe("editor-bbb");
+  });
+
+  it("persistence write failure does not throw from register", () => {
+    // Portable way to force writeJsonFile to fail: make the target path a
+    // directory so fs.writeFileSync (to path + ".tmp") succeeds but rename()
+    // onto a directory fails with EISDIR/EPERM on every platform.
+    const file = tempPidFile();
+    mkdirSync(file, { recursive: true }); // target exists as a directory
+    const reg = createEditorPidRegistry({ pidFilePath: file });
+    expect(() => reg.register({ id: "editor-aaa", pid: 1, port: 1, cwd: "/a", dataDir: "/d" })).not.toThrow();
+    // In-memory entry still tracked even when disk write failed.
+    expect(reg.size()).toBe(1);
+  });
+});
+
+describe("createEditorPidRegistry — cleanupOrphans", () => {
+  it("returns without throwing when file does not exist", async () => {
+    const file = join(mkdtempSync(join(tmpdir(), "missing-")), "nope.json");
+    const reg = createEditorPidRegistry({ pidFilePath: file });
+    await expect(reg.cleanupOrphans()).resolves.toBeUndefined();
+  });
+
+  it("returns without throwing when file is corrupt", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, "{not json");
+    const reg = createEditorPidRegistry({ pidFilePath: file });
+    await expect(reg.cleanupOrphans()).resolves.toBeUndefined();
+  });
+
+  it("skips dead PIDs", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, JSON.stringify({
+      entries: [{ id: "editor-x", pid: 999999, port: 1, cwd: "/a", dataDir: "/d", spawnedAt: new Date().toISOString() }],
+    }));
+    const killed: Array<{ pid: number; sig: string }> = [];
+    const reg = createEditorPidRegistry({
+      pidFilePath: file,
+      isProcessAlive: () => false,
+      getCmdline: () => VALID_CMDLINE,
+      kill: (pid, sig) => { killed.push({ pid, sig }); return true; },
+      graceMs: 1,
+    });
+    await reg.cleanupOrphans();
+    expect(killed).toEqual([]);
+  });
+
+  it("does NOT signal a live PID whose cmdline doesn't match (PID reuse)", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, JSON.stringify({
+      entries: [{ id: "editor-x", pid: 1234, port: 1, cwd: "/a", dataDir: "/d", spawnedAt: new Date().toISOString() }],
+    }));
+    const killed: Array<{ pid: number; sig: string }> = [];
+    const reg = createEditorPidRegistry({
+      pidFilePath: file,
+      isProcessAlive: () => true,
+      getCmdline: () => UNRELATED_CMDLINE,
+      kill: (pid, sig) => { killed.push({ pid, sig }); return true; },
+      graceMs: 1,
+    });
+    await reg.cleanupOrphans();
+    expect(killed).toEqual([]);
+  });
+
+  it("does NOT signal when cmdline lookup fails (cannot verify)", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, JSON.stringify({
+      entries: [{ id: "editor-x", pid: 1234, port: 1, cwd: "/a", dataDir: "/d", spawnedAt: new Date().toISOString() }],
+    }));
+    const killed: Array<{ pid: number; sig: string }> = [];
+    const reg = createEditorPidRegistry({
+      pidFilePath: file,
+      isProcessAlive: () => true,
+      getCmdline: () => null,
+      kill: (pid, sig) => { killed.push({ pid, sig }); return true; },
+      graceMs: 1,
+    });
+    await reg.cleanupOrphans();
+    expect(killed).toEqual([]);
+  });
+
+  it("SIGTERMs verified live orphans then SIGKILLs survivors", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, JSON.stringify({
+      entries: [
+        { id: "editor-x", pid: 5961, port: 63584, cwd: "/a", dataDir: "/d1", spawnedAt: new Date().toISOString() },
+        { id: "editor-y", pid: 5962, port: 63585, cwd: "/b", dataDir: "/d2", spawnedAt: new Date().toISOString() },
+      ],
+    }));
+    const killed: Array<{ pid: number; sig: string }> = [];
+    // First call: alive. After SIGTERM grace, simulate that 5961 died, 5962 survived.
+    let phase: "before" | "after" = "before";
+    const reg = createEditorPidRegistry({
+      pidFilePath: file,
+      isProcessAlive: (pid) => phase === "before" ? true : pid === 5962,
+      getCmdline: () => VALID_CMDLINE,
+      kill: (pid, sig) => { killed.push({ pid, sig }); return true; },
+      graceMs: 1,
+    });
+    // Toggle phase right after SIGTERMs are sent.
+    const origSetTimeout = setTimeout;
+    const promise = reg.cleanupOrphans();
+    // microtask flip
+    queueMicrotask(() => { phase = "after"; });
+    await promise;
+
+    expect(killed.filter((k) => k.sig === "SIGTERM").map((k) => k.pid).sort()).toEqual([5961, 5962]);
+    expect(killed.filter((k) => k.sig === "SIGKILL").map((k) => k.pid)).toEqual([5962]);
+  });
+
+  it("rewrites the registry file empty after sweep", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, JSON.stringify({
+      entries: [{ id: "editor-x", pid: 5961, port: 1, cwd: "/a", dataDir: "/d", spawnedAt: new Date().toISOString() }],
+    }));
+    const reg = createEditorPidRegistry({
+      pidFilePath: file,
+      isProcessAlive: () => true,
+      getCmdline: () => VALID_CMDLINE,
+      kill: () => true,
+      graceMs: 1,
+    });
+    await reg.cleanupOrphans();
+    expect(readEntries(file)).toEqual([]);
+  });
+});

package/packages/server/src/__tests__/editor-registry.test.ts

@@ -77,8 +77,9 @@ describe("editor-registry", () => {
       mockedExecSync.mockImplementation((cmd) => {
         const s = String(cmd);
         if (s.includes("pgrep")) {
-          // Only Zed is running
-          if (s.includes("Zed")) return Buffer.from("12345\n");
+          // Only Zed is running — match on both the macOS pattern
+          // ("/Applications/Zed.app") and the Linux pattern ("zed").
+          if (s.includes("Zed") || s.includes("zed")) return Buffer.from("12345\n");
           throw new Error("not found");
         }
         if (s.includes("which")) {

package/packages/server/src/__tests__/fix-pty-permissions.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Regression test for the postinstall `fix-pty-permissions.cjs` script.
+ *
+ * Ensures that after `npm install` the native `spawn-helper` binary in the
+ * current platform's `node-pty` prebuild directory has at least one execute
+ * bit set. Without this, `pty.spawn(...)` fails with "posix_spawnp failed."
+ * and the dashboard's "New Terminal" button appears dead.
+ */
+import { describe, it, expect } from "vitest";
+import { existsSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+
+describe("fix-pty-permissions", () => {
+  it.skipIf(process.platform === "win32")(
+    "spawn-helper for current platform is executable",
+    () => {
+      const require = createRequire(import.meta.url);
+      const ptyPkg = require.resolve("node-pty/package.json");
+      const ptyRoot = dirname(ptyPkg);
+      const platformDir =
+        process.platform === "darwin"
+          ? process.arch === "arm64"
+            ? "darwin-arm64"
+            : "darwin-x64"
+          : process.arch === "arm64"
+          ? "linux-arm64"
+          : "linux-x64";
+
+      // node-pty ships pre-packed binaries under `prebuilds/<platform>-<arch>/`
+      // when the tarball includes a prebuild for the host platform (macOS,
+      // Windows, some Linux builds). Otherwise node-pty's install script
+      // falls back to `node-gyp rebuild`, producing artifacts under
+      // `build/Release/` instead. Accept either location so this test is
+      // stable across local dev (prebuilt) and Linux CI (built from source).
+      const candidates = [
+        join(ptyRoot, "prebuilds", platformDir, "spawn-helper"),
+        join(ptyRoot, "build", "Release", "spawn-helper"),
+      ];
+      const helper = candidates.find((p) => existsSync(p));
+
+      if (!helper) {
+        // No spawn-helper anywhere means node-pty's install step did not
+        // produce the binary on this host (e.g. missing build toolchain).
+        // The fix-permissions script is defensive — it silently skips when
+        // the prebuild dir is absent — so skipping here matches runtime
+        // behavior rather than masking a real regression.
+        console.warn(
+          `[fix-pty-permissions.test] no spawn-helper found at any of: ${candidates.join(", ")} — skipping`,
+        );
+        return;
+      }
+
+      const mode = statSync(helper).mode;
+      // At least one execute bit (owner/group/other) must be set.
+      expect(mode & 0o111).not.toBe(0);
+    },
+  );
+});

package/packages/server/src/__tests__/git-operations.test.ts

@@ -18,7 +18,9 @@ function git(cmd: string, cwd: string) {
 
 function makeRepo(): string {
   const dir = mkdtempSync(join(tmpdir(), "git-ops-test-"));
-  git("init", dir);
+  // Force `main` as the default branch so tests are deterministic regardless
+  // of the host user's `init.defaultBranch` config.
+  git("-c init.defaultBranch=main init", dir);
   git("config user.email test@test.com", dir);
   git("config user.name Test", dir);
   // Initial commit so we have a branch
@@ -122,7 +124,7 @@ describe("git-operations", () => {
         writeFileSync(join(repo, "remote.txt"), "data");
         git("add .", repo);
         git("commit -m remote-only", repo);
-        git("checkout master", repo);
+        git("checkout main", repo);
 
         // Fetch in clone
         git("fetch origin", clone);
@@ -151,7 +153,7 @@ describe("git-operations", () => {
   describe("checkoutBranch", () => {
     it("checks out a local branch on clean repo", () => {
       git("checkout -b feature-x", repo);
-      git("checkout master", repo);
+      git("checkout main", repo);
       const result = checkoutBranch(repo, "feature-x", false);
       expect(result.success).toBe(true);
       const head = execSync("git rev-parse --abbrev-ref HEAD", { cwd: repo, encoding: "utf-8" }).trim();
@@ -160,7 +162,7 @@ describe("git-operations", () => {
 
     it("returns dirty when working tree is dirty and stash=false", () => {
       git("checkout -b feature-y", repo);
-      git("checkout master", repo);
+      git("checkout main", repo);
       writeFileSync(join(repo, "README.md"), "dirty");
       const result = checkoutBranch(repo, "feature-y", false);
       expect(result.success).toBe(false);
@@ -172,7 +174,7 @@ describe("git-operations", () => {
 
     it("stashes and checks out when stash=true", () => {
       git("checkout -b feature-z", repo);
-      git("checkout master", repo);
+      git("checkout main", repo);
       writeFileSync(join(repo, "README.md"), "dirty");
       const result = checkoutBranch(repo, "feature-z", true);
       expect(result.success).toBe(true);
@@ -184,7 +186,7 @@ describe("git-operations", () => {
     });
 
     it("returns success when already on target branch", () => {
-      const result = checkoutBranch(repo, "master", false);
+      const result = checkoutBranch(repo, "main", false);
       expect(result.success).toBe(true);
     });
 
@@ -194,7 +196,7 @@ describe("git-operations", () => {
       writeFileSync(join(repo, "r.txt"), "data");
       git("add .", repo);
       git("commit -m r", repo);
-      git("checkout master", repo);
+      git("checkout main", repo);
 
       const clone = mkdtempSync(join(tmpdir(), "git-ops-clone-"));
       try {

package/packages/server/src/__tests__/health-endpoint.test.ts

@@ -2,28 +2,26 @@
  * Tests for GET /api/health endpoint.
  */
 import { describe, it, expect, afterEach } from "vitest";
-import { createServer, type DashboardServer } from "../server.js";
+import { createTestServer, type TestServerHandle } from "../test-support/test-server.js";
+import type { DashboardServer } from "../server.js";
 
-const httpPort = 19090;
-const piPort = 19091;
-let server: DashboardServer;
+let handle: TestServerHandle | undefined;
+let server: DashboardServer | undefined;
 
 describe("GET /api/health", () => {
   afterEach(async () => {
-    if (server) {
-      try { await server.stop(); } catch { /* already stopped */ }
+    if (handle) {
+      try { await handle.stop(); } catch { /* already stopped */ }
+      handle = undefined;
+      server = undefined;
     }
   });
 
   it("should return ok, pid, and uptime", async () => {
-    server = await createServer({
-      port: httpPort, piPort, dev: true,
-      autoShutdown: false, shutdownIdleSeconds: 999, tunnel: false,
-    editor: { idleTimeoutMinutes: 10, maxInstances: 3 },
-    });
-    await server.start();
+    handle = await createTestServer();
+    server = handle.server;
 
-    const res = await fetch(`http://localhost:${httpPort}/api/health`);
+    const res = await fetch(`http://localhost:${handle.httpPort}/api/health`);
     expect(res.status).toBe(200);
 
     const body = await res.json();

package/packages/server/src/__tests__/openspec-tasks-parser.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import {
+  parseTasksMarkdown,
+  readTasks,
+  toggleTask,
+  NotFoundError,
+  LineMismatchError,
+  NotACheckboxError,
+} from "../openspec-tasks.js";
+
+describe("parseTasksMarkdown", () => {
+  it("parses ticked + unticked mix and tracks groups", () => {
+    const md = [
+      "## 1. Setup",
+      "",
+      "- [ ] 1.1 Create module",
+      "- [x] 1.2 Add dep",
+      "",
+      "## 2. Tests",
+      "- [x] 2.1 Write vitest",
+      "- [ ] 2.2 Write e2e",
+    ].join("\n");
+    const tasks = parseTasksMarkdown(md);
+    expect(tasks).toEqual([
+      { id: "1.1", text: "Create module", done: false, line: 3, group: "1. Setup" },
+      { id: "1.2", text: "Add dep", done: true, line: 4, group: "1. Setup" },
+      { id: "2.1", text: "Write vitest", done: true, line: 7, group: "2. Tests" },
+      { id: "2.2", text: "Write e2e", done: false, line: 8, group: "2. Tests" },
+    ]);
+  });
+
+  it("ignores unparseable lines without failing", () => {
+    const md = [
+      "## Misc",
+      "- foo bar",
+      "- [ ] 1.1 Valid task",
+      "random text",
+      "  - [ ] 1.2 Indented, not top-level",
+      "- [x] 1.3 Another valid",
+    ].join("\n");
+    const tasks = parseTasksMarkdown(md);
+    expect(tasks.map((t) => t.id)).toEqual(["1.1", "1.3"]);
+    expect(tasks.map((t) => t.done)).toEqual([false, true]);
+  });
+
+  it("handles capital X as done", () => {
+    const tasks = parseTasksMarkdown("## G\n- [X] 1.1 Done-uppercase");
+    expect(tasks).toHaveLength(1);
+    expect(tasks[0].done).toBe(true);
+  });
+
+  it("handles CRLF line endings", () => {
+    const md = "## 1. G\r\n- [ ] 1.1 Test\r\n- [x] 1.2 Done\r\n";
+    const tasks = parseTasksMarkdown(md);
+    expect(tasks).toHaveLength(2);
+    expect(tasks[0].group).toBe("1. G");
+    expect(tasks[0].line).toBe(2);
+    expect(tasks[1].done).toBe(true);
+  });
+
+  it("returns empty list for no tasks", () => {
+    expect(parseTasksMarkdown("# Title\n\nJust prose.\n")).toEqual([]);
+  });
+
+  it("handles tasks without a preceding heading (empty group)", () => {
+    const tasks = parseTasksMarkdown("- [ ] 1.1 Loose task");
+    expect(tasks[0].group).toBe("");
+  });
+});
+
+describe("readTasks + toggleTask (writer)", () => {
+  let tmpDir: string;
+  let changeDir: string;
+  let tasksFile: string;
+  const CWD_CHANGE = ["my-cwd-placeholder", "demo-change"] as const;
+
+  const initialMd = [
+    "## 1. Setup",
+    "",
+    "- [ ] 1.1 First task",
+    "- [x] 1.2 Second task",
+    "",
+    "## 2. Docs",
+    "- [ ] 2.1 Third task",
+    "",
+  ].join("\n");
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "openspec-tasks-test-"));
+    changeDir = path.join(tmpDir, "openspec", "changes", CWD_CHANGE[1]);
+    fs.mkdirSync(changeDir, { recursive: true });
+    tasksFile = path.join(changeDir, "tasks.md");
+    fs.writeFileSync(tasksFile, initialMd, "utf-8");
+  });
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("readTasks returns parsed entries", async () => {
+    const tasks = await readTasks(tmpDir, CWD_CHANGE[1]);
+    expect(tasks.map((t) => t.id)).toEqual(["1.1", "1.2", "2.1"]);
+  });
+
+  it("readTasks throws NotFoundError when file is missing", async () => {
+    await expect(readTasks(tmpDir, "does-not-exist")).rejects.toBeInstanceOf(NotFoundError);
+  });
+
+  it("toggle ticks an unticked task and preserves other lines", async () => {
+    const result = await toggleTask(tmpDir, CWD_CHANGE[1], "1.1", true, 3);
+    expect(result.done).toBe(true);
+    expect(result.id).toBe("1.1");
+    expect(result.line).toBe(3);
+    expect(result.group).toBe("1. Setup");
+
+    const after = fs.readFileSync(tasksFile, "utf-8");
+    const expected = initialMd.replace("- [ ] 1.1 First task", "- [x] 1.1 First task");
+    expect(after).toBe(expected);
+  });
+
+  it("toggle unticks a ticked task", async () => {
+    const result = await toggleTask(tmpDir, CWD_CHANGE[1], "1.2", false, 4);
+    expect(result.done).toBe(false);
+    const after = fs.readFileSync(tasksFile, "utf-8");
+    expect(after).toBe(initialMd.replace("- [x] 1.2 Second task", "- [ ] 1.2 Second task"));
+  });
+
+  it("toggle raises LineMismatchError when line is already in the target state", async () => {
+    // Line 4 is already done=true; requesting done=true again → mismatch
+    await expect(toggleTask(tmpDir, CWD_CHANGE[1], "1.2", true, 4)).rejects.toBeInstanceOf(
+      LineMismatchError,
+    );
+    // File untouched
+    expect(fs.readFileSync(tasksFile, "utf-8")).toBe(initialMd);
+  });
+
+  it("toggle raises LineMismatchError when id does not match target line", async () => {
+    await expect(toggleTask(tmpDir, CWD_CHANGE[1], "9.9", true, 3)).rejects.toBeInstanceOf(
+      LineMismatchError,
+    );
+  });
+
+  it("toggle raises LineMismatchError for out-of-range line", async () => {
+    await expect(toggleTask(tmpDir, CWD_CHANGE[1], "1.1", true, 9999)).rejects.toBeInstanceOf(
+      LineMismatchError,
+    );
+  });
+
+  it("toggle raises NotACheckboxError when target line is a heading", async () => {
+    // Line 1 is "## 1. Setup"
+    await expect(toggleTask(tmpDir, CWD_CHANGE[1], "1.1", true, 1)).rejects.toBeInstanceOf(
+      NotACheckboxError,
+    );
+  });
+
+  it("toggle raises NotFoundError when file is absent", async () => {
+    await expect(toggleTask(tmpDir, "missing", "1.1", true, 3)).rejects.toBeInstanceOf(
+      NotFoundError,
+    );
+  });
+
+  it("toggle writes atomically (no .tmp left behind)", async () => {
+    await toggleTask(tmpDir, CWD_CHANGE[1], "1.1", true, 3);
+    const files = fs.readdirSync(changeDir);
+    expect(files.some((f) => f.endsWith(".tmp"))).toBe(false);
+  });
+
+  it("toggle preserves byte-for-byte all other lines", async () => {
+    const weirdMd =
+      "# Title line\n\n## 1. Group\n- [ ] 1.1 Task one\n> quote line\n\n    indented code\n- [x] 1.2 Task two\n";
+    fs.writeFileSync(tasksFile, weirdMd, "utf-8");
+    await toggleTask(tmpDir, CWD_CHANGE[1], "1.1", true, 4);
+    const after = fs.readFileSync(tasksFile, "utf-8");
+    expect(after).toBe(weirdMd.replace("- [ ] 1.1 Task one", "- [x] 1.1 Task one"));
+  });
+});