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

package/packages/shared/src/__tests__/resolve-jiti.test.ts

@@ -1,17 +1,53 @@
 import { describe, it, expect } from "vitest";
+import { buildJitiRegisterUrl, resolveJitiImport } from "../resolve-jiti.js";
+
+describe("buildJitiRegisterUrl", () => {
+  // Pure function: given a jiti package.json path, return the file:// URL of
+  // its register hook. The URL contract is the critical invariant — Node's
+  // --import on Windows rejects raw drive-letter paths (parses "C:" as a
+  // URL scheme). See change: fix-windows-server-parity.
+
+  it("returns a file:// URL", () => {
+    const url = buildJitiRegisterUrl("/usr/lib/node_modules/@mariozechner/jiti/package.json");
+    expect(url.startsWith("file://")).toBe(true);
+  });
+
+  it("URL is parseable by new URL() without throwing", () => {
+    const url = buildJitiRegisterUrl("/usr/lib/node_modules/@mariozechner/jiti/package.json");
+    expect(() => new URL(url)).not.toThrow();
+  });
+
+  it("points at lib/jiti-register.mjs under the package dir", () => {
+    const url = buildJitiRegisterUrl("/usr/lib/node_modules/@mariozechner/jiti/package.json");
+    expect(url.endsWith("/lib/jiti-register.mjs")).toBe(true);
+  });
+
+  it("handles Windows drive-letter paths (regression for ERR_UNSUPPORTED_ESM_URL_SCHEME)", () => {
+    // This is the exact shape that crashed pre-fix: a raw path with a
+    // drive letter was passed to `node --import` and Node parsed "B:" as
+    // a URL scheme. A file:// URL sidesteps the parser entirely.
+    const url = buildJitiRegisterUrl("B:\\Dev\\Nodejs\\global\\node_modules\\@mariozechner\\jiti\\package.json");
+    expect(url.startsWith("file:///")).toBe(true);
+    expect(() => new URL(url)).not.toThrow();
+    expect(new URL(url).protocol).toBe("file:");
+    // The drive letter survives as part of the pathname, not as a protocol
+    expect(url.toLowerCase()).toContain("/b:/");
+    expect(url.endsWith("/lib/jiti-register.mjs")).toBe(true);
+  });
+
+});
 
 describe("resolveJitiImport", () => {
-  it("throws with clear error when pi-coding-agent is not resolvable", async () => {
-    // In test context (vitest, not inside pi's jiti loader),
-    // peer deps are not resolvable — should throw
-    const { resolveJitiImport } = await import("../resolve-jiti.js");
+  // Integration-lite: in vitest context (not inside pi's jiti loader),
+  // process.argv[1] points at the test runner, not pi — so peer-dep
+  // resolution fails and the function throws a helpful error. The
+  // URL-contract behavior is covered by buildJitiRegisterUrl above.
 
+  it("throws with clear error when pi-coding-agent is not resolvable", () => {
     expect(() => resolveJitiImport()).toThrow("Cannot find pi's TypeScript loader");
   });
 
-  it("error message mentions pi-coding-agent", async () => {
-    const { resolveJitiImport } = await import("../resolve-jiti.js");
-
+  it("error message mentions pi-coding-agent", () => {
     expect(() => resolveJitiImport()).toThrow("pi-coding-agent");
   });
 });

package/packages/shared/src/__tests__/semaphore.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from "vitest";
+import { createSemaphore } from "../semaphore.js";
+
+function defer<T = void>(): { promise: Promise<T>; resolve: (v: T) => void; reject: (e: any) => void } {
+  let resolve!: (v: T) => void;
+  let reject!: (e: any) => void;
+  const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej; });
+  return { promise, resolve, reject };
+}
+
+describe("createSemaphore", () => {
+  it("throws when max < 1", () => {
+    expect(() => createSemaphore(0)).toThrow();
+    expect(() => createSemaphore(-1)).toThrow();
+  });
+
+  it("runs tasks immediately up to the cap", async () => {
+    const sem = createSemaphore(2);
+    const a = defer<string>();
+    const b = defer<string>();
+    const pa = sem.run(() => a.promise);
+    const pb = sem.run(() => b.promise);
+    expect(sem.size()).toBe(2);
+    a.resolve("a");
+    b.resolve("b");
+    expect(await pa).toBe("a");
+    expect(await pb).toBe("b");
+    expect(sem.size()).toBe(0);
+  });
+
+  it("caps concurrency: third task waits", async () => {
+    const sem = createSemaphore(2);
+    const a = defer<string>();
+    const b = defer<string>();
+    const c = defer<string>();
+
+    let cStarted = false;
+    const pa = sem.run(() => a.promise);
+    const pb = sem.run(() => b.promise);
+    const pc = sem.run(() => { cStarted = true; return c.promise; });
+
+    // Wait a microtask for queue placement
+    await Promise.resolve();
+    expect(cStarted).toBe(false);
+    expect(sem.size()).toBe(3); // active + queued
+
+    a.resolve("a");
+    await pa;
+    // c should now be started
+    await Promise.resolve();
+    expect(cStarted).toBe(true);
+    b.resolve("b");
+    c.resolve("c");
+    expect(await pb).toBe("b");
+    expect(await pc).toBe("c");
+  });
+
+  it("FIFO order of queued tasks", async () => {
+    const sem = createSemaphore(1);
+    const order: string[] = [];
+    const blockers = [defer<void>(), defer<void>(), defer<void>()];
+    const ps = blockers.map((d, i) =>
+      sem.run(async () => { order.push(`start-${i}`); await d.promise; order.push(`end-${i}`); }),
+    );
+    await Promise.resolve();
+    blockers[0].resolve(); await ps[0];
+    blockers[1].resolve(); await ps[1];
+    blockers[2].resolve(); await ps[2];
+    expect(order).toEqual(["start-0", "end-0", "start-1", "end-1", "start-2", "end-2"]);
+  });
+
+  it("releases slot on reject so queued tasks still run", async () => {
+    const sem = createSemaphore(1);
+    const failed = sem.run(async () => { throw new Error("boom"); });
+    await expect(failed).rejects.toThrow("boom");
+    const ok = sem.run(async () => "ok");
+    expect(await ok).toBe("ok");
+  });
+
+  it("setMax increases cap and drains queued tasks immediately", async () => {
+    const sem = createSemaphore(1);
+    const a = defer<void>();
+    const b = defer<void>();
+    let bStarted = false;
+    const pa = sem.run(() => a.promise);
+    const pb = sem.run(() => { bStarted = true; return b.promise; });
+    await Promise.resolve();
+    expect(bStarted).toBe(false);
+
+    sem.setMax(2);
+    await Promise.resolve();
+    expect(bStarted).toBe(true);
+
+    a.resolve(); b.resolve();
+    await pa; await pb;
+  });
+
+  it("setMax shrinking does not interrupt in-flight tasks but caps new ones", async () => {
+    const sem = createSemaphore(3);
+    const a = defer<void>();
+    const b = defer<void>();
+    const pa = sem.run(() => a.promise);
+    const pb = sem.run(() => b.promise);
+
+    sem.setMax(1);
+    const c = defer<void>();
+    let cStarted = false;
+    const pc = sem.run(() => { cStarted = true; return c.promise; });
+    await Promise.resolve();
+    expect(cStarted).toBe(false);
+
+    a.resolve(); b.resolve();
+    await pa; await pb;
+    await Promise.resolve();
+    expect(cStarted).toBe(true);
+    c.resolve();
+    await pc;
+  });
+});

package/packages/shared/src/__tests__/source-matching.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect } from "vitest";
+import { parseSourceKey, sourcesMatch } from "../source-matching.js";
+
+describe("parseSourceKey", () => {
+	it("parses npm:<name>", () => {
+		expect(parseSourceKey("npm:pi-web-access")).toEqual({ kind: "npm", name: "pi-web-access" });
+	});
+
+	it("parses npm:<name>@<version>", () => {
+		expect(parseSourceKey("npm:pi-web-access@0.10.6")).toEqual({
+			kind: "npm",
+			name: "pi-web-access",
+		});
+	});
+
+	it("parses scoped npm name without version", () => {
+		expect(parseSourceKey("npm:@tintinweb/pi-subagents")).toEqual({
+			kind: "npm",
+			name: "@tintinweb/pi-subagents",
+		});
+	});
+
+	it("parses scoped npm name with version", () => {
+		expect(parseSourceKey("npm:@tintinweb/pi-subagents@0.5.2")).toEqual({
+			kind: "npm",
+			name: "@tintinweb/pi-subagents",
+		});
+	});
+
+	it("parses git SSH sources", () => {
+		expect(parseSourceKey("git@github.com:BlackBeltTechnology/pi-flows.git")).toEqual({
+			kind: "git",
+			host: "github.com",
+			owner: "BlackBeltTechnology",
+			repo: "pi-flows",
+		});
+	});
+
+	it("parses git HTTPS sources", () => {
+		expect(parseSourceKey("https://github.com/BlackBeltTechnology/pi-flows.git")).toEqual({
+			kind: "git",
+			host: "github.com",
+			owner: "BlackBeltTechnology",
+			repo: "pi-flows",
+		});
+	});
+
+	it("parses git:<host>/... sources", () => {
+		expect(parseSourceKey("git:github.com/BlackBeltTechnology/pi-flows#main")).toEqual({
+			kind: "git",
+			host: "github.com",
+			owner: "BlackBeltTechnology",
+			repo: "pi-flows",
+		});
+	});
+
+	it("returns raw for local paths", () => {
+		expect(parseSourceKey("../pi-flows")).toEqual({ kind: "raw", source: "../pi-flows" });
+		expect(parseSourceKey("/abs/path")).toEqual({ kind: "raw", source: "/abs/path" });
+	});
+});
+
+describe("sourcesMatch", () => {
+	it("matches npm by name regardless of version", () => {
+		expect(sourcesMatch("npm:pi-web-access@0.10.6", "npm:pi-web-access")).toBe(true);
+	});
+
+	it("matches scoped npm names", () => {
+		expect(
+			sourcesMatch("npm:@tintinweb/pi-subagents@0.5.2", "npm:@tintinweb/pi-subagents"),
+		).toBe(true);
+	});
+
+	it("matches git SSH vs HTTPS forms", () => {
+		expect(
+			sourcesMatch(
+				"git@github.com:BlackBeltTechnology/pi-flows.git",
+				"https://github.com/BlackBeltTechnology/pi-flows.git",
+			),
+		).toBe(true);
+	});
+
+	it("is case-insensitive for git host/owner/repo", () => {
+		expect(
+			sourcesMatch(
+				"git@github.com:BlackBeltTechnology/pi-flows.git",
+				"git@github.com:blackbelttechnology/pi-flows.git",
+			),
+		).toBe(true);
+	});
+
+	it("distinguishes different repos", () => {
+		expect(
+			sourcesMatch(
+				"git@github.com:BlackBeltTechnology/pi-flows.git",
+				"git@github.com:BlackBeltTechnology/pi-anthropic-messages.git",
+			),
+		).toBe(false);
+	});
+
+	it("distinguishes different npm names", () => {
+		expect(sourcesMatch("npm:pi-web-access", "npm:pi-agent-browser")).toBe(false);
+	});
+
+	it("cross-matches git URL against local path whose basename is the repo", () => {
+		expect(
+			sourcesMatch(
+				"git@github.com:BlackBeltTechnology/pi-flows.git",
+				"../pi-flows",
+			),
+		).toBe(true);
+		expect(
+			sourcesMatch(
+				"../pi-anthropic-messages/",
+				"git@github.com:BlackBeltTechnology/pi-anthropic-messages.git",
+			),
+		).toBe(true);
+		expect(
+			sourcesMatch(
+				"git@github.com:Org/pi-flows.git",
+				"/abs/path/to/pi-flows.git",
+			),
+		).toBe(true);
+	});
+
+	it("does not cross-match a git URL against an unrelated local path", () => {
+		expect(
+			sourcesMatch(
+				"git@github.com:BlackBeltTechnology/pi-flows.git",
+				"../pi-web-access",
+			),
+		).toBe(false);
+	});
+
+	it("does not cross-match a git URL against a deep local path", () => {
+		expect(
+			sourcesMatch(
+				"git@github.com:BlackBeltTechnology/pi-flows.git",
+				"../pi-flows/packages/core",
+			),
+		).toBe(false);
+	});
+});

package/packages/shared/src/__tests__/spawn-mechanism.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Tests for platform/spawn-mechanism.ts pure selector + argv builders.
+ *
+ * Every test passes `platform` explicitly. Never mutates process.platform.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  selectMechanism,
+  buildWtArgs,
+  sessionFlagsToArgv,
+  type SpawnMechanismContext,
+} from "../platform/spawn-mechanism.js";
+
+function ctx(overrides: Partial<SpawnMechanismContext> = {}): SpawnMechanismContext {
+  return {
+    platform: "linux",
+    userStrategy: "tmux",
+    electronMode: false,
+    available: { tmux: false, wt: false, wslTmux: false },
+    ...overrides,
+  };
+}
+
+describe("selectMechanism", () => {
+  it("electron mode always returns headless", () => {
+    expect(selectMechanism(ctx({ electronMode: true, platform: "win32", available: { tmux: false, wt: true, wslTmux: true } }))).toBe("headless");
+    expect(selectMechanism(ctx({ electronMode: true, platform: "linux", available: { tmux: true, wt: false, wslTmux: false } }))).toBe("headless");
+    expect(selectMechanism(ctx({ electronMode: true, platform: "darwin", available: { tmux: true, wt: false, wslTmux: false } }))).toBe("headless");
+  });
+
+  it("userStrategy headless always returns headless", () => {
+    expect(selectMechanism(ctx({ userStrategy: "headless", platform: "win32", available: { tmux: false, wt: true, wslTmux: true } }))).toBe("headless");
+    expect(selectMechanism(ctx({ userStrategy: "headless", platform: "linux", available: { tmux: true, wt: false, wslTmux: false } }))).toBe("headless");
+  });
+
+  it("Linux with tmux returns tmux", () => {
+    expect(selectMechanism(ctx({ platform: "linux", available: { tmux: true, wt: false, wslTmux: false } }))).toBe("tmux");
+  });
+
+  it("macOS with tmux returns tmux", () => {
+    expect(selectMechanism(ctx({ platform: "darwin", available: { tmux: true, wt: false, wslTmux: false } }))).toBe("tmux");
+  });
+
+  it("Linux without tmux returns headless", () => {
+    expect(selectMechanism(ctx({ platform: "linux", available: { tmux: false, wt: false, wslTmux: false } }))).toBe("headless");
+  });
+
+  it("Windows with wt returns wt", () => {
+    expect(selectMechanism(ctx({ platform: "win32", available: { tmux: false, wt: true, wslTmux: false } }))).toBe("wt");
+  });
+
+  it("Windows with wt AND wsl-tmux prefers wt", () => {
+    expect(selectMechanism(ctx({ platform: "win32", available: { tmux: false, wt: true, wslTmux: true } }))).toBe("wt");
+  });
+
+  it("Windows with only wsl-tmux returns wsl-tmux", () => {
+    expect(selectMechanism(ctx({ platform: "win32", available: { tmux: false, wt: false, wslTmux: true } }))).toBe("wsl-tmux");
+  });
+
+  it("Windows with nothing available returns headless", () => {
+    expect(selectMechanism(ctx({ platform: "win32", available: { tmux: false, wt: false, wslTmux: false } }))).toBe("headless");
+  });
+
+  it("unknown platform falls back to headless", () => {
+    expect(selectMechanism(ctx({ platform: "openbsd" as NodeJS.Platform, available: { tmux: true, wt: false, wslTmux: false } }))).toBe("headless");
+  });
+});
+
+describe("buildWtArgs", () => {
+  it("produces argv in expected order", () => {
+    const argv = buildWtArgs({
+      cwd: "C:\\proj",
+      title: "proj",
+      piArgv: ["C:\\node.exe", "cli.js", "--mode", "rpc"],
+    });
+    expect(argv).toEqual([
+      "-w", "0",
+      "new-tab",
+      "-d", "C:\\proj",
+      "--title", "proj",
+      "--",
+      "C:\\node.exe", "cli.js", "--mode", "rpc",
+    ]);
+  });
+
+  it("preserves cwd with spaces as a single argv element", () => {
+    const argv = buildWtArgs({
+      cwd: "C:\\Users\\Bob's Project (2)",
+      title: "x",
+      piArgv: ["pi"],
+    });
+    expect(argv).toContain("C:\\Users\\Bob's Project (2)");
+    expect(argv.filter(a => a.includes("Bob"))).toHaveLength(1);
+  });
+
+  it("places piArgv after -- sentinel with --fork intact", () => {
+    const argv = buildWtArgs({
+      cwd: "C:\\proj",
+      title: "proj",
+      piArgv: ["node.exe", "cli.js", "--fork", "C:\\x\\session.jsonl"],
+    });
+    const sentinelIdx = argv.indexOf("--");
+    expect(sentinelIdx).toBeGreaterThan(0);
+    expect(argv.slice(sentinelIdx + 1)).toEqual(["node.exe", "cli.js", "--fork", "C:\\x\\session.jsonl"]);
+  });
+
+  it("never includes -p profile flag", () => {
+    const argv = buildWtArgs({ cwd: "C:\\x", title: "y", piArgv: ["pi"] });
+    expect(argv).not.toContain("-p");
+  });
+});
+
+describe("sessionFlagsToArgv", () => {
+  it("returns --session file for continue mode", () => {
+    expect(sessionFlagsToArgv({ sessionFile: "/s/abc.jsonl", mode: "continue" })).toEqual(["--session", "/s/abc.jsonl"]);
+  });
+
+  it("returns --fork file for fork mode", () => {
+    expect(sessionFlagsToArgv({ sessionFile: "C:\\s\\abc.jsonl", mode: "fork" })).toEqual(["--fork", "C:\\s\\abc.jsonl"]);
+  });
+
+  it("returns empty array with no file", () => {
+    expect(sessionFlagsToArgv({})).toEqual([]);
+    expect(sessionFlagsToArgv({ mode: "continue" })).toEqual([]);
+    expect(sessionFlagsToArgv({ mode: "fork" })).toEqual([]);
+  });
+
+  it("returns empty array with file but no mode", () => {
+    expect(sessionFlagsToArgv({ sessionFile: "/s/x.jsonl" })).toEqual([]);
+  });
+});