@andares/pi-toolkits 0.10.0 → 0.11.0

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/index.ts

@@ -12,6 +12,7 @@
  *  - compact — dedicated compact model for /compact + auto-compact summaries
  *  - autostart — replay project-declared slash commands at session start (/add-dir persistence)
  *  - permission — session-scoped boundary permission checks (/ask-perm)
+ *  - init — agent memory framework install / adoption (/ask-init)
  *
  * `ask` and `permission` are independent gates on one bus: each answers its own
  * question and the strictest answer wins, so they compose rather than replace
@@ -24,6 +25,7 @@ import { registerAsk } from "./features/ask/index.js";
 import { registerAutostart } from "./features/autostart/index.js";
 import { registerCompact } from "./features/compact/index.js";
 import { registerFavorites } from "./features/favorites/index.js";
+import { registerInit } from "./features/init/index.js";
 import { registerPermission } from "./features/permission/index.js";
 import { registerReview } from "./features/review/index.js";
 import { registerStash } from "./features/stash/index.js";
@@ -41,6 +43,7 @@ export default function piToolkits(pi: ExtensionAPI): void {
 	registerAutostart(pi);
 	registerCompact(pi);
 	registerFavorites(pi);
+	registerInit(pi);
 	registerReview(pi);
 	registerStash(pi);