pi-plans 0.1.0

package/tests/state.test.ts

@@ -0,0 +1,240 @@
+/** State test suite (node:test, stdlib only). */
+
+import * as assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { after, before, describe, it } from "node:test";
+import {
+	initState,
+	getRun,
+	readActive,
+	recordDecision,
+	setLanguage,
+	setArtifactRoot,
+	setRole,
+	setRunStatus,
+	showConfig,
+	startRun,
+	StateError,
+	testHooks,
+	utcNow,
+} from "../src/state.ts";
+
+let tmpRoot: string;
+
+function mkWorkdir(name: string): string {
+	const dir = path.join(tmpRoot, name);
+	fs.mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+function git(workdir: string, ...args: string[]): void {
+	const result = spawnSync("git", args, { cwd: workdir, encoding: "utf8" });
+	assert.equal(result.status, 0, result.stderr ?? "");
+}
+
+function commonDir(workdir: string): string {
+	const result = spawnSync("git", ["rev-parse", "--git-common-dir"], { cwd: workdir, encoding: "utf8" });
+	assert.equal(result.status, 0, result.stderr ?? "");
+	const raw = result.stdout.trim();
+	return path.resolve(workdir, raw);
+}
+
+function readConfig(workdir: string): Record<string, any> {
+	return JSON.parse(fs.readFileSync(path.join(commonDir(workdir), "pi_plans", "config.json"), "utf8"));
+}
+
+before(() => {
+	tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-test-"));
+});
+
+after(() => {
+	fs.rmSync(tmpRoot, { recursive: true, force: true });
+	testHooks.now = () => new Date();
+});
+
+describe("init", () => {
+	it("auto-inits and resolves state under the git common dir", () => {
+		const workdir = mkWorkdir("fresh");
+		const result = initState(workdir);
+		assert.ok(result.notices.some((notice) => notice.includes("git init")));
+		const state = path.join(workdir, ".git", "pi_plans");
+		assert.equal(path.join(commonDir(workdir), "pi_plans"), state);
+		const config = JSON.parse(fs.readFileSync(path.join(state, "config.json"), "utf8"));
+		assert.equal(config.schema, 1);
+		assert.equal(config.language.tag, null);
+		assert.equal(config.reviewer.mode, "delegated-subagent");
+		assert.equal(config.reviewer.confirmed_at, null);
+		assert.equal(config.criticizer.confirmed_at, null);
+		assert.equal(config.artifact_root, "./docs/pi-plans");
+		assert.equal(config.artifact_root_source, "unset");
+		assert.equal(config.artifact_root_updated_at, null);
+	});
+
+	it("migrates legacy artifact roots to ./docs/pi-plans", () => {
+		const workdir = mkWorkdir("artifact-root-migration");
+		initState(workdir);
+		const configPath = path.join(commonDir(workdir), "pi_plans", "config.json");
+		const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+		config.artifact_root = "docs/plans";
+		delete config.artifact_root_source;
+		delete config.artifact_root_updated_at;
+		fs.writeFileSync(configPath, `${JSON.stringify(config, null, "\t")}\n`, "utf8");
+		const updated = initState(workdir);
+		assert.equal(updated.config.artifact_root, "./docs/pi-plans");
+		assert.equal(updated.config.artifact_root_source, "unset");
+		assert.equal(readConfig(workdir).artifact_root, "./docs/pi-plans");
+		assert.equal(readConfig(workdir).artifact_root_source, "unset");
+	});
+
+	it("roundtrips language, artifact root, and start-run", () => {
+		const workdir = mkWorkdir("roundtrip");
+		setLanguage(workdir, "zh-Hans", "user");
+		setArtifactRoot(workdir, "./docs/pi-plans", "user");
+		assert.equal(readConfig(workdir).language.tag, "zh-Hans");
+		assert.equal(readConfig(workdir).artifact_root, "./docs/pi-plans");
+		assert.equal(readConfig(workdir).artifact_root_source, "user");
+		const { run } = startRun(workdir, {
+			topic: "Example Plan",
+			skill: "plan-small",
+			requestText: "Plan the example",
+		});
+		assert.ok(fs.statSync(run.artifact_dir).isDirectory());
+		const active = readActive(workdir);
+		assert.equal(active?.run_id, run.run_id);
+		assert.ok(fs.existsSync(path.join(active!.run_dir, "run.json")));
+		const loaded = getRun(workdir, run.run_id);
+		assert.equal(loaded?.status, "planning");
+		recordDecision(workdir, run.run_id, {
+			question: "Q?",
+			options: ["a", "b"],
+			answer: "a",
+			answer_source: "user",
+		});
+		const decisions = fs.readFileSync(path.join(active!.run_dir, "decisions.jsonl"), "utf8").trim().split("\n");
+		assert.equal(decisions.length, 1);
+		assert.equal(JSON.parse(decisions[0]!).answer, "a");
+	});
+
+	it("subdir uses the enclosing repo", () => {
+		const repo = mkWorkdir("enclosing");
+		git(repo, "init", "-q");
+		const sub = path.join(repo, "pkg", "sub");
+		fs.mkdirSync(sub, { recursive: true });
+		const result = initState(sub);
+		assert.ok(result.notices.some((notice) => notice.includes("enclosing repository")));
+		assert.ok(fs.existsSync(path.join(commonDir(repo), "pi_plans", "config.json")));
+		assert.ok(!fs.existsSync(path.join(sub, ".git")));
+	});
+
+	it("supports private planning docs under .git/pi_plans/plans", () => {
+		const workdir = mkWorkdir("private-artifact-root");
+		setArtifactRoot(workdir, "./.git/pi_plans/plans", "user");
+		const { run } = startRun(workdir, {
+			topic: "Private Docs",
+			skill: "plan-small",
+			requestText: "Plan the example",
+		});
+		assert.ok(fs.statSync(run.artifact_dir).isDirectory());
+		assert.equal(readConfig(workdir).artifact_root, "./.git/pi_plans/plans");
+		assert.equal(run.artifact_dir, path.join(workdir, ".git", "pi_plans", "plans", `${run.created_at.slice(0, 10)}-private-docs`));
+	});
+
+	it("scrubs leaked GIT_DIR env", () => {
+		const repoA = mkWorkdir("repo-a");
+		git(repoA, "init", "-q");
+		const workdir = mkWorkdir("repo-b");
+		const stateUrl = new URL("../src/state.ts", import.meta.url).href;
+		const driver = path.join(tmpRoot, "env-driver.mjs");
+		fs.writeFileSync(
+			driver,
+			`import { initState } from ${JSON.stringify(stateUrl)};\ninitState(process.argv[2]);\n`,
+		);
+		const result = spawnSync(process.execPath, ["--experimental-strip-types", driver, workdir], {
+			env: { ...process.env, GIT_DIR: path.join(repoA, ".git") },
+			encoding: "utf8",
+		});
+		assert.equal(result.status, 0, result.stderr ?? "");
+		assert.ok(fs.existsSync(path.join(workdir, ".git", "pi_plans", "config.json")));
+		assert.ok(!fs.existsSync(path.join(repoA, ".git", "pi_plans")));
+	});
+
+	it("refuses broken .git entries and bare repos", () => {
+		const broken = mkWorkdir("broken");
+		fs.writeFileSync(path.join(broken, ".git"), "gitdir: /nonexistent/xyz\n");
+		assert.throws(() => initState(broken), StateError);
+		assert.ok(fs.statSync(path.join(broken, ".git")).isFile());
+
+		const bare = mkWorkdir("bare");
+		git(bare, "init", "-q", "--bare");
+		assert.throws(() => initState(bare), StateError);
+	});
+});
+
+describe("runs", () => {
+	it("dedups run ids within the same second", () => {
+		const workdir = mkWorkdir("dedup");
+		git(workdir, "init", "-q");
+		testHooks.now = () => new Date("2026-08-25T13:00:00Z");
+		assert.equal(utcNow(), "2026-08-25T13:00:00Z");
+		const first = startRun(workdir, { topic: "Same Topic", skill: "plan-normal", requestText: "x" });
+		const second = startRun(workdir, { topic: "Same Topic", skill: "plan-normal", requestText: "x" });
+		assert.equal(first.run.run_id, "20260825T130000Z-same-topic");
+		assert.equal(second.run.run_id, "20260825T130000Z-same-topic-2");
+	});
+
+	it("tracks run status transitions", () => {
+		const workdir = mkWorkdir("status");
+		git(workdir, "init", "-q");
+		const { run } = startRun(workdir, { topic: "status flow", skill: "plan-normal", requestText: "x" });
+		const updated = setRunStatus(workdir, run.run_id, "accepted");
+		assert.equal(updated.status, "accepted");
+		assert.equal(getRun(workdir, run.run_id)?.status, "accepted");
+		assert.throws(() => setRunStatus(workdir, run.run_id, "bogus"), StateError);
+	});
+});
+
+describe("set-role invariants", () => {
+	it("mode-only edits never forge or discard confirmations", () => {
+		const workdir = mkWorkdir("roles");
+		git(workdir, "init", "-q");
+		initState(workdir);
+
+		setRole(workdir, { role: "reviewer", mode: "current-session" });
+		let role = readConfig(workdir).reviewer;
+		assert.equal(role.mode, "current-session");
+		assert.equal(role.confirmed_at, null);
+
+		setRole(workdir, {
+			role: "reviewer",
+			mode: "delegated-subagent",
+			modelSelector: "deepseek/deepseek-v4-flash",
+			confirmed: true,
+		});
+		role = readConfig(workdir).reviewer;
+		assert.equal(role.model_selector, "deepseek/deepseek-v4-flash");
+		const stamped = role.confirmed_at;
+		assert.ok(stamped);
+
+		setRole(workdir, { role: "reviewer", mode: "current-session" });
+		role = readConfig(workdir).reviewer;
+		assert.equal(role.mode, "current-session");
+		assert.equal(role.model_selector, "deepseek/deepseek-v4-flash");
+		assert.equal(role.confirmed_at, stamped);
+
+		setRole(workdir, { role: "reviewer", resetConfirmation: true });
+		role = readConfig(workdir).reviewer;
+		assert.equal(role.confirmed_at, null);
+		assert.equal(role.model_selector, "deepseek/deepseek-v4-flash");
+
+		// Confirmed-inherit is distinguishable from never-confirmed.
+		setRole(workdir, { role: "criticizer", confirmed: true });
+		role = readConfig(workdir).criticizer;
+		assert.equal(role.model_selector, null);
+		assert.ok(role.confirmed_at);
+
+		assert.throws(() => setRole(workdir, { role: "reviewer", confirmed: true, resetConfirmation: true }), StateError);
+	});
+});

package/tools/ask-choice.ts

@@ -0,0 +1,199 @@
+/**
+ * `ask_choice` tool — the choice-prompt contract as a Pi tool.
+ *
+ * Every user-facing planning/refinement question goes through this tool:
+ * recommended option first, real alternatives next, `Other` second-last,
+ * `Auto-complete` last. Auto-complete may answer planning and refinement
+ * questions only; it is forbidden for execution handoff and any
+ * external-state change (pass autoComplete: false there).
+ *
+ * Answers are recorded automatically in the active run's decisions.jsonl.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { normalizeWorkdir, readActive, recordDecision } from "../src/state.ts";
+
+const Option = Type.Object({
+	label: Type.String({ description: "Option label" }),
+	description: Type.Optional(Type.String({ description: "Short tradeoff that matters, shown to the user" })),
+	recommended: Type.Optional(Type.Boolean({ description: "Mark exactly one recommended option; put it first" })),
+});
+
+const AskChoiceParams = Type.Object({
+	question: Type.String({ description: "The question to ask, in the configured language" }),
+	options: Type.Array(Option, { description: "Ordered options: recommended first, alternatives next. Do not include Other or Auto-complete yourself." }),
+	allowOther: Type.Optional(Type.Boolean({ description: "Offer free-form input (default true)" })),
+	autoComplete: Type.Optional(
+		Type.Boolean({
+			description:
+				"Offer the Auto-complete option (default true). MUST be false for the execution handoff, install waivers, publishing, deployment, merge, push, credential use, or any external-state change.",
+		}),
+	),
+	workdir: Type.Optional(Type.String({ description: "Target workspace; default current working directory" })),
+});
+
+interface AskChoiceDetails {
+	question: string;
+	options: string[];
+	answer: string | null;
+	source: "user" | "auto-complete" | "other" | "cancelled";
+}
+
+export function registerAskChoiceTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "ask_choice",
+		label: "Ask Choice",
+		description:
+			"Ask the user one planning or refinement question as a numbered choice prompt: recommended option first, alternatives next, then Other and Auto-complete. One question per call. Use for every user-facing planning question, the final scope confirmation, refinement-mode questions, language/role/model settings, and the execution handoff (with autoComplete: false).",
+		promptSnippet: "Ask structured planning questions with recommended/Other/Auto-complete ordering",
+		promptGuidelines: [
+			"Use ask_choice for every pi-plans question to the user instead of plain-text questions; it enforces option ordering and records decisions.",
+		],
+		parameters: AskChoiceParams,
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const workdir = normalizeWorkdir(params.workdir ?? ctx.cwd);
+			const allowOther = params.allowOther ?? true;
+			const autoComplete = params.autoComplete ?? true;
+			const options = params.options;
+			if (options.length === 0) throw new Error("ask_choice requires at least one option");
+			const recommended = options.find((option) => option.recommended) ?? options[0];
+
+			const record = (answer: string, source: AskChoiceDetails["source"]) => {
+				const active = readActive(workdir);
+				if (!active) return;
+				try {
+					recordDecision(workdir, active.run_id, {
+						question: params.question,
+						options: options.map((option) => option.label),
+						answer,
+						answer_source: source === "auto-complete" ? "auto-complete" : "user",
+					});
+				} catch {
+					/* recording is best-effort; the question still gets answered */
+				}
+			};
+
+			const details = (answer: string | null, source: AskChoiceDetails["source"]): AskChoiceDetails => ({
+				question: params.question,
+				options: options.map((option) => option.label),
+				answer,
+				source,
+			});
+
+			// No UI (print/json mode): planning questions may auto-complete;
+			// questions without Auto-complete must stop and wait for the user.
+			if (!ctx.hasUI) {
+				if (!autoComplete) {
+					throw new Error(
+						"No UI available and this question must not be auto-completed (execution handoff or external-state change). Stop and wait for the user.",
+					);
+				}
+				record(recommended.label, "auto-complete");
+				return {
+					content: [
+						{
+							type: "text",
+							text: `No UI available. Auto-complete selected the recommended option: ${recommended.label}`,
+						},
+					],
+					details: details(recommended.label, "auto-complete"),
+				};
+			}
+
+			const displayLabels: string[] = options.map((option, index) => {
+				let label = `${index + 1}. ${option.label}`;
+				if (option === recommended) label += "  (recommended)";
+				if (option.description) label += ` — ${option.description}`;
+				return label;
+			});
+			if (allowOther) displayLabels.push("Other…  (type your own answer)");
+			if (autoComplete) displayLabels.push("Auto-complete  (take the recommended option)");
+
+			const selected = await ctx.ui.select(params.question, displayLabels);
+			if (selected === undefined) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "User cancelled the question. Do not treat this as approval for anything; ask again later or stop.",
+						},
+					],
+					details: details(null, "cancelled"),
+				};
+			}
+
+			if (autoComplete && selected.startsWith("Auto-complete")) {
+				record(recommended.label, "auto-complete");
+				return {
+					content: [
+						{
+							type: "text",
+							text: `User selected Auto-complete; take the recommended option: ${options.findIndex((o) => o === recommended) + 1}. ${recommended.label}`,
+						},
+					],
+					details: details(recommended.label, "auto-complete"),
+				};
+			}
+
+			if (allowOther && selected.startsWith("Other…")) {
+				const typed = await ctx.ui.input(`${params.question} — your answer:`);
+				if (typed === undefined || !typed.trim()) {
+					return {
+						content: [{ type: "text", text: "User cancelled the free-form answer. Ask again or stop." }],
+						details: details(null, "cancelled"),
+					};
+				}
+				const answer = typed.trim();
+				record(answer, "user");
+				return {
+					content: [{ type: "text", text: `User wrote: ${answer}` }],
+					details: details(answer, "other"),
+				};
+			}
+
+			const index = displayLabels.indexOf(selected);
+			const option = index >= 0 && index < options.length ? options[index] : undefined;
+			if (!option) {
+				return {
+					content: [{ type: "text", text: `User selected: ${selected}` }],
+					details: details(selected, "user"),
+				};
+			}
+			record(option.label, "user");
+			return {
+				content: [{ type: "text", text: `User selected: ${index + 1}. ${option.label}` }],
+				details: details(option.label, "user"),
+			};
+		},
+
+		renderCall(args, theme) {
+			let text = theme.fg("toolTitle", theme.bold("ask_choice ")) + theme.fg("muted", args.question);
+			const labels = (args.options ?? []).map((option: { label: string }, i: number) => `${i + 1}. ${option.label}`);
+			if (labels.length) text += `\n${theme.fg("dim", `  Options: ${labels.join(", ")}`)}`;
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, _options, theme) {
+			const details = result.details as AskChoiceDetails | undefined;
+			if (!details) {
+				const text = result.content[0];
+				return new Text(text?.type === "text" ? text.text : "", 0, 0);
+			}
+			if (details.answer === null || details.source === "cancelled") {
+				return new Text(theme.fg("warning", "✗ cancelled"), 0, 0);
+			}
+			const prefix =
+				details.source === "auto-complete"
+					? theme.fg("muted", "✓ (auto-complete) ")
+					: details.source === "other"
+						? theme.fg("muted", "✓ (wrote) ")
+						: theme.fg("success", "✓ ");
+			return new Text(prefix + theme.fg("accent", details.answer), 0, 0);
+		},
+	});
+}

package/tools/execute-plan.ts

@@ -0,0 +1,137 @@
+/**
+ * `execute_plan` tool — the execution handoff. On explicit user approval (no
+ * Auto-complete) the extension enters execution mode with checklist tracking.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { startExecution } from "../src/exec.ts";
+import { latestPlanVersion, parseChecklist } from "../src/plan.ts";
+import { normalizeWorkdir, readActive } from "../src/state.ts";
+
+const ExecutePlanParams = Type.Object({
+	planPath: Type.Optional(
+		Type.String({ description: "Path to the accepted PLAN_vN.md. Default: highest version in the active run's artifact directory." }),
+	),
+	workdir: Type.Optional(Type.String({ description: "Target workspace; default current working directory" })),
+});
+
+export interface HandoffOutcome {
+	status: "executing" | "declined" | "error";
+	planPath?: string;
+	itemCount?: number;
+	message: string;
+}
+
+/** Shared handoff logic for the execute_plan tool and /plans-execute command. */
+export async function executeHandoff(
+	ctx: ExtensionContext,
+	planPathArg?: string,
+	workdirArg?: string,
+): Promise<HandoffOutcome> {
+	const workdir = normalizeWorkdir(workdirArg ?? ctx.cwd);
+
+	let planPath: string | null = null;
+	if (planPathArg) {
+		planPath = path.resolve(workdir, planPathArg.replace(/^@/, ""));
+	} else {
+		const active = readActive(workdir);
+		if (!active) {
+			return {
+				status: "error",
+				message: "No plan path given and no active planning run found. Pass planPath or start a run first.",
+			};
+		}
+		const latest = latestPlanVersion(active.artifact_dir);
+		if (!latest) {
+			return { status: "error", message: `No PLAN_vN.md found in ${active.artifact_dir}` };
+		}
+		planPath = latest.path;
+	}
+	if (!fs.existsSync(planPath)) {
+		return { status: "error", message: `Plan file not found: ${planPath}` };
+	}
+
+	const items = parseChecklist(fs.readFileSync(planPath, "utf8"));
+	if (items.length === 0) {
+		return {
+			status: "error",
+			message: `${planPath} has no parsable \`## Verifier Checklist\` with \`- [ ] \`VC-###\` ...\` items. Fix the plan before execution.`,
+		};
+	}
+
+	if (!ctx.hasUI) {
+		return {
+			status: "error",
+			message:
+				"The execution handoff requires explicit user approval and must never be auto-completed. Run interactively.",
+		};
+	}
+
+	const preview = items.map((item) => `- ${item.done ? "☑" : "☐"} ${item.id}`).join("\n");
+	const approved = await ctx.ui.confirm(
+		"Execute this plan now?",
+		`${planPath}\n${items.length} verifier item(s):\n${preview}\n\nExecution mode enables write access and tracks [DONE:VC-xxx] progress.`,
+	);
+	if (!approved) {
+		return { status: "declined", message: "User declined execution. Stay in planning; ask how to proceed.", planPath };
+	}
+
+	startExecution(getCurrentApi(), ctx, planPath, items);
+	return {
+		status: "executing",
+		planPath,
+		itemCount: items.length,
+		message: `Execution approved. ${items.length} verifier item(s) queued; implement in dependency order and mark verified items with [DONE:VC-xxx].`,
+	};
+}
+
+// The tool registers with the ExtensionAPI in scope; keep a module-level
+// reference so the shared handoff helper can reach appendEntry/sendMessage.
+let currentApi: ExtensionAPI | null = null;
+export function setCurrentApi(api: ExtensionAPI): void {
+	currentApi = api;
+}
+function getCurrentApi(): ExtensionAPI {
+	if (!currentApi) throw new Error("execute_plan used before extension initialization");
+	return currentApi;
+}
+
+export function registerExecutePlanTool(pi: ExtensionAPI): void {
+	setCurrentApi(pi);
+	pi.registerTool({
+		name: "execute_plan",
+		label: "Execute Plan",
+		description:
+			"Execution handoff for an accepted plan. Asks the user for explicit approval (never auto-completed), then enters plan-execution mode: the extension injects the remaining Verifier Checklist every turn, tracks [DONE:VC-xxx] markers, and completes when every item passes. Only call after the user chose 'Execute this plan now' at the handoff question.",
+		promptSnippet: "Hand an accepted plan off to the tracked execution loop",
+		parameters: ExecutePlanParams,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const outcome = await executeHandoff(ctx, params.planPath, params.workdir);
+			if (outcome.status === "error") throw new Error(outcome.message);
+			return {
+				content: [{ type: "text", text: outcome.message }],
+				details: outcome,
+			};
+		},
+
+		renderCall(args, theme) {
+			const short = args.planPath ? args.planPath.split("/").pop() : "latest accepted plan";
+			return new Text(
+				theme.fg("toolTitle", theme.bold("execute_plan ")) + theme.fg("accent", short ?? ""),
+				0,
+				0,
+			);
+		},
+
+		renderResult(result, _options, theme) {
+			const text = result.content[0];
+			const raw = text?.type === "text" ? text.text : "";
+			return new Text(theme.fg("success", "🚀 ") + theme.fg("muted", raw.slice(0, 160)), 0, 0);
+		},
+	});
+}