fapony 0.3.0 → 0.3.4

package/src/stats/data.ts

@@ -2,11 +2,10 @@
 
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
-import { type Event, openDb, PLAN_DIR, type Run } from "../db/index.js";
-import { loadConfig } from "../db/load.js";
+import { type Event, loadConfig, PLAN_DIR, type Run } from "../core/config.js";
+import { REASON_CODES, REGIME_CODES } from "../core/enums.js";
+import { openDb } from "../db/store.js";
 import { enrichGateWindows } from "../gates.js";
-import { avg, minutesBetween } from "../math.js";
-import { REASON_CODES, REGIME_CODES } from "../mcp/types.js";
 import {
   isPassFamily,
   qualityScore,
@@ -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

@@ -13,12 +13,12 @@ import {
   type Config,
   type Event,
   loadConfig,
-  openDb,
   type Run,
-} from "./db/index.js";
+} from "./core/config.js";
+import { openDb } from "./db/store.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/usage/cache.ts

@@ -12,8 +12,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { faponyDir } from "../db/load.js";
-import type { Config } from "../db/types.js";
+import { type Config, faponyDir } from "../core/config.js";
 
 const CACHE_FILENAME = "usage-cache.jsonl";
 

package/src/usage/cli.ts

@@ -3,7 +3,7 @@
 // Reads from usage-cache.jsonl (written by `fapony usage-scan`).
 // No live session scanning — serves static HTML.
 
-import { loadConfig } from "../db/index.js";
+import { loadConfig } from "../core/config.js";
 import type { PassiveUsageResult } from "../session/types.js";
 import { type CacheEntry, cacheMeta, readCache } from "./cache.js";
 import { renderUsageHtml } from "./render.js";

package/src/usage/scan.ts

@@ -5,7 +5,8 @@
 // Per-worktree + global aggregate — the cache now carries a worktree dimension.
 // Progress bar on TTY, plain lines on pipe/CI.
 
-import { loadConfig, openDb } from "../db/index.js";
+import { loadConfig } from "../core/config.js";
+import { openDb } from "../db/store.js";
 import { CLIENTS } from "../session/index.js";
 import type { PassiveUsageResult } from "../session/types.js";
 import {

package/src/util.ts

@@ -1,32 +1,10 @@
-// Replacement values are inserted via a function so `$&`, `$'` etc. in the
-// value are treated as literal text, not replace() special patterns.
-export function templateArgs(
-  arr: string[],
-  vars: Record<string, string>,
-): string[] {
-  return arr.map((s) => {
-    let out = s;
-    for (const [k, v] of Object.entries(vars)) {
-      out = out.replaceAll(`{${k}}`, () => v);
-    }
-    return out;
-  });
-}
-
-/** Fill a prompt template with {{VARS}} (all occurrences). Missing vars → "". */
-export function fillPrompt(
-  template: string,
-  vars: Record<string, string>,
-): string {
-  let out = template;
-  for (const [k, v] of Object.entries(vars)) {
-    out = out.replaceAll(`{{${k}}}`, () => v);
-  }
-  return out;
-}
-
-/** 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";
-}
+// shim — moved to src/core/util.ts
+export {
+  avg,
+  fillPrompt,
+  isAffirmative,
+  minutesBetween,
+  templateArgs,
+  type WalkDirOpts,
+  walkDir,
+} from "./core/util.js";

package/src/web/html.ts

@@ -1,33 +1,2 @@
-// src/web/html.ts — shared HTML helpers for report-web and usage-web
-
-/** HTML-escape interpolated strings. */
-export function esc(s: string): string {
-  return s
-    .replaceAll("&", "&")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;");
-}
-
-/** Common dark-theme CSS variables + base reset used by all HTML pages. */
-export const DARK_THEME_CSS = `
-  :root { --bg: #0d1117; --fg: #c9d1d9; --border: #30363d; --accent: #58a6ff; --green: #3fb950; --red: #f85149; --yellow: #d29922; --muted: #8b949e; }
-  * { box-sizing: border-box; margin: 0; padding: 0; }
-  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; background: var(--bg); color: var(--fg); line-height: 1.6; padding: 2rem; max-width: 960px; margin: 0 auto; }
-`;
-
-/** Shared table + typography CSS used by both report and usage pages. */
-export const TABLE_CSS = `
-  h1 { font-size: 1.5rem; margin-bottom: 0.5rem; }
-  h2 { font-size: 1.1rem; color: var(--accent); margin: 1.5rem 0 0.5rem; border-bottom: 1px solid var(--border); padding-bottom: 0.3rem; }
-  .meta { color: var(--muted); font-size: 0.85rem; margin-bottom: 1.5rem; }
-  table { width: 100%; border-collapse: collapse; margin-bottom: 1rem; font-size: 0.9rem; }
-  th, td { padding: 0.5rem 0.8rem; text-align: left; border-bottom: 1px solid var(--border); }
-  th { color: var(--muted); font-weight: 600; font-size: 0.8rem; text-transform: uppercase; }
-  tr:hover { background: #161b22; }
-  .pass { color: var(--green); }
-  .fail { color: var(--red); }
-  .warn { color: var(--yellow); }
-  .muted { color: var(--muted); }
-  .sample { font-size: 0.8rem; color: var(--muted); }
-`;
+// shim — moved to src/core/format.ts
+export { DARK_THEME_CSS, esc, TABLE_CSS } from "../core/format.js";

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.

package/src/db/defaults.ts

@@ -1,34 +0,0 @@
-import type { Config } from "./types.js";
-
-export const DEFAULT_SAFETY_DENY = [
-  "reset\\s+--hard",
-  "clean\\s+-[a-z]*f",
-  "checkout\\s+--\\s",
-  "git\\s+stash",
-];
-// --- .fapony/ layout (single source of truth — do not hardcode ".fapony" elsewhere) ---
-// plan/spec live in .fapony/ — not configurable (gitignored = private).
-export const FAPONY_DIR = ".fapony";
-export const CONFIG_FILENAME = "fapony.config.json";
-export const CONVENTIONS_FILENAME = "conventions.json";
-export const EVIDENCE_FILENAME = "evidence.json";
-export const CONVENTIONS_FILE = `${FAPONY_DIR}/${CONVENTIONS_FILENAME}`;
-// plan/spec live in .fapony/ — not configurable (gitignored = private).
-export const PLAN_DIR = `${FAPONY_DIR}/plan`;
-export const SPEC_DIR = `${FAPONY_DIR}/spec`;
-// Archive sits beside plan/, not inside it, so archiving never changes a file's
-// depth and its relative links survive the move untouched.
-export const DEFAULT_DONE_DIR = `${FAPONY_DIR}/done`;
-export const DEFAULT_MEM_DIR = `${FAPONY_DIR}/.memory`;
-export const DEFAULT_EVIDENCE_FILE = `${FAPONY_DIR}/${EVIDENCE_FILENAME}`;
-
-export const DEFAULT_CONFIG: Config = {
-  worktrees: {},
-  review: {
-    maxRounds: 2,
-  },
-  memory: null,
-  telemetry: null,
-  paths: null,
-  safety: null,
-};

package/src/db/getters.ts

@@ -1,35 +0,0 @@
-import {
-  DEFAULT_DONE_DIR,
-  DEFAULT_EVIDENCE_FILE,
-  DEFAULT_MEM_DIR,
-  DEFAULT_SAFETY_DENY,
-  PLAN_DIR,
-  SPEC_DIR,
-} from "./defaults.js";
-import type { Config } from "./types.js";
-
-export function safetyDeny(config?: Config): string[] {
-  return config?.safety?.deny ?? DEFAULT_SAFETY_DENY;
-}
-
-/** Hardcoded — plan/spec live in .fapony/ (gitignored = private). */
-export function planDir(): string {
-  return PLAN_DIR;
-}
-
-/** Hardcoded — plan/spec live in .fapony/ (gitignored = private). */
-export function specDir(): string {
-  return SPEC_DIR;
-}
-
-export function doneDir(config?: Config): string {
-  return config?.paths?.doneDir ?? DEFAULT_DONE_DIR;
-}
-
-export function memoryDir(config?: Config): string {
-  return config?.paths?.memDir ?? DEFAULT_MEM_DIR;
-}
-
-export function evidenceFile(config?: Config): string {
-  return config?.paths?.evidenceFile ?? DEFAULT_EVIDENCE_FILE;
-}

package/src/db/index.ts

@@ -1,7 +0,0 @@
-// barrel — re-export everything from db/* so existing imports from "./db/index.js" keep working
-
-export * from "./defaults.js";
-export * from "./getters.js";
-export * from "./load.js";
-export * from "./store.js";
-export * from "./types.js";

package/src/db/load.ts

@@ -1,57 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { CONFIG_FILENAME, DEFAULT_CONFIG } from "./defaults.js";
-import type { Config } from "./types.js";
-
-// XDG Base Directory convention (macOS ignores Apple's ~/Library/Application Support
-// for CLI tools by common practice — gh, ripgrep-adjacent tools, etc. use ~/.config too)
-// Override order: $FAPONY_STATE_DIR > config.paths.stateDir > $XDG_CONFIG_HOME > ~/.config
-export function faponyDir(config?: Config): string {
-  if (process.env.FAPONY_STATE_DIR) return process.env.FAPONY_STATE_DIR;
-  if (config?.paths?.stateDir) return config.paths.stateDir;
-  const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-  return join(base, "fapony");
-}
-
-function _dbPath(config?: Config): string {
-  return join(faponyDir(config), "state.db");
-}
-
-export function configFilePath(): string {
-  if (process.env.FAPONY_CONFIG) return process.env.FAPONY_CONFIG;
-  return join(process.cwd(), CONFIG_FILENAME);
-}
-
-function freshDefaultConfig(): Config {
-  return {
-    ...DEFAULT_CONFIG,
-    worktrees: { ...DEFAULT_CONFIG.worktrees },
-    review: {
-      ...DEFAULT_CONFIG.review,
-    },
-  };
-}
-
-export function loadConfig(configPath?: string): Config {
-  const resolved = configPath ?? configFilePath();
-  if (!existsSync(resolved)) return freshDefaultConfig();
-
-  try {
-    const raw = readFileSync(resolved, "utf-8");
-    const file = JSON.parse(raw) as Partial<Config>;
-
-    return {
-      ...DEFAULT_CONFIG,
-      ...file,
-      review: {
-        ...DEFAULT_CONFIG.review,
-        ...file.review,
-      },
-      paths: file.paths ? { ...file.paths } : DEFAULT_CONFIG.paths,
-      safety: file.safety ? { ...file.safety } : DEFAULT_CONFIG.safety,
-    };
-  } catch {
-    return freshDefaultConfig();
-  }
-}

package/src/db/types.ts

@@ -1,77 +0,0 @@
-export type RunStatus =
-  | "running"
-  | "awaiting_review"
-  | "fixing"
-  | "passed"
-  | "stopped"
-  | "stalled";
-
-export interface Run {
-  id: number;
-  worktree: string;
-  plan: string | null;
-  mem_id: string | null;
-  status: RunStatus;
-  base_sha: string;
-  round: number;
-  created_at: string;
-  updated_at: string;
-}
-
-export interface Event {
-  id: number;
-  run_id: number;
-  ts: string;
-  kind: string;
-  data: string | null;
-}
-
-export interface Config {
-  worktrees: Record<string, string>;
-  review: {
-    maxRounds: number;
-  };
-  memory: {
-    claim: string[];
-    close: string[];
-    add: string[];
-    kickoff?: string[];
-  } | null;
-  // opt-in only — omit or leave null to keep everything local. See TELEMETRY.md
-  // for the exact payload shape (KPI numbers + event kind/timestamp, no
-  // plan/commit/gate-note content, ever).
-  telemetry?: {
-    enabled: boolean;
-    endpoint: string;
-    /** Self-reported metadata — advisory, not machine-observed. */
-    metadata?: {
-      task_category?: string;
-      stack?: string;
-      notes?: string;
-    };
-  } | null;
-  // --- Flexible paths / limits (all optional, defaults = old hardcodes) ---
-  paths?: {
-    // state dir override (default: $XDG_CONFIG_HOME/fapony or ~/.config/fapony).
-    // $FAPONY_STATE_DIR env wins over this when set.
-    stateDir?: string;
-    // plan/spec live in .fapony/{plan,spec} — not configurable (gitignored = private).
-    doneDir?: string;
-    memDir?: string;
-    evidenceFile?: string;
-  } | null;
-  safety?: {
-    // regex sources tested against the joined argv; default = the 4 git patterns.
-    deny?: string[];
-  } | null;
-  usageWeb?: {
-    port?: number;
-    hostname?: string;
-    ownerName?: string;
-  } | null;
-}
-
-export interface RolePricing {
-  inputPer1k: number;
-  outputPer1k: number;
-}

package/src/math.ts

@@ -1,13 +0,0 @@
-// src/math.ts — pure numeric helpers shared across modules
-
-/** 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;
-}

package/src/mcp/tools/verdict.ts

@@ -1,161 +0,0 @@
-// src/mcp/tools/verdict.ts — verdict_submit tool
-
-import {
-  findOpenRun,
-  findOpenRunWithNullPlan,
-  getRun,
-  newRun,
-  openDb,
-  patchLastGateEvent,
-} from "../../db/index.js";
-import { gateOnce } from "../../gate.js";
-import { VERDICT_GRADES, type VerdictGrade } from "../../parse.js";
-import {
-  errorResult,
-  jsonResult,
-  REASON_CODES,
-  REGIME_CODES,
-  type ReasonCode,
-  type RegimeCode,
-  type ToolResult,
-} from "../types.js";
-import { resolveWorktreeArg } from "../worktree.js";
-
-// --- Tool implementation ---
-
-export function toolVerdictSubmit(args: Record<string, unknown>): ToolResult {
-  const {
-    run_id,
-    verdict,
-    reason_code,
-    regime,
-    note,
-    worktree,
-    plan,
-    session_id,
-    files,
-  } = args;
-
-  if (typeof verdict !== "string" || !VERDICT_GRADES.has(verdict)) {
-    return errorResult(
-      `verdict must be one of: ${[...VERDICT_GRADES].join(", ")}`,
-    );
-  }
-  const grade = verdict as VerdictGrade;
-  if (!REASON_CODES.includes(reason_code as ReasonCode)) {
-    return errorResult(
-      `reason_code must be one of: ${REASON_CODES.join(", ")}`,
-    );
-  }
-  if (reason_code === "other" && (!note || typeof note !== "string")) {
-    return errorResult("reason_code 'other' requires a note");
-  }
-  if (!REGIME_CODES.includes(regime as RegimeCode)) {
-    return errorResult(`regime must be one of: ${REGIME_CODES.join(", ")}`);
-  }
-  const regimeCode = regime as RegimeCode;
-
-  const db = openDb();
-
-  // Resolve or create run_id
-  let resolvedRunId: number;
-  if (typeof run_id === "number" && Number.isInteger(run_id)) {
-    const run = getRun(db, run_id);
-    if (!run) {
-      return jsonResult({ stored: false, error: "run not found" });
-    }
-    resolvedRunId = run_id;
-  } else {
-    // Bind to the latest still-open run for the same worktree+plan so a
-    // round-2+ verdict lands on the original row (round keeps counting and
-    // review.maxRounds can actually trigger). Only when no open run matches
-    // is a fresh row created. plan=null always opens a new run (no guess).
-    // Free-text plans are normalized (trim+lowercase) so "Fix Login" and
-    // "fix login" bind to the same run. When no exact match exists, falls
-    // back to any open run with plan=null (the "no PLAN file" flow).
-    const resolvedWorktree =
-      typeof worktree === "string" && worktree
-        ? resolveWorktreeArg(worktree)
-        : "mcp-external";
-    const resolvedPlan =
-      typeof plan === "string" && plan ? plan.trim().toLowerCase() : null;
-    // BEGIN IMMEDIATE makes the find-then-create below atomic across
-    // concurrent MCP processes: without it, two agents closing the same
-    // worktree+plan at once can both see "no open run" and each insert a
-    // row. The write lock taken here blocks (busy_timeout, not throws) the
-    // second caller until the first commits, so it re-reads and finds the
-    // row already there instead of duplicating it.
-    db.run("BEGIN IMMEDIATE");
-    try {
-      let open = resolvedPlan
-        ? findOpenRun(db, resolvedWorktree, resolvedPlan)
-        : null;
-      // Fallback: if no exact match and plan is non-null, try any open run with
-      // plan=null.  This lets a verdict with free-text intent bind to a run that
-      // was created without a plan (the common "no PLAN file" flow).
-      if (!open && resolvedPlan) {
-        open = findOpenRunWithNullPlan(db, resolvedWorktree);
-      }
-      if (open) {
-        resolvedRunId = open.id;
-      } else {
-        // worktree/plan let callers (e.g. move-to-done) attribute the verdict
-        // so byReasonCode/bestPassing aggregate correctly instead of collapsing
-        // into "mcp-external".
-        resolvedRunId = newRun(db, resolvedWorktree, resolvedPlan, null, "mcp");
-      }
-      db.run("COMMIT");
-    } catch (e) {
-      db.run("ROLLBACK");
-      throw e;
-    }
-  }
-
-  // Normalize files: must be a non-empty array of strings.
-  const resolvedFiles =
-    Array.isArray(files) && files.length > 0
-      ? files.filter((f): f is string => typeof f === "string" && f.length > 0)
-      : undefined;
-
-  // Route through gateOnce for consistent status/round/memory handling.
-  const mcpNote =
-    typeof note === "string" && note
-      ? `[${reason_code}] ${note}`
-      : `[${reason_code}]`;
-  const result = gateOnce(resolvedRunId, grade, mcpNote, resolvedFiles);
-
-  if (result.error) {
-    return jsonResult({
-      stored: false,
-      error: result.error,
-      run_id: resolvedRunId,
-      status: result.status,
-      round: result.round,
-    });
-  }
-
-  // Patch the gate event with MCP-specific fields (reason_code, source).
-  // session_id lets gates.ts resolve model from client session logs when the
-  // window has no spawn events (the old execute→review loop that wrote spawns
-  // is gone). Optional — agents that can't expose it just omit it.
-  const patch: Record<string, unknown> = {
-    reason_code,
-    regime: regimeCode,
-    source: "mcp",
-  };
-  if (typeof session_id === "string" && session_id) {
-    patch.session_id = session_id;
-  }
-  patchLastGateEvent(db, resolvedRunId, patch);
-
-  return jsonResult({
-    stored: true,
-    run_id: resolvedRunId,
-    verdict: grade,
-    reason_code,
-    regime: regimeCode,
-    status: result.status,
-    round: result.round,
-    ...(resolvedFiles ? { files: resolvedFiles } : {}),
-  });
-}

package/src/mcp/types.ts

@@ -1,54 +0,0 @@
-// src/mcp/types.ts — ReasonCode enum, ToolResult, helpers
-
-// --- ReasonCode enum (locked in step 0, append-only) ---
-
-export const REASON_CODES = [
-  "missing_test",
-  "scope_mismatch",
-  "unsafe_command",
-  "spec_gap",
-  "timeout",
-  "blocked",
-  "incomplete",
-  "none",
-  "other",
-] as const;
-
-export type ReasonCode = (typeof REASON_CODES)[number];
-
-// --- RegimeCode enum (task-shape axis for model × project × regime × quality) ---
-
-export const REGIME_CODES = [
-  "code",
-  "fix",
-  "review",
-  "plan",
-  "inquiry",
-  "test",
-] as const;
-
-export type RegimeCode = (typeof REGIME_CODES)[number];
-
-// --- Tool result types ---
-
-export interface ToolResult {
-  content: { type: "text"; text: string }[];
-  isError?: boolean;
-}
-
-export function jsonResult(data: unknown): ToolResult {
-  return {
-    content: [{ type: "text", text: JSON.stringify(data) }],
-  };
-}
-
-export function errorResult(message: string): ToolResult {
-  return {
-    content: [{ type: "text", text: JSON.stringify({ error: message }) }],
-    isError: true,
-  };
-}
-
-export function parseToolResult(result: ToolResult): unknown {
-  return JSON.parse(result.content[0].text);
-}