fapony 0.1.0

package/src/mcp/tools/collect.ts

@@ -0,0 +1,157 @@
+// src/mcp/tools/collect.ts — handoff_collect tool
+
+import { execSync } from "node:child_process";
+import { isTestFile } from "../../analyze.js";
+import { errorResult, jsonResult, type ToolResult } from "../types.js";
+
+// --- Git helper ---
+
+function execGitSafe(
+  cmd: string,
+  cwd: string,
+): { ok: boolean; output: string; error?: string } {
+  try {
+    const output = execSync(cmd, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 15_000,
+    });
+    return { ok: true, output: output.trim() };
+  } catch (e: unknown) {
+    const msg =
+      e && typeof e === "object" && ("stderr" in e || "message" in e)
+        ? String(
+            (e as { stderr?: string; message?: string }).stderr ??
+              (e as { message?: string }).message ??
+              "unknown",
+          )
+        : "unknown";
+    return { ok: false, output: "", error: msg.trim() };
+  }
+}
+
+// ahead/behind vs the default remote branch, as of the last fetch — no network here.
+// ponytail: origin/main|master only; add upstream/`origin/HEAD` lookup if a repo names it otherwise.
+function aheadBehind(
+  worktree: string,
+): { ahead: number; behind: number; ref: string } | null {
+  for (const ref of ["origin/main", "origin/master"]) {
+    const r = execGitSafe(
+      `git rev-list --left-right --count ${ref}...HEAD`,
+      worktree,
+    );
+    if (!r.ok) continue;
+    const [behind, ahead] = r.output.split(/\s+/).map((n) => parseInt(n, 10));
+    if (Number.isNaN(behind) || Number.isNaN(ahead)) continue;
+    return { ahead, behind, ref };
+  }
+  return null;
+}
+
+// --- Tool implementation ---
+
+export function toolHandoffCollect(args: Record<string, unknown>): ToolResult {
+  const { base_sha, head_sha, worktree } = args;
+
+  if (typeof worktree !== "string") {
+    return errorResult("worktree is required as a string");
+  }
+
+  // Auto-detect commit range if not provided
+  let resolvedBaseSha = base_sha;
+  let resolvedHeadSha = head_sha;
+
+  if (typeof resolvedBaseSha !== "string") {
+    const detected = execGitSafe("git rev-parse HEAD~1", worktree);
+    if (!detected.ok) {
+      return errorResult(
+        `cannot auto-detect base_sha: ${detected.error}. Provide base_sha explicitly.`,
+      );
+    }
+    resolvedBaseSha = detected.output;
+  }
+
+  if (typeof resolvedHeadSha !== "string") {
+    const detected = execGitSafe("git rev-parse HEAD", worktree);
+    if (!detected.ok) {
+      return errorResult(
+        `cannot auto-detect head_sha: ${detected.error}. Provide head_sha explicitly.`,
+      );
+    }
+    resolvedHeadSha = detected.output;
+  }
+
+  // Diff stat
+  let files_changed = 0;
+  let lines_changed = 0;
+  let insertions = 0;
+  let deletions = 0;
+  let gitError: string | undefined;
+
+  const diffResult = execGitSafe(
+    `git diff --stat ${resolvedBaseSha}..${resolvedHeadSha} -- .`,
+    worktree,
+  );
+
+  if (diffResult.ok) {
+    const fileMatch = diffResult.output.match(/(\d+) files? changed/);
+    files_changed = fileMatch ? parseInt(fileMatch[1], 10) : 0;
+    const insMatch = diffResult.output.match(/(\d+) insertions?\(\+\)/);
+    const delMatch = diffResult.output.match(/(\d+) deletions?\(-\)/);
+    insertions = insMatch ? parseInt(insMatch[1], 10) : 0;
+    deletions = delMatch ? parseInt(delMatch[1], 10) : 0;
+    lines_changed = insertions + deletions;
+  } else {
+    gitError = `git diff failed: ${diffResult.error}`;
+  }
+
+  // Commits
+  const logResult = execGitSafe(
+    `git log --oneline ${resolvedBaseSha}..${resolvedHeadSha}`,
+    worktree,
+  );
+  const commits = logResult.ok
+    ? logResult.output
+        .split("\n")
+        .filter(Boolean)
+        .map((l) => l.split(" ")[0])
+    : [];
+
+  // Branch
+  const branchResult = execGitSafe("git branch --show-current", worktree);
+  const branch = branchResult.ok ? branchResult.output : "";
+
+  // Check file types
+  const nameResult = execGitSafe(
+    `git diff --name-only ${resolvedBaseSha}..${resolvedHeadSha}`,
+    worktree,
+  );
+  const names = nameResult.ok
+    ? nameResult.output.split("\n").filter(Boolean)
+    : [];
+  const has_test_changes = names.some((n) => isTestFile(n));
+  const has_docs_changes = names.some((n) => /\.md$/i.test(n));
+
+  return jsonResult({
+    facts: {
+      files_changed,
+      lines_changed,
+      insertions,
+      deletions,
+      commits,
+      branch,
+      files: names,
+      ahead_behind: aheadBehind(worktree),
+      git_error: gitError ?? null,
+    },
+    checks: {
+      has_test_changes,
+      has_docs_changes,
+    },
+    provenance: {
+      verified: true,
+      source: "git_cli",
+    },
+  });
+}

package/src/mcp/tools/context.ts

@@ -0,0 +1,66 @@
+// src/mcp/tools/context.ts — project_health_context tool
+//
+// Single call, any caller: returns the paste-ready "known patterns" block built
+// from real run history, keyed by files[] (no raw dump, ~15 lines max). Not a
+// pre-edit reflex — most files have no history (see CLAUDE.md rule 8); it earns
+// its call on a file that does. `plan-with-pony` is one caller, not the only one.
+//
+// It also surfaces project decisions from the mem log — that read is the only
+// I/O here; `buildProjectHealthContext` stays pure and just renders.
+
+import { blastRadiusForWorktree } from "../../analyze.js";
+import {
+  buildProjectHealthContext,
+  HUB_DEPENDENTS_MIN,
+  type HubEntry,
+} from "../../context/index.js";
+import { readRecentMemDecisions } from "../../memory.js";
+import { getStatsData } from "../../stats/index.js";
+import type { ToolResult } from "../types.js";
+
+export function toolProjectHealthContext(
+  args: Record<string, unknown>,
+): ToolResult {
+  const worktree =
+    typeof args.worktree === "string" && args.worktree
+      ? args.worktree
+      : undefined;
+  const files =
+    Array.isArray(args.files) && args.files.length > 0
+      ? args.files.filter(
+          (f): f is string => typeof f === "string" && f.length > 0,
+        )
+      : undefined;
+
+  // No worktree (or no log) → no decisions line, block still returns.
+  const memDecisions = worktree
+    ? readRecentMemDecisions(worktree, 3, files).map((r) => ({
+        text: r.text,
+        spec: r.spec,
+      }))
+    : [];
+
+  // Hub detection needs both worktree (graph root) and files[] (what to map).
+  // Same live-graph cost handoff_check already pays; null/unreadable graph →
+  // no hub line, never a throw (PLAN-hub-signal §3).
+  const hubs: HubEntry[] =
+    worktree && files
+      ? Object.entries(blastRadiusForWorktree(worktree, files) ?? {})
+          .filter(([, b]) => b.dependents >= HUB_DEPENDENTS_MIN)
+          .sort((a, b) => b[1].dependents - a[1].dependents)
+          .map(([file, b]) => ({
+            file,
+            dependents: b.dependents,
+            tested: b.tested,
+            transitive: b.transitive,
+          }))
+      : [];
+
+  const block = buildProjectHealthContext(getStatsData(), {
+    worktree,
+    files,
+    memDecisions,
+    hubs,
+  });
+  return { content: [{ type: "text", text: block }] };
+}

package/src/mcp/tools/index.ts

@@ -0,0 +1,309 @@
+// src/mcp/tools/index.ts — barrel + TOOLS array
+
+import { VERDICT_GRADES } from "../../parse.js";
+import { REASON_CODES, REGIME_CODES } from "../types.js";
+
+export { toolProjectHealthContext } from "./context.js";
+export { toolMemFind } from "./mem.js";
+export { toolPlanList } from "./plans.js";
+export { toolFaponyStats } from "./stats.js";
+export { toolPassiveUsage } from "./usage.js";
+export { toolVerdictSubmit } from "./verdict.js";
+
+// --- Tool definitions ---
+
+export const TOOLS = [
+  {
+    name: "verdict_submit",
+    description:
+      "Grade a finished unit of work. " +
+      "WHEN: every unit that ends, including work that went right the first " +
+      "time — this is a grade on the work, not a confession, and a model's " +
+      "record is only worth the number of graded units behind it. " +
+      "If a first attempt was wrong, submit 'fail' the moment you realize it, " +
+      "then a pass-family verdict once the fix is verified. " +
+      "Never leave a run open — one stuck at running/fixing " +
+      "absorbs later unrelated verdicts for that worktree. " +
+      "Without run_id, binds to the latest still-open run for the same " +
+      "worktree+plan (round keeps counting toward review.maxRounds); " +
+      "creates a new run entry only when none is open.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        run_id: {
+          type: "number",
+          description:
+            "Optional run ID from fapony. If omitted, a new run is created automatically.",
+        },
+        verdict: {
+          type: "string",
+          enum: [...VERDICT_GRADES],
+          description: "Verdict grade",
+        },
+        reason_code: {
+          type: "string",
+          enum: [...REASON_CODES],
+          description:
+            "Standardized failure reason code. Use 'none' for clean passes (not 'other').",
+        },
+        regime: {
+          type: "string",
+          enum: [...REGIME_CODES],
+          description:
+            "Task shape: code=new feature/refactor, fix=debugging an existing defect, " +
+            "review=reviewing someone else's work/diff, plan=producing a plan or spec, " +
+            "inquiry=asking questions without editing files, test=writing or editing tests as primary work",
+        },
+        note: {
+          type: "string",
+          description: "Optional note (required when reason_code = 'other')",
+        },
+        worktree: {
+          type: "string",
+          description:
+            "Absolute path of the repo/worktree (git rev-parse --show-toplevel), used when run_id is omitted. " +
+            "Send it: every fapony query scopes by absolute path, so a bare repo name lands in a bucket no " +
+            'query reads, and omitting it files the verdict under "mcp-external" instead of the project. ' +
+            "Neither case errors.",
+        },
+        plan: {
+          type: "string",
+          description:
+            "Optional plan file path for a new run (used only when run_id is omitted)",
+        },
+        session_id: {
+          type: "string",
+          description:
+            "The client session id — Claude Code/Codex: the transcript .jsonl path; " +
+            "OpenCode/ZCode: the session id. It is what attributes this verdict to a model; " +
+            "without it fapony infers the model from whichever session is running, which is a " +
+            "guess. Send it whenever the client exposes it. Cannot find it → omit, never invent one.",
+        },
+        files: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Repo-relative paths of the files this work unit touched. Technically " +
+            "optional, but always send them: this is the only input to per-file " +
+            "risk history — a verdict with no files[] teaches the next session " +
+            "nothing about where the risk was.",
+        },
+      },
+      required: ["verdict", "reason_code", "regime"],
+    },
+  },
+  {
+    name: "fapony_stats",
+    description:
+      "Query accumulated run statistics: pass/stall rates, quality scores, " +
+      "breakdown by model/grade/worktree. Returns StatsData shape. " +
+      "With mode='verdict', returns the model to pay for each regime — the " +
+      "Pareto frontier of quality vs tokens/pass, one line per regime (or the " +
+      "full frontier/dominated/candidates breakdown for one regime). This is " +
+      "the answer the ledger exists to give; call it before assuming which " +
+      "model fits a task. With group_by='reason_code'|'plan'|'file', returns " +
+      "top-N rows for that grouping (recurring failure signatures / per-plan " +
+      "totals / per-file gate-vs-fail counts) instead of the full shape.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        mode: {
+          type: "string",
+          enum: ["verdict"],
+          description:
+            "'verdict' ranks models by quality vs tokens/pass instead of listing " +
+            "raw counts — the leaderboard, not the ledger dump. Models below " +
+            "n=5 are shown separately and never picked as the answer; a model " +
+            "tried once at top quality does not get to define the frontier.",
+        },
+        regime: {
+          type: "string",
+          enum: ["code", "fix", "review", "plan", "inquiry", "test"],
+          description:
+            "With mode='verdict', narrows to one regime's full frontier " +
+            "(dominated models + candidates too). Omitted = one summary line " +
+            "per regime.",
+        },
+        json: {
+          type: "boolean",
+          description:
+            "If true, return raw JSON StatsData. If false (default), return human-readable text. Ignored when mode='verdict' (always text).",
+        },
+        group_by: {
+          type: "string",
+          enum: ["reason_code", "plan", "file"],
+          description:
+            "Optional grouping: top-N reason_code counts, per-plan totals, or " +
+            "per-file risk (graded touches vs fails) from real gate events.",
+        },
+        top: {
+          type: "number",
+          description: "Max rows returned with group_by (default 10).",
+        },
+        worktree: {
+          type: "string",
+          description:
+            "Scope a query (verdict mode, group_by, or the default view) to one worktree path (absolute). Defaults to the repo the server is running in.",
+        },
+        all: {
+          type: "boolean",
+          description:
+            "Ignore the default worktree scope and report every project at once. Off by default: averaging several projects reads as 'in this project' while being no such thing, and it is the largest payload this tool returns.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "fapony_usage",
+    description:
+      "Query passive usage across every coding client on this machine — " +
+      "OpenCode, Claude Code, Codex, and ZCode — on one ruler: token counts, " +
+      "cost, and breakdown by model. No client's own session log can see " +
+      "another's, so this is the only way to compare them. Filter by " +
+      "worktree and time range.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        worktree: {
+          type: "string",
+          description: "Filter by worktree path (absolute)",
+        },
+        since: {
+          type: "number",
+          description:
+            "Unix timestamp — include sessions created at or after this time",
+        },
+        until: {
+          type: "number",
+          description:
+            "Unix timestamp — include sessions created at or before this time",
+        },
+        detail: {
+          type: "boolean",
+          description:
+            "If true, include tool-call breakdown + step counts per session " +
+            "(activity signal, not quality). Default false keeps output compact.",
+        },
+        json: {
+          type: "boolean",
+          description:
+            "If true, return raw JSON PassiveUsageResult. If false (default), return human-readable text.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "project_health_context",
+    description:
+      "Known-patterns block for files[]: recurring fail reasons, escalated runs, " +
+      "and round-1-pass shapes from real run history. Worth a call when you are " +
+      "about to touch a file that has history — a long-lived file, one you have " +
+      "not seen before, or one a previous attempt already failed on. The unit is " +
+      "touched files, not a plan; a bug fix with no plan file still qualifies. " +
+      "Returns nothing when there is no history (most files); short plain-text " +
+      "block, framed as watch-fors, not constraints.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        worktree: {
+          type: "string",
+          description:
+            "Scope to one worktree path (absolute). Global across worktrees when omitted.",
+        },
+        files: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Filter findings to only those related to these files. " +
+            "Matches against stored gate event files and note text.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "mem_find",
+    description:
+      "Search the project's mem log (.fapony/.memory/log*.jsonl — decisions, " +
+      "bugs, notes, and bookkeeping kinds alike; NO default kind filter). " +
+      "Read-only. Answer 'what was ever decided about this file?' in one call " +
+      "BEFORE editing: pass files[] (repo-relative) to match rows mentioning " +
+      "them. mem never stored files[], so match is substring over text/spec/ref " +
+      "— a row that never names the file cannot be found (limit of the data, " +
+      "not the query). In a monorepo only the log of the app guessed from the " +
+      "worktree name is read; memDir in the result shows which one. Returns " +
+      "{rows, total, filesFound, skipped, memDir}: total is the match count " +
+      "before limit, memDir:null means no mem at all (not 'nothing matched').",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        worktree: {
+          type: "string",
+          description:
+            "Absolute path (git rev-parse --show-toplevel) — required; " +
+            "scope of the mem log to read",
+        },
+        files: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Repo-relative paths — match rows whose text/spec/ref mentions them (substring)",
+        },
+        text: {
+          type: "string",
+          description: "Substring, case-insensitive",
+        },
+        kind: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Filter by kind (decision/note/bug/close/…). Omit = every kind — " +
+            "no default filter",
+        },
+        since: {
+          type: "string",
+          description: "ISO date — only rows at or after this time",
+        },
+        limit: {
+          type: "number",
+          description:
+            "Max rows returned (default 20) — total still counts all matches",
+        },
+      },
+      required: ["worktree"],
+    },
+  },
+  {
+    name: "plan_list",
+    description:
+      "List pending plan files grouped by state — active / blocked / " +
+      "untouched / superseded / trackers — each with title and last-run " +
+      "status joined from fapony run history, plus a count of archived " +
+      "ones. Not a raw directory listing: answers 'what is left, what is " +
+      "waiting on what, what should come next'. State comes from optional " +
+      "plan frontmatter (kind: tracker | status: active|blocked|superseded " +
+      "| blocked_by: | blocks: | superseded_by:); a plan without " +
+      "frontmatter is grouped by run history alone (attempted = active, " +
+      "never attempted = untouched). Within active, whatever unblocks the " +
+      "most other plans is listed first.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        worktree: {
+          type: "string",
+          description: "Absolute path to the project's git worktree",
+        },
+        format: {
+          type: "string",
+          enum: ["json", "markdown"],
+          description:
+            "'markdown' renders the groups as a checklist to paste or read; " +
+            "default 'json'.",
+        },
+      },
+      required: ["worktree"],
+    },
+  },
+];

package/src/mcp/tools/mem.ts

@@ -0,0 +1,95 @@
+// src/mcp/tools/mem.ts — mem_find: read-only search over the project's mem log
+//
+// "เขียนได้ ≠ อ่านกลับได้" — the write side works from the CLI with no MCP
+// (vela: 2,920 rows / 49 days); what was missing is "which rows are about the
+// files I am about to touch". Read-only over readMemLog (PLAN-mem-mcp chunk 2).
+//
+// No default kind filter — chunk 0 chose A: every kind is still live, so
+// filtering `synced`/`next`/`claim` by default would be enforcing prose that
+// was already retracted.
+
+import { type MemRow, readMemLog, resolveMemDir } from "../../memory.js";
+import { errorResult, jsonResult, type ToolResult } from "../types.js";
+
+export interface MemFindResult {
+  rows: MemRow[];
+  total: number;
+  filesFound: number;
+  skipped: number;
+  memDir: string | null;
+}
+
+export function memFind(args: {
+  worktree: string;
+  files?: string[];
+  text?: string;
+  kind?: string[];
+  since?: string;
+  limit?: number;
+}): MemFindResult {
+  const read = readMemLog(args.worktree, args.since);
+
+  let rows = read.rows;
+  if (args.kind && args.kind.length > 0) {
+    const kinds = new Set(args.kind);
+    rows = rows.filter((r) => kinds.has(r.kind));
+  }
+  if (args.text) {
+    const needle = args.text.toLowerCase();
+    rows = rows.filter((r) => r.text.toLowerCase().includes(needle));
+  }
+  if (args.files && args.files.length > 0) {
+    // mem never stored files[] — match is substring over text/spec/ref.
+    // Low recall by nature (spec §5.4): a row that never names the file
+    // cannot be found — a limit of the data, not of the query.
+    const paths = args.files.map((f) => f.toLowerCase());
+    rows = rows.filter((r) => {
+      const hay = `${r.text}\n${r.spec ?? ""}\n${r.ref ?? ""}`.toLowerCase();
+      return paths.some((p) => hay.includes(p));
+    });
+  }
+
+  const total = rows.length;
+  const limit = Math.max(0, args.limit ?? 20);
+  return {
+    rows: rows.slice(0, limit),
+    total,
+    filesFound: read.filesFound,
+    skipped: read.skipped,
+    // memDir separates "no mem at all" from "nothing matched" (spec §3) and
+    // makes the monorepo single-log limit visible (spec §5.1).
+    memDir: resolveMemDir(args.worktree),
+  };
+}
+
+export function toolMemFind(args: Record<string, unknown>): ToolResult {
+  const worktree =
+    typeof args.worktree === "string" ? args.worktree.trim() : "";
+  if (!worktree) {
+    return errorResult(
+      "worktree is required and must be an absolute path " +
+        "(git rev-parse --show-toplevel) — an empty result without it would be " +
+        "misread as 'no history'",
+    );
+  }
+  if (!worktree.startsWith("/")) {
+    return errorResult(
+      `worktree must be an absolute path, got: ${worktree} — a bare name scopes to nothing`,
+    );
+  }
+  const files = Array.isArray(args.files)
+    ? args.files.filter(
+        (f): f is string => typeof f === "string" && f.length > 0,
+      )
+    : undefined;
+  const kind = Array.isArray(args.kind)
+    ? args.kind.filter(
+        (k): k is string => typeof k === "string" && k.length > 0,
+      )
+    : undefined;
+  const text = typeof args.text === "string" ? args.text : undefined;
+  const since = typeof args.since === "string" ? args.since : undefined;
+  const limit = typeof args.limit === "number" ? args.limit : undefined;
+
+  return jsonResult(memFind({ worktree, files, text, kind, since, limit }));
+}