@pixelsnis/pi-plan-mode 0.1.2

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@pixelsnis/pi-plan-mode",
+  "version": "0.1.2",
+  "description": "Plan and Build modes for Pi with deny-by-default planning tools and explicit plan approval.",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "plan-file.ts",
+    "review-ui.ts",
+    "README.md",
+    "skills/plan-writing/SKILL.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pixelsnis/pi-extensions.git",
+    "directory": "extensions/plan-mode"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "plan-mode"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills/plan-writing"
+    ]
+  }
+}

package/plan-file.ts

@@ -0,0 +1,95 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, mkdtemp } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+export const MAX_PLAN_BYTES = 200 * 1024;
+
+function safeSlug(value: string): string {
+	return value.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "plan";
+}
+
+async function createSecureDirectory(path: string): Promise<string> {
+	try {
+		const before = await lstat(path);
+		if (before.isSymbolicLink() || !before.isDirectory()) {
+			throw new Error(`Plan directory must be a real directory: ${path}`);
+		}
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	await mkdir(path, { recursive: true, mode: 0o700 });
+	const canonical = await realpath(path);
+	if (canonical !== resolve(path)) throw new Error(`Refusing redirected plan directory: ${path}`);
+	return canonical;
+}
+
+export async function createPlanPath(options: {
+	cwd: string;
+	sessionId: string;
+	gitAdminDir?: string;
+}): Promise<string> {
+	let planDir: string;
+	if (options.gitAdminDir) {
+		const gitDir = await realpath(resolve(options.gitAdminDir));
+		planDir = await createSecureDirectory(join(gitDir, "implementation-plans"));
+	} else {
+		const project = safeSlug(basename(resolve(options.cwd)));
+		planDir = await realpath(await mkdtemp(join(tmpdir(), `${project}-implementation-plans.`)));
+	}
+	const session = safeSlug(options.sessionId).slice(-20) || "session";
+	const filename = `plan-${session}-${Date.now()}-plan.md`;
+	return join(planDir, filename);
+}
+
+async function assertPlanPath(path: string): Promise<string> {
+	if (!path || !resolve(path).endsWith("-plan.md") || resolve(path) !== path) {
+		throw new Error("Invalid extension-owned plan file path");
+	}
+	const folder = dirname(path);
+	if (await realpath(folder) !== folder) throw new Error("Refusing a redirected plan directory");
+	try {
+		const info = await lstat(path);
+		if (info.isSymbolicLink() || !info.isFile() || info.nlink > 1) {
+			throw new Error("Plan path must be a regular, non-linked file");
+		}
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	return path;
+}
+
+export async function writePlan(path: string, content: string): Promise<void> {
+	if (typeof content !== "string" || content.trim().length === 0) {
+		throw new Error("The plan must be non-empty Markdown");
+	}
+	if (Buffer.byteLength(content, "utf8") > MAX_PLAN_BYTES) {
+		throw new Error(`Plan exceeds the ${MAX_PLAN_BYTES / 1024} KiB limit`);
+	}
+	const target = await assertPlanPath(path);
+	const noFollow = constants.O_NOFOLLOW ?? 0;
+	const nonBlock = constants.O_NONBLOCK ?? 0;
+	const file = await open(target, constants.O_WRONLY | constants.O_CREAT | noFollow | nonBlock, 0o600);
+	try {
+		const info = await file.stat();
+		if (!info.isFile() || info.nlink > 1) throw new Error("Plan target is not a private regular file");
+		await file.truncate(0);
+		await file.writeFile(content, { encoding: "utf8" });
+	} finally {
+		await file.close();
+	}
+}
+
+export async function readPlan(path: string): Promise<string> {
+	const target = await assertPlanPath(path);
+	const file = await open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+	try {
+		const info = await file.stat();
+		if (!info.isFile() || info.nlink > 1) throw new Error("Plan target is not a regular private file");
+		if (info.size <= 0) throw new Error("Plan file is empty");
+		if (info.size > MAX_PLAN_BYTES) throw new Error("Plan file exceeds the 200 KiB limit");
+		return await file.readFile({ encoding: "utf8" });
+	} finally {
+		await file.close();
+	}
+}

package/review-ui.ts

@@ -0,0 +1,88 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Markdown, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+export type ReviewChoice = "refine" | "execute-new" | "execute-here" | "cancel";
+
+function fit(text: string, width: number): string {
+	return width <= 0 ? "" : truncateToWidth(text, width, "");
+}
+
+function border(width: number, left: string, fill: string, right: string): string {
+	if (width <= 1) return fit(fill, width);
+	return left + fill.repeat(Math.max(0, width - 2)) + right;
+}
+
+function framedLine(text: string, width: number): string {
+	if (width < 4) return fit(text, width);
+	const contentWidth = width - 4;
+	const content = truncateToWidth(text, contentWidth, "");
+	const padding = Math.max(0, contentWidth - visibleWidth(content));
+	return `│ ${content}${" ".repeat(padding)} │`;
+}
+
+function reviewLayout(rows: number): { topPadding: number; viewportHeight: number } {
+	const topPadding = Math.min(3, Math.max(0, rows - 10));
+	return { topPadding, viewportHeight: Math.max(1, rows - 8 - topPadding) };
+}
+
+export async function showPlanReview(
+	ctx: ExtensionContext,
+	path: string,
+	content: string,
+): Promise<ReviewChoice | undefined> {
+	return ctx.ui.custom<ReviewChoice>((tui, theme, _keybindings, done) => {
+		const markdown = new Markdown(content, 0, 0, getMarkdownTheme());
+		let scrollTop = 0;
+
+		const component = {
+			render(width: number): string[] {
+				const safeWidth = Math.max(1, width);
+				const innerWidth = Math.max(1, safeWidth - 4);
+				const contentLines = markdown.render(innerWidth);
+				const { topPadding, viewportHeight } = reviewLayout(tui.terminal.rows);
+				const maxScroll = Math.max(0, contentLines.length - viewportHeight);
+				scrollTop = Math.min(Math.max(0, scrollTop), maxScroll);
+
+				const lines = [
+					...Array.from({ length: topPadding }, () => ""),
+					border(safeWidth, "╭", "─", "╮"),
+					framedLine(theme.fg("accent", theme.bold("Plan review · approval required")), safeWidth),
+					framedLine(theme.fg("dim", path), safeWidth),
+				];
+				for (let i = 0; i < viewportHeight; i++) {
+					lines.push(framedLine(contentLines[scrollTop + i] ?? "", safeWidth));
+				}
+				const range = contentLines.length === 0
+					? "0 lines"
+					: `${scrollTop + 1}-${Math.min(scrollTop + viewportHeight, contentLines.length)} of ${contentLines.length}`;
+				lines.push(framedLine(theme.fg("muted", `Scroll ${range} · ↑↓/PgUp/PgDn · Home/End`), safeWidth));
+				lines.push(framedLine(theme.fg("accent", "[R] Refine  [N] Approve & Execute  [H] Approve & Execute Here  [Esc] Cancel"), safeWidth));
+				lines.push(border(safeWidth, "╰", "─", "╯"));
+				return lines.map((line) => fit(line, safeWidth));
+			},
+			handleInput(data: string): void {
+				const { viewportHeight } = reviewLayout(tui.terminal.rows);
+				const total = markdown.render(Math.max(1, tui.terminal.columns - 4)).length;
+				const maxScroll = Math.max(0, total - viewportHeight);
+				if (matchesKey(data, "escape")) return done("cancel");
+				if (matchesKey(data, "r")) return done("refine");
+				if (matchesKey(data, "n")) return done("execute-new");
+				if (matchesKey(data, "h")) return done("execute-here");
+				if (matchesKey(data, "up") || matchesKey(data, "k")) scrollTop = Math.max(0, scrollTop - 1);
+				else if (matchesKey(data, "down") || matchesKey(data, "j")) scrollTop = Math.min(maxScroll, scrollTop + 1);
+				else if (matchesKey(data, "pageUp")) scrollTop = Math.max(0, scrollTop - viewportHeight);
+				else if (matchesKey(data, "pageDown")) scrollTop = Math.min(maxScroll, scrollTop + viewportHeight);
+				else if (matchesKey(data, "home")) scrollTop = 0;
+				else if (matchesKey(data, "end")) scrollTop = maxScroll;
+				else return;
+				tui.requestRender();
+			},
+			invalidate(): void {
+				markdown.invalidate();
+			},
+		};
+
+		return component;
+	});
+}

package/skills/plan-writing/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: plan-writing
+description: Use when preparing or revising an implementation plan for a multi-step software change, or handing an approved plan to a fresh-context implementer.
+---
+
+# Writing Implementation Plans
+
+An implementation plan is an execution specification: an implementer who has not seen the planning conversation should be able to follow it in order, make no design decisions, and tell when each step is complete.
+
+## Explore before planning
+
+1. Read the full request, specifications, project instructions, and relevant source/configuration. Find existing utilities and callers before proposing new ones.
+2. During planning, do not edit application files or run state-changing commands. The only file to create or update is the temporary plan.
+3. Ground paths, symbols, interfaces, behavior, and commands in sources inspected during this task. Mark unconfirmed details `unverified — confirm first`; never present guesses as facts.
+4. Resolve uncertainty by inspection first. Ask only when a real unresolved preference changes behavior, scope, or architecture. Recommend a default and give a fallback for any assumption that could block implementation.
+5. Draft and revise the plan as you learn. Reuse an existing plan only when it is for this same task.
+
+## Plan location
+
+Keep the plan outside the tracked working tree. For a Git project, use the checkout's Git administrative directory:
+
+```bash
+project_root="$(git rev-parse --show-toplevel)"
+git_admin_dir="$(git -C "$project_root" rev-parse --absolute-git-dir)"
+mkdir -p "$git_admin_dir/implementation-plans"
+```
+
+Save to `$git_admin_dir/implementation-plans/<short-kebab-case-slug>-plan.md`. For a non-Git project, create a unique directory under `${TMPDIR:-/tmp}` prefixed with the project directory name, and save the plan there. When using Plan Mode's `plan_save`, use and report only the exact relative path it returns; the extension may retain the canonical absolute path internally, but callers must not substitute or expose it. Never put a temporary plan in tracked documentation or commit it.
+
+## Required plan structure
+
+Use this template, scaling its depth to the change:
+
+```markdown
+# [Feature] Implementation Plan
+
+**Context:** [2–4 sentences: request, need, intended outcome.]
+
+**Approach:** [Short overview of ordered changes.]
+
+**Constraints:** [Only load-bearing requirements.]
+
+**Assumptions and contingencies:** [User-overridable decisions and fallback, or “None.”]
+
+## Implementation steps
+
+### Step 1: [Behavior or deliverable]
+
+**Depends on:** [Earlier steps or “None”]
+**Files:** [Exact paths and create/modify actions]
+**Interfaces:** [Exact signatures, schemas, callers, errors, or “None”]
+**Change:** [Concrete ordered actions and boundary/error handling]
+**Done when:** [Observable success condition]
+
+- [ ] [Executable action]
+- [ ] [Executable action]
+
+## Critical files and anchors
+
+- `[verified/path]`, `[symbol/region]` — [why it matters]
+
+## Verification
+
+- [Action/input] → [observable expected result]
+
+## Assumptions and contingencies
+
+[Only decisions the user may override; include fallback, or “None.”]
+```
+
+Each implementation step must specify the exact files, behavior, interfaces and data shapes, error/empty/invalid/boundary cases, and an observable completion condition. Order dependent work; mark parallel work only when interfaces and files are independent. Identify every caller affected by a changed interface or provide an exact search command. Critical files should be verified and limited to five. Keep assumptions user-overridable; resolve implementation decisions in the steps instead of deferring them.
+
+## Verification and scope
+
+Include at least one behavior-specific check with its input/action and expected result. Give exact commands and prerequisites when tests are requested or required by project instructions. Otherwise, do not add tests, commits, documentation, or cleanup tasks unless requested or required; state verification limits when no check is authorized.
+
+## Fresh-context handoff
+
+When handing work to a fresh Pi session through Plan Mode approval, rely on the session's existing working directory; do not inject or request an absolute project root. Refer to the approved plan using only the exact relative path returned by `plan_save`, and include the exact step or scope and execution constraints. The handoff itself must direct the new implementer to:
+
+1. Inspect `git status --short --branch` from the existing working directory, preserving existing changes.
+2. Read project instructions for the assigned files.
+3. Read the plan context, constraints, applicable assumptions, the full assigned step, and its named sources/interfaces.
+4. Stop and report any conflict or missing required decision instead of guessing.
+
+The implementer must make only the assigned changes, follow the plan in order, run only authorized/required verification, and report changed files, commands/results, remaining issues, and commits.