implannotator 0.2.0

package/extensions/policy/mutation-gate.ts

@@ -0,0 +1,40 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { RunRecord } from "../domain/types.js";
+
+const TERMINAL = new Set(["complete", "stopped", "failed"]);
+const PRE_APPROVAL = new Set(["inspecting", "planning", "awaiting-plan-review", "awaiting-text-approval"]);
+const READ_ONLY_BASH = /^\s*(pwd|ls|find|rg|grep|head|tail|wc|stat|file|git\s+(status|diff|log|show|branch)|npm\s+(view|list|ls)|node\s+--version)\b/;
+const FORBIDDEN_GIT = /\bgit\s+(commit|stash|reset|clean|push|checkout|switch|restore|rebase|merge)\b/i;
+
+function pathInside(cwd: string, path: string): boolean {
+  const rel = relative(resolve(cwd), resolve(cwd, path));
+  return !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+export function registerMutationGate(pi: ExtensionAPI, activeRun: (cwd: string) => RunRecord | undefined): void {
+  pi.on("tool_call", (event, ctx) => {
+    const run = activeRun(ctx.cwd);
+    if (!run || TERMINAL.has(run.phase) || event.toolName === "implannotator_control") return;
+
+    if (event.toolName === "bash") {
+      const command = typeof event.input.command === "string" ? event.input.command : "";
+      if (FORBIDDEN_GIT.test(command)) {
+        return { block: true, reason: "Implannotator never performs automatic stash/reset/commit/push or other destructive Git operations." };
+      }
+      if (PRE_APPROVAL.has(run.phase) && !READ_ONLY_BASH.test(command)) {
+        return { block: true, reason: `Implannotator approval gate: mutating shell commands are blocked during ${run.phase}.` };
+      }
+    }
+
+    if ((event.toolName === "write" || event.toolName === "edit") && PRE_APPROVAL.has(run.phase)) {
+      return { block: true, reason: `Implannotator approval gate: file mutation is blocked during ${run.phase}. Submit and approve the plan first.` };
+    }
+
+    if (event.toolName === "write" || event.toolName === "edit") {
+      const input = event.input as Record<string, unknown>;
+      const path = typeof input.path === "string" ? input.path : typeof input.file_path === "string" ? input.file_path : undefined;
+      if (path && !pathInside(ctx.cwd, path)) return { block: true, reason: "Implannotator blocks writes outside the active project." };
+    }
+  });
+}

package/extensions/policy/non-git-diff.ts

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { relative, resolve } from "node:path";
+
+const EXCLUDED = new Set([".git", ".implannotator", "node_modules", "dist", "build", "coverage", ".next"]);
+const MAX_FILE_BYTES = 10 * 1024 * 1024;
+
+export function snapshotFiles(cwd: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  const visit = (directory: string) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (EXCLUDED.has(entry.name)) continue;
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) { visit(path); continue; }
+      if (!entry.isFile()) continue;
+      const stat = statSync(path);
+      if (stat.size > MAX_FILE_BYTES) continue;
+      result[relative(cwd, path).replaceAll("\\", "/")] = createHash("sha256").update(readFileSync(path)).digest("hex");
+    }
+  };
+  visit(cwd);
+  return result;
+}
+
+export function diffSnapshots(before: Record<string, string>, after: Record<string, string>): string[] {
+  return [...new Set([...Object.keys(before), ...Object.keys(after)])]
+    .filter((path) => before[path] !== after[path])
+    .sort();
+}

package/extensions/qa/checklist.ts

@@ -0,0 +1,31 @@
+import type { QaProfile } from "../domain/types.js";
+
+const QUICK = [
+  "build-tests-types-lint",
+  "targeted-viewport",
+  "console-page-network-errors",
+  "keyboard-focus",
+  "accessibility-contrast",
+  "screenshot",
+];
+
+const STANDARD = [
+  ...QUICK,
+  "desktop-tablet-mobile",
+  "touch-targets-overflow",
+  "loading-empty-error-long-content",
+  "themes-reduced-motion",
+  "content-resilience",
+];
+
+const FULL = [
+  ...STANDARD,
+  "reference-visual-comparison",
+  "performance-core-web-vitals",
+  "cross-browser-when-available",
+  "internationalization-resilience",
+];
+
+export function requiredChecks(profile: QaProfile): string[] {
+  return [...(profile === "quick" ? QUICK : profile === "standard" ? STANDARD : FULL)];
+}

package/extensions/qa/classifier.ts

@@ -0,0 +1,23 @@
+import type { QaProfile, RiskLevel } from "../domain/types.js";
+
+export interface QaScope {
+  changedFileCount: number;
+  sharedComponents?: boolean;
+  navigation?: boolean;
+  newPage?: boolean;
+  redesign?: boolean;
+  authOrPayments?: boolean;
+}
+
+export function classifyRisk(scope: QaScope): RiskLevel {
+  if (scope.authOrPayments || scope.navigation || scope.redesign) return "high";
+  if (scope.newPage || scope.sharedComponents || scope.changedFileCount > 3) return "medium";
+  return "low";
+}
+
+export function selectQaProfile(scope: QaScope): QaProfile {
+  const risk = classifyRisk(scope);
+  if (risk === "high" || scope.newPage || scope.redesign) return "full";
+  if (risk === "medium" || scope.changedFileCount > 1) return "standard";
+  return "quick";
+}

package/extensions/review/final-report.ts

@@ -0,0 +1,6 @@
+import type { RunRecord } from "../domain/types.js";
+
+export function finalReport(run: RunRecord): string {
+  const finalReview = [...run.reviews].reverse().find((review) => review.stage === "final");
+  return `# Implannotator run ${run.id}\n\n- Status: ${run.phase}\n- Command: ${run.command}${run.target ? ` ${run.target}` : ""}\n- QA profile: ${run.qaProfile}\n- Repairs: ${run.repairCount}/3\n- Changed files: ${run.changedFiles.length}\n- Final review: ${finalReview?.approved ? "approved" : run.completionOverride ? "overridden with warning" : "not approved"}\n- Created: ${run.createdAt}\n- Updated: ${run.updatedAt}\n`;
+}

package/extensions/state/atomic-file.ts

@@ -0,0 +1,14 @@
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export function atomicWrite(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temp, content, { encoding: "utf8", mode: 0o600 });
+  renameSync(temp, path);
+}
+
+export function atomicWriteJson(path: string, value: unknown): void {
+  atomicWrite(path, `${JSON.stringify(value, null, 2)}\n`);
+}

package/extensions/state/redaction.ts

@@ -0,0 +1,19 @@
+const SECRET_PATTERNS: Array<[RegExp, string]> = [
+  [/(api[_-]?key|access[_-]?token|auth[_-]?token|password|secret)(\s*[:=]\s*)(["']?)[^\s,"']{8,}\3/gi, "$1$2[REDACTED]"],
+  [/\bsk-[a-zA-Z0-9_-]{16,}\b/g, "[REDACTED]"],
+  [/\bgh[pousr]_[a-zA-Z0-9]{20,}\b/g, "[REDACTED]"],
+  [/\b(Bearer\s+)[a-zA-Z0-9._~+/-]{16,}/gi, "$1[REDACTED]"],
+];
+
+export function redactText(value: string): string {
+  return SECRET_PATTERNS.reduce((result, [pattern, replacement]) => result.replace(pattern, replacement), value);
+}
+
+export function redactValue(value: unknown): unknown {
+  if (typeof value === "string") return redactText(value);
+  if (Array.isArray(value)) return value.map(redactValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, /password|secret|token|api.?key/i.test(key) ? "[REDACTED]" : redactValue(item)]));
+  }
+  return value;
+}

package/extensions/state/run-layout.ts

@@ -0,0 +1,40 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+export interface RunLayout {
+  root: string;
+  runJson: string;
+  plan: string;
+  decisions: string;
+  changedFiles: string;
+  qaReport: string;
+  reviews: string;
+  repairs: string;
+  evidence: string;
+  finalReport: string;
+}
+
+export function assertInside(parent: string, child: string): string {
+  const resolvedParent = resolve(parent);
+  const resolvedChild = resolve(child);
+  const rel = relative(resolvedParent, resolvedChild);
+  if (rel.startsWith("..") || isAbsolute(rel)) throw new Error(`Path escapes audit root: ${child}`);
+  return resolvedChild;
+}
+
+export function runLayout(cwd: string, auditDirectory: string, id: string): RunLayout {
+  if (!/^[a-zA-Z0-9_-]+$/.test(id)) throw new Error("Invalid run id.");
+  const auditRoot = assertInside(cwd, resolve(cwd, auditDirectory));
+  const root = assertInside(auditRoot, resolve(auditRoot, id));
+  return {
+    root,
+    runJson: resolve(root, "run.json"),
+    plan: resolve(root, "plan.md"),
+    decisions: resolve(root, "decisions.ndjson"),
+    changedFiles: resolve(root, "changed-files.json"),
+    qaReport: resolve(root, "qa", "report.json"),
+    reviews: resolve(root, "reviews"),
+    repairs: resolve(root, "repairs"),
+    evidence: resolve(root, "evidence"),
+    finalReport: resolve(root, "final-report.md"),
+  };
+}

package/extensions/state/run-store.ts

@@ -0,0 +1,97 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { DecisionRecord, QaReport, ReviewRecord, RunRecord } from "../domain/types.js";
+import { atomicWrite, atomicWriteJson } from "./atomic-file.js";
+import { redactText, redactValue } from "./redaction.js";
+import { runLayout } from "./run-layout.js";
+
+export class RunStore {
+  readonly auditRoot: string;
+  readonly activePointer: string;
+
+  constructor(readonly cwd: string, readonly auditDirectory: string) {
+    this.auditRoot = resolve(cwd, auditDirectory);
+    this.activePointer = join(dirname(this.auditRoot), "active-run");
+  }
+
+  create(command: string, target: string | undefined, risk: RunRecord["risk"], qaProfile: RunRecord["qaProfile"]): RunRecord {
+    const now = new Date().toISOString();
+    const id = `${now.replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`;
+    const run: RunRecord = {
+      schemaVersion: 1,
+      id,
+      cwd: this.cwd,
+      command,
+      ...(target ? { target } : {}),
+      risk,
+      phase: "inspecting",
+      createdAt: now,
+      updatedAt: now,
+      repairCount: 0,
+      qaProfile,
+      changedFiles: [],
+      decisions: [],
+      reviews: [],
+    };
+    this.save(run);
+    atomicWrite(this.activePointer, `${id}\n`);
+    return run;
+  }
+
+  save(run: RunRecord): void {
+    run.updatedAt = new Date().toISOString();
+    const layout = runLayout(this.cwd, this.auditDirectory, run.id);
+    mkdirSync(layout.root, { recursive: true, mode: 0o700 });
+    atomicWriteJson(layout.runJson, redactValue(run));
+    atomicWriteJson(layout.changedFiles, run.changedFiles);
+    if (run.plan !== undefined) {
+      const plan = redactText(run.plan);
+      atomicWrite(layout.plan, plan.endsWith("\n") ? plan : `${plan}\n`);
+    }
+  }
+
+  load(id: string): RunRecord {
+    const path = runLayout(this.cwd, this.auditDirectory, id).runJson;
+    const run = JSON.parse(readFileSync(path, "utf8")) as RunRecord;
+    if (run.schemaVersion !== 1 || run.cwd !== this.cwd) throw new Error("Unsupported or misplaced run record.");
+    return run;
+  }
+
+  active(): RunRecord | undefined {
+    if (!existsSync(this.activePointer)) return undefined;
+    const id = readFileSync(this.activePointer, "utf8").trim();
+    if (!id) return undefined;
+    try { return this.load(basename(id)); } catch { return undefined; }
+  }
+
+  appendDecision(run: RunRecord, decision: DecisionRecord): void {
+    run.decisions.push(decision);
+    const layout = runLayout(this.cwd, this.auditDirectory, run.id);
+    mkdirSync(dirname(layout.decisions), { recursive: true, mode: 0o700 });
+    appendFileSync(layout.decisions, `${JSON.stringify(redactValue(decision))}\n`, { encoding: "utf8", mode: 0o600 });
+    this.save(run);
+  }
+
+  saveQa(run: RunRecord, report: QaReport): void {
+    atomicWriteJson(runLayout(this.cwd, this.auditDirectory, run.id).qaReport, redactValue(report));
+  }
+
+  saveReview(run: RunRecord, review: ReviewRecord): void {
+    run.reviews.push(review);
+    const path = join(runLayout(this.cwd, this.auditDirectory, run.id).reviews, `${review.stage}-${run.reviews.length}.json`);
+    atomicWriteJson(path, redactValue(review));
+    this.save(run);
+  }
+
+  saveRepair(run: RunRecord, summary: string): void {
+    const path = join(runLayout(this.cwd, this.auditDirectory, run.id).repairs, `${run.repairCount}.md`);
+    const redacted = redactText(summary);
+    atomicWrite(path, redacted.endsWith("\n") ? redacted : `${redacted}\n`);
+  }
+
+  saveFinalReport(run: RunRecord, report: string): void {
+    const redacted = redactText(report);
+    atomicWrite(runLayout(this.cwd, this.auditDirectory, run.id).finalReport, redacted.endsWith("\n") ? redacted : `${redacted}\n`);
+  }
+}

package/extensions/tools/control-tool.ts

@@ -0,0 +1,95 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { QaReport, QaProfile, ReviewStage, RiskLevel } from "../domain/types.js";
+import type { Orchestrator } from "../workflow/orchestrator.js";
+
+const Parameters = Type.Object({
+  action: Type.Union([
+    Type.Literal("start"), Type.Literal("status"), Type.Literal("submit_plan"), Type.Literal("text_decision"),
+    Type.Literal("begin_implementation"), Type.Literal("record_qa"), Type.Literal("record_repair"),
+    Type.Literal("review"), Type.Literal("resume"), Type.Literal("stop"),
+  ]),
+  command: Type.Optional(Type.String()),
+  target: Type.Optional(Type.String()),
+  risk: Type.Optional(Type.Union([Type.Literal("low"), Type.Literal("medium"), Type.Literal("high")])),
+  qaProfile: Type.Optional(Type.Union([Type.Literal("quick"), Type.Literal("standard"), Type.Literal("full")])),
+  plan: Type.Optional(Type.String()),
+  reportJson: Type.Optional(Type.String()),
+  summary: Type.Optional(Type.String()),
+  stage: Type.Optional(Type.Union([Type.Literal("plan"), Type.Literal("initial"), Type.Literal("final")])),
+  decision: Type.Optional(Type.Union([Type.Literal("approve"), Type.Literal("revise"), Type.Literal("proceed"), Type.Literal("stop")])),
+  reason: Type.Optional(Type.String()),
+  warned: Type.Optional(Type.Boolean()),
+  confirmation: Type.Optional(Type.String()),
+});
+
+export function registerControlTool(pi: ExtensionAPI, getOrchestrator: (cwd: string) => Orchestrator): void {
+  pi.registerTool({
+    name: "implannotator_control",
+    label: "Implannotator",
+    description: "Control the approval-gated Implannotator frontend workflow. Start a run, submit a plan, open reviews, record QA/repairs, resume, or stop.",
+    promptSnippet: "Use implannotator_control at every Implannotator phase boundary.",
+    promptGuidelines: [
+      "Never begin file mutation until submit_plan returns an approved phase and begin_implementation succeeds.",
+      "Record complete QA evidence before review; never open browser review during intermediate repairs.",
+    ],
+    parameters: Parameters,
+    executionMode: "sequential",
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      try {
+        const workflow = getOrchestrator(ctx.cwd);
+        let result;
+        switch (params.action) {
+          case "start":
+            result = workflow.start(params.command ?? "craft", params.target, (params.risk ?? "medium") as RiskLevel, (params.qaProfile ?? "standard") as QaProfile);
+            break;
+          case "status": {
+            const run = workflow.active();
+            if (!run) return output("No Implannotator run exists in this project.", undefined);
+            result = { run, message: `Run ${run.id}: ${run.phase}; repairs ${run.repairCount}/3; QA ${run.qaProfile}.` };
+            break;
+          }
+          case "submit_plan":
+            if (!params.plan?.trim()) throw new Error("submit_plan requires plan.");
+            result = await workflow.submitPlan(params.plan, ctx, signal);
+            break;
+          case "text_decision":
+            if (!params.stage || !params.decision) throw new Error("text_decision requires stage and decision.");
+            result = workflow.textDecision(params.stage as ReviewStage, params.decision, params.reason, params.warned ?? false, params.confirmation);
+            break;
+          case "begin_implementation":
+            result = workflow.beginImplementation();
+            break;
+          case "record_qa": {
+            if (!params.reportJson) throw new Error("record_qa requires reportJson.");
+            let report: QaReport;
+            try { report = JSON.parse(params.reportJson) as QaReport; } catch { throw new Error("reportJson must be valid JSON."); }
+            result = workflow.recordQa(report);
+            break;
+          }
+          case "record_repair":
+            if (!params.summary?.trim()) throw new Error("record_repair requires summary.");
+            result = workflow.recordRepair(params.summary);
+            break;
+          case "review":
+            if (params.stage !== "initial" && params.stage !== "final") throw new Error("review stage must be initial or final.");
+            result = await workflow.review(params.stage, ctx, signal);
+            break;
+          case "resume":
+            result = workflow.resume();
+            break;
+          case "stop":
+            result = workflow.stop(params.reason);
+            break;
+        }
+        return output(result.message, result.run);
+      } catch (error) {
+        return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], details: { ok: false }, isError: true };
+      }
+    },
+  });
+}
+
+function output(message: string, run: unknown) {
+  return { content: [{ type: "text" as const, text: message }], details: { ok: true, run } };
+}

package/extensions/workflow/approval-policy.ts

@@ -0,0 +1,21 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { RunRecord } from "../domain/types.js";
+
+export type RejectionChoice = "revise" | "proceed" | "stop";
+
+export async function chooseAfterRejection(ctx: ExtensionContext, run: RunRecord, feedback?: string): Promise<RejectionChoice | "text-required"> {
+  if (!ctx.hasUI) return "text-required";
+  const choice = await ctx.ui.select(
+    "Implannotator review was not approved",
+    ["Revise the plan or implementation", "Proceed anyway", "Stop"],
+  );
+  if (choice === "Proceed anyway") {
+    const confirmed = await ctx.ui.confirm(
+      "Proceed without approval?",
+      `This overrides the mandatory review gate and will be recorded in ${run.id}.${feedback ? `\n\nReview feedback: ${feedback}` : ""}`,
+    );
+    return confirmed ? "proceed" : "revise";
+  }
+  if (choice === "Stop" || !choice) return "stop";
+  return "revise";
+}