@milanglacier/pi-plan-mode 0.5.1

package/index.ts

@@ -0,0 +1,240 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { registerPlanModeCommand } from "./flow";
+import { resolveActivePlanFilePath } from "./plan-files";
+import { loadPlanModePrompt } from "./prompts";
+import { registerRequestUserInputTool } from "./request-user-input";
+import { RequestUserInputSchema, SetPlanSchema } from "./schemas";
+import { CONTEXT_ENTRY_TYPE, createPlanModeStateManager } from "./state";
+
+function summarizeSnippet(text: string, maxLength: number = 120): string {
+	const singleLine = text.replaceAll(/\s+/g, " ").trim();
+	if (!singleLine) {
+		return "";
+	}
+	if (singleLine.length <= maxLength) {
+		return singleLine;
+	}
+	return `${singleLine.slice(0, maxLength - 3)}...`;
+}
+
+interface SetPlanDetails {
+	plan: string;
+}
+
+interface PlanModeExitDetails {
+	planFilePath: string;
+	planText?: string;
+}
+
+const PLAN_MODE_EXIT_ENTRY_TYPE = "pi-plan:exit";
+const STARTUP_REFRESH_DELAY_MS = 250;
+
+export default function (pi: ExtensionAPI) {
+	const stateManager = createPlanModeStateManager(pi);
+
+	pi.registerMessageRenderer(PLAN_MODE_EXIT_ENTRY_TYPE, (message, { expanded }, theme) => {
+		const render = (text: string) => new Text(text, 1, 0, (segment) => theme.bg("customMessageBg", segment));
+		const details = message.details as PlanModeExitDetails | undefined;
+		const title = String(message.content || "Plan mode ended.");
+		const lines = [theme.fg("accent", theme.bold(title))];
+
+		if (!details?.planFilePath) {
+			return render(lines.join("\n"));
+		}
+
+		if (!details.planText?.trim()) {
+			lines.push(theme.fg("warning", "No plan created."));
+			return render(lines.join("\n"));
+		}
+
+		lines.push(theme.fg("muted", `Plan file: ${details.planFilePath}`));
+		if (!expanded) {
+			lines.push(theme.fg("dim", keyHint("expandTools", "to expand")));
+			return render(lines.join("\n"));
+		}
+
+		lines.push("");
+		lines.push(details.planText);
+		return render(lines.join("\n"));
+	});
+
+	pi.registerTool({
+		description:
+			"Overwrite the plan file with the full latest plan text. Call this whenever the plan changes so the plan file stays canonical.",
+		async execute(
+			_toolCallId,
+			params: { plan: string },
+			_signal,
+			_onUpdate,
+			ctx,
+		): Promise<AgentToolResult<SetPlanDetails>> {
+			if (!stateManager.getState().active) {
+				return {
+					isError: true,
+					content: [
+						{
+							type: "text",
+							text: "set_plan is only available while plan mode is active.",
+						},
+					],
+				};
+			}
+
+			const planFilePath = resolveActivePlanFilePath(ctx, stateManager.getState().planFilePath);
+			if (!planFilePath) {
+				return {
+					isError: true,
+					content: [
+						{
+							type: "text",
+							text: "No active plan file. Restart plan mode and try again.",
+						},
+					],
+				};
+			}
+
+			const plan = String(params.plan ?? "").trim();
+			if (!plan) {
+				return {
+					isError: true,
+					content: [
+						{
+							type: "text",
+							text: "set_plan requires non-empty plan text.",
+						},
+					],
+				};
+			}
+
+			await mkdir(path.dirname(planFilePath), { recursive: true });
+			await writeFile(planFilePath, `${plan}\n`, "utf8");
+
+			if (stateManager.getState().planFilePath !== planFilePath) {
+				stateManager.setState(ctx, {
+					...stateManager.getState(),
+					planFilePath,
+				});
+			}
+			return {
+				content: [{ type: "text", text: "Plan written." }],
+				details: {
+					plan,
+				},
+			};
+		},
+		label: "set_plan",
+		name: "set_plan",
+		parameters: SetPlanSchema,
+		renderCall(args, theme) {
+			const preview = summarizeSnippet(String(args.plan ?? ""), 90);
+			return new Text(
+				`${theme.fg("toolTitle", theme.bold("set_plan "))}${theme.fg("muted", preview || "(empty)")}`,
+				0,
+				0,
+			);
+		},
+		renderResult(result, { expanded, isPartial }, theme) {
+			if (isPartial) {
+				return new Text(theme.fg("muted", "Writing plan..."), 0, 0);
+			}
+
+			const details = result.details as SetPlanDetails | undefined;
+			if (!details?.plan) {
+				const text = result.content.find((item) => item.type === "text");
+				return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+			}
+
+			if (!expanded) {
+				return new Text(
+					`${theme.fg("success", "Plan written.")}\n${theme.fg("dim", keyHint("expandTools", "to view plan"))}`,
+					0,
+					0,
+				);
+			}
+
+			return new Text(`${theme.fg("success", "Plan written.")}\n${details.plan}`, 0, 0);
+		},
+	});
+
+	registerRequestUserInputTool(pi, {
+		getState: stateManager.getState,
+		requestUserInputSchema: RequestUserInputSchema,
+	});
+
+
+	registerPlanModeCommand(pi, {
+		onPlanModeExited: ({ planFilePath, planText }) => {
+			pi.sendMessage({
+				customType: PLAN_MODE_EXIT_ENTRY_TYPE,
+				content: "Plan mode ended.",
+				display: true,
+				details: {
+					planFilePath,
+					planText,
+				},
+			});
+		},
+		stateManager,
+	});
+
+	pi.on("before_agent_start", async () => {
+		stateManager.syncTools();
+		if (!stateManager.getState().active) {
+			return;
+		}
+
+		const prompt = await loadPlanModePrompt();
+		return {
+			message: {
+				content: prompt,
+				customType: CONTEXT_ENTRY_TYPE,
+				display: false,
+			},
+		};
+	});
+
+	let startupRefreshTimer: ReturnType<typeof setTimeout> | undefined;
+	const cancelStartupRefresh = () => {
+		if (!startupRefreshTimer) {
+			return;
+		}
+		clearTimeout(startupRefreshTimer);
+		startupRefreshTimer = undefined;
+	};
+	const refreshState = (ctx: ExtensionContext) => {
+		cancelStartupRefresh();
+		stateManager.refresh(ctx);
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		cancelStartupRefresh();
+		startupRefreshTimer = setTimeout(() => {
+			startupRefreshTimer = undefined;
+			stateManager.refresh(ctx);
+		}, STARTUP_REFRESH_DELAY_MS);
+		startupRefreshTimer.unref?.();
+	});
+
+	pi.on("session_switch", async (_event, ctx) => {
+		refreshState(ctx);
+	});
+
+	pi.on("session_tree", async (_event, ctx) => {
+		refreshState(ctx);
+	});
+
+	pi.on("session_fork", async (_event, ctx) => {
+		refreshState(ctx);
+	});
+
+	pi.on("session_shutdown", async () => {
+		cancelStartupRefresh();
+	});
+}

package/install.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+
+const PACKAGE_NAME = "@milanglacier/pi-plan-mode";
+
+function parseArgs(argv) {
+	const args = argv.slice(2);
+	let local = false;
+	let remove = false;
+	let help = false;
+
+	for (const arg of args) {
+		if (arg === "--local" || arg === "-l") {
+			local = true;
+		} else if (arg === "--remove" || arg === "-r") {
+			remove = true;
+		} else if (arg === "--help" || arg === "-h") {
+			help = true;
+		} else {
+			console.error(`Unknown argument: ${arg}`);
+			process.exit(1);
+		}
+	}
+
+	return { help, local, remove };
+}
+
+function printHelp() {
+	console.log(
+		`
+pi-plan — install the pi-plan-mode extension into pi
+
+Usage:
+  npx @milanglacier/pi-plan-mode            Install globally
+  npx @milanglacier/pi-plan-mode --local    Install into project .pi/settings.json
+  npx @milanglacier/pi-plan-mode --remove   Remove from pi
+
+Options:
+  -l, --local    Install project-locally instead of globally
+  -r, --remove   Remove the package from pi
+  -h, --help     Show this help
+
+Direct install:
+  pi install npm:${PACKAGE_NAME}
+`.trim(),
+	);
+}
+
+function findPi() {
+	try {
+		execFileSync("pi", ["--version"], { stdio: "ignore" });
+		return "pi";
+	} catch {
+		console.error("Error: 'pi' command not found. Install pi-coding-agent first:");
+		console.error("  npm install -g @earendil-works/pi-coding-agent");
+		process.exit(1);
+	}
+}
+
+function run(pi, command, args) {
+	try {
+		execFileSync(pi, [command, ...args], { stdio: "pipe", timeout: 60_000 });
+		return { ok: true, status: "ok" };
+	} catch (error) {
+		const stderr = error?.stderr?.toString?.().trim?.() ?? "";
+		if (stderr.includes("already installed") || stderr.includes("already exists")) {
+			return { ok: true, status: "already-installed" };
+		}
+		if (stderr.includes("not installed") || stderr.includes("not found") || stderr.includes("No such")) {
+			return { ok: true, status: "already-removed" };
+		}
+		if (stderr) {
+			console.error(stderr.split("\n")[0]);
+		}
+		return { ok: false, status: "error" };
+	}
+}
+
+const opts = parseArgs(process.argv);
+if (opts.help) {
+	printHelp();
+	process.exit(0);
+}
+
+const pi = findPi();
+const source = `npm:${PACKAGE_NAME}`;
+const localFlag = opts.local ? ["-l"] : [];
+const result = opts.remove ? run(pi, "remove", [source, ...localFlag]) : run(pi, "install", [source, ...localFlag]);
+
+if (!result.ok) {
+	process.exit(1);
+}
+
+if (opts.remove) {
+	console.log(
+		result.status === "already-removed"
+			? "\n✅ @milanglacier/pi-plan-mode is already absent from pi."
+			: "\n✅ Removed @milanglacier/pi-plan-mode from pi.",
+	);
+} else {
+	console.log(
+		result.status === "already-installed"
+			? "\n✅ @milanglacier/pi-plan-mode is already installed in pi."
+			: "\n✅ Installed @milanglacier/pi-plan-mode into pi. Restart pi to load it.",
+	);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@milanglacier/pi-plan-mode",
+	"version": "0.5.1",
+	"description": "Planning mode extension for pi with persistent plan files and branch-aware planning.",
+	"keywords": [
+		"branch-planning",
+		"pi",
+		"pi-coding-agent",
+		"pi-package",
+		"plan-mode",
+		"planning",
+		"research"
+	],
+	"homepage": "https://github.com/milanglacier/pi-plan-mode",
+	"bugs": {
+		"url": "https://github.com/milanglacier/pi-plan-mode/issues"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/milanglacier/pi-plan-mode.git"
+	},
+	"bin": {
+		"pi-plan": "install.mjs"
+	},
+	"files": [
+		"*.ts",
+		"*.mjs",
+		"qna",
+		"prompts",
+		"README.md",
+		"!**/*.test.ts",
+		"!tests/**"
+	],
+	"type": "module",
+	"scripts": {
+		"test": "vitest run"
+	},
+	"devDependencies": {
+		"vitest": "^4.1.8"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-agent-core": ">=0.56.1",
+		"@earendil-works/pi-ai": ">=0.56.1",
+		"@earendil-works/pi-coding-agent": ">=0.56.1",
+		"@earendil-works/pi-tui": ">=0.56.1",
+		"typebox": "*"
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	}
+}

package/plan-files.ts

@@ -0,0 +1,154 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { resolvePlanFilePath } from "./utils";
+
+export function getPlanFilePathForSession(ctx: ExtensionContext): string {
+	const sessionFile = ctx.sessionManager.getSessionFile();
+	if (!sessionFile) {
+		return path.join(ctx.sessionManager.getSessionDir(), `${ctx.sessionManager.getSessionId()}.plan.md`);
+	}
+
+	const parsed = path.parse(sessionFile);
+	return path.join(parsed.dir, `${parsed.name}.plan.md`);
+}
+
+export function resolveActivePlanFilePath(ctx: ExtensionContext, planFilePath: string | undefined): string {
+	if (planFilePath && planFilePath.trim().length > 0) {
+		return planFilePath;
+	}
+	return getPlanFilePathForSession(ctx);
+}
+
+export function buildTimestampedPlanFilename(sessionId: string): string {
+	const timestamp = new Date().toISOString().replaceAll(/[.:]/g, "-");
+	const safeSessionId = sessionId.replaceAll(/[^a-zA-Z0-9._-]/g, "-");
+	return `${timestamp}-${safeSessionId}.plan.md`;
+}
+
+export async function createFreshPlanFilePath(ctx: ExtensionContext, baseDir: string): Promise<string> {
+	const baseFilename = buildTimestampedPlanFilename(ctx.sessionManager.getSessionId());
+	let candidate = path.join(baseDir, baseFilename);
+	if (!(await pathExists(candidate))) {
+		return candidate;
+	}
+
+	const parsed = path.parse(baseFilename);
+	for (let counter = 1; counter <= 999; counter++) {
+		candidate = path.join(baseDir, `${parsed.name}-${counter}${parsed.ext}`);
+		if (!(await pathExists(candidate))) {
+			return candidate;
+		}
+	}
+
+	return path.join(baseDir, `${parsed.name}-${Date.now()}${parsed.ext}`);
+}
+
+export async function resolvePlanLocationInput(ctx: ExtensionContext, rawLocation: string): Promise<string | null> {
+	const trimmed = rawLocation.trim();
+	if (!trimmed) {
+		return null;
+	}
+
+	const resolvedPath = resolvePlanFilePath(ctx.cwd, trimmed);
+	if (!resolvedPath) {
+		return null;
+	}
+
+	let isDirectory = /[\\/]$/.test(trimmed);
+	try {
+		const pathStats = await stat(resolvedPath);
+		if (pathStats.isDirectory()) {
+			isDirectory = true;
+		}
+	} catch (error) {
+		const { code } = error as { code?: string };
+		if (code !== "ENOENT") {
+			throw error;
+		}
+	}
+
+	if (isDirectory) {
+		return path.join(resolvedPath, buildTimestampedPlanFilename(ctx.sessionManager.getSessionId()));
+	}
+
+	return resolvedPath;
+}
+
+export async function movePlanFile(sourcePath: string | undefined, targetPath: string): Promise<void> {
+	await mkdir(path.dirname(targetPath), { recursive: true });
+
+	if (!sourcePath) {
+		await ensurePlanFileExists(targetPath);
+		return;
+	}
+
+	if (sourcePath === targetPath) {
+		await ensurePlanFileExists(targetPath);
+		return;
+	}
+
+	try {
+		await rename(sourcePath, targetPath);
+		return;
+	} catch (error) {
+		const { code } = error as { code?: string };
+		if (code === "ENOENT") {
+			await ensurePlanFileExists(targetPath);
+			return;
+		}
+		if (code === "EXDEV") {
+			const existingContent = await readFile(sourcePath, "utf8");
+			await writeFile(targetPath, existingContent, "utf8");
+			try {
+				await unlink(sourcePath);
+			} catch (unlinkError) {
+				const unlinkCode = (unlinkError as { code?: string }).code;
+				if (unlinkCode !== "ENOENT") {
+					throw unlinkError;
+				}
+			}
+			return;
+		}
+		throw error;
+	}
+}
+
+export async function ensurePlanFileExists(planFilePath: string): Promise<void> {
+	await mkdir(path.dirname(planFilePath), { recursive: true });
+	await writeFile(planFilePath, "", { encoding: "utf8", flag: "a" });
+}
+
+export async function resetPlanFile(planFilePath: string): Promise<void> {
+	await mkdir(path.dirname(planFilePath), { recursive: true });
+	await writeFile(planFilePath, "", "utf8");
+}
+
+export async function readPlanFile(planFilePath: string | undefined): Promise<string | undefined> {
+	if (!planFilePath) {
+		return undefined;
+	}
+	try {
+		return await readFile(planFilePath, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+export async function pathExists(filePath: string | undefined): Promise<boolean> {
+	if (!filePath) {
+		return false;
+	}
+	try {
+		await stat(filePath);
+		return true;
+	} catch (error) {
+		const { code } = error as { code?: string };
+		if (code === "ENOENT") {
+			return false;
+		}
+		throw error;
+	}
+}

package/prompts/PLAN.prompt.md

@@ -0,0 +1,13 @@
+[PLAN MODE ACTIVE] Create a concrete implementation plan only.
+
+Guidance:
+
+- Focus on planning and analysis; do not write implementation code in this mode.
+- Start with direct local inspection for obvious, self-contained questions.
+- Use direct local inspection for codebase exploration and validation.
+- Use web_search/fetch_url when external references are needed.
+- Ask clarifying questions when requirements or constraints are unclear, preferably via request_user_input for short multiple-choice questions.
+- Avoid pedantic questions about obvious defaults; make reasonable assumptions and continue.
+- Keep a single up-to-date plan in the plan file by calling set_plan whenever the plan changes.
+- Include the goal at the top of the plan.
+- Before exiting plan mode, ensure set_plan has the full latest plan text.

package/prompts.ts

@@ -0,0 +1,45 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PLAN_MODE_PROMPT_FILENAME = "PLAN.prompt.md";
+
+function getBundledPromptPath(): string {
+	return path.join(import.meta.dirname, "prompts", PLAN_MODE_PROMPT_FILENAME);
+}
+
+async function readNonEmptyFile(filePath: string): Promise<string | null> {
+	try {
+		const content = await readFile(filePath, "utf8");
+		const trimmed = content.trim();
+		return trimmed.length > 0 ? trimmed : null;
+	} catch (error) {
+		const { code } = error as NodeJS.ErrnoException;
+		if (code === "ENOENT") {
+			return null;
+		}
+		throw error;
+	}
+}
+
+export async function loadPlanModePrompt(options?: {
+	agentDirPath?: string;
+	bundledPromptPath?: string;
+}): Promise<string> {
+	const agentDirPath = options?.agentDirPath ?? getAgentDir();
+	const bundledPromptPath = options?.bundledPromptPath ?? getBundledPromptPath();
+	const overridePromptPath = path.join(agentDirPath, PLAN_MODE_PROMPT_FILENAME);
+
+	const overridePrompt = await readNonEmptyFile(overridePromptPath);
+	if (overridePrompt) {
+		return overridePrompt;
+	}
+
+	const bundledPrompt = await readNonEmptyFile(bundledPromptPath);
+	if (bundledPrompt) {
+		return bundledPrompt;
+	}
+
+	throw new Error(`Plan mode prompt is missing or empty: ${bundledPromptPath}`);
+}

package/qna/index.ts

@@ -0,0 +1,3 @@
+export * from "./pi-tui-loader.js";
+export * from "./qna-tui.js";
+export * from "./scroll-select.js";