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

package/packages/shared/src/__tests__/platform-process.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Tests for packages/shared/src/platform/process.ts.
+ *
+ * Every helper accepts injectable `platform`, `exec`, and `kill` parameters,
+ * so no `Object.defineProperty(process, "platform", ...)` mutation is needed.
+ * See change: consolidate-platform-handlers.
+ */
+import { describe, it, expect, vi } from "vitest";
+import {
+  findPortHolders,
+  parseNetstatListeners,
+  isProcessAlive,
+  killProcess,
+  killPidWithGroup,
+} from "../platform/process.js";
+
+describe("parseNetstatListeners", () => {
+  const selfPid = 99999;
+
+  it("parses a Windows netstat listener", () => {
+    const output = [
+      "  Proto  Local Address     Foreign Address   State       PID",
+      "  TCP    0.0.0.0:8000      0.0.0.0:0         LISTENING   12345",
+    ].join("\r\n");
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([12345]);
+  });
+
+  it("excludes non-LISTENING rows", () => {
+    const output = "  TCP    0.0.0.0:8000    0.0.0.0:0    ESTABLISHED    1111";
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([]);
+  });
+
+  it("excludes current process PID", () => {
+    const output = `  TCP    0.0.0.0:8000    0.0.0.0:0    LISTENING    ${selfPid}`;
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([]);
+  });
+
+  it("only matches the requested port", () => {
+    const output = [
+      "  TCP    0.0.0.0:8000     0.0.0.0:0    LISTENING    1111",
+      "  TCP    0.0.0.0:18000    0.0.0.0:0    LISTENING    2222",
+    ].join("\n");
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([1111]);
+  });
+
+  it("handles IPv6 addresses", () => {
+    const output = "  TCP    [::]:8000    [::]:0    LISTENING    7777";
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([7777]);
+  });
+});
+
+describe("findPortHolders", () => {
+  it("uses netstat when platform=win32 is injected", () => {
+    const exec = vi.fn().mockReturnValue(
+      "  TCP    0.0.0.0:8000    0.0.0.0:0    LISTENING    12345\n",
+    );
+    const result = findPortHolders(8000, { platform: "win32", exec });
+    expect(exec).toHaveBeenCalledOnce();
+    expect(exec.mock.calls[0][0]).toMatch(/netstat/i);
+    expect(result).toEqual([12345]);
+  });
+
+  it("uses lsof when platform=linux is injected", () => {
+    const exec = vi.fn().mockReturnValue("12345\n67890\n");
+    const result = findPortHolders(8000, { platform: "linux", exec });
+    expect(exec).toHaveBeenCalledOnce();
+    expect(exec.mock.calls[0][0]).toMatch(/lsof.*:8000/);
+    expect(result.sort()).toEqual([12345, 67890]);
+  });
+
+  it("returns [] on exec failure (best-effort)", () => {
+    const exec = vi.fn().mockImplementation(() => {
+      throw new Error("boom");
+    });
+    expect(findPortHolders(8000, { platform: "win32", exec })).toEqual([]);
+  });
+});
+
+describe("isProcessAlive", () => {
+  it("returns true when kill(pid, 0) succeeds", () => {
+    const kill = vi.fn().mockReturnValue(undefined);
+    expect(isProcessAlive(12345, { kill })).toBe(true);
+    expect(kill).toHaveBeenCalledWith(12345, 0);
+  });
+
+  it("returns false when kill(pid, 0) throws", () => {
+    const kill = vi.fn().mockImplementation(() => {
+      throw new Error("ESRCH");
+    });
+    expect(isProcessAlive(12345, { kill })).toBe(false);
+  });
+});
+
+describe("killProcess", () => {
+  it("uses taskkill on Windows", async () => {
+    const exec = vi.fn().mockReturnValue("");
+    const kill = vi.fn().mockReturnValue(undefined); // isProcessAlive → true
+    const result = await killProcess(12345, { platform: "win32", exec, kill });
+    expect(exec).toHaveBeenCalledWith(
+      expect.stringMatching(/taskkill\s+\/F\s+\/T\s+\/PID\s+12345/),
+      expect.any(Object),
+    );
+    expect(result).toEqual({ ok: true, forced: false });
+  });
+
+  it("returns { ok: false } when pid already dead", async () => {
+    const kill = vi.fn().mockImplementation(() => {
+      throw new Error("ESRCH");
+    });
+    const result = await killProcess(12345, { platform: "linux", kill });
+    expect(result).toEqual({ ok: false, forced: false });
+  });
+
+  it("sends SIGTERM on Unix and reports clean stop when process dies", async () => {
+    let aliveCount = 0;
+    const kill = vi.fn().mockImplementation((_pid, sig) => {
+      // isProcessAlive pre-check (signal 0) must succeed once to enter the branch
+      if (sig === 0) {
+        aliveCount++;
+        if (aliveCount === 1) return; // alive
+        throw new Error("ESRCH"); // dead after SIGTERM
+      }
+      if (sig === "SIGTERM") return;
+      throw new Error("unexpected signal");
+    });
+    const result = await killProcess(12345, { platform: "linux", kill, timeoutMs: 500 });
+    expect(kill).toHaveBeenCalledWith(12345, "SIGTERM");
+    expect(result).toEqual({ ok: true, forced: false });
+  });
+
+  it("forces SIGKILL when process survives SIGTERM", async () => {
+    const kill = vi.fn().mockImplementation((_pid, sig) => {
+      if (sig === 0) return; // always alive during polling
+      if (sig === "SIGTERM" || sig === "SIGKILL") return;
+    });
+    const result = await killProcess(12345, { platform: "linux", kill, timeoutMs: 300 });
+    expect(kill).toHaveBeenCalledWith(12345, "SIGKILL");
+    expect(result).toEqual({ ok: true, forced: true });
+  });
+});
+
+describe("killPidWithGroup", () => {
+  it("signals -pid on Unix (process group)", () => {
+    const kill = vi.fn();
+    killPidWithGroup(12345, "SIGTERM", { platform: "linux", kill });
+    expect(kill).toHaveBeenCalledWith(-12345, "SIGTERM");
+  });
+
+  it("signals +pid on Windows (no process groups)", () => {
+    const kill = vi.fn();
+    killPidWithGroup(12345, "SIGTERM", { platform: "win32", kill });
+    expect(kill).toHaveBeenCalledWith(12345, "SIGTERM");
+  });
+
+  it("signals -pid on macOS", () => {
+    const kill = vi.fn();
+    killPidWithGroup(99999, "SIGKILL", { platform: "darwin", kill });
+    expect(kill).toHaveBeenCalledWith(-99999, "SIGKILL");
+  });
+});

package/packages/shared/src/__tests__/platform-runner.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Tests for packages/shared/src/platform/runner.ts — the Recipe engine.
+ * Uses real subprocess execution against node itself (always available)
+ * so we test the full pipeline: resolve → spawn → parse → Result.
+ *
+ * See change: platform-command-executor.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import { run, unwrap, resetResolverCache, type Recipe } from "../platform/runner.js";
+
+// A trivial Recipe that runs `node --version` and returns the version string.
+const NODE_VERSION: Recipe<Record<string, never>, string> = {
+  argv: () => [process.execPath, "--version"],
+  parse: (stdout) => stdout.trim(),
+};
+
+// A Recipe that runs `node -e "process.exit(N)"` where N comes from input.
+const NODE_EXIT: Recipe<{ code: number }, string> = {
+  argv: ({ code }) => [process.execPath, "-e", `process.exit(${code})`],
+  parse: (stdout) => stdout.trim(),
+};
+
+// A Recipe that uses tolerate to accept exit 1.
+const NODE_EXIT_1_TOLERATED: Recipe<Record<string, never>, string> = {
+  argv: () => [process.execPath, "-e", "process.exit(1)"],
+  parse: (stdout) => stdout.trim() || "exited-1-but-ok",
+  tolerate: [1],
+};
+
+// A Recipe that times out (sleeps 10s, we allow 100ms).
+const NODE_SLEEP_LONG: Recipe<Record<string, never>, string> = {
+  argv: () => [process.execPath, "-e", "setTimeout(() => {}, 10000)"],
+  parse: (stdout) => stdout,
+  timeout: 100,
+};
+
+// A Recipe pointing at a binary that cannot be on PATH.
+const NONEXISTENT_BINARY: Recipe<Record<string, never>, string> = {
+  argv: () => ["this-binary-does-not-exist-12345abcde", "--help"],
+  parse: (stdout) => stdout,
+};
+
+describe("run()", () => {
+  beforeEach(() => {
+    resetResolverCache();
+  });
+
+  it("executes a successful recipe and returns parsed value", () => {
+    const result = run(NODE_VERSION, {});
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toMatch(/^v\d+\.\d+\.\d+/);
+    }
+  });
+
+  it("returns { ok: false, error: not-found } when binary is missing", () => {
+    const result = run(NONEXISTENT_BINARY, {});
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("not-found");
+      if (result.error.kind === "not-found") {
+        expect(result.error.binary).toBe("this-binary-does-not-exist-12345abcde");
+      }
+    }
+  });
+
+  it("returns { ok: false, error: exit } when subprocess exits non-zero (not tolerated)", () => {
+    const result = run(NODE_EXIT, { code: 42 });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("exit");
+      if (result.error.kind === "exit") {
+        expect(result.error.code).toBe(42);
+      }
+    }
+  });
+
+  it("returns { ok: true } when non-zero exit code is in recipe.tolerate", () => {
+    const result = run(NODE_EXIT_1_TOLERATED, {});
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe("exited-1-but-ok");
+    }
+  });
+
+  it("returns { ok: false, error: timeout } when subprocess exceeds timeout", () => {
+    const result = run(NODE_SLEEP_LONG, {});
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("timeout");
+      if (result.error.kind === "timeout") {
+        expect(result.error.timeoutMs).toBe(100);
+      }
+    }
+  }, 2000);
+
+  it("ctx.timeout overrides recipe.timeout", () => {
+    // Recipe says 100ms, context says 10s — a 500ms subprocess should succeed.
+    const FAST: Recipe<Record<string, never>, string> = {
+      argv: () => [process.execPath, "-e", "setTimeout(() => process.exit(0), 200)"],
+      parse: () => "ok",
+      timeout: 50, // would cause timeout without override
+    };
+    const result = run(FAST, {}, { timeout: 5000 });
+    expect(result.ok).toBe(true);
+  }, 10000);
+
+  it("caches binary resolution across calls", () => {
+    // First call resolves + caches
+    const a = run(NODE_VERSION, {});
+    expect(a.ok).toBe(true);
+    // Second call reuses cache — behavior identical
+    const b = run(NODE_VERSION, {});
+    expect(b.ok).toBe(true);
+  });
+
+  it("resetResolverCache forces re-resolution", () => {
+    const a = run(NODE_VERSION, {});
+    expect(a.ok).toBe(true);
+    resetResolverCache();
+    const b = run(NODE_VERSION, {});
+    expect(b.ok).toBe(true);
+  });
+
+  it("passes cwd from ctx to the subprocess", () => {
+    const PWD: Recipe<Record<string, never>, string> = {
+      argv: () => [process.execPath, "-e", "process.stdout.write(process.cwd())"],
+      parse: (out) => out.trim(),
+    };
+    const result = run(PWD, {}, { cwd: process.cwd() });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      // Normalize separators for cross-platform comparison
+      const normalizedOut = result.value.replace(/\\/g, "/").toLowerCase();
+      const normalizedCwd = process.cwd().replace(/\\/g, "/").toLowerCase();
+      expect(normalizedOut).toBe(normalizedCwd);
+    }
+  });
+
+  it("passes env from ctx to the subprocess (merged over process.env)", () => {
+    const PRINT_ENV: Recipe<Record<string, never>, string> = {
+      argv: () => [process.execPath, "-e", "process.stdout.write(process.env.TEST_VAR_RUNNER || 'unset')"],
+      parse: (out) => out.trim(),
+    };
+    const result = run(PRINT_ENV, {}, { env: { TEST_VAR_RUNNER: "hello-from-ctx" } });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe("hello-from-ctx");
+    }
+  });
+
+  it("rejects recipes with empty argv", () => {
+    const EMPTY: Recipe<Record<string, never>, string> = {
+      argv: () => [],
+      parse: () => "",
+    };
+    const result = run(EMPTY, {});
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("spawn-failure");
+    }
+  });
+});
+
+describe("unwrap()", () => {
+  it("returns value on success", () => {
+    expect(unwrap({ ok: true, value: 42 }, 0)).toBe(42);
+  });
+
+  it("returns fallback on error", () => {
+    expect(unwrap({ ok: false, error: { kind: "not-found", binary: "x" } }, 99)).toBe(99);
+  });
+});

package/packages/shared/src/__tests__/platform-shell.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Tests for packages/shared/src/platform/shell.ts.
+ * All four platform × env-present/absent branches are exercised via injected
+ * `platform` and `env`. No `process.env` or `process.platform` mutation.
+ * See change: consolidate-platform-handlers.
+ */
+import { describe, it, expect } from "vitest";
+import { detectShell, getTerminalEnvHints } from "../platform/shell.js";
+
+describe("detectShell", () => {
+  it("uses COMSPEC on Windows when present", () => {
+    expect(detectShell({
+      platform: "win32",
+      env: { COMSPEC: "C:\\Windows\\System32\\cmd.exe" },
+    })).toBe("C:\\Windows\\System32\\cmd.exe");
+  });
+
+  it("falls back to powershell.exe on Windows when COMSPEC missing", () => {
+    expect(detectShell({ platform: "win32", env: {} })).toBe("powershell.exe");
+  });
+
+  it("uses SHELL on Linux when present", () => {
+    expect(detectShell({
+      platform: "linux",
+      env: { SHELL: "/bin/zsh" },
+    })).toBe("/bin/zsh");
+  });
+
+  it("falls back to /bin/bash on Linux when SHELL missing", () => {
+    expect(detectShell({ platform: "linux", env: {} })).toBe("/bin/bash");
+  });
+
+  it("uses SHELL on macOS when present", () => {
+    expect(detectShell({
+      platform: "darwin",
+      env: { SHELL: "/bin/zsh" },
+    })).toBe("/bin/zsh");
+  });
+
+  it("falls back to /bin/bash on macOS when SHELL missing", () => {
+    expect(detectShell({ platform: "darwin", env: {} })).toBe("/bin/bash");
+  });
+
+  it("ignores SHELL on Windows (uses COMSPEC path)", () => {
+    // Even if some Windows environment sets SHELL (e.g. Git Bash), the PTY
+    // primitive must use COMSPEC / powershell because that's what node-pty
+    // can actually spawn on win32.
+    expect(detectShell({
+      platform: "win32",
+      env: { SHELL: "/usr/bin/bash" },
+    })).toBe("powershell.exe");
+  });
+});
+
+describe("getTerminalEnvHints", () => {
+  it("adds TERM=cygwin on Windows when TERM is not set", () => {
+    expect(getTerminalEnvHints({ platform: "win32", env: {} })).toEqual({ TERM: "cygwin" });
+  });
+
+  it("leaves TERM alone on Windows when already set", () => {
+    expect(getTerminalEnvHints({
+      platform: "win32",
+      env: { TERM: "xterm-256color" },
+    })).toEqual({});
+  });
+
+  it("adds no hints on Linux", () => {
+    expect(getTerminalEnvHints({ platform: "linux", env: {} })).toEqual({});
+  });
+
+  it("adds no hints on macOS", () => {
+    expect(getTerminalEnvHints({ platform: "darwin", env: {} })).toEqual({});
+  });
+});

package/packages/shared/src/__tests__/process-identify.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Tests for platform/process-identify.ts.
+ *
+ * Uses an injected fake `exec` so we can simulate ps/tasklist output on
+ * any host OS. All tests pass `platform` explicitly.
+ */
+import { describe, it, expect, vi } from "vitest";
+import {
+  findPidByMarker,
+  isProcessLikePi,
+  isPiCommandLine,
+} from "../platform/process-identify.js";
+
+describe("isPiCommandLine", () => {
+  it("matches pi", () => {
+    expect(isPiCommandLine("/usr/bin/pi --mode rpc")).toBe(true);
+  });
+  it("matches node", () => {
+    expect(isPiCommandLine("node cli.js")).toBe(true);
+  });
+  it("matches pi even with path prefixes", () => {
+    expect(isPiCommandLine("/opt/foo/pi --args")).toBe(true);
+  });
+  it("does not match unrelated processes", () => {
+    expect(isPiCommandLine("/bin/bash")).toBe(false);
+    expect(isPiCommandLine("/usr/bin/zsh")).toBe(false);
+  });
+  it("does not match substrings without word boundary", () => {
+    // "pip" and "typescript" must not match pi or node.
+    expect(isPiCommandLine("pip install something")).toBe(false);
+    expect(isPiCommandLine("/usr/bin/typescript-compiler")).toBe(false);
+  });
+});
+
+describe("findPidByMarker", () => {
+  it("Windows returns empty array without execution", () => {
+    const exec = vi.fn(() => "should not be called");
+    const result = findPidByMarker("marker", { platform: "win32", exec: exec as any });
+    expect(result).toEqual([]);
+    expect(exec).not.toHaveBeenCalled();
+  });
+
+  it("Linux parses ps output and filters to sentinel lines", () => {
+    const fakeOutput = [
+      "12345 sh -c tail -f /dev/null | pi --mode rpc session-abc",
+      "67890 grep session-abc",
+      "11111 sleep 2147483647 | pi --mode rpc session-abc",
+      "22222 vim notes-about-session-abc.txt",
+    ].join("\n");
+    const exec = vi.fn(() => fakeOutput) as any;
+    const result = findPidByMarker("session-abc", { platform: "linux", exec });
+    expect(result).toEqual([12345, 11111]);
+  });
+
+  it("macOS parses ps output similarly", () => {
+    const fakeOutput = "99999 tail -f /dev/null | pi --mode rpc s1";
+    const exec = vi.fn(() => fakeOutput) as any;
+    const result = findPidByMarker("s1", { platform: "darwin", exec });
+    expect(result).toEqual([99999]);
+  });
+
+  it("returns empty array when no match", () => {
+    const exec = vi.fn(() => "") as any;
+    const result = findPidByMarker("nothing", { platform: "linux", exec });
+    expect(result).toEqual([]);
+  });
+
+  it("returns empty array when exec throws (process dead / permission)", () => {
+    const exec = vi.fn(() => { throw new Error("no such command"); }) as any;
+    const result = findPidByMarker("x", { platform: "linux", exec });
+    expect(result).toEqual([]);
+  });
+
+  it("excludes lines without pi headless sentinels", () => {
+    const fakeOutput = "12345 some-random-process matching-marker-only";
+    const exec = vi.fn(() => fakeOutput) as any;
+    const result = findPidByMarker("matching-marker", { platform: "linux", exec });
+    expect(result).toEqual([]);
+  });
+});
+
+describe("isProcessLikePi", () => {
+  it("Windows returns true unconditionally", () => {
+    const exec = vi.fn(() => "should not be called");
+    expect(isProcessLikePi(1234, { platform: "win32", exec: exec as any })).toBe(true);
+    expect(exec).not.toHaveBeenCalled();
+  });
+
+  it("Linux matches via /proc cmdline", () => {
+    const exec = vi.fn(() => "/usr/bin/node /opt/pi-coding-agent/dist/cli.js") as any;
+    expect(isProcessLikePi(1234, { platform: "linux", exec })).toBe(true);
+  });
+
+  it("Linux does not match non-pi", () => {
+    const exec = vi.fn(() => "/bin/bash") as any;
+    expect(isProcessLikePi(1234, { platform: "linux", exec })).toBe(false);
+  });
+
+  it("macOS uses ps -p -o command=", () => {
+    let capturedCmd = "";
+    const exec = ((cmd: string) => {
+      capturedCmd = cmd;
+      return "node cli.js --mode rpc";
+    }) as any;
+    expect(isProcessLikePi(555, { platform: "darwin", exec })).toBe(true);
+    expect(capturedCmd).toMatch(/ps -p 555 -o command=/);
+  });
+
+  it("returns false when process has exited (exec throws)", () => {
+    const exec = vi.fn(() => { throw new Error("no such process"); }) as any;
+    expect(isProcessLikePi(9999, { platform: "linux", exec })).toBe(false);
+  });
+});

package/packages/shared/src/__tests__/recommended-extensions.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect } from "vitest";
+import {
+	BUNDLED_EXTENSION_IDS,
+	RECOMMENDED_EXTENSIONS,
+	getRecommendedExtension,
+	getRecommendedByStatus,
+	type RecommendedExtension,
+} from "../recommended-extensions.js";
+
+describe("RECOMMENDED_EXTENSIONS manifest", () => {
+	it("contains exactly the five expected entries", () => {
+		const ids = RECOMMENDED_EXTENSIONS.map((e) => e.id).sort();
+		expect(ids).toEqual(
+			[
+				"pi-anthropic-messages",
+				"pi-agent-browser",
+				"pi-flows",
+				"pi-web-access",
+				"tintinweb-pi-subagents",
+			].sort(),
+		);
+	});
+
+	it("every entry has the required shape", () => {
+		for (const entry of RECOMMENDED_EXTENSIONS) {
+			expect(typeof entry.id).toBe("string");
+			expect(entry.id.length).toBeGreaterThan(0);
+			expect(typeof entry.source).toBe("string");
+			expect(entry.source.length).toBeGreaterThan(0);
+			expect(typeof entry.displayName).toBe("string");
+			expect(typeof entry.fallbackDescription).toBe("string");
+			expect(entry.fallbackDescription.length).toBeGreaterThan(10);
+			expect(["required", "strongly-suggested", "optional"]).toContain(entry.status);
+			expect(Array.isArray(entry.unlocks)).toBe(true);
+			expect(entry.unlocks.length).toBeGreaterThan(0);
+		}
+	});
+
+	it("pi-anthropic-messages is marked required and uses HTTPS git URL", () => {
+		const entry = getRecommendedExtension("pi-anthropic-messages");
+		expect(entry).toBeDefined();
+		expect(entry?.status).toBe("required");
+		expect(entry?.source).toContain("https://github.com/BlackBeltTechnology/pi-anthropic-messages.git");
+		expect(entry?.autowired).toBe(true);
+	});
+
+	it("pi-flows uses HTTPS git URL and registers flow-engine tools", () => {
+		const entry = getRecommendedExtension("pi-flows");
+		expect(entry).toBeDefined();
+		expect(entry?.source).toBe("https://github.com/BlackBeltTechnology/pi-flows.git");
+		expect(entry?.toolsRegistered).toContain("subagent");
+		expect(entry?.toolsRegistered).toContain("flow_write");
+	});
+
+	it("tintinweb-pi-subagents registers Agent under its canonical capitalization", () => {
+		const entry = getRecommendedExtension("tintinweb-pi-subagents");
+		expect(entry).toBeDefined();
+		expect(entry?.source).toBe("npm:@tintinweb/pi-subagents");
+		expect(entry?.toolsRegistered).toContain("Agent");
+	});
+
+	it("npm-sourced entries use the npm: prefix", () => {
+		const npmEntries = RECOMMENDED_EXTENSIONS.filter((e) => e.source.startsWith("npm:"));
+		expect(npmEntries.map((e) => e.id).sort()).toEqual(
+			["pi-agent-browser", "pi-web-access", "tintinweb-pi-subagents"].sort(),
+		);
+	});
+
+	it("git-sourced entries use the https://github.com/.../.git HTTPS form", () => {
+		const gitEntries = RECOMMENDED_EXTENSIONS.filter((e) =>
+			e.source.startsWith("https://github.com/"),
+		);
+		for (const entry of gitEntries) {
+			expect(entry.source).toMatch(/^https:\/\/github\.com\/[^/]+\/[^/]+\.git$/);
+		}
+		expect(gitEntries.map((e) => e.id).sort()).toEqual(
+			["pi-anthropic-messages", "pi-flows"].sort(),
+		);
+	});
+});
+
+describe("getRecommendedExtension", () => {
+	it("returns the entry when id matches", () => {
+		const e = getRecommendedExtension("pi-web-access");
+		expect(e?.displayName).toBe("pi-web-access");
+	});
+
+	it("returns undefined for unknown ids", () => {
+		expect(getRecommendedExtension("does-not-exist")).toBeUndefined();
+	});
+});
+
+describe("getRecommendedByStatus", () => {
+	it("filters by required", () => {
+		const required = getRecommendedByStatus("required");
+		expect(required.map((e) => e.id)).toEqual(["pi-anthropic-messages"]);
+	});
+
+	it("filters by strongly-suggested", () => {
+		const suggested = getRecommendedByStatus("strongly-suggested");
+		expect(suggested.map((e) => e.id).sort()).toEqual(
+			["pi-flows", "pi-web-access", "tintinweb-pi-subagents"].sort(),
+		);
+	});
+
+	it("filters by optional", () => {
+		const optional = getRecommendedByStatus("optional");
+		expect(optional.map((e) => e.id)).toEqual(["pi-agent-browser"]);
+	});
+});
+
+describe("RecommendedExtension type", () => {
+	it("accepts a minimal entry", () => {
+		const entry: RecommendedExtension = {
+			id: "x",
+			source: "npm:x",
+			displayName: "X",
+			fallbackDescription: "A test extension description.",
+			status: "optional",
+			unlocks: ["something"],
+		};
+		expect(entry.id).toBe("x");
+	});
+});
+
+// ── BUNDLED_EXTENSION_IDS manifest (task 2 of bundle-first-party-extensions) ──
+
+describe("BUNDLED_EXTENSION_IDS manifest", () => {
+	it("contains exactly the v0.x initial bundled set", () => {
+		expect([...BUNDLED_EXTENSION_IDS].sort()).toEqual(
+			["pi-anthropic-messages", "pi-flows"].sort(),
+		);
+	});
+
+	it("every bundled id appears in RECOMMENDED_EXTENSIONS", () => {
+		const recommendedIds = new Set(RECOMMENDED_EXTENSIONS.map((e) => e.id));
+		for (const id of BUNDLED_EXTENSION_IDS) {
+			expect(recommendedIds.has(id)).toBe(true);
+		}
+	});
+
+	it("every bundled id has a git-based source (no npm:, no local paths)", () => {
+		for (const id of BUNDLED_EXTENSION_IDS) {
+			const entry = RECOMMENDED_EXTENSIONS.find((e) => e.id === id);
+			expect(entry, `RECOMMENDED_EXTENSIONS missing entry for ${id}`).toBeDefined();
+			const source = entry!.source;
+			const isGit =
+				source.endsWith(".git") ||
+				source.startsWith("git@") ||
+				source.startsWith("git:") ||
+				/^https?:\/\/.+\/.+/.test(source);
+			expect(isGit, `${id} source is not git-based: ${source}`).toBe(true);
+			expect(source.startsWith("npm:"), `${id} must not be an npm source`).toBe(false);
+		}
+	});
+});