@andares/pi-toolkits 0.10.0 → 0.11.1

package/src/features/init/types.ts

@@ -0,0 +1,284 @@
+/**
+ * init feature — types shared by detect / plan / apply / audit.
+ *
+ * The split is intentional: `Facts` is what the disk says (no judgement),
+ * `Plan` is what the command intends to do about it (deterministic actions for
+ * code, tasks for the model), and `Finding` is what the audit can prove.
+ */
+import type { ProjectLanguage } from "./spec.js";
+
+export type Severity = "error" | "warning" | "info";
+
+/** One audit result. `code` is stable so reports stay machine-readable. */
+export interface Finding {
+	readonly code: string;
+	readonly severity: Severity;
+	readonly message: string;
+	readonly path?: string;
+	readonly line?: number;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Facts                                                                       */
+/* -------------------------------------------------------------------------- */
+
+export interface FileInfo {
+	/** Path relative to the project root, POSIX separators. */
+	readonly rel: string;
+	readonly bytes: number;
+	readonly lines: number;
+	readonly mtimeMs: number;
+}
+
+export interface Heading {
+	readonly level: number;
+	readonly text: string;
+	readonly line: number;
+}
+
+export interface DocInfo extends FileInfo {
+	readonly text: string;
+	readonly headings: readonly Heading[];
+}
+
+export interface RootInfo {
+	readonly label: string;
+	/** Path as registered (relative to the project root when inside it). */
+	readonly path: string;
+	readonly absolute: string;
+	readonly role?: string;
+	readonly agentsMd: "none" | "scope-card" | "independent" | "unknown";
+	readonly source: "state" | "add-dir";
+	readonly exists: boolean;
+	readonly lastSeen?: string;
+}
+
+export interface FrameworkState {
+	version: number;
+	tool: string;
+	created: string;
+	updated: string;
+	profile: "core" | "full";
+	modules: string[];
+	lang: ProjectLanguage;
+	budgets?: {
+		agentsMdSoftChars?: number;
+		agentsMdHardChars?: number;
+		memoryFileChars?: number;
+	};
+	roots: RootInfo[];
+	managed: Array<{ path: string; sha256: string; template: string }>;
+	migrations: Array<{ at: string; to: string; notes?: string }>;
+}
+
+export interface RefArea {
+	files: number;
+	hits: number;
+}
+
+/** Bare `memory/` / `implementations/` references that a move would break. */
+export interface RefScan {
+	/** Text files inspected. */
+	files: number;
+	/** Bare occurrences (already excludes `.agents/…` and `my-memory/`-style). */
+	hits: number;
+	byArea: Record<string, RefArea>;
+	examples: Array<{ path: string; line: number; text: string }>;
+	/** Files that contain at least one bare occurrence. */
+	paths: string[];
+}
+
+export interface ProjectFacts {
+	manifests: string[];
+	lockfiles: string[];
+	license?: string;
+	ci: string[];
+	scripts: Record<string, string>;
+	pkgManager?: string;
+}
+
+export interface ContextFiles {
+	agents?: DocInfo;
+	claude?: DocInfo;
+	override?: DocInfo;
+	piAgents?: DocInfo;
+}
+
+export interface Facts {
+	root: string;
+	isGit: boolean;
+	gitClean?: boolean;
+	gitDirtyCount?: number;
+	/** Present when the state file exists and parsed. */
+	state?: FrameworkState;
+	stateError?: string;
+	context: ContextFiles;
+	/** Framework-relevant directories that exist (relative paths). */
+	dirs: Record<string, boolean>;
+	/** Legacy locations that the framework wants under `.agents/`. */
+	deprecated: { memory: boolean; implementations: boolean; prompts: boolean };
+	/** File counts for the three legacy locations (all file types). */
+	deprecatedFiles: { memory: number; implementations: number; prompts: number };
+	/** `todos/` is retired; content becomes specs. */
+	retiredTodos: boolean;
+	/** Zero-byte files sitting at the root (crash artefacts, placeholders). */
+	rootEmptyFiles: string[];
+	/** Memory docs found at the canonical location, sorted by name. */
+	memory: DocInfo[];
+	/** Extra memory docs found in a legacy `memory/` directory. */
+	legacyMemory: DocInfo[];
+	specs: DocInfo[];
+	implementations: FileInfo[];
+	todos: DocInfo[];
+	legacyDocs: DocInfo[];
+	nestedAgents: FileInfo[];
+	/** Memory-module ids that already have a file (design, terms, review, …). */
+	modulesPresent: string[];
+	refs: RefScan;
+	project: ProjectFacts;
+	language: ProjectLanguage;
+	roots: RootInfo[];
+	warnings: string[];
+}
+
+/* -------------------------------------------------------------------------- */
+/* Plan                                                                        */
+/* -------------------------------------------------------------------------- */
+
+export type PlanMode =
+	| "fresh"
+	| "adopt"
+	| "reconcile"
+	| "upgrade"
+	| "audit-only"
+	| "unsupported";
+
+export interface SnapshotAction {
+	readonly kind: "snapshot";
+	readonly paths: string[];
+	readonly files: number;
+}
+
+export interface MoveAction {
+	readonly kind: "move-dir";
+	readonly from: string;
+	readonly to: string;
+	readonly files: number;
+	/** untracked files ride along with a plain rename instead of `git mv`. */
+	readonly trackedOnly: boolean;
+}
+
+export interface MoveFileAction {
+	readonly kind: "move-file";
+	readonly from: string;
+	readonly to: string;
+}
+
+export interface RewriteAction {
+	readonly kind: "rewrite-refs";
+	/** Applied in order; first match wins (longest prefixes first). */
+	readonly pairs: Array<{ from: string; to: string }>;
+	readonly files: number;
+	readonly hits: number;
+}
+
+export interface CreateFileAction {
+	readonly kind: "create-file";
+	readonly path: string;
+	/** Template name in `templates/` or "inline" with `content`. */
+	readonly template: string;
+	readonly tokens: Record<string, string>;
+	readonly note: string;
+}
+
+export interface CreateDirsAction {
+	readonly kind: "create-dirs";
+	readonly paths: string[];
+}
+
+export interface WriteStateAction {
+	readonly kind: "write-state";
+	readonly state: FrameworkState;
+}
+
+export type Action =
+	| SnapshotAction
+	| MoveAction
+	| MoveFileAction
+	| RewriteAction
+	| CreateDirsAction
+	| CreateFileAction
+	| WriteStateAction;
+
+export type TaskKind =
+	| "survey"
+	| "edit-agents"
+	| "merge-plan"
+	| "merge-legacy"
+	| "triage-todos"
+	| "fill-file"
+	| "root-cards"
+	| "budget-debt"
+	| "coverage";
+
+export interface Task {
+	readonly id: string;
+	readonly kind: TaskKind;
+	readonly detail: string;
+	readonly targets?: string[];
+	readonly acceptance: string[];
+}
+
+export interface Plan {
+	readonly mode: PlanMode;
+	readonly root: string;
+	readonly language: ProjectLanguage;
+	readonly frameworkVersion: number;
+	readonly toolVersion: string;
+	readonly createdAt: string;
+	readonly actions: Action[];
+	readonly tasks: Task[];
+	/** Paths this run writes for the model and the operator. */
+	readonly artifacts: { plan?: string; coverage?: string; rewrite?: string; snapshot?: string };
+	/** Human summary lines shown in the confirmation panel. */
+	readonly summary: string[];
+	readonly warnings: string[];
+	readonly facts: Facts;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Apply                                                                       */
+/* -------------------------------------------------------------------------- */
+
+export interface ApplyResult {
+	readonly snapshot?: { dir: string; files: number };
+	readonly moved: Array<{ from: string; to: string; files: number }>;
+	readonly rewrites?: { files: number; hits: number; report: string };
+	readonly created: string[];
+	readonly skipped: Array<{ path: string; reason: string }>;
+	readonly statePath?: string;
+	/** Machine-readable work order for the model stage. */
+	readonly planPath?: string;
+	readonly summary: string[];
+}
+
+/* -------------------------------------------------------------------------- */
+/* Coverage                                                                    */
+/* -------------------------------------------------------------------------- */
+
+export type CoverageStatus = "hit" | "mapped" | "open";
+
+export interface CoverageRow {
+	readonly source: string;
+	readonly heading: string;
+	readonly status: CoverageStatus;
+	readonly destination?: string;
+	readonly reason?: string;
+}
+
+export interface CoverageReport {
+	readonly rows: CoverageRow[];
+	readonly open: number;
+	readonly mapped: number;
+	readonly hit: number;
+}

package/src/features/init/ui.ts

@@ -0,0 +1,160 @@
+/**
+ * init feature — the plan preview and confirmation.
+ *
+ * Migration moves files, so the operator must see what will happen before it
+ * happens. Three paths:
+ *
+ *  - **TUI**: a bounded preview panel (summary, warnings, task ids) with one
+ *    keystroke answers — `y`/Enter applies, `d` writes nothing (dry run),
+ *    Esc cancels.
+ *  - **dialog-capable non-TUI** (RPC): the host's selector.
+ *  - **no UI** (print/json): fail closed — report only, never write.
+ *
+ * The preview is bounded on purpose: a plan can list hundreds of tasks, and a
+ * panel that scrolls off the screen is worse than a summary plus the full plan
+ * written to `.agents/framework/plans/` on the next step.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type Component, matchesKey, Text } from "@earendil-works/pi-tui";
+import type { Plan } from "./types.js";
+
+export type PlanDecision = "proceed" | "dry-run" | "cancel";
+
+const MAX_PREVIEW_LINES = 16;
+
+function previewLines(plan: Plan): string[] {
+	const lines: string[] = [`/ask-init — ${plan.mode}`, ""];
+	lines.push(...plan.summary);
+	if (plan.warnings.length > 0) {
+		lines.push("", "warnings:");
+		for (const warning of plan.warnings.slice(0, 4)) lines.push(`  ! ${warning}`);
+		if (plan.warnings.length > 4) lines.push(`  … ${plan.warnings.length - 4} more`);
+	}
+	if (plan.tasks.length > 0) {
+		lines.push("", `model tasks: ${plan.tasks.map((task) => task.id).join(", ")}`);
+	}
+	if (lines.length > MAX_PREVIEW_LINES) {
+		lines.splice(MAX_PREVIEW_LINES);
+		lines.push("…");
+	}
+	return lines;
+}
+
+class PlanPanel implements Component {
+	constructor(
+		private readonly body: Text,
+		private readonly footer: Text,
+		private readonly done: (decision: PlanDecision) => void,
+	) {}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.done("cancel");
+			return;
+		}
+		if (matchesKey(data, "enter") || data === "y" || data === "Y") {
+			this.done("proceed");
+			return;
+		}
+		if (data === "d" || data === "D") {
+			this.done("dry-run");
+			return;
+		}
+	}
+
+	render(width: number): string[] {
+		return [...this.body.render(width), ...this.footer.render(width)];
+	}
+
+	invalidate(): void {
+		this.body.invalidate();
+		this.footer.invalidate();
+	}
+}
+
+/** Ask the operator what to do with this plan. */
+export async function confirmPlan(
+	ctx: ExtensionContext,
+	plan: Plan,
+): Promise<PlanDecision> {
+	if (!ctx.hasUI) return "dry-run";
+
+	if (ctx.mode !== "tui") {
+		const choice = await ctx.ui.select(
+			`/ask-init ${plan.mode}: ${plan.summary[0] ?? ""}`,
+			["Proceed", "Report only (no writes)", "Cancel"],
+		);
+		if (choice === "Proceed") return "proceed";
+		if (choice === "Report only (no writes)") return "dry-run";
+		return "cancel";
+	}
+
+	return ctx.ui.custom<PlanDecision>((_tui, _theme, _keybindings, done) => {
+		const body = new Text(previewLines(plan).join("\n"));
+		const footer = new Text(
+			"[Enter/y] apply   [d] report only, write nothing   [Esc] cancel",
+		);
+		return new PlanPanel(body, footer, done);
+	});
+}
+
+/* -------------------------------------------------------------------------- */
+/* Read-only report panel                                                      */
+/* -------------------------------------------------------------------------- */
+
+const MAX_REPORT_LINES = 22;
+
+class ReportPanel implements Component {
+	constructor(
+		private readonly body: Text,
+		private readonly footer: Text,
+		private readonly done: () => void,
+	) {}
+
+	handleInput(data: string): void {
+		if (
+			matchesKey(data, "escape") ||
+			matchesKey(data, "enter") ||
+			matchesKey(data, "ctrl+c") ||
+			data === "q"
+		) {
+			this.done();
+		}
+	}
+
+	render(width: number): string[] {
+		return [...this.body.render(width), ...this.footer.render(width)];
+	}
+
+	invalidate(): void {
+		this.body.invalidate();
+		this.footer.invalidate();
+	}
+}
+
+/**
+ * Show a report (plan or audit) without writing anything. In TUI it opens a
+ * bounded panel; elsewhere the first lines go through `notify`, which is the
+ * only output channel print/json modes have.
+ */
+export async function showReport(
+	ctx: ExtensionContext,
+	title: string,
+	text: string,
+	options: { path?: string } = {},
+): Promise<void> {
+	const lines = text.split("\n");
+	if (!ctx.hasUI || ctx.mode !== "tui") {
+		const head = lines.filter((line) => line.trim().length > 0).slice(0, 6).join("\n");
+		ctx.ui.notify(`${title}\n${head}${options.path ? `\n→ ${options.path}` : ""}`, "info");
+		return;
+	}
+	const clipped = lines.slice(0, MAX_REPORT_LINES);
+	if (lines.length > MAX_REPORT_LINES) clipped.push(`… ${lines.length - MAX_REPORT_LINES} more lines`);
+	if (options.path) clipped.push("", `full report: ${options.path}`);
+	await ctx.ui.custom<void>((_tui, _theme, _keybindings, done) => {
+		const body = new Text(clipped.join("\n"));
+		const footer = new Text("[Enter/Esc] close");
+		return new ReportPanel(body, footer, () => done(undefined));
+	});
+}

package/src/features/permission/audit.test.ts

@@ -45,7 +45,7 @@ function audit(command: string, ctx: PolicyContext, prompt?: readonly string[])
 describe("permission audit payload", () => {
 	it("records the decomposition, target scope and deciding layer", () => {
 		const cwd = project();
-		const payload = audit("rm -rf /tmp/outside/x", makeContext(cwd));
+		const payload = audit("rm -rf /var/pi-perm-outside/x", makeContext(cwd));
 
 		expect(payload.modes).toEqual({
 			inRead: "allow",
@@ -58,7 +58,7 @@ describe("permission audit payload", () => {
 			expect.objectContaining({
 				head: "rm",
 				command: "rm",
-				args: ["-rf", "/tmp/outside/x"],
+				args: ["-rf", "/var/pi-perm-outside/x"],
 				base: canonicalize(cwd),
 				effect: "write",
 				opaque: false,
@@ -66,8 +66,8 @@ describe("permission audit payload", () => {
 				layer: "mode",
 				targets: [
 					{
-						path: "/tmp/outside/x",
-						canonical: "/tmp/outside/x",
+						path: "/var/pi-perm-outside/x",
+						canonical: canonicalize("/var/pi-perm-outside/x"),
 						effect: "write",
 						source: "operand",
 						scope: "out",
@@ -79,11 +79,11 @@ describe("permission audit payload", () => {
 			action: "ask",
 			layer: "mode",
 			unit: 0,
-			target: "/tmp/outside/x",
+			target: canonicalize("/var/pi-perm-outside/x"),
 			effect: "write",
 			scope: "out",
 			grantScope: "root",
-			grantRoot: "/tmp/outside",
+			grantRoot: canonicalize("/var/pi-perm-outside"),
 		});
 	});
 
@@ -137,20 +137,20 @@ describe("permission audit payload", () => {
 
 	it("carries the exact prompt lines when asked", () => {
 		const cwd = project();
-		const payload = audit("rm -rf /tmp/outside/x", makeContext(cwd), [
+		const payload = audit("rm -rf /var/pi-perm-outside/x", makeContext(cwd), [
 			"Permission required",
-			"Command: rm -rf /tmp/outside/x",
+			"Command: rm -rf /var/pi-perm-outside/x",
 		]);
 		expect(payload.prompt).toEqual([
 			"Permission required",
-			"Command: rm -rf /tmp/outside/x",
+			"Command: rm -rf /var/pi-perm-outside/x",
 		]);
 	});
 
 	it("clips long arguments but keeps the target", () => {
 		const cwd = project();
 		const longArg = `--flag=${"x".repeat(2000)}`;
-		const payload = audit(`rm -rf /tmp/outside/x ${longArg}`, makeContext(cwd));
+		const payload = audit(`rm -rf /var/pi-perm-outside/x ${longArg}`, makeContext(cwd));
 		const unit = (payload.units as Array<Record<string, unknown>>)[0];
 		const args = unit.args as string[];
 		expect(args[2]).toContain("[+");

package/src/features/permission/constants.test.ts

@@ -2,10 +2,16 @@
  * Fixed safety tables: credential paths are denied in every mode, destructive
  * commands always ask.
  */
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { dangerReason, secretReason } from "./constants.js";
+import { canonicalize } from "./paths.js";
+import {
+	dangerReason,
+	isTemporaryPath,
+	secretReason,
+	temporaryRoots,
+} from "./constants.js";
 
 const HOME = homedir();
 
@@ -37,11 +43,30 @@ describe("secrets table", () => {
 	});
 });
 
+describe("temporary write zone", () => {
+	it("covers the OS temp root and the common volatile directories", () => {
+		expect(temporaryRoots()).toContain(canonicalize(tmpdir()));
+		expect(temporaryRoots()).toContain(canonicalize("/var/tmp"));
+		expect(temporaryRoots()).toContain(canonicalize("/dev/shm"));
+		expect(isTemporaryPath(join(tmpdir(), "pi", "x"))).toBe(true);
+		expect(isTemporaryPath(join("/var/tmp", "x"))).toBe(true);
+		expect(isTemporaryPath(join("/dev/shm", "x"))).toBe(true);
+	});
+
+	it("does not over-match a sibling prefix or an ordinary path", () => {
+		expect(isTemporaryPath(`${tmpdir()}-evil/x`)).toBe(false);
+		expect(isTemporaryPath("/var/tmp-evil/x")).toBe(false);
+		expect(isTemporaryPath("/proj/x")).toBe(false);
+	});
+});
+
 describe("danger table", () => {
 	it("catches the destructive core", () => {
 		expect(dangerReason("rm", ["-rf", "/"], ["/"], "/proj")).toContain("recursive delete");
 		expect(dangerReason("rm", ["-rf", HOME], [HOME], "/proj")).toContain("recursive delete");
 		expect(dangerReason("rm", ["-rf", "/proj"], ["/proj"], "/proj")).toContain("recursive delete");
+		expect(dangerReason("rm", ["-rf", tmpdir()], [tmpdir()], "/proj")).toContain("recursive delete");
+		expect(dangerReason("rm", ["-rf", "/var/tmp"], ["/var/tmp"], "/proj")).toContain("recursive delete");
 		expect(dangerReason("git", ["push", "--force"], [], "/proj")).toBe("forced git push");
 		expect(dangerReason("git", ["push", "-f"], [], "/proj")).toBe("forced git push");
 		expect(dangerReason("git", ["reset", "--hard"], [], "/proj")).toBe("git reset --hard");
@@ -53,6 +78,7 @@ describe("danger table", () => {
 
 	it("does not flag ordinary commands", () => {
 		expect(dangerReason("rm", ["-rf", "/proj/build"], ["/proj/build"], "/proj")).toBeUndefined();
+		expect(dangerReason("rm", ["-rf", join(tmpdir(), "x")], [join(tmpdir(), "x")], "/proj")).toBeUndefined();
 		expect(dangerReason("git", ["push"], [], "/proj")).toBeUndefined();
 		expect(dangerReason("git", ["log"], [], "/proj")).toBeUndefined();
 		expect(dangerReason("npm", ["view", "react"], [], "/proj")).toBeUndefined();

package/src/features/permission/constants.ts

@@ -13,8 +13,9 @@
  *    when their scope says allow (`rm -rf .` inside the project is still a
  *    guarded operation). Scope alone cannot express "destructive".
  */
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { basename, join, sep } from "node:path";
+import { canonicalize } from "./paths.js";
 
 /** Three-way mode, used for outside-project operations. */
 export type TriMode = "ask" | "allow" | "deny";
@@ -85,6 +86,29 @@ function isSecretEnvFile(pathValue: string): boolean {
 	return name === ".env" || name.startsWith(".env.");
 }
 
+/**
+ * Ephemeral directories whose writes are built-in safe: a scratch artifact
+ * under the OS temp root is not a boundary crossing worth a dialog. Kept to
+ * genuinely volatile locations; `~/.cache` is deliberately not included (it
+ * is a home-directory state area, not a scratch area).
+ *
+ * Resolved once at module load so the comparisons use the same spelling as the
+ * policy's canonical paths (`/tmp` is a symlink to `/private/tmp` on macOS).
+ */
+const TEMPORARY_ROOTS: readonly string[] = [tmpdir(), "/var/tmp", "/dev/shm"].map(
+	(root) => canonicalize(root),
+);
+
+export function temporaryRoots(): string[] {
+	return [...TEMPORARY_ROOTS];
+}
+
+/** `true` when `pathValue` is inside one of {@link temporaryRoots}. */
+export function isTemporaryPath(pathValue: string): boolean {
+	const canonical = canonicalize(pathValue);
+	return TEMPORARY_ROOTS.some((root) => pathWithin(root, canonical));
+}
+
 /** Absolute secret prefixes, `~` expanded. */
 export function secretRoots(): string[] {
 	return SECRET_ROOTS.map((root) =>
@@ -118,11 +142,12 @@ export function dangerReason(
 	const inDangerousRoot = (pathValue: string): boolean =>
 		pathValue === "/" ||
 		pathValue === home ||
-		(base !== null && pathValue === base);
+		(base !== null && pathValue === base) ||
+		TEMPORARY_ROOTS.includes(canonicalize(pathValue));
 
 	if (command === "sudo" || command === "doas") return "privileged command";
 	if (command === "rm" && targets.some(inDangerousRoot)) {
-		return "recursive delete of /, the home directory, or the working directory";
+		return "recursive delete of /, the home directory, the working directory, or a temp root";
 	}
 	if (command === "git") {
 		const [verb, ...rest] = args;