fapony 0.1.3 → 0.2.1

package/src/mcp/tools/plans.ts

@@ -1,255 +0,0 @@
-// 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/stats.ts

@@ -1,96 +0,0 @@
-// 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 → pure StatsData (SPEC-verdict-stats) — no other text may be inserted
-  if (args.json === true) {
-    return jsonResult(data);
-  }
-
-  // json:false → the same text as `fapony stats` — same formatter, raw (not JSON-wrapped)
-  return { content: [{ type: "text", text: formatStatsText(data) }] };
-}

package/templates/mem/commands/read.ts

@@ -1,194 +0,0 @@
-// commands/read.ts — read-only commands: now (default), done, stale, find, kickoff
-
-import { doneLines, fmtClose, fmtRow, printOpenRows } from "../render.js";
-import { claimsOf, openRows, staleReport } from "../selectors.js";
-import type { CloseRow, WorkRow } from "../store.js";
-import { app, memCmd, rows } from "../store.js";
-import { planSweepCmd, shippedNotMoved } from "./plan.js";
-import { THRESHOLD } from "./rotate.js";
-
-const rotateLine = (n: number) =>
-  n >= THRESHOLD
-    ? `\n## 🗜 log ${n} rows (≥ ${THRESHOLD}) — run: ${memCmd} rotate --apply`
-    : "";
-
-const planSweepLine = () => {
-  const pending = shippedNotMoved();
-  return pending.length
-    ? `\n## 📦 shipped but not archived into done/ (${pending.length})\n` +
-        pending.map((n) => `- ${n}`).join("\n") +
-        `\n(move: ${planSweepCmd} <file.md> --apply)`
-    : "";
-};
-
-export const cmdNow = () => {
-  // mem now (default) — next+bug+hold. decision/note is not pending work → search with find instead
-  const all = rows();
-  console.log(`# ${app} — ${all.length} entries`);
-  printOpenRows(all, { showHold: true });
-  const decisionN = openRows(all).filter((r) => r.kind === "decision").length;
-  const noteN = openRows(all).filter((r) => r.kind === "note").length;
-  console.log(
-    `\n## decision ${decisionN} · note ${noteN} — search: ${memCmd} find <word>`,
-  );
-  const stale = staleReport(all);
-  if (stale.length)
-    console.log(
-      `\n## ⚠ stale (${stale.length})\n` +
-        stale.map((l) => `- ${l}`).join("\n"),
-    );
-  const sweep = planSweepLine();
-  if (sweep) console.log(sweep);
-  const rotate = rotateLine(all.length);
-  if (rotate) console.log(rotate);
-};
-
-export const cmdDone = () => {
-  const all = rows();
-  for (const l of doneLines(all)) console.log(l);
-};
-
-export const cmdStale = () => {
-  for (const l of staleReport(rows())) console.log(l);
-};
-
-export const cmdFind = (a: string[]) => {
-  // mem find <word> — grep text/spec case-insensitively, newest first, capped at 20 rows
-  const q = a.join(" ").toLowerCase();
-  if (!q) {
-    console.error(`usage: ${memCmd} find <word>`);
-    process.exit(1);
-  }
-  const hits = rows()
-    .filter(
-      (r): r is WorkRow =>
-        r.kind !== "close" &&
-        r.kind !== "synced" &&
-        r.kind !== "claim" &&
-        r.kind !== "release",
-    )
-    .filter(
-      (r) =>
-        r.text.toLowerCase().includes(q) ||
-        (r.spec ?? "").toLowerCase().includes(q),
-    )
-    .slice(-20);
-  for (const r of hits)
-    console.log(
-      `- [${r.id}] ${r.ts.slice(0, 10)} ${r.kind} ${r.text}${r.spec ? ` → ${r.spec}` : ""}`,
-    );
-  if (!hits.length) console.log("(no matches)");
-};
-
-export const cmdKickoff = (a: string[]) => {
-  // mem kickoff [id|spec.md]
-  const all = rows();
-  const arg = a[0] ?? "";
-
-  if (!arg) {
-    // no args = now + a "recent" section = the last 10 closes
-    console.log(`# ${app} — ${all.length} entries`);
-    printOpenRows(all, { showHold: true });
-    console.log(`\n## recent\n${doneLines(all, 10).join("\n")}`);
-    const stale = staleReport(all);
-    if (stale.length)
-      console.log(
-        `\n## ⚠ stale (${stale.length})\n` +
-          stale.map((l) => `- ${l}`).join("\n"),
-      );
-    const sweep = planSweepLine();
-    if (sweep) console.log(sweep);
-    const rotate = rotateLine(all.length);
-    if (rotate) console.log(rotate);
-  } else if (arg.endsWith(".md")) {
-    // spec.md = a brief for that spec
-    const workAll = all.filter((r): r is WorkRow => "id" in r);
-    const byId = new Map(workAll.map((r) => [r.id, r] as const));
-    const open = openRows(all);
-    const specRows = open.filter((r) => r.spec === arg);
-    const specDecisions = all
-      .filter((r): r is WorkRow => r.kind === "decision" && r.spec === arg)
-      .slice(-5);
-    const specCloses = all
-      .filter((r): r is CloseRow => r.kind === "close")
-      .filter((r) => byId.get(r.ref)?.spec === arg)
-      .slice(-3);
-
-    console.log(`# ${arg} — ${specRows.length} open rows`);
-    if (specRows.length) {
-      console.log(`\n## open\n${specRows.map((r) => fmtRow(r)).join("\n")}`);
-    }
-    if (specDecisions.length) {
-      console.log(
-        `\n## decisions\n` +
-          specDecisions
-            .map((r) => `- ${r.ts.slice(0, 10)} ${r.text}`)
-            .join("\n"),
-      );
-    }
-    if (specCloses.length) {
-      console.log(
-        `\n## closes\n${specCloses.map((c) => fmtClose(c, byId)).join("\n")}`,
-      );
-    }
-    if (!specRows.length && !specDecisions.length && !specCloses.length) {
-      console.log("(no entries for this spec)");
-    }
-  } else {
-    // id = a brief for that task
-    const workAll = all.filter((r): r is WorkRow => "id" in r);
-    const byId = new Map(workAll.map((r) => [r.id, r] as const));
-    const target = byId.get(arg);
-    if (!target) {
-      console.error(`no id "${arg}" in the log`);
-      process.exit(1);
-    }
-    const claims = claimsOf(all);
-    const claimInfo = claims.has(arg)
-      ? `\nClaimed by: ${claims.get(arg)?.agent} (${claims.get(arg)?.ts.slice(0, 10)})`
-      : "";
-
-    const spec = target.spec;
-    const open = spec
-      ? openRows(all).filter((r) => r.spec === spec && r.id !== arg)
-      : [];
-    const specDecisions = spec
-      ? all
-          .filter((r): r is WorkRow => r.kind === "decision" && r.spec === spec)
-          .slice(-5)
-      : [];
-    const specNotes = spec
-      ? all
-          .filter((r): r is WorkRow => r.kind === "note" && r.spec === spec)
-          .slice(-5)
-      : [];
-    const specCloses = spec
-      ? all
-          .filter((r): r is CloseRow => r.kind === "close")
-          .filter((r) => byId.get(r.ref)?.spec === spec)
-          .slice(-3)
-      : [];
-
-    console.log(
-      `# [${target.id}] ${target.kind} — ${target.text}${target.spec ? ` → ${target.spec}` : ""}${claimInfo}`,
-    );
-    if (open.length) {
-      console.log(
-        `\n## open (same spec)\n` +
-          open.map((r) => fmtRow(r, claims)).join("\n"),
-      );
-    }
-    if (specDecisions.length || specNotes.length) {
-      console.log(`\n## decisions & notes (spec)\n`);
-      for (const r of [...specDecisions, ...specNotes]) {
-        console.log(`- ${r.ts.slice(0, 10)} ${r.kind} ${r.text}`);
-      }
-    }
-    if (specCloses.length) {
-      console.log(
-        `\n## closes (spec)\n` +
-          specCloses.map((c) => fmtClose(c, byId)).join("\n"),
-      );
-    }
-  }
-};