fapony 0.1.0

package/src/mcp/tools/plans.ts

@@ -0,0 +1,255 @@
+// src/mcp/tools/plans.ts — plan_list tool
+//
+// Answers "what's pending, what's blocked on what, and what should come
+// next" — not a directory listing (an agent can `ls` on its own for that).
+// Two joins give it that: filesystem plan files × real run history from
+// `runs`/`events`, and the plan's own frontmatter × the plans it points at.
+//
+// The frontmatter is deliberately tiny (4 keys) because everything else is
+// derivable: "never touched" comes from run history, ordering comes from the
+// blocks/blocked_by edges. A plan with no frontmatter at all still lands in a
+// sensible group, so an existing repo gets value before anyone annotates it.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  doneDir,
+  type Event,
+  loadConfig,
+  openDb,
+  planDir,
+  type Run,
+} from "../../db/index.js";
+import { getLastVerdictByPlan, resolveMaxRounds } from "../../stats/index.js";
+import { errorResult, jsonResult, type ToolResult } from "../types.js";
+
+type Front = {
+  kind?: string;
+  status?: string;
+  blocked_by?: string;
+  blocks: string[];
+  superseded_by?: string;
+  spec?: string;
+};
+
+type Entry = {
+  file: string;
+  title: string;
+  runs: number;
+  last: string;
+  escalated: boolean;
+  progress?: string;
+  blocked_by?: string;
+  blocks?: string[];
+  superseded_by?: string;
+  spec?: string;
+};
+
+const EMPTY: Front = { blocks: [] };
+
+/** Frontmatter without a YAML dependency: flat `key: value` lines only. */
+export function parseFront(text: string): Front {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return { blocks: [] };
+  const front: Front = { blocks: [] };
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^\s*([a-z_]+)\s*:\s*(.*?)\s*$/.exec(line);
+    if (!kv) continue;
+    // A trailing `# why` comment is prose for the human, not part of the value.
+    const value = kv[2].replace(/\s+#.*$/, "").trim();
+    if (!value) continue;
+    if (kv[1] === "blocks") {
+      front.blocks = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    } else if (kv[1] === "kind") front.kind = value;
+    else if (kv[1] === "spec") front.spec = value;
+    else if (kv[1] === "status") front.status = value;
+    else if (kv[1] === "blocked_by") front.blocked_by = value;
+    else if (kv[1] === "superseded_by") front.superseded_by = value;
+  }
+  return front;
+}
+
+/**
+ * Checkbox tally of the plan's summary block — the first `##` section after
+ * the title, whatever it is called. Anchoring on position instead of on the
+ * literal "TL;DR" keeps this working for plans written in any language; the
+ * deeper sections are skipped on purpose, because a step list halfway down a
+ * 140KB plan is detail, not status.
+ */
+function progressOf(text: string): string | undefined {
+  const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---/, "");
+  const start = body.search(/^##\s+/m);
+  if (start < 0) return undefined;
+  const rest = body.slice(start);
+  const next = rest.slice(3).search(/^##\s+/m);
+  const block = next < 0 ? rest : rest.slice(0, next + 3);
+  const total = block.match(/^\s*[-*]\s+\[[ xX]\]/gm)?.length ?? 0;
+  if (!total) return undefined;
+  const done = block.match(/^\s*[-*]\s+\[[xX]\]/gm)?.length ?? 0;
+  return `${done}/${total}`;
+}
+
+function read(path: string): {
+  title: string;
+  front: Front;
+  progress?: string;
+} {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return { title: "(unreadable)", front: EMPTY };
+  }
+  const m = /^#\s+(.+)$/m.exec(text);
+  return {
+    title: m ? m[1].trim() : "(no title)",
+    front: parseFront(text),
+    progress: progressOf(text),
+  };
+}
+
+type Groups = {
+  active: Entry[];
+  blocked: Entry[];
+  untouched: Entry[];
+  superseded: Entry[];
+  trackers: Entry[];
+  done: number;
+};
+
+function line(e: Entry): string {
+  const bits: string[] = [e.progress ?? e.last];
+  if (e.blocks?.length) bits.push(`unblocks ${e.blocks.join(", ")}`);
+  if (e.blocked_by) bits.push(`waiting: ${e.blocked_by}`);
+  if (e.superseded_by) bits.push(`replaced by ${e.superseded_by}`);
+  if (e.escalated) bits.push("escalated");
+  const box = e.progress?.match(/^(\d+)\/\1$/) ? "x" : " ";
+  return `- [${box}] ${e.file.replace(/\.md$/, "")} — ${bits.join(" · ")}`;
+}
+
+/**
+ * The hand-maintained master checklist, generated instead. Everything here
+ * already lives in the plans themselves (frontmatter edges + summary
+ * checkboxes), so a rendered view can never drift out of date the way a
+ * MASTER.md does.
+ */
+export function renderPlanList(g: Groups): string {
+  const out: string[] = [];
+  const section = (name: string, list: Entry[]) => {
+    if (!list.length) return;
+    out.push(`## ${name} (${list.length})`);
+    for (const e of list) out.push(line(e));
+    out.push("");
+  };
+  section("active — in order", g.active);
+  section("blocked", g.blocked);
+  section("untouched", g.untouched);
+  section("superseded — archive these", g.superseded);
+  section("trackers — not backlog", g.trackers);
+  out.push(`done: ${g.done} archived`);
+  return out.join("\n");
+}
+
+export function toolPlanList(args: Record<string, unknown>): ToolResult {
+  const worktree = typeof args.worktree === "string" ? args.worktree : "";
+  if (!worktree) return errorResult("worktree is required (absolute path)");
+  const markdown = args.format === "markdown";
+
+  // Path layout belongs to the worktree being listed, not to wherever the MCP
+  // server happened to start — a repo that keeps plans in apps/<app>/plan says
+  // so in its own fapony.config.json. Fall back to the server-global config
+  // (FAPONY_CONFIG or cwd) when the worktree has none.
+  const localConfig = join(worktree, "fapony.config.json");
+  const config = existsSync(localConfig)
+    ? loadConfig(localConfig)
+    : loadConfig();
+  const dir = join(worktree, planDir(config));
+  // Archive lives beside plan/, so a plan keeps its depth (and its relative
+  // links) when it is archived. Repos from before that layout keep theirs:
+  // fall back to plan/done/ rather than silently reporting 0 archived.
+  const configured = join(worktree, doneDir(config));
+  const archive = existsSync(configured) ? configured : join(dir, "done");
+  const empty = {
+    active: [],
+    blocked: [],
+    untouched: [],
+    superseded: [],
+    trackers: [],
+  };
+  if (!existsSync(dir)) {
+    return jsonResult({ ...empty, done: 0, error: `no plan dir at ${dir}` });
+  }
+
+  const pendingFiles = readdirSync(dir).filter((f) => f.endsWith(".md"));
+  const doneCount = existsSync(archive)
+    ? readdirSync(archive).filter((f) => f.endsWith(".md")).length
+    : 0;
+
+  const db = openDb();
+  const runs = db.prepare("SELECT * FROM runs ORDER BY id").all() as Run[];
+  const events = db
+    .prepare("SELECT * FROM events ORDER BY run_id, id")
+    .all() as Event[];
+  const byPlan = getLastVerdictByPlan(runs, events, resolveMaxRounds());
+
+  const active: Entry[] = [];
+  const blocked: Entry[] = [];
+  const untouched: Entry[] = [];
+  const superseded: Entry[] = [];
+  const trackers: Entry[] = [];
+
+  for (const file of pendingFiles) {
+    const { title, front, progress } = read(join(dir, file));
+    // Runs record whatever plan string the caller passed (often a relative
+    // or absolute path) — match by filename suffix, not exact equality.
+    const match = byPlan.find((p) => p.plan.endsWith(file));
+    const entry: Entry = {
+      file,
+      title,
+      runs: match?.runs ?? 0,
+      last: match
+        ? match.lastReasonCode
+          ? `${match.lastVerdict}(${match.lastReasonCode})`
+          : match.lastVerdict
+        : "never attempted",
+      escalated: match?.escalated ?? false,
+    };
+    if (progress) entry.progress = progress;
+    if (front.spec) entry.spec = front.spec;
+    if (front.blocked_by) entry.blocked_by = front.blocked_by;
+    if (front.blocks.length) entry.blocks = front.blocks;
+    if (front.superseded_by) entry.superseded_by = front.superseded_by;
+
+    // A tracker is never a unit of work, so it never "finishes" and must not
+    // sit in the backlog shaming everyone — that's why done/ never moved.
+    if (front.kind === "tracker") trackers.push(entry);
+    else if (front.status === "superseded") superseded.push(entry);
+    else if (front.status === "blocked" || front.blocked_by)
+      blocked.push(entry);
+    else if (front.status === "active" || entry.runs > 0) active.push(entry);
+    else untouched.push(entry);
+  }
+
+  // Ordering falls out of the blocks edges: what unblocks the most goes first.
+  // No priority number to argue with later.
+  active.sort(
+    (a, b) =>
+      (b.blocks?.length ?? 0) - (a.blocks?.length ?? 0) ||
+      a.file.localeCompare(b.file),
+  );
+
+  const groups: Groups = {
+    active,
+    blocked,
+    untouched,
+    superseded,
+    trackers,
+    done: doneCount,
+  };
+  return markdown
+    ? { content: [{ type: "text", text: renderPlanList(groups) }] }
+    : jsonResult(groups);
+}

package/src/mcp/tools/report.ts

@@ -0,0 +1,285 @@
+// src/mcp/tools/report.ts — verification_report MCP tool
+//
+// High-level composition: collects facts + handoff check + evidence +
+// run metrics + verdict into a single VerificationReport.
+// Calls existing primitives — no duplicate parser/conformance logic.
+
+import { blastRadiusForWorktree } from "../../analyze.js";
+import { getEvents, getRun, openDb } from "../../db/index.js";
+import { loadConfig } from "../../db/load.js";
+import { parseGateEventData } from "../../parse.js";
+import { collectEvidence } from "../evidence.js";
+import type { CheckResult, VerificationReport } from "../primitives.js";
+import {
+  computeEvidenceSummary,
+  getServerSha,
+  renderReportText,
+} from "../primitives.js";
+import { errorResult, jsonResult, type ToolResult } from "../types.js";
+import { resolveWorktreeArg } from "../worktree.js";
+import { extractMultiField, toolHandoffCheck } from "./check.js";
+import { toolHandoffCollect } from "./collect.js";
+
+// --- Handoff text reader ---
+
+function readHandoffFromEvents(runId: number): string | null {
+  const db = openDb();
+  try {
+    const events = getEvents(db, runId);
+    for (let i = events.length - 1; i >= 0; i--) {
+      if (events[i].kind !== "handoff") continue;
+      try {
+        const parsed = JSON.parse(events[i].data ?? "") as {
+          missing?: boolean;
+        };
+        if (!parsed.missing && events[i].data) {
+          // Reconstruct handoff text from the parsed data. The executor
+          // template mandates uncertain:/not_done: lines always, so empty
+          // arrays rebuild as "none" — faithful to what the agent reported.
+          const dataStr = events[i].data as string;
+          const d = JSON.parse(dataStr) as Record<string, unknown>;
+          const lines = ["## HANDOFF"];
+          if (d.claimed) lines.push(`claimed: ${d.claimed}`);
+          if (d.commits)
+            lines.push(
+              `commits: ${Array.isArray(d.commits) ? d.commits.join(" ") : d.commits}`,
+            );
+          if (d.checks) lines.push(`checks: ${d.checks}`);
+          lines.push(
+            `uncertain: ${d.uncertain && Array.isArray(d.uncertain) && d.uncertain.length ? d.uncertain.join("\n") : "none"}`,
+          );
+          lines.push(
+            `not_done: ${d.not_done && Array.isArray(d.not_done) && d.not_done.length ? d.not_done.join("\n") : "none"}`,
+          );
+          return lines.join("\n");
+        }
+      } catch {
+        // skip unparseable events
+      }
+      break;
+    }
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
+// --- Tool implementation ---
+
+export function toolVerificationReport(
+  args: Record<string, unknown>,
+): ToolResult {
+  const {
+    run_id,
+    worktree,
+    base_sha,
+    head_sha,
+    handoff: handoffArg,
+    evidence_commands,
+    format,
+  } = args;
+
+  // --- Resolve worktree + run ---
+  let resolvedWorktree: string | null = null;
+  let resolvedRunId: number | null = null;
+
+  if (typeof run_id === "number" && Number.isInteger(run_id)) {
+    const db = openDb();
+    try {
+      const run = getRun(db, run_id);
+      if (!run) {
+        return errorResult(`run ${run_id} not found`);
+      }
+      resolvedRunId = run_id;
+      // run.worktree may be a key (e.g. "falsify"), an absolute path, or
+      // the "mcp-external" sentinel — resolve via shared helper so git
+      // commands run in the right directory.
+      try {
+        resolvedWorktree = resolveWorktreeArg(run.worktree);
+      } catch (e) {
+        return errorResult((e as Error).message);
+      }
+    } finally {
+      db.close();
+    }
+  } else if (typeof worktree === "string") {
+    resolvedWorktree = worktree;
+  } else {
+    return errorResult("provide run_id or worktree");
+  }
+
+  // --- Git facts ---
+  let facts: VerificationReport["facts"] = {
+    files_changed: 0,
+    lines_changed: 0,
+    insertions: 0,
+    deletions: 0,
+    commits: [],
+    branch: "",
+    files: [],
+    git_error: null,
+  };
+
+  if (resolvedWorktree) {
+    const collectResult = toolHandoffCollect({
+      worktree: resolvedWorktree,
+      ...(typeof base_sha === "string" ? { base_sha } : {}),
+      ...(typeof head_sha === "string" ? { head_sha } : {}),
+    });
+    const collectData = JSON.parse(collectResult.content[0].text) as {
+      facts?: VerificationReport["facts"];
+      error?: unknown;
+    };
+    if (collectData.facts) {
+      facts = {
+        files_changed: collectData.facts.files_changed ?? 0,
+        lines_changed: collectData.facts.lines_changed ?? 0,
+        insertions: collectData.facts.insertions ?? 0,
+        deletions: collectData.facts.deletions ?? 0,
+        commits: collectData.facts.commits ?? [],
+        branch: collectData.facts.branch ?? "",
+        files: Array.isArray(collectData.facts.files)
+          ? collectData.facts.files.filter(
+              (f): f is string => typeof f === "string",
+            )
+          : [],
+        git_error: collectData.facts.git_error ?? null,
+      };
+    }
+    // Don't swallow collection failures: a refused/errored collect leaves
+    // zeroed facts, so surface the error instead of reporting "0 files".
+    if (
+      typeof collectData.error === "string" &&
+      collectData.error &&
+      !facts.git_error
+    ) {
+      facts = { ...facts, git_error: collectData.error };
+    }
+  }
+
+  // --- Handoff checks ---
+  let handoffChecks: VerificationReport["handoff_checks"] = null;
+  const handoffText =
+    typeof handoffArg === "string"
+      ? handoffArg
+      : resolvedRunId
+        ? readHandoffFromEvents(resolvedRunId)
+        : null;
+
+  if (handoffText) {
+    // Forward caller-supplied uncertain/not_done/checks when present;
+    // otherwise a field present in the agent's text counts as reported
+    // (content is always read from the text by toolHandoffCheck). This keeps
+    // the composed tool exactly as strict as handoff_check on the same text —
+    // no hardcoded "none" vouching for fields the caller never supplied.
+    const checkArgs: Record<string, unknown> = { handoff: handoffText, facts };
+    for (const field of ["uncertain", "not_done", "checks"] as const) {
+      const fromCaller = args[field];
+      if (typeof fromCaller === "string") {
+        checkArgs[field] = fromCaller;
+      } else if (new RegExp(`^\\s*${field}:`, "im").test(handoffText)) {
+        checkArgs[field] = extractMultiField(handoffText, field)[0] ?? "";
+      }
+    }
+    const checkResult = toolHandoffCheck(checkArgs);
+    const checkData = JSON.parse(checkResult.content[0].text) as {
+      checks?: unknown[];
+      summary?: {
+        total: number;
+        passed: number;
+        failed: number;
+        needs_human_review: boolean;
+      };
+    };
+    if (checkData.checks && checkData.summary) {
+      handoffChecks = {
+        checks: checkData.checks as CheckResult[],
+        summary: checkData.summary,
+      };
+    }
+  }
+
+  // --- Evidence ---
+  const agentCmds = Array.isArray(evidence_commands)
+    ? evidence_commands.filter((c): c is string => typeof c === "string")
+    : undefined;
+  const evidence = resolvedWorktree
+    ? collectEvidence({
+        worktree: resolvedWorktree,
+        agentCommands: agentCmds,
+        files: facts.files ?? [],
+        config: loadConfig(),
+      })
+    : [];
+  const evidence_summary = computeEvidenceSummary(evidence);
+
+  // --- Verdict ---
+  // Gate events store JSON ({verdict, note, round}), so read the JSON
+  // shape directly via parseGateEventData.
+  let verdict: VerificationReport["verdict"] = null;
+  if (resolvedRunId) {
+    const db = openDb();
+    try {
+      const events = getEvents(db, resolvedRunId);
+      for (let i = events.length - 1; i >= 0; i--) {
+        if (events[i].kind !== "gate") continue;
+        const parsed = parseGateEventData(events[i].data);
+        if (parsed) {
+          verdict = { grade: parsed.verdict, note: parsed.note };
+        }
+        break;
+      }
+    } finally {
+      db.close();
+    }
+  }
+
+  // --- Duration + rounds ---
+  let duration_ms: number | null = null;
+  let rounds = 0;
+  if (resolvedRunId) {
+    const db = openDb();
+    try {
+      const run = getRun(db, resolvedRunId);
+      if (run) {
+        rounds = run.round;
+        const t0 = new Date(`${run.created_at.replace(" ", "T")}Z`).getTime();
+        const t1 = new Date(`${run.updated_at.replace(" ", "T")}Z`).getTime();
+        duration_ms = t1 - t0;
+      }
+    } finally {
+      db.close();
+    }
+  }
+
+  // No standalone logging: a report is a read, not a unit of work. A
+  // worktree-only call (no run_id) leaves runs/events untouched — opening a
+  // row here left orphan runs stuck at running forever and inflated
+  // runs.total / byWorktree / project_health_context counts.
+
+  // --- Assemble report ---
+  const report: VerificationReport = {
+    facts,
+    handoff_checks: handoffChecks,
+    blast_radius: resolvedWorktree
+      ? blastRadiusForWorktree(resolvedWorktree, facts.files ?? [])
+      : null,
+    evidence,
+    evidence_summary,
+    verdict,
+    duration_ms,
+    rounds,
+    meta: {
+      generated_at: new Date().toISOString(),
+      source: "fapony_mcp",
+      run_id: resolvedRunId,
+      server_sha: getServerSha(),
+    },
+  };
+
+  // --- Output ---
+  if (format === "json") {
+    return jsonResult(report);
+  }
+  return { content: [{ type: "text", text: renderReportText(report) }] };
+}

package/src/mcp/tools/stats.ts

@@ -0,0 +1,96 @@
+// src/mcp/tools/stats.ts — fapony_stats tool
+
+import type { Run } from "../../db/index.js";
+import { openDb } from "../../db/index.js";
+import {
+  currentWorktree,
+  formatStatsText,
+  formatVerdictText,
+  getPlanBreakdown,
+  getStatsData,
+  type PlanBreakdown,
+  resolveMaxRounds,
+} from "../../stats/index.js";
+import { errorResult, jsonResult, type ToolResult } from "../types.js";
+
+export function toolFaponyStats(args: Record<string, unknown>): ToolResult {
+  // Same default as `fapony stats` (src/stats/cli.ts): the project you are
+  // standing in. A bare MCP call used to go global, so an agent asking about
+  // one repo got every repo averaged together — wrong answer AND the biggest
+  // payload the tool can return. `all:true` is the opt-in, mirroring `--all`.
+  const worktree =
+    typeof args.worktree === "string" && args.worktree
+      ? args.worktree
+      : args.all === true
+        ? undefined
+        : (currentWorktree() ?? undefined);
+  const data = getStatsData(worktree);
+
+  // group_by: top-N slice from real events (PLAN-project-health-context §2).
+  // Worktree-scoped when `worktree` is given, global otherwise.
+  const groupBy = args.group_by;
+  if (groupBy === "reason_code" || groupBy === "plan" || groupBy === "file") {
+    const top =
+      typeof args.top === "number" && args.top > 0 ? Math.floor(args.top) : 10;
+    if (groupBy === "file") {
+      const rows = (
+        worktree
+          ? data.byFile.filter((f) => f.worktree === worktree)
+          : data.byFile
+      ).slice(0, top);
+      return jsonResult({
+        group_by: groupBy,
+        worktree: worktree ?? null,
+        rows,
+      });
+    }
+    if (groupBy === "reason_code") {
+      const rows = (
+        worktree
+          ? data.byReasonCode.filter((r) => r.worktree === worktree)
+          : data.byReasonCode
+      ).slice(0, top);
+      return jsonResult({
+        group_by: groupBy,
+        worktree: worktree ?? null,
+        rows,
+      });
+    }
+    // plan grouping: recompute from scoped runs when worktree is given,
+    // so counts reflect only runs in that worktree (not global counts).
+    let rows: PlanBreakdown[];
+    if (worktree) {
+      const db = openDb();
+      try {
+        const scopedRuns = db
+          .prepare("SELECT * FROM runs WHERE worktree = ? ORDER BY id")
+          .all(worktree) as Run[];
+        rows = getPlanBreakdown(scopedRuns, resolveMaxRounds()).slice(0, top);
+      } finally {
+        db.close();
+      }
+    } else {
+      rows = data.byPlan.slice(0, top);
+    }
+    return jsonResult({ group_by: groupBy, worktree: worktree ?? null, rows });
+  }
+  if (typeof groupBy !== "undefined") {
+    return errorResult(`group_by must be one of: reason_code, plan, file`);
+  }
+
+  // mode: "verdict" → Pareto frontier of quality vs tokens/pass
+  if (args.mode === "verdict") {
+    const regime = typeof args.regime === "string" ? args.regime : undefined;
+    return {
+      content: [{ type: "text", text: formatVerdictText(data, regime) }],
+    };
+  }
+
+  // json:true → StatsData ล้วน (SPEC-verdict-stats) — ห้ามแทรก text อื่น
+  if (args.json === true) {
+    return jsonResult(data);
+  }
+
+  // json:false → text เดียวกับ `fapony stats` — same formatter, raw (not JSON-wrapped)
+  return { content: [{ type: "text", text: formatStatsText(data) }] };
+}