@juicesharp/rpiv-pi 0.9.1 → 0.11.0

package/extensions/rpiv-core/agents.test.ts

@@ -0,0 +1,194 @@
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { BUNDLED_AGENTS_DIR, syncBundledAgents } from "./agents.js";
+
+let cwd: string;
+let targetDir: string;
+let manifestPath: string;
+
+beforeEach(() => {
+	cwd = mkdtempSync(join(tmpdir(), "rpiv-agents-"));
+	targetDir = join(cwd, ".pi", "agents");
+	manifestPath = join(targetDir, ".rpiv-managed.json");
+});
+afterEach(() => {
+	rmSync(cwd, { recursive: true, force: true });
+	vi.restoreAllMocks();
+});
+
+describe("syncBundledAgents — first run (empty target)", () => {
+	it("copies every source .md and writes manifest", () => {
+		const r = syncBundledAgents(cwd, false);
+		const bundled = readdirSync(BUNDLED_AGENTS_DIR).filter((f) => f.endsWith(".md"));
+		expect(r.added.sort()).toEqual(bundled.sort());
+		expect(r.updated).toEqual([]);
+		expect(r.errors).toEqual([]);
+		expect(existsSync(manifestPath)).toBe(true);
+		const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+		expect(manifest.sort()).toEqual(bundled.sort());
+	});
+});
+
+describe("syncBundledAgents — bootstrap-claim from manifest-less drift", () => {
+	it("claims pre-existing files matching bundled names as managed", () => {
+		const bundled = readdirSync(BUNDLED_AGENTS_DIR).filter((f) => f.endsWith(".md"));
+		if (bundled.length === 0) return;
+		mkdirSync(targetDir, { recursive: true });
+		writeFileSync(join(targetDir, bundled[0]), "drift content", "utf-8");
+		const r = syncBundledAgents(cwd, false);
+		expect(r.pendingUpdate).toContain(bundled[0]);
+		expect(readFileSync(join(targetDir, bundled[0]), "utf-8")).toBe("drift content");
+	});
+});
+
+describe("syncBundledAgents — apply=false (detect only)", () => {
+	it("reports pendingUpdate for changed managed files without touching them", () => {
+		const bundled = readdirSync(BUNDLED_AGENTS_DIR).filter((f) => f.endsWith(".md"));
+		if (bundled.length === 0) return;
+		syncBundledAgents(cwd, true);
+		writeFileSync(join(targetDir, bundled[0]), "user-modified", "utf-8");
+		const r = syncBundledAgents(cwd, false);
+		expect(r.pendingUpdate).toContain(bundled[0]);
+		expect(readFileSync(join(targetDir, bundled[0]), "utf-8")).toBe("user-modified");
+	});
+});
+
+describe("syncBundledAgents — apply=true (mutating sync)", () => {
+	it("overwrites changed managed files", () => {
+		const bundled = readdirSync(BUNDLED_AGENTS_DIR).filter((f) => f.endsWith(".md"));
+		if (bundled.length === 0) return;
+		syncBundledAgents(cwd, true);
+		writeFileSync(join(targetDir, bundled[0]), "user-modified", "utf-8");
+		const r = syncBundledAgents(cwd, true);
+		expect(r.updated).toContain(bundled[0]);
+		const srcContent = readFileSync(join(BUNDLED_AGENTS_DIR, bundled[0]), "utf-8");
+		expect(readFileSync(join(targetDir, bundled[0]), "utf-8")).toBe(srcContent);
+	});
+
+	it("removes stale managed files absent from source", () => {
+		mkdirSync(targetDir, { recursive: true });
+		writeFileSync(join(targetDir, "stale.md"), "x", "utf-8");
+		writeFileSync(manifestPath, JSON.stringify(["stale.md"]), "utf-8");
+		const r = syncBundledAgents(cwd, true);
+		expect(r.removed).toContain("stale.md");
+		expect(existsSync(join(targetDir, "stale.md"))).toBe(false);
+	});
+
+	it("leaves unchanged managed files alone", () => {
+		syncBundledAgents(cwd, true);
+		const r = syncBundledAgents(cwd, true);
+		expect(r.updated).toEqual([]);
+		expect(r.unchanged.length).toBeGreaterThan(0);
+	});
+});
+
+describe("syncBundledAgents — error paths", () => {
+	it.skipIf(process.platform === "win32")("collects copy error when dest is read-only", () => {
+		// Create a read-only target dir so copyFileSync fails with EACCES/EPERM
+		const bundled = readdirSync(BUNDLED_AGENTS_DIR).filter((f) => f.endsWith(".md"));
+		if (bundled.length === 0) return;
+		mkdirSync(targetDir, { recursive: true });
+		chmodSync(targetDir, 0o500);
+		try {
+			const r = syncBundledAgents(cwd, false);
+			// At least one copy op should have failed; otherwise nothing proves the error path
+			const errorTripped = r.errors.some((e) => e.op === "copy") || r.added.length < bundled.length;
+			expect(errorTripped).toBe(true);
+		} finally {
+			chmodSync(targetDir, 0o700);
+		}
+	});
+});
+
+describe("syncBundledAgents — stale-file detection (apply=false)", () => {
+	it("reports pendingRemove when a managed file has no matching source", () => {
+		mkdirSync(targetDir, { recursive: true });
+		writeFileSync(join(targetDir, "stale.md"), "x", "utf-8");
+		writeFileSync(manifestPath, JSON.stringify(["stale.md"]), "utf-8");
+		const r = syncBundledAgents(cwd, false);
+		expect(r.pendingRemove).toContain("stale.md");
+		expect(r.removed).toEqual([]);
+		expect(existsSync(join(targetDir, "stale.md"))).toBe(true);
+	});
+
+	it("keeps pendingRemove entries in the manifest so the next apply can finish removal", () => {
+		mkdirSync(targetDir, { recursive: true });
+		writeFileSync(join(targetDir, "stale.md"), "x", "utf-8");
+		writeFileSync(manifestPath, JSON.stringify(["stale.md"]), "utf-8");
+		syncBundledAgents(cwd, false);
+		const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as string[];
+		expect(manifest).toContain("stale.md");
+	});
+
+	it("skips pendingRemove when the stale file no longer exists on disk", () => {
+		mkdirSync(targetDir, { recursive: true });
+		// Manifest claims stale.md but disk does not have it
+		writeFileSync(manifestPath, JSON.stringify(["stale.md"]), "utf-8");
+		const r = syncBundledAgents(cwd, false);
+		expect(r.pendingRemove).not.toContain("stale.md");
+		expect(r.removed).not.toContain("stale.md");
+	});
+});
+
+describe("syncBundledAgents — manifest robustness", () => {
+	it("treats a corrupt manifest (invalid JSON) as empty and re-bootstraps", () => {
+		mkdirSync(targetDir, { recursive: true });
+		writeFileSync(manifestPath, "{ not json ::", "utf-8");
+		const r = syncBundledAgents(cwd, false);
+		expect(r.errors).toEqual([]);
+		// After sync, the manifest should be valid JSON again.
+		const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as string[];
+		expect(Array.isArray(manifest)).toBe(true);
+	});
+
+	it("treats a non-array manifest as empty and re-bootstraps", () => {
+		mkdirSync(targetDir, { recursive: true });
+		writeFileSync(manifestPath, JSON.stringify({ oops: true }), "utf-8");
+		const r = syncBundledAgents(cwd, false);
+		expect(r.errors).toEqual([]);
+		const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as string[];
+		expect(Array.isArray(manifest)).toBe(true);
+	});
+
+	it("filters non-string manifest entries during parse", () => {
+		mkdirSync(targetDir, { recursive: true });
+		writeFileSync(join(targetDir, "unrelated.md"), "keep me", "utf-8");
+		// Write manifest containing mixed types (must be ignored per-entry rather than whole-file)
+		writeFileSync(manifestPath, JSON.stringify([42, null, "unrelated.md"]), "utf-8");
+		const r = syncBundledAgents(cwd, false);
+		expect(r.errors).toEqual([]);
+		// unrelated.md is not in source, so it will be tracked for pendingRemove
+		expect(r.pendingRemove).toContain("unrelated.md");
+	});
+});
+
+describe("syncBundledAgents — subsequent-run bookkeeping", () => {
+	it("reports unchanged (not added) on a second run with no changes", () => {
+		syncBundledAgents(cwd, true);
+		const r = syncBundledAgents(cwd, false);
+		expect(r.added).toEqual([]);
+		expect(r.updated).toEqual([]);
+		expect(r.pendingUpdate).toEqual([]);
+		expect(r.unchanged.length).toBeGreaterThan(0);
+	});
+
+	it("treats a destination file that was manually removed as a new add on next sync", () => {
+		syncBundledAgents(cwd, true);
+		const bundled = readdirSync(BUNDLED_AGENTS_DIR).filter((f) => f.endsWith(".md"));
+		if (bundled.length === 0) return;
+		rmSync(join(targetDir, bundled[0]));
+		const r = syncBundledAgents(cwd, false);
+		expect(r.added).toContain(bundled[0]);
+	});
+});

package/extensions/rpiv-core/constants.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { FLAG_DEBUG, MSG_TYPE_GIT_CONTEXT, MSG_TYPE_GUIDANCE } from "./constants.js";
+
+describe("rpiv-core constants", () => {
+	it("FLAG_DEBUG is the canonical debug-flag name", () => {
+		expect(FLAG_DEBUG).toBe("rpiv-debug");
+	});
+	it("MSG_TYPE_GIT_CONTEXT is the canonical git-context message type", () => {
+		expect(MSG_TYPE_GIT_CONTEXT).toBe("rpiv-git-context");
+	});
+	it("MSG_TYPE_GUIDANCE is the canonical guidance message type", () => {
+		expect(MSG_TYPE_GUIDANCE).toBe("rpiv-guidance");
+	});
+});

package/extensions/rpiv-core/git-context.matcher.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { isGitMutatingCommand } from "./git-context.js";
+
+describe("isGitMutatingCommand — positives", () => {
+	const mutating = [
+		"git checkout main",
+		"git switch feature",
+		"git commit -m 'x'",
+		"git merge main",
+		"git rebase main",
+		"git pull",
+		"git reset --hard HEAD",
+		"git revert abc",
+		"git cherry-pick abc",
+		"git worktree add ../wt",
+		"git am < patch",
+		"git stash",
+	];
+	for (const cmd of mutating) {
+		it(`matches: ${cmd}`, () => {
+			expect(isGitMutatingCommand(cmd)).toBe(true);
+		});
+	}
+	it("matches when chained with preceding command", () => {
+		expect(isGitMutatingCommand("cd x && git commit")).toBe(true);
+	});
+});
+
+describe("isGitMutatingCommand — negatives", () => {
+	const nonMutating = [
+		"git status",
+		"git log",
+		"git diff",
+		"git rev-parse HEAD",
+		"git config user.name",
+		"gitmoji commit",
+		"git --version",
+	];
+	for (const cmd of nonMutating) {
+		it(`does NOT match: ${cmd}`, () => {
+			expect(isGitMutatingCommand(cmd)).toBe(false);
+		});
+	}
+	it("rejects empty string", () => {
+		expect(isGitMutatingCommand("")).toBe(false);
+	});
+});

package/extensions/rpiv-core/git-context.test.ts

@@ -0,0 +1,109 @@
+import { createMockPi, stubGitExec } from "@juicesharp/rpiv-test-utils";
+import { beforeEach, describe, expect, it } from "vitest";
+import { clearGitContextCache, getGitContext, resetInjectedMarker, takeGitContextIfChanged } from "./git-context.js";
+
+beforeEach(() => {
+	clearGitContextCache();
+	resetInjectedMarker();
+});
+
+describe("getGitContext", () => {
+	it("parses branch + commit + user from three exec calls", async () => {
+		const { pi } = createMockPi({
+			exec: stubGitExec({ branch: "main", commit: "abc1234", user: "alice" }) as never,
+		});
+		const ctx = await getGitContext(pi);
+		expect(ctx).toEqual({ branch: "main", commit: "abc1234", user: "alice" });
+	});
+
+	it("remaps literal HEAD to 'detached'", async () => {
+		const { pi } = createMockPi({
+			exec: stubGitExec({ branch: "HEAD", commit: "abc", user: "alice" }) as never,
+		});
+		const ctx = await getGitContext(pi);
+		expect(ctx?.branch).toBe("detached");
+	});
+
+	it("returns null when both branch and commit are empty (not a repo)", async () => {
+		const { pi } = createMockPi({ exec: stubGitExec({}) as never });
+		expect(await getGitContext(pi)).toBeNull();
+	});
+
+	it("falls back to process.env.USER when git config user.name errors", async () => {
+		const { pi } = createMockPi({
+			exec: stubGitExec({ branch: "main", commit: "abc", userError: new Error("no config") }) as never,
+		});
+		process.env.USER = "env-alice";
+		const ctx = await getGitContext(pi);
+		expect(ctx?.user).toBe("env-alice");
+	});
+
+	it("falls back to 'unknown' when neither git nor env has user", async () => {
+		const origUser = process.env.USER;
+		delete process.env.USER;
+		try {
+			const { pi } = createMockPi({
+				exec: stubGitExec({ branch: "main", commit: "abc", userError: new Error("x") }) as never,
+			});
+			const ctx = await getGitContext(pi);
+			expect(ctx?.user).toBe("unknown");
+		} finally {
+			if (origUser) process.env.USER = origUser;
+		}
+	});
+
+	it("memoises: subsequent calls do not re-exec", async () => {
+		const exec = stubGitExec({ branch: "main", commit: "abc", user: "alice" });
+		const { pi } = createMockPi({ exec: exec as never });
+		await getGitContext(pi);
+		await getGitContext(pi);
+		expect(exec).toHaveBeenCalledTimes(3); // 3 initial exec calls, no second-round
+	});
+
+	it("clearGitContextCache forces re-read", async () => {
+		const exec = stubGitExec({ branch: "main", commit: "abc", user: "alice" });
+		const { pi } = createMockPi({ exec: exec as never });
+		await getGitContext(pi);
+		clearGitContextCache();
+		await getGitContext(pi);
+		expect(exec).toHaveBeenCalledTimes(6);
+	});
+});
+
+describe("takeGitContextIfChanged", () => {
+	it("returns the context-line on first call", async () => {
+		const { pi } = createMockPi({
+			exec: stubGitExec({ branch: "main", commit: "abc", user: "alice" }) as never,
+		});
+		const r = await takeGitContextIfChanged(pi);
+		expect(r).toContain("- Branch: main");
+		expect(r).toContain("- Commit: abc");
+		expect(r).toContain("- User: alice");
+	});
+
+	it("returns null on second call when signature unchanged", async () => {
+		const { pi } = createMockPi({
+			exec: stubGitExec({ branch: "main", commit: "abc", user: "alice" }) as never,
+		});
+		await takeGitContextIfChanged(pi);
+		expect(await takeGitContextIfChanged(pi)).toBeNull();
+	});
+
+	it("re-emits after clearGitContextCache + resetInjectedMarker + signature change", async () => {
+		const { pi } = createMockPi({
+			exec: stubGitExec({ branch: "main", commit: "abc", user: "alice" }) as never,
+		});
+		await takeGitContextIfChanged(pi);
+		clearGitContextCache();
+		resetInjectedMarker();
+		const { pi: pi2 } = createMockPi({
+			exec: stubGitExec({ branch: "feature", commit: "def", user: "alice" }) as never,
+		});
+		expect(await takeGitContextIfChanged(pi2)).not.toBeNull();
+	});
+
+	it("returns null when not in a git repo", async () => {
+		const { pi } = createMockPi({ exec: stubGitExec({}) as never });
+		expect(await takeGitContextIfChanged(pi)).toBeNull();
+	});
+});

package/extensions/rpiv-core/guidance.test.ts

@@ -0,0 +1,136 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createMockPi, writeGuidanceTree } from "@juicesharp/rpiv-test-utils";
+import { afterEach, beforeEach, describe, expect, it, type vi } from "vitest";
+import { clearInjectionState, handleToolCallGuidance, injectRootGuidance, resolveGuidance } from "./guidance.js";
+
+let projectDir: string;
+
+beforeEach(() => {
+	projectDir = mkdtempSync(join(tmpdir(), "rpiv-guidance-"));
+	clearInjectionState();
+});
+afterEach(() => {
+	rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe("resolveGuidance — ladder", () => {
+	it("AGENTS.md > CLAUDE.md > architecture.md at depth > 0", () => {
+		writeGuidanceTree(projectDir, {
+			"src/AGENTS.md": "agents-body",
+			"src/CLAUDE.md": "claude-body",
+			".rpiv/guidance/src/architecture.md": "arch-body",
+		});
+		const resolved = resolveGuidance(join(projectDir, "src", "foo.ts"), projectDir);
+		const srcEntry = resolved.find((r) => r.relativePath.startsWith("src/"));
+		expect(srcEntry?.kind).toBe("agents");
+	});
+
+	it("depth 0 skips AGENTS/CLAUDE but keeps root architecture.md", () => {
+		writeGuidanceTree(projectDir, {
+			"AGENTS.md": "root-agents",
+			".rpiv/guidance/architecture.md": "root-arch",
+		});
+		const resolved = resolveGuidance(join(projectDir, "any", "file.ts"), projectDir);
+		const rootEntry = resolved.find((r) => r.relativePath === ".rpiv/guidance/architecture.md");
+		expect(rootEntry?.kind).toBe("architecture");
+		expect(resolved.some((r) => r.relativePath === "AGENTS.md")).toBe(false);
+	});
+
+	it("returns root-first, specific-last order", () => {
+		writeGuidanceTree(projectDir, {
+			".rpiv/guidance/architecture.md": "root",
+			"a/AGENTS.md": "a",
+			"a/b/AGENTS.md": "ab",
+		});
+		const resolved = resolveGuidance(join(projectDir, "a", "b", "c.ts"), projectDir);
+		expect(resolved.map((r) => r.content)).toEqual(["root", "a", "ab"]);
+	});
+
+	it("returns empty when file is outside projectDir", () => {
+		expect(resolveGuidance("/totally/elsewhere/foo.ts", projectDir)).toEqual([]);
+	});
+
+	it("returns empty when nothing exists along the ladder", () => {
+		expect(resolveGuidance(join(projectDir, "x.ts"), projectDir)).toEqual([]);
+	});
+});
+
+describe("injectRootGuidance", () => {
+	it("sends root architecture.md when present", () => {
+		writeGuidanceTree(projectDir, { ".rpiv/guidance/architecture.md": "body" });
+		const { pi } = createMockPi();
+		injectRootGuidance(projectDir, pi);
+		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
+		expect((pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0].content).toContain("body");
+	});
+
+	it("is idempotent across calls within a session", () => {
+		writeGuidanceTree(projectDir, { ".rpiv/guidance/architecture.md": "body" });
+		const { pi } = createMockPi();
+		injectRootGuidance(projectDir, pi);
+		injectRootGuidance(projectDir, pi);
+		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
+	});
+
+	it("re-injects after clearInjectionState", () => {
+		writeGuidanceTree(projectDir, { ".rpiv/guidance/architecture.md": "body" });
+		const { pi } = createMockPi();
+		injectRootGuidance(projectDir, pi);
+		clearInjectionState();
+		injectRootGuidance(projectDir, pi);
+		expect(pi.sendMessage).toHaveBeenCalledTimes(2);
+	});
+
+	it("no-ops when root architecture.md is missing", () => {
+		const { pi } = createMockPi();
+		injectRootGuidance(projectDir, pi);
+		expect(pi.sendMessage).not.toHaveBeenCalled();
+	});
+});
+
+describe("handleToolCallGuidance", () => {
+	it("skips non-read/edit/write tools", () => {
+		const { pi } = createMockPi();
+		handleToolCallGuidance({ toolName: "bash", input: {} }, { cwd: projectDir }, pi);
+		expect(pi.sendMessage).not.toHaveBeenCalled();
+	});
+
+	it("dedupes per-file across multiple tool_calls", () => {
+		writeGuidanceTree(projectDir, { "src/AGENTS.md": "a" });
+		const { pi } = createMockPi();
+		const ev = { toolName: "read", input: { file_path: join(projectDir, "src", "x.ts") } };
+		handleToolCallGuidance(ev, { cwd: projectDir }, pi);
+		handleToolCallGuidance(ev, { cwd: projectDir }, pi);
+		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
+	});
+
+	it("supports both 'path' and 'file_path' input keys", () => {
+		writeGuidanceTree(projectDir, { "src/AGENTS.md": "a" });
+		const { pi } = createMockPi();
+		handleToolCallGuidance(
+			{ toolName: "edit", input: { path: join(projectDir, "src", "x.ts") } },
+			{ cwd: projectDir },
+			pi,
+		);
+		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
+	});
+
+	it("emits one sendMessage combining multiple newly-resolved files", () => {
+		writeGuidanceTree(projectDir, {
+			".rpiv/guidance/architecture.md": "root",
+			"src/AGENTS.md": "src",
+		});
+		const { pi } = createMockPi();
+		handleToolCallGuidance(
+			{ toolName: "write", input: { file_path: join(projectDir, "src", "x.ts") } },
+			{ cwd: projectDir },
+			pi,
+		);
+		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
+		const content = (pi.sendMessage as ReturnType<typeof vi.fn>).mock.calls[0][0].content;
+		expect(content).toContain("root");
+		expect(content).toContain("src");
+	});
+});

package/extensions/rpiv-core/package-checks.test.ts

@@ -0,0 +1,59 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { findMissingSiblings } from "./package-checks.js";
+import { SIBLINGS } from "./siblings.js";
+
+const SETTINGS_PATH = join(process.env.HOME!, ".pi", "agent", "settings.json");
+
+function writeSettings(contents: unknown) {
+	mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+	writeFileSync(SETTINGS_PATH, JSON.stringify(contents), "utf-8");
+}
+
+describe("findMissingSiblings", () => {
+	it("returns all 7 siblings when settings.json is missing", () => {
+		expect(findMissingSiblings()).toHaveLength(SIBLINGS.length);
+	});
+
+	it("returns all 7 siblings when JSON is invalid", () => {
+		mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+		writeFileSync(SETTINGS_PATH, "{not json", "utf-8");
+		expect(findMissingSiblings()).toHaveLength(SIBLINGS.length);
+	});
+
+	it("returns all 7 siblings when packages field is absent", () => {
+		writeSettings({ other: "data" });
+		expect(findMissingSiblings()).toHaveLength(SIBLINGS.length);
+	});
+
+	it("returns all 7 siblings when packages is not an array", () => {
+		writeSettings({ packages: "not-array" });
+		expect(findMissingSiblings()).toHaveLength(SIBLINGS.length);
+	});
+
+	it("filters out non-string entries defensively", () => {
+		writeSettings({ packages: [null, 42, "@juicesharp/rpiv-todo"] });
+		const missing = findMissingSiblings();
+		expect(missing.find((s) => s.matches.test("@juicesharp/rpiv-todo"))).toBeUndefined();
+	});
+
+	it("matches case-insensitively", () => {
+		writeSettings({ packages: ["@JUICESHARP/RPIV-TODO"] });
+		const missing = findMissingSiblings();
+		expect(missing.find((s) => s.matches.test("@juicesharp/rpiv-todo"))).toBeUndefined();
+	});
+
+	it("rpiv-args word-boundary: treats rpiv-args-extended as non-install", () => {
+		writeSettings({ packages: ["@juicesharp/rpiv-args-extended"] });
+		const missing = findMissingSiblings();
+		expect(missing.find((s) => s.pkg.endsWith("/rpiv-args"))).toBeDefined();
+	});
+
+	it("returns [] when all 7 siblings are installed", () => {
+		writeSettings({
+			packages: SIBLINGS.map((s) => s.pkg.replace(/^npm:/, "")),
+		});
+		expect(findMissingSiblings()).toEqual([]);
+	});
+});

package/extensions/rpiv-core/pi-installer.test.ts

@@ -0,0 +1,100 @@
+import { makeSpawnStub } from "@juicesharp/rpiv-test-utils";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("node:child_process", () => ({ spawn: vi.fn() }));
+
+import { spawn } from "node:child_process";
+import { spawnPiInstall } from "./pi-installer.js";
+
+beforeEach(() => {
+	vi.mocked(spawn).mockReset();
+});
+
+describe("spawnPiInstall — success path", () => {
+	it("resolves with exit 0 + buffered stdout/stderr", async () => {
+		vi.mocked(spawn).mockImplementationOnce(
+			() => makeSpawnStub({ stdout: "installed\n", stderr: "", exitCode: 0 }) as unknown as ReturnType<typeof spawn>,
+		);
+		const r = await spawnPiInstall("@x/y", 30_000);
+		expect(r).toEqual({ code: 0, stdout: "installed\n", stderr: "" });
+	});
+});
+
+describe("spawnPiInstall — non-zero exit", () => {
+	it("returns exit code and accumulated stderr", async () => {
+		vi.mocked(spawn).mockImplementationOnce(
+			() => makeSpawnStub({ stdout: "", stderr: "fail\n", exitCode: 2 }) as unknown as ReturnType<typeof spawn>,
+		);
+		const r = await spawnPiInstall("@x/y", 30_000);
+		expect(r.code).toBe(2);
+		expect(r.stderr).toBe("fail\n");
+	});
+
+	it("fallback code=1 when close emits null", async () => {
+		const stub = makeSpawnStub({ neverSettles: true });
+		vi.mocked(spawn).mockImplementationOnce(() => stub as unknown as ReturnType<typeof spawn>);
+		const promise = spawnPiInstall("@x/y", 30_000);
+		stub.emit("close", null);
+		const r = await promise;
+		expect(r.code).toBe(1);
+	});
+});
+
+describe("spawnPiInstall — error event before close", () => {
+	it("settles with code=1 + error.message in stderr", async () => {
+		vi.mocked(spawn).mockImplementationOnce(
+			() => makeSpawnStub({ error: new Error("ENOENT pi") }) as unknown as ReturnType<typeof spawn>,
+		);
+		const r = await spawnPiInstall("@x/y", 30_000);
+		expect(r.code).toBe(1);
+		expect(r.stderr).toContain("ENOENT pi");
+	});
+});
+
+describe("spawnPiInstall — timeout", () => {
+	it("kills with SIGTERM at timeout and resolves with code 124", async () => {
+		vi.useFakeTimers();
+		const stub = makeSpawnStub({ neverSettles: true });
+		const killSpy = vi.spyOn(stub, "kill");
+		vi.mocked(spawn).mockImplementationOnce(() => stub as unknown as ReturnType<typeof spawn>);
+		const promise = spawnPiInstall("@x/y", 30_000);
+		await vi.advanceTimersByTimeAsync(30_000);
+		vi.useRealTimers();
+		const r = await promise;
+		expect(killSpy).toHaveBeenCalledWith("SIGTERM");
+		expect(r.code).toBe(124);
+		expect(r.stderr).toContain("timed out");
+	});
+});
+
+describe("spawnPiInstall — settle idempotence", () => {
+	it("only resolves once even if close fires after timeout", async () => {
+		vi.useFakeTimers();
+		const stub = makeSpawnStub({ neverSettles: true });
+		vi.mocked(spawn).mockImplementationOnce(() => stub as unknown as ReturnType<typeof spawn>);
+		const promise = spawnPiInstall("@x/y", 30_000);
+		await vi.advanceTimersByTimeAsync(30_000);
+		stub.emit("close", 0); // late close — must not replace the timeout result
+		vi.useRealTimers();
+		const r = await promise;
+		expect(r.code).toBe(124);
+	});
+});
+
+describe("spawnPiInstall — Windows branch", () => {
+	it("invokes via cmd.exe /c pi install on win32", async () => {
+		const origPlatform = process.platform;
+		Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+		try {
+			vi.mocked(spawn).mockImplementationOnce(
+				() => makeSpawnStub({ exitCode: 0 }) as unknown as ReturnType<typeof spawn>,
+			);
+			await spawnPiInstall("@x/y", 30_000);
+			const firstCall = vi.mocked(spawn).mock.calls[0];
+			expect(firstCall[0]).toBe("cmd.exe");
+			expect(firstCall[1]).toEqual(["/c", "pi", "install", "@x/y"]);
+		} finally {
+			Object.defineProperty(process, "platform", { value: origPlatform, configurable: true });
+		}
+	});
+});