@hank-warren/pi-plan-mode 0.1.0

package/src/plan-action-controller.ts

@@ -0,0 +1,103 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { PlanExportDestination } from "./plan-export.js";
+import type { PlanModeState } from "./state.js";
+
+type InteractiveUi = typeof import("./interactive-ui.js");
+
+interface MenuLifecycle {
+	signal: AbortSignal;
+	isCurrent(): boolean;
+}
+
+interface PlanActionControllerOptions {
+	loadInteractiveUi(): Promise<InteractiveUi>;
+	getState(): PlanModeState;
+	captureLifecycle(): MenuLifecycle;
+	statusText(): string;
+	implementationOutcome(): string;
+	getExportDestination(ctx: ExtensionContext): PlanExportDestination;
+	show(ctx: ExtensionContext): void;
+	finalize(ctx: ExtensionContext): void;
+	implementHere(ctx: ExtensionContext): void | Promise<void>;
+	implementFresh(ctx: ExtensionContext, isCurrent: () => boolean): void | Promise<void>;
+	exportPlan(
+		ctx: ExtensionContext,
+		path: string,
+		signal: AbortSignal,
+		isCurrent: () => boolean,
+	): Promise<boolean>;
+	settings(ctx: ExtensionContext, signal: AbortSignal, isCurrent: () => boolean): Promise<boolean>;
+	save(ctx: ExtensionContext): void;
+	stay(ctx: ExtensionContext): void;
+	exitReady(ctx: ExtensionContext): void;
+	clearSaved(ctx: ExtensionContext): void;
+}
+
+export function createPlanActionController(options: PlanActionControllerOptions) {
+	const freshAction = (ctx: ExtensionContext, lifecycle: MenuLifecycle, signal: AbortSignal) =>
+		options.implementFresh(ctx, () => lifecycle.isCurrent() && !signal.aborted);
+
+	return {
+		async showSaved(ctx: ExtensionContext) {
+			const lifecycle = options.captureLifecycle();
+			if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
+			const ui = await options.loadInteractiveUi();
+			if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
+			await ui.showSavedPlanMenu(ctx, {
+				statusText: options.statusText(),
+				implementationOutcome: options.implementationOutcome,
+				getExportDestination: () => options.getExportDestination(ctx),
+				signal: lifecycle.signal,
+				isCurrent: lifecycle.isCurrent,
+				show: () => options.show(ctx),
+				implementHere: () => options.implementHere(ctx),
+				implementFresh: (signal) => freshAction(ctx, lifecycle, signal),
+				exportPlan: (path, signal) => options.exportPlan(ctx, path, signal, lifecycle.isCurrent),
+				settings: (signal) => options.settings(ctx, signal, lifecycle.isCurrent),
+				clear: () => options.clearSaved(ctx),
+			});
+		},
+		async showCurrent(ctx: ExtensionContext) {
+			if (!ctx.hasUI) {
+				ctx.ui.notify(options.statusText(), "info");
+				return;
+			}
+			const lifecycle = options.captureLifecycle();
+			if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
+			const ui = await options.loadInteractiveUi();
+			if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
+			await ui.showPlanModeMenu(ctx, {
+				statusText: options.statusText(),
+				hasReadyPlan: options.getState().latestPlan !== undefined,
+				implementationOutcome: options.implementationOutcome,
+				getExportDestination: () => options.getExportDestination(ctx),
+				...lifecycle,
+				show: () => options.show(ctx),
+				finalize: () => options.finalize(ctx),
+				implementHere: () => options.implementHere(ctx),
+				implementFresh: (signal) => freshAction(ctx, lifecycle, signal),
+				exportPlan: (path, signal) => options.exportPlan(ctx, path, signal, lifecycle.isCurrent),
+				save: () => options.save(ctx),
+				stay: () => options.stay(ctx),
+				exit: () => options.exitReady(ctx),
+			});
+		},
+		async showReady(ctx: ExtensionContext) {
+			const lifecycle = options.captureLifecycle();
+			if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
+			const ui = await options.loadInteractiveUi();
+			if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
+			await ui.showReadyPlanMenu(ctx, {
+				...lifecycle,
+				implementationOutcome: options.implementationOutcome,
+				getExportDestination: () => options.getExportDestination(ctx),
+				implementHere: () => options.implementHere(ctx),
+				implementFresh: (signal) => freshAction(ctx, lifecycle, signal),
+				exportPlan: (path, signal) => options.exportPlan(ctx, path, signal, lifecycle.isCurrent),
+				save: () => options.save(ctx),
+				stay: () => undefined,
+				exit: () => options.exitReady(ctx),
+			});
+		},
+	};
+}

package/src/plan-action-menus.ts

@@ -0,0 +1,197 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import { type PlanExportDestinationProvider, planExportInputScreen } from "./plan-export-screen.js";
+
+interface MenuLifecycle {
+	signal: AbortSignal;
+	isCurrent(): boolean;
+}
+
+const IMPLEMENTATION_CONTEXT_LINES = [
+	"Implement here keeps this planning conversation.",
+	"Start fresh transfers only the approved plan to a new session.",
+] as const;
+
+interface PlanMenuOptions extends MenuLifecycle {
+	statusText: string;
+	hasReadyPlan: boolean;
+	implementationOutcome(): string;
+	getExportDestination: PlanExportDestinationProvider;
+	show(): void;
+	finalize(): void;
+	implementHere(): void | Promise<void>;
+	implementFresh(signal: AbortSignal): void | Promise<void>;
+	exportPlan(path: string, signal: AbortSignal): Promise<boolean>;
+	save(): void;
+	stay(): void;
+	exit(): void;
+}
+
+export async function showPlanModeMenu(ctx: ExtensionContext, options: PlanMenuOptions) {
+	type Screen = "main" | "export";
+	type Action =
+		| "show"
+		| "finalize"
+		| "implement-here"
+		| "implement-fresh"
+		| "export"
+		| "save"
+		| "stay"
+		| "exit";
+	const menu = defineMenu<undefined, Screen, Action, ExtensionContext>({
+		start: "main",
+		screens: {
+			main: () => ({
+				kind: "actions",
+				title: "Plan mode",
+				lines: [
+					options.statusText,
+					...(options.hasReadyPlan
+						? [...IMPLEMENTATION_CONTEXT_LINES, options.implementationOutcome()]
+						: []),
+				],
+				items: options.hasReadyPlan
+					? [
+							{ id: "show", label: "Show latest proposed plan", action: "show" },
+							{
+								id: "implement-here",
+								label: "Implement here",
+								description: "Continue in this session with the planning conversation.",
+								action: "implement-here",
+							},
+							{
+								id: "implement-fresh",
+								label: "Start fresh and implement",
+								description: "Open a new linked session; transfer only the approved plan.",
+								action: "implement-fresh",
+								busyLabel: "Starting fresh implementation session…",
+							},
+							{ id: "export", label: "Export plan…", to: "export" },
+							{ id: "save", label: "Save for later", action: "save" },
+							{ id: "stay", label: "Stay in Plan mode", action: "stay" },
+							{ id: "exit", label: "Discard plan and exit", action: "exit" },
+						]
+					: [
+							{ id: "finalize", label: "Request final plan", action: "finalize" },
+							{ id: "stay", label: "Stay in Plan mode", action: "stay" },
+							{ id: "exit", label: "Exit Plan mode", action: "exit" },
+						],
+				hint: "close",
+			}),
+			export: () => planExportInputScreen(options.getExportDestination),
+		},
+		actions: {
+			show: async () => {
+				options.show();
+				return { kind: "close" };
+			},
+			finalize: async () => {
+				options.finalize();
+				return { kind: "close" };
+			},
+			"implement-here": async () => {
+				await options.implementHere();
+				return { kind: "close" };
+			},
+			"implement-fresh": async ({ signal }) => {
+				await options.implementFresh(signal);
+				return { kind: "close" };
+			},
+			export: async ({ value, signal }) =>
+				(await options.exportPlan(value ?? "", signal)) ? { kind: "close" } : { kind: "rejected" },
+			save: async () => {
+				options.save();
+				return { kind: "close" };
+			},
+			stay: async () => {
+				options.stay();
+				return { kind: "close" };
+			},
+			exit: async () => {
+				options.exit();
+				return { kind: "close" };
+			},
+		},
+	});
+	await runMenu(ctx, menu, {
+		getState: () => undefined,
+		signal: options.signal,
+		isCurrent: options.isCurrent,
+	});
+}
+
+interface ReadyPlanMenuOptions extends MenuLifecycle {
+	implementationOutcome(): string;
+	getExportDestination: PlanExportDestinationProvider;
+	implementHere(): void | Promise<void>;
+	implementFresh(signal: AbortSignal): void | Promise<void>;
+	exportPlan(path: string, signal: AbortSignal): Promise<boolean>;
+	save(): void;
+	stay(): void;
+	exit(): void;
+}
+
+export async function showReadyPlanMenu(ctx: ExtensionContext, options: ReadyPlanMenuOptions) {
+	type Screen = "ready" | "export";
+	type Action = "implement-here" | "implement-fresh" | "export" | "save" | "stay" | "exit";
+	const menu = defineMenu<undefined, Screen, Action, ExtensionContext>({
+		start: "ready",
+		screens: {
+			ready: () => ({
+				kind: "actions",
+				title: "Proposed plan ready. What next?",
+				lines: [...IMPLEMENTATION_CONTEXT_LINES, options.implementationOutcome()],
+				items: [
+					{
+						id: "implement-here",
+						label: "Implement here",
+						description: "Continue in this session with the planning conversation.",
+						action: "implement-here",
+					},
+					{
+						id: "implement-fresh",
+						label: "Start fresh and implement",
+						description: "Open a new linked session; transfer only the approved plan.",
+						action: "implement-fresh",
+						busyLabel: "Starting fresh implementation session…",
+					},
+					{ id: "export", label: "Export plan…", to: "export" },
+					{ id: "save", label: "Save for later", action: "save" },
+					{ id: "stay", label: "Stay in Plan mode", action: "stay" },
+					{ id: "exit", label: "Discard plan and exit", action: "exit" },
+				],
+				hint: "close",
+			}),
+			export: () => planExportInputScreen(options.getExportDestination),
+		},
+		actions: {
+			"implement-here": async () => {
+				await options.implementHere();
+				return { kind: "close" };
+			},
+			"implement-fresh": async ({ signal }) => {
+				await options.implementFresh(signal);
+				return { kind: "close" };
+			},
+			export: async ({ value, signal }) =>
+				(await options.exportPlan(value ?? "", signal)) ? { kind: "close" } : { kind: "rejected" },
+			save: async () => {
+				options.save();
+				return { kind: "close" };
+			},
+			stay: async () => {
+				options.stay();
+				return { kind: "close" };
+			},
+			exit: async () => {
+				options.exit();
+				return { kind: "close" };
+			},
+		},
+	});
+	await runMenu(ctx, menu, {
+		getState: () => undefined,
+		signal: options.signal,
+		isCurrent: options.isCurrent,
+	});
+}

package/src/plan-export-controller.ts

@@ -0,0 +1,38 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { exportStoredPlan, planExportDestination } from "./plan-export.js";
+import { configuredPlanExportPath, type PlanModeSettings } from "./settings.js";
+import type { PlanModeState } from "./state.js";
+
+interface PlanExportControllerOptions {
+	getState(): PlanModeState;
+	getSettings(): PlanModeSettings;
+	finishReady(ctx: ExtensionContext): void;
+}
+
+export function createPlanExportController(options: PlanExportControllerOptions) {
+	return {
+		export(
+			path: string | undefined,
+			ctx: ExtensionContext,
+			signal: AbortSignal,
+			isCurrent: () => boolean,
+		) {
+			const state = options.getState();
+			return exportStoredPlan(
+				state,
+				path,
+				ctx,
+				{
+					signal,
+					isCurrent,
+					getState: options.getState,
+					finishReady: () => options.finishReady(ctx),
+				},
+				configuredPlanExportPath(options.getSettings()),
+			);
+		},
+		getDestination(ctx: ExtensionContext) {
+			return planExportDestination(configuredPlanExportPath(options.getSettings()), ctx.cwd);
+		},
+	};
+}

package/src/plan-export-screen.ts

@@ -0,0 +1,19 @@
+import type { PlanExportDestination } from "./plan-export.js";
+
+export type PlanExportDestinationProvider = () => PlanExportDestination;
+
+export function planExportInputScreen(getDestination: PlanExportDestinationProvider) {
+	const destination = getDestination();
+	return {
+		kind: "input" as const,
+		title: "Export plan",
+		lines: [
+			"Existing paths are never overwritten.",
+			`Default: ${destination.configuredPath}`,
+			`Resolves to: ${destination.resolvedPath}`,
+		],
+		placeholder: destination.configuredPath,
+		action: "export" as const,
+		hint: "back" as const,
+	};
+}

package/src/plan-export.ts

@@ -0,0 +1,145 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { type ExtensionContext, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_PLAN_EXPORT_PATH } from "./settings.js";
+import type { PlanModeState } from "./state.js";
+
+export { DEFAULT_PLAN_EXPORT_PATH };
+
+export interface PlanExportResult {
+	path: string;
+}
+
+export interface PlanExportDestination {
+	configuredPath: string;
+	resolvedPath: string;
+}
+
+export interface PlanExportLifecycle {
+	signal: AbortSignal;
+	isCurrent(): boolean;
+	getState?(): PlanModeState;
+	finishReady?(): void;
+}
+
+export async function exportStoredPlan(
+	state: PlanModeState,
+	requestedPath: string | undefined,
+	ctx: ExtensionContext,
+	lifecycle?: PlanExportLifecycle,
+	defaultPath = DEFAULT_PLAN_EXPORT_PATH,
+) {
+	const plan =
+		(state.enabled ? state.latestPlan : undefined)?.trim() ??
+		state.savedPlan?.plan.trim() ??
+		state.activeImplementation?.plan.trim();
+	if (!plan) {
+		const error = new Error(
+			"No completed plan is available to export. Use /plan finalize when planning is complete.",
+		);
+		if (!ctx.hasUI) throw error;
+		ctx.ui.notify(error.message, "warning");
+		return false;
+	}
+
+	const isCurrent = () =>
+		!lifecycle ||
+		(lifecycle.isCurrent() && (!lifecycle.getState || lifecycle.getState() === state));
+	let result: PlanExportResult;
+	try {
+		result = await exportPlanToFile(
+			plan,
+			requestedPath,
+			ctx.cwd,
+			lifecycle?.signal,
+			isCurrent,
+			defaultPath,
+		);
+	} catch (error: unknown) {
+		if (lifecycle?.signal.aborted || !isCurrent()) return false;
+		if (!ctx.hasUI) throw error;
+		const detail = error instanceof Error ? error.message : String(error);
+		ctx.ui.notify(safeNotification(`Unable to export plan: ${detail}`), "error");
+		return false;
+	}
+
+	if (!isCurrent()) return false;
+	const finishedReady =
+		state.enabled && Boolean(state.latestPlan?.trim()) && lifecycle?.finishReady !== undefined;
+	if (finishedReady) lifecycle.finishReady?.();
+	const detail = finishedReady ? " Plan mode disabled." : "";
+	ctx.ui.notify(safeNotification(`Plan exported to ${result.path}.${detail}`), "info");
+	return true;
+}
+
+export async function exportPlanToFile(
+	plan: string,
+	requestedPath: string | undefined,
+	cwd: string,
+	signal?: AbortSignal,
+	isCurrent: () => boolean = () => true,
+	defaultPath = DEFAULT_PLAN_EXPORT_PATH,
+): Promise<PlanExportResult> {
+	const path = resolvePlanExportPath(requestedPath, cwd, defaultPath);
+	await withFileMutationQueue(path, async () => {
+		throwIfCancelled(signal, isCurrent);
+		await mkdir(dirname(path), { recursive: true });
+		throwIfCancelled(signal, isCurrent);
+		try {
+			await writeFile(path, `${plan}\n`, { encoding: "utf8", flag: "wx" });
+		} catch (error: unknown) {
+			if (isNodeError(error) && error.code === "EEXIST") {
+				throw new Error(
+					`Plan export target already exists: ${path}. Choose another path or remove it first.`,
+				);
+			}
+			throw error;
+		}
+	});
+	return { path };
+}
+
+export function planExportDestination(defaultPath: string, cwd: string): PlanExportDestination {
+	return {
+		configuredPath: safeNotification(defaultPath),
+		resolvedPath: safeNotification(resolvePlanExportPath(undefined, cwd, defaultPath)),
+	};
+}
+
+export function resolvePlanExportPath(
+	requestedPath: string | undefined,
+	cwd: string,
+	defaultPath = DEFAULT_PLAN_EXPORT_PATH,
+) {
+	const rawPath = requestedPath?.trim() || defaultPath;
+	const normalizedPath = rawPath.startsWith("@") ? rawPath.slice(1) : rawPath;
+	if (!normalizedPath.trim()) throw new Error("Plan export path must not be empty.");
+	if (normalizedPath.includes("\0")) {
+		throw new Error("Plan export path must not contain NUL bytes.");
+	}
+	return resolve(cwd, normalizedPath);
+}
+
+function safeNotification(value: string) {
+	let sanitized = "";
+	for (const character of stripVTControlCharacters(value)) {
+		const codePoint = character.codePointAt(0);
+		sanitized +=
+			codePoint !== undefined && codePoint > 0x1f && !(codePoint >= 0x7f && codePoint <= 0x9f)
+				? character
+				: " ";
+	}
+	return sanitized;
+}
+
+function throwIfCancelled(signal: AbortSignal | undefined, isCurrent: () => boolean) {
+	if (!signal?.aborted && isCurrent()) return;
+	throw signal?.reason instanceof Error
+		? signal.reason
+		: new DOMException("Plan export cancelled", "AbortError");
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}

package/src/plan-launch-menu.ts

@@ -0,0 +1,122 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+
+export interface PlanLaunchTool {
+	name: string;
+	description: string;
+	searchText: string;
+	disabled: boolean;
+	disabledReason?: string;
+}
+
+interface PlanLaunchMenuOptions {
+	statusText: string;
+	toolSummary(selectedNames: ReadonlySet<string>): string;
+	getSelectedNames(): ReadonlySet<string>;
+	tools: readonly PlanLaunchTool[];
+	signal: AbortSignal;
+	isCurrent(): boolean;
+	initialScreen?: "main" | "tools";
+	start(signal: AbortSignal): void;
+	startWithTools(toolNames: string[], signal: AbortSignal): void;
+	settings(signal: AbortSignal): Promise<boolean>;
+}
+
+export async function showPlanLaunchMenu(ctx: ExtensionContext, options: PlanLaunchMenuOptions) {
+	type Screen = "main" | "tools" | "help";
+	type Action = "start" | "toggle-tool" | "start-with-tools" | "settings";
+	const selectedNames = new Set(options.getSelectedNames());
+	let draftChanged = false;
+	const menu = defineMenu<undefined, Screen, Action, ExtensionContext>({
+		start: options.initialScreen ?? "main",
+		screens: {
+			main: () => ({
+				kind: "actions",
+				title: "Plan mode",
+				lines: [options.statusText, options.toolSummary(selectedNames)],
+				items: [
+					{ id: "start", label: "Start Plan mode", action: "start" },
+					{ id: "tools", label: "Choose tools, then start…", to: "tools" },
+					{ id: "settings", label: "Settings", action: "settings" },
+					{ id: "help", label: "How Plan mode works", to: "help" },
+				],
+				hint: "close",
+			}),
+			tools: () => ({
+				kind: "multiSelect",
+				title: "Choose Plan-mode tools",
+				lines: [
+					"Changes apply only when you start Plan mode.",
+					"Non-built-in tools run at user risk.",
+				],
+				enableSearch: true,
+				viewportSize: 10,
+				items: options.tools.map((tool) => ({
+					id: tool.name,
+					label: tool.name,
+					description: tool.description,
+					searchText: tool.searchText,
+					selected: selectedNames.has(tool.name),
+					disabled: tool.disabled,
+					disabledReason: tool.disabledReason,
+				})),
+				action: "toggle-tool",
+				actions: [
+					{
+						id: "start-with-tools",
+						label: "Done — start Plan mode",
+						action: "start-with-tools",
+					},
+				],
+				hint: "back",
+			}),
+			help: () => ({
+				kind: "detail",
+				title: "How Plan mode works",
+				lines: [
+					"Plan mode uses read-only exploration to understand the project before implementation.",
+					"The agent can ask important decision questions, then returns a complete implementation-ready plan.",
+					"File mutation stays blocked until you explicitly choose to implement the completed plan.",
+				],
+				hint: "back",
+			}),
+		},
+		actions: {
+			start: async ({ signal }) => {
+				if (signal.aborted || !options.isCurrent()) return { kind: "rejected" };
+				options.start(signal);
+				return { kind: "close" };
+			},
+			"toggle-tool": async ({ itemId, selected, signal }) => {
+				if (signal.aborted || !options.isCurrent()) return { kind: "rejected" };
+				const tool = options.tools.find((candidate) => candidate.name === itemId);
+				if (!tool || tool.disabled) return { kind: "rejected" };
+				if (selected) selectedNames.add(tool.name);
+				else selectedNames.delete(tool.name);
+				draftChanged = true;
+				return { kind: "stay" };
+			},
+			"start-with-tools": async ({ signal }) => {
+				if (signal.aborted || !options.isCurrent()) return { kind: "rejected" };
+				options.startWithTools(Array.from(selectedNames), signal);
+				return { kind: "close" };
+			},
+			settings: async ({ signal }) => {
+				if (signal.aborted || !options.isCurrent()) return { kind: "rejected" };
+				const close = await options.settings(signal);
+				if (signal.aborted || !options.isCurrent()) return { kind: "rejected" };
+				if (close) return { kind: "close" };
+				if (!draftChanged) {
+					selectedNames.clear();
+					for (const name of options.getSelectedNames()) selectedNames.add(name);
+				}
+				return { kind: "stay" };
+			},
+		},
+	});
+	await runMenu(ctx, menu, {
+		getState: () => undefined,
+		signal: options.signal,
+		isCurrent: options.isCurrent,
+	});
+}