fapony 0.2.1 → 0.3.3

package/src/{plan-seed.ts → seed/plan-seed.ts}

@@ -1,4 +1,4 @@
-// src/plan-seed.ts — `fapony plan-seed <name> [--spec] [--scope <path>]...`
+// src/seed/plan-seed.ts — `fapony plan-seed <name> [--spec] [--scope <path>]...`
 //
 // Writes PLAN + SPEC straight into planDir/specDir. What it pre-fills is the
 // structure (frontmatter, the 8 sections, prior art, ledger context) — the
@@ -25,7 +25,6 @@
 //
 // Composes existing producers — no new parsing, no new table, no MCP tool.
 
-import { execSync } from "node:child_process";
 import {
   existsSync,
   mkdirSync,
@@ -35,15 +34,16 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, join, relative, resolve, sep } from "node:path";
-import { collectSourceFiles, isSkippedDir, SCAN_EXTS } from "./analyze.js";
-import { computeModelFit } from "./context/projectHealth.js";
-import { doneDir, planDir, specDir } from "./db/getters.js";
-import { CONFIG_FILENAME } from "./db/index.js";
-import { loadConfig } from "./db/load.js";
-import type { Config } from "./db/types.js";
-import { extractExports } from "./map.js";
-import { readRecentMemDecisions } from "./memory.js";
-import { getStatsData } from "./stats/data.js";
+import { collectSourceFiles, isSkippedDir, SCAN_EXTS } from "../analyze.js";
+import { computeModelFit } from "../context/projectHealth.js";
+import { doneDir, planDir, specDir } from "../db/getters.js";
+import { CONFIG_FILENAME } from "../db/index.js";
+import { loadConfig } from "../db/load.js";
+import type { Config } from "../db/types.js";
+import { extractExports } from "../map.js";
+import { readRecentMemDecisions } from "../memory.js";
+import { getStatsData } from "../stats/data.js";
+import { capLines, execGit, SIG_MAX } from "./primitives.js";
 
 // One chunk = one module's signatures — past ~40 lines a module is its own
 // reading task, and the whole-SPEC cap below does the final trim.
@@ -56,7 +56,6 @@ const SCOPE_WARN_FILES = 300;
 // Shipped plans/specs that already touched this scope. Capped low on purpose:
 // this is a "go read that first" pointer, not a bibliography.
 const MAX_PRIOR_ART = 5;
-const SIG_MAX = 90;
 // Anchor-safe slug: lowercase, non-alphanumerics → dash.
 const slug = (s: string): string =>
   s
@@ -224,7 +223,7 @@ next step in the same session is what rule 9 forbids.
 1. _(agent fills in — each step must be verifiable)_
 
 **Closing a step:** tick its TL;DR box with the sha · \`git commit\` this step's
-files only · \`verdict_submit\` (MCP) with this step's \`regime\` · then hand off:
+files only · then hand off:
 
 \`\`\`bash
 fapony mem add note "<what chunk N+1 must know>" --files <f1,f2> ${planRel}
@@ -257,16 +256,6 @@ interface Chunk {
   body: string;
 }
 
-// review-seed's cap shape: keep the head, always say how much was cut — a
-// silent cut is indistinguishable from "that was everything".
-function capLines(lines: string[], cap: number, what: string): string[] {
-  if (lines.length <= cap) return lines;
-  const rest = lines.length - (cap - 1);
-  const kept = lines.slice(0, cap - 1);
-  kept.push(`… +${rest} more ${what}`);
-  return kept;
-}
-
 function capChunk(c: Chunk): Chunk {
   return {
     ...c,
@@ -530,15 +519,8 @@ export function cmdPlanSeed(args: string[]): void {
   // state.db uses (git rev-parse --show-toplevel). Running from a subdir
   // would otherwise mismatch: stats return empty, Context (fapony) always
   // prints "(not enough graded history yet)".
-  let worktree: string;
-  try {
-    worktree = execSync("git rev-parse --show-toplevel", {
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-    }).trim();
-  } catch {
-    worktree = cwd;
-  }
+  const root = execGit("git rev-parse --show-toplevel", cwd);
+  const worktree = root.ok ? root.output.split("\n")[0] : cwd;
 
   // Scope: explicit paths win; default is the cwd. Resolved absolutes,
   // deduped — the same path twice is one scope. Nested roots are pruned:

package/src/seed/primitives.ts

@@ -0,0 +1,66 @@
+// src/seed/primitives.ts — shared helpers for plan-seed + review-seed
+//
+// Git execution, output capping, signature formatting — the pieces both
+// commands need. §0 rule: add-only — never remove or rename exported symbols.
+
+import { execSync } from "node:child_process";
+
+// --- Error class ---
+
+export class SeedError extends Error {}
+
+// --- Git helpers ---
+
+export function execGit(
+  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 err = e as { stderr?: string; message?: string };
+    return {
+      ok: false,
+      output: "",
+      error: (err.stderr ?? err.message ?? "").trim(),
+    };
+  }
+}
+
+export function gitOk(r: { ok: boolean; error?: string }, cmd: string): void {
+  if (!r.ok)
+    throw new SeedError(`git failed: ${cmd}\n${r.error ?? "unknown error"}`);
+}
+
+// Values interpolated into a git command line must be plain refs/paths —
+// blocks shell metacharacters before execSync ever sees them.
+const GIT_VALUE_RE = /^[A-Za-z0-9._/{}^~+-]+$/;
+
+export function gitValue(kind: string, value: string): string {
+  if (!GIT_VALUE_RE.test(value)) {
+    throw new SeedError(`invalid ${kind}: ${value}`);
+  }
+  return value;
+}
+
+// --- Output capping ---
+
+// Keep the head, always say how much was cut — a silent cut is
+// indistinguishable from "that was everything".
+export function capLines(lines: string[], cap: number, what: string): string[] {
+  if (lines.length <= cap) return lines;
+  const rest = lines.length - (cap - 1);
+  const kept = lines.slice(0, cap - 1);
+  kept.push(`… +${rest} more ${what}`);
+  return kept;
+}
+
+// --- Signature formatting ---
+
+export const SIG_MAX = 90;

package/src/{review-seed.ts → seed/review-seed.ts}

@@ -1,4 +1,4 @@
-// src/review-seed.ts — `fapony review-seed [--staged|--commit <sha>|--range <a...b>|--files f1,f2,dir|--plan <PLAN.md>]`
+// src/seed/review-seed.ts — `fapony review-seed [--staged|--commit <sha>|--range <a...b>|--files f1,f2,dir|--plan <PLAN.md>]`
 //
 // Seeds a code review with the deterministic facts of the scope the agent
 // asked about: which files changed (per the exact git expression, echoed),
@@ -12,14 +12,13 @@
 // cite rule 5 "never write into a target worktree", dropped 2026-09-17 because
 // four commands broke it; being read-only was always a property of this
 // command, never of that rule. Facts only: nothing here says broken/fixed
-// — judgment lives in the reviewer and the ledger (verdict_submit), never in
+// — judgment lives in the reviewer and mem log, never in
 // this output. Deterministic: same input, same bytes, no LLM.
 //
 // Composes existing producers — buildGraph (analyze.ts) for importers/untested,
 // extractExports (map.ts) for signatures. One flag = one declared git call;
 // no magic parsing.
 
-import { execSync } from "node:child_process";
 import type { Stats } from "node:fs";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -30,9 +29,10 @@ import {
   isTestedThroughBarrels,
   isTestFile,
   SCAN_EXTS,
-} from "./analyze.js";
-import { extractBody, extractExports } from "./map.js";
-import { assertSafe } from "./safety.js";
+} from "../analyze.js";
+import { extractBody, extractExports } from "../map.js";
+import { assertSafe } from "../safety.js";
+import { execGit, gitOk, gitValue, SeedError, SIG_MAX } from "./primitives.js";
 
 const WRAP_WIDTH = 88;
 // The changed list is the review's scope boundary, not context: a file hidden
@@ -58,7 +58,6 @@ const LOOKUP_OUTPUT_CAP = 120;
 // files is already past "this component area" into "the whole tree" — cut
 // there and say so, a folder-shaped wall is not an answer either.
 // Signature text cap per symbol (same trim as map.ts's file view).
-const SIG_MAX = 90;
 const DISCLAIMER =
   "static graph only — seed is where to enter, not what is verified";
 const USAGE =
@@ -70,52 +69,6 @@ const MAX_BODY_LINES = 80;
 const MAX_CALLER_FILES = 12;
 const MAX_CALLER_HITS = 20;
 
-export class SeedError extends Error {}
-
-// --- Git helpers (same shape as collect.ts execGitSafe) ---
-
-function execGit(
-  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 err = e as { stderr?: string; message?: string };
-    return {
-      ok: false,
-      output: "",
-      error: (err.stderr ?? err.message ?? "").trim(),
-    };
-  }
-}
-
-// A scope's primary git call failing must never masquerade as "nothing
-// changed" — surface it. merge-base failures are tolerated (label fallback).
-function gitOk(r: { ok: boolean; error?: string }, cmd: string): void {
-  if (!r.ok)
-    throw new SeedError(
-      `review-seed: git failed: ${cmd}\n${r.error ?? "unknown error"}`,
-    );
-}
-
-// Values interpolated into a git command line must be plain refs/paths —
-// blocks shell metacharacters before execSync ever sees them.
-const GIT_VALUE_RE = /^[A-Za-z0-9._/{}^~+-]+$/;
-
-function gitValue(kind: string, value: string): string {
-  if (!GIT_VALUE_RE.test(value)) {
-    throw new SeedError(`review-seed: invalid ${kind}: ${value}`);
-  }
-  return value;
-}
-
 // --- Scope flags: exactly one source of scope ---
 
 type Scope =
@@ -233,7 +186,7 @@ function parseScope(args: string[]): Scope {
 
 // --- Scope resolution: one flag = one declared git call ---
 
-interface FileEntry {
+export interface FileEntry {
   path: string;
   ins: number | null;
   del: number | null;

package/src/session/helpers.ts

@@ -270,7 +270,7 @@ export function readDetailFromDb(
     .all(...filter.params) as DetailPerSessionToolRow[];
 
   // Context bytes per tool — summed `state.output` length. Same signal the
-  // Claude Code/Codex readers derive from tool_result blocks, so `fapony_usage`
+  // Claude Code/Codex readers derive from tool_result blocks, so usage-scan
   // stops reporting zero bytes for the SQLite clients.
   const bytesRows = db
     .prepare(

package/src/session/registry.ts

@@ -2,8 +2,8 @@
 //
 // Adding a client: write its reader (src/session/<name>.ts, same
 // PassiveUsageResult shape as an existing one — SQLite or JSONL, whatever the
-// client actually stores), then add one entry below. usage-scan and
-// fapony_usage both iterate this list; neither needs any other change.
+// client actually stores), then add one entry below. usage-scan iterates
+// this list; nothing else needs any other change.
 //
 // This does not remove the real work of a new client (reverse-engineering
 // its storage format) — it only removes the "wire it into 2 call sites"
@@ -16,12 +16,10 @@ import type { PassiveUsageReader } from "./types.js";
 import { readZcodeUsage } from "./zcode.js";
 
 export interface ClientAdapter {
-  /** cache `client` field and fapony_usage JSON key. */
+  /** usage-cache.jsonl `client` field and usage-scan label default. */
   key: string;
   /** usage-scan progress label — defaults to `key`. */
   scanLabel?: string;
-  /** fapony_usage text-report section label — defaults to `key`. */
-  reportLabel?: string;
   /** The one client whose totals lead the report as the unlabeled top-level summary. */
   primary?: boolean;
   read: PassiveUsageReader;
@@ -38,7 +36,6 @@ export const CLIENTS: ClientAdapter[] = [
   {
     key: "claude_code",
     scanLabel: "claude-code",
-    reportLabel: "claude code",
     read: readClaudeCodeUsage,
   },
   { key: "codex", read: readCodexUsage },

package/src/setup.ts

@@ -229,7 +229,7 @@ export async function cmdSetup(deps: SetupDeps = {}): Promise<void> {
   │     fapony install --platform claude    │
   │                                         │
   │  2. Ask your agent:                     │
-  │     "Run fapony_stats and fapony_usage" │
+  │     "Find past decisions with mem_find" │
   │                                         │
   │  3. Read a run's report:                │
   │     fapony report <run-id>              │

package/src/stats/data.ts

@@ -5,7 +5,6 @@ import { join } from "node:path";
 import { type Event, openDb, PLAN_DIR, type Run } from "../db/index.js";
 import { loadConfig } from "../db/load.js";
 import { enrichGateWindows } from "../gates.js";
-import { avg, minutesBetween } from "../math.js";
 import { REASON_CODES, REGIME_CODES } from "../mcp/types.js";
 import {
   isPassFamily,
@@ -20,6 +19,7 @@ import {
   readPassiveUsage,
   readZcodeUsage,
 } from "../session/index.js";
+import { avg, minutesBetween } from "../util.js";
 
 // Walks events per run in order and pairs up spawn→route (executor time)
 // and route→gate (review turnaround) per round, since one run row can span

package/src/telemetry.ts

@@ -17,8 +17,8 @@ import {
   type Run,
 } from "./db/index.js";
 import { enrichGateWindows } from "./gates.js";
-import { avg, minutesBetween } from "./math.js";
 import { readPassiveUsage } from "./session/index.js";
+import { avg, minutesBetween } from "./util.js";
 
 // ─── Schema version ────────────────────────────────────────────────────
 

package/src/util.ts

@@ -25,8 +25,69 @@ export function fillPrompt(
   return out;
 }
 
+/** Minutes between two ISO-like timestamps (space separator, UTC assumed). */
+export function minutesBetween(a: string, b: string): number {
+  const t0 = new Date(`${a.replace(" ", "T")}Z`).getTime();
+  const t1 = new Date(`${b.replace(" ", "T")}Z`).getTime();
+  return (t1 - t0) / 60000;
+}
+
+/** Arithmetic mean of a numeric array. 0 for empty arrays. */
+export function avg(xs: number[]): number {
+  return xs.length ? xs.reduce((s, x) => s + x, 0) / xs.length : 0;
+}
+
 /** True for "y"/"yes" (case-insensitive, trimmed) — the only affirmative answers. */
 export function isAffirmative(answer: string): boolean {
   const normalized = answer.trim().toLowerCase();
   return normalized === "y" || normalized === "yes";
 }
+
+// --- Recursive directory walker ---
+
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export interface WalkDirOpts {
+  /** Max recursion depth (default 4). */
+  depth?: number;
+  /** Skip node_modules (default true). */
+  skipNodeModules?: boolean;
+  /** Dot-directories to descend into (default []). Others starting with . are skipped. */
+  includeDotDirs?: string[];
+  /** Extra filter: return true to collect this dir. Omit to collect all reached dirs. */
+  predicate?: (dirPath: string) => boolean;
+}
+
+/**
+ * Recursively walk directories under `root`.
+ * Returns absolute paths of dirs for which `predicate` returned true (or all
+ * reached dirs when no predicate is given). Skips node_modules by default.
+ */
+export function walkDir(root: string, opts?: WalkDirOpts): string[] {
+  const maxDepth = opts?.depth ?? 4;
+  const skipNm = opts?.skipNodeModules ?? true;
+  const includeDot = new Set(opts?.includeDotDirs ?? []);
+  const pred = opts?.predicate;
+  const result: string[] = [];
+
+  const walk = (dir: string, depth: number): void => {
+    if (depth > maxDepth) return;
+    if (!pred || pred(dir)) result.push(dir);
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (entry.isSymbolicLink()) continue;
+        if (skipNm && entry.name === "node_modules") continue;
+        if (entry.name.startsWith(".") && !includeDot.has(entry.name)) {
+          continue;
+        }
+        walk(join(dir, entry.name), depth + 1);
+      }
+    } catch {
+      // ignore unreadable dirs
+    }
+  };
+  walk(root, 0);
+  return result;
+}

package/templates/SPEC.md

@@ -14,11 +14,18 @@
 
 ---
 
+## Non-goals
+What this explicitly does **not** do, one line of why each. Widening scope is an
+agent's default; a spec that only says what to build never stopped anything.
+
 ## Shape (data / API / schema)
 Concrete types, request/response bodies, DB columns — whatever the code needs.
 
 ## Edge cases
-Table or bullets: input → expected behavior.
+Three columns: input → expected → **verify** (a command that actually runs).
+An edge case with no check after it is an opinion, not a requirement — and a
+verify built from a substring of the prose is not a verify (real case: `grep "sed"`
+matched "superseded", so the check passed while the work was missing).
 
 ## Examples
 Before / after, request / response, sample payloads — as long as it needs to be.