fapony 0.1.0

package/src/map.ts

@@ -0,0 +1,320 @@
+// src/map.ts — extractExports(): an on-demand source index for TS/JS projects.
+//
+// Library only. The `fapony map` command this grew out of was deleted once
+// plan-seed and review-seed were its only callers — see PLAN-code-map.
+//
+// Zero persistence: every export list is read from the filesystem and thrown
+// away. No index file, no table, no MCP tool, no cache — standing cost to every
+// other session is exactly zero (the opposite of a cached graph). Read-only.
+//
+// Export names come from a line-based scan; Bun.Transpiler.scan() is the parse
+// gate (throws => "parse error", never guessed away). scan() itself is not the
+// export source: it returns names without lines and drops type-only exports
+// (`export type`, `export interface`, `type X` inside braces) that a code map
+// needs. See SPEC-code-map.md.
+//
+// A content-hash cache was prototyped and cut: hashing content requires reading
+// every file, and reading already costs more than the parse the cache would
+// save, so it bought no wall-clock win at L1 (measured 2026-09-15). It is
+// deferred to L2 (crux excerpt), where per-file work is heavy enough to pay.
+
+export type ExportKind =
+  | "fn"
+  | "class"
+  | "const"
+  | "type"
+  | "interface"
+  | "enum"
+  | "namespace"
+  | "default"
+  | "re-export";
+
+export interface ExportSymbol {
+  name: string;
+  /** 1-based line where the symbol is declared. */
+  line: number;
+  kind: ExportKind;
+}
+
+export interface ExportScan {
+  symbols: ExportSymbol[];
+  error: string | null;
+}
+
+// --- Parse gate ---
+
+let transpiler: Bun.Transpiler | null = null;
+
+interface ScanResult {
+  error: string | null;
+  exports: string[];
+}
+
+function scanSource(source: string): ScanResult {
+  try {
+    if (!transpiler) transpiler = new Bun.Transpiler({ loader: "tsx" });
+    const scanned = transpiler.scan(source) as { exports: string[] };
+    return { error: null, exports: scanned.exports };
+  } catch (e) {
+    return {
+      error: e instanceof Error ? e.message.split("\n")[0] : "Parse error",
+      exports: [],
+    };
+  }
+}
+
+// Identifiers in one line of code, skipping strings, template spans, and
+// comments. Same-line only — enough to find extra bindings on a declaration
+// line without treating sample text as code.
+function codeIdentifiers(line: string): string[] {
+  const out: string[] = [];
+  let cur = "";
+  const flush = () => {
+    if (/^[A-Za-z_$][\w$]*$/.test(cur)) out.push(cur);
+    cur = "";
+  };
+  let i = 0;
+  while (i < line.length) {
+    const c = line[i];
+    const next = line[i + 1] ?? "";
+    if (c === "/" && next === "/") break;
+    if (c === "/" && next === "*") {
+      const end = line.indexOf("*/", i + 2);
+      i = end < 0 ? line.length : end + 2;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === "`") {
+      const quote = c;
+      i++;
+      while (i < line.length && line[i] !== quote) {
+        i += line[i] === "\\" ? 2 : 1;
+      }
+      i++;
+      continue;
+    }
+    if (/[A-Za-z_$0-9]/.test(c)) {
+      cur += c;
+    } else {
+      flush();
+    }
+    i++;
+  }
+  flush();
+  return out;
+}
+
+// --- Export extraction (name + line + kind) ---
+
+const RE = {
+  fn: /^export\s+(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/,
+  cls: /^export\s+(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/,
+  iface: /^export\s+interface\s+([A-Za-z_$][\w$]*)/,
+  typ: /^export\s+type\s+([A-Za-z_$][\w$]*)/,
+  en: /^export\s+(?:const\s+)?enum\s+([A-Za-z_$][\w$]*)/,
+  ns: /^export\s+namespace\s+([A-Za-z_$][\w$]*)/,
+  starAs: /^export\s*\*\s*as\s+([A-Za-z_$][\w$]*)/,
+  star: /^export\s*\*\s+from\b/,
+  brace: /^export\s+(?:type\s+)?\{/,
+};
+
+// Names in one `export { ... }` fragment. Handles `a as b` (keep b),
+// per-name `type X`, and a whole block that started as `export type { ... }`
+// (blockType is set by the caller from the opening line and carried across
+// fragments, so every name in a multi-line type block stays `type`).
+function braceNames(
+  frag: string,
+  blockType = false,
+): { name: string; kind: ExportKind }[] {
+  let text = frag.replace(/[{};]/g, " ");
+  text = text.replace(/\bfrom\b[\s\S]*$/, " ");
+  text = text.replace(/^export\s+/, "");
+  const blockIsType = blockType || /^type\b/.test(text.trim());
+  text = text.replace(/^type\s+/, "");
+  const out: { name: string; kind: ExportKind }[] = [];
+  for (let part of text.split(",")) {
+    part = part.trim();
+    if (!part) continue;
+    let kind: ExportKind = blockIsType ? "type" : "re-export";
+    if (/^type\s+/.test(part)) {
+      part = part.replace(/^type\s+/, "");
+      kind = "type";
+    }
+    const as = part.split(/\s+as\s+/);
+    const name = (as.length > 1 ? as[as.length - 1] : as[0]).trim();
+    if (name === "export") continue;
+    if (name !== "default" && !/^[A-Za-z_$][\w$]*$/.test(name)) continue;
+    out.push({ name, kind });
+  }
+  return out;
+}
+
+const VAR_DECL_RE = /^export\s+(?:const|let|var)\b/;
+
+export function extractExports(source: string): ExportScan {
+  const scanned = scanSource(source);
+  if (scanned.error) return { symbols: [], error: scanned.error };
+
+  // Ambient declarations (`export declare ...`) are invisible to scan(), so
+  // validate value names against the union of the real source and a
+  // declare-stripped variant scanned on the same lines.
+  const stripped = source.replace(
+    /^([ \t]*)export\s+declare\s+/gm,
+    "$1export ",
+  );
+  const strippedScan = scanSource(stripped);
+  const valid = new Set([
+    ...scanned.exports,
+    ...(strippedScan.error ? [] : strippedScan.exports),
+  ]);
+  const seen = new Set<string>();
+  // scan() is blind to namespaces (and to ambient `declare`), so those kinds
+  // stay regex-authoritative; everything else must appear in the parsed export
+  // set, which is what filters sample text out of comments and strings.
+  const SCAN_BLIND: ExportKind[] = ["type", "interface", "namespace"];
+  const keep = (name: string, kind: ExportKind, declared: boolean): boolean => {
+    if (name === "*") return true;
+    if (SCAN_BLIND.includes(kind)) return true;
+    if (seen.has(name)) return false;
+    if (!declared && !valid.has(name)) return false;
+    seen.add(name);
+    return true;
+  };
+  const push = (
+    out: ExportSymbol[],
+    name: string,
+    line: number,
+    kind: ExportKind,
+    declared: boolean,
+  ): void => {
+    if (keep(name, kind, declared)) out.push({ name, line, kind });
+  };
+
+  const lines = source.split("\n");
+  const out: ExportSymbol[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    let t = lines[i].trim();
+    if (!t.startsWith("export")) continue;
+    const declared = /^export\s+declare\s+/.test(t);
+    t = t.replace(/^export\s+declare\s+/, "export ");
+    const line = i + 1;
+    let m: RegExpMatchArray | null;
+
+    if (RE.brace.test(t)) {
+      const blockType = /^export\s+type\b/.test(t);
+      const frags = [{ text: t, line }];
+      let joined = t;
+      let j = i;
+      while (!joined.includes("}") && j + 1 < lines.length) {
+        j++;
+        frags.push({ text: lines[j].trim(), line: j + 1 });
+        joined += ` ${lines[j].trim()}`;
+      }
+      for (const f of frags) {
+        for (const s of braceNames(f.text, blockType)) {
+          push(out, s.name, f.line, s.kind, declared);
+        }
+      }
+      i = j;
+      continue;
+    }
+    if (/^export\s+default\b/.test(t)) {
+      push(out, "default", line, "default", declared);
+      continue;
+    }
+    if ((m = t.match(RE.fn))) {
+      push(out, m[1], line, "fn", declared);
+      continue;
+    }
+    if ((m = t.match(RE.cls))) {
+      push(out, m[1], line, "class", declared);
+      continue;
+    }
+    if ((m = t.match(RE.iface))) {
+      push(out, m[1], line, "interface", declared);
+      continue;
+    }
+    if ((m = t.match(RE.en))) {
+      push(out, m[1], line, "enum", declared);
+      continue;
+    }
+    if ((m = t.match(RE.ns))) {
+      push(out, m[1], line, "namespace", declared);
+      continue;
+    }
+    if ((m = t.match(RE.starAs))) {
+      push(out, m[1], line, "namespace", declared);
+      continue;
+    }
+    if (RE.star.test(t)) {
+      push(out, "*", line, "re-export", declared);
+      continue;
+    }
+    if ((m = t.match(RE.typ))) {
+      push(out, m[1], line, "type", declared);
+      continue;
+    }
+    const varMatch = t.match(VAR_DECL_RE);
+    if (varMatch) {
+      // A `const`/`let`/`var` line can bind several names
+      // (`a = 1, b = 2`, `{ a, b } = …`, `[x] = …`). The scan set says which
+      // identifiers on this line are real exports; initializers and sample
+      // text never are.
+      for (const name of codeIdentifiers(t.slice(varMatch[0].length))) {
+        if (valid.has(name)) push(out, name, line, "const", declared);
+      }
+    }
+  }
+  return { symbols: out, error: null };
+}
+
+// First comment content in the first ~12 lines + the line it sits on. Used only
+// to guess a leaf dir's objective — a module header, not a doc parser.
+
+// Objective guess for a dir with no subdirs: the module header of the most
+// descriptive file. Prefers `// path — desc` (the repo's convention), then a
+// first-line comment, then any comment; ties break to the lexical-first file.
+// Capped: a guess reads at most MAX_OBJECTIVE_FILES files, never a whole tree.
+
+// --- Declaration slice (indent-out, no parser) ---
+
+// Slice from the declaration line until the first line at the declaration's
+// own indent level that is non-blank (indent-out). Raw indentation as the
+// close signal means no brace counting and no parse — a one-liner returns
+// itself, nested blocks and object literals never return to the base indent
+// until the declaration is over. The closing line is the exception indent-out
+// cannot see: `}` sits AT the declaration indent, so the walk stops one line
+// short of it. Take that line when it is nothing but closers — which is why
+// the slice a caller pastes into an edit is syntactically whole.
+// Callers: review-seed --body, conventions seeder (wrapper detection).
+const MAX_BODY_LINES = 80;
+
+export function extractBody(source: string, line: number): string[] {
+  const lines = source.split("\n");
+  const start = line - 1;
+  if (start < 0 || start >= lines.length) return [];
+  const decl = lines[start];
+  if (decl.trim() === "") return [];
+  const base = decl.match(/^\s*/)?.[0].length ?? 0;
+  const out: string[] = [decl];
+  for (
+    let i = start + 1;
+    i < lines.length && out.length < MAX_BODY_LINES;
+    i++
+  ) {
+    const l = lines[i];
+    if (l.trim() === "") {
+      out.push(l);
+      continue;
+    }
+    if ((l.match(/^\s*/)?.[0].length ?? 0) <= base) {
+      // Closers only (`}`, `};`, `});`) — never the next declaration.
+      if (/^[)\]}]+[;,]?$/.test(l.trim())) out.push(l);
+      break;
+    }
+    out.push(l);
+  }
+  // Trailing blank lines inside the slice are padding, not body.
+  while (out.length > 1 && out[out.length - 1].trim() === "") out.pop();
+  return out;
+}

package/src/math.ts

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

@@ -0,0 +1,332 @@
+// src/mcp/evidence.ts — allowlist-based evidence collector
+//
+// Runs only commands listed in the evidence allowlist (default
+// `.fapony/evidence.json`, movable via paths.evidenceFile) inside the worktree,
+// sequentially, each under assertSafe() + per-command timeout. Returns
+// structured EvidenceItem[] without storing secret output.
+//
+// Agent-proposed commands are NEVER executed here — they are recorded as
+// `unverified` claims (provenance: agent_report), matching the contract that
+// `verified:false` means "fapony did not run this".
+//
+// Rule 5b: this module writes nothing — it only reads config and runs
+// allowlisted commands (cwd = worktree). Evidence has to stay the owner's own
+// record; a claim fapony fabricated would be worth nothing. (Previously cited
+// the blanket "fapony never writes to the worktree" rule, dropped 2026-09-17.)
+
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { type Config, evidenceFile, safetyDeny } from "../db/index.js";
+import { assertSafe } from "../safety.js";
+import type { EvidenceItem, EvidenceStatus } from "./primitives.js";
+
+// --- Config shape (.fapony/evidence.json by default, paths.evidenceFile to move it) ---
+
+interface EvidenceCommand {
+  name: string;
+  cmd: string;
+  timeout_ms?: number;
+}
+
+interface EvidenceConfig {
+  commands: EvidenceCommand[];
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const TOTAL_TIMEOUT_MS = 180_000;
+
+const VERIFIED_PROVENANCE = { verified: true, source: "fapony_cli" } as const;
+const AGENT_PROVENANCE = { verified: false, source: "agent_report" } as const;
+
+// --- App-scoped resolution ---
+
+// Monorepo group dirs — same order as templates/mem/store.ts (first hit wins there;
+// here every file must already agree on one group+app, so order never matters).
+const APP_GROUPS = ["apps", "packages", "services"];
+
+function relOf(worktree: string, f: string): string {
+  const r = f.startsWith(`${worktree}/`) ? relative(worktree, f) : f;
+  return r.replace(/^\.\//, "").replace(/\\/g, "/");
+}
+
+/**
+ * Which evidence.json applies to this report — pure over (worktree, files).
+ *
+ * No new fields: the app is inferred from changed files already present in
+ * the report facts (precedent: activeSession.ts infers model from spans
+ * instead of asking the caller). Every file must sit under the same
+ * <group>/<app>/ and that app must have its own .fapony/evidence.json —
+ * otherwise (mixed apps, no files[], missing file) the root allowlist
+ * applies, exactly the old behavior. A declared paths.evidenceFile always
+ * wins: config beats guessing.
+ */
+export function resolveEvidencePath(
+  worktree: string,
+  files: string[] = [],
+  config?: Config,
+): string {
+  if (config?.paths?.evidenceFile)
+    return join(worktree, config.paths.evidenceFile);
+  const rels = files
+    .filter((f) => typeof f === "string" && f.trim())
+    .map((f) => relOf(worktree, f));
+  if (rels.length > 0) {
+    const heads = rels.map((r) => r.split("/"));
+    const [group, app] = heads[0];
+    if (
+      group &&
+      app &&
+      APP_GROUPS.includes(group) &&
+      heads.every(([g, a]) => g === group && a === app)
+    ) {
+      const candidate = join(worktree, group, app, ".fapony", "evidence.json");
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return join(worktree, evidenceFile(config));
+}
+
+// --- Allowlist reader ---
+
+export function readEvidenceConfig(
+  worktree: string,
+  config?: Config,
+  files: string[] = [],
+): EvidenceConfig | null {
+  const configPath = resolveEvidencePath(worktree, files, config);
+  if (!existsSync(configPath)) return null;
+
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      Array.isArray((parsed as EvidenceConfig).commands)
+    ) {
+      return parsed as EvidenceConfig;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function isValidEntry(entry: unknown): entry is EvidenceCommand {
+  return (
+    !!entry &&
+    typeof entry === "object" &&
+    typeof (entry as EvidenceCommand).cmd === "string" &&
+    (entry as EvidenceCommand).cmd.trim().length > 0
+  );
+}
+
+function effectiveTimeout(entry: EvidenceCommand): number {
+  const t = entry.timeout_ms;
+  return typeof t === "number" && Number.isFinite(t) && t > 0
+    ? t
+    : DEFAULT_TIMEOUT_MS;
+}
+
+// --- Single command runner ---
+
+interface CommandOutcome {
+  exit_code: number | null;
+  duration_ms: number;
+  timedOut: boolean;
+  errorNote?: string;
+}
+
+function runCommand(
+  cmd: string,
+  worktree: string,
+  timeoutMs: number,
+): CommandOutcome {
+  const start = Date.now();
+  try {
+    execSync(cmd, {
+      cwd: worktree,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: timeoutMs,
+    });
+    return {
+      exit_code: 0,
+      duration_ms: Date.now() - start,
+      timedOut: false,
+    };
+  } catch (e: unknown) {
+    const duration_ms = Date.now() - start;
+    if (e && typeof e === "object") {
+      const err = e as { signal?: unknown; killed?: unknown; status?: unknown };
+      // Signal kill (incl. execSync timeout → SIGTERM) or missing status
+      // means the process never exited normally — never message-sniffing:
+      // Bun reports timeouts as "spawnSync /bin/sh ETIMEDOUT" with
+      // status:null, which contains neither "timeout" nor "SIGTERM".
+      if (err.signal != null || err.killed === true || err.status === null) {
+        return { exit_code: null, duration_ms, timedOut: true };
+      }
+      if (typeof err.status === "number") {
+        return { exit_code: err.status, duration_ms, timedOut: false };
+      }
+    }
+    const msg =
+      e && typeof e === "object" && "message" in e
+        ? String((e as { message?: string }).message ?? "unknown")
+        : "unknown";
+    return {
+      exit_code: -1,
+      duration_ms,
+      timedOut: false,
+      errorNote: msg.slice(0, 200),
+    };
+  }
+}
+
+function statusFor(outcome: CommandOutcome): {
+  status: EvidenceStatus;
+  note?: string;
+} {
+  if (outcome.timedOut) return { status: "timeout" };
+  if (outcome.exit_code === 0) return { status: "passed" };
+  return { status: "failed", note: outcome.errorNote };
+}
+
+// --- Main collector ---
+
+export interface CollectOptions {
+  worktree: string;
+  /** Agent-proposed commands — recorded as unverified, never executed. */
+  agentCommands?: string[];
+  /** Changed files (repo-relative) — infers the app-scoped allowlist. */
+  files?: string[];
+  /** Config for safetyDeny(); omit for built-in defaults. */
+  config?: Config;
+}
+
+/**
+ * Collect evidence from allowlisted commands + agent-proposed claims.
+ *
+ * Execution is sequential. Per-command timeout from config (default 30s),
+ * clamped to the remaining share of the 60s total budget so one slow
+ * command cannot blow past the cap. Remaining commands after the cap →
+ * `timeout`. A command refused by assertSafe() → `failed` with the refusal
+ * as note (surfaced, never silent, never crashing the report).
+ */
+export function collectEvidence(options: CollectOptions): EvidenceItem[] {
+  const { worktree, agentCommands, files, config } = options;
+  const items: EvidenceItem[] = [];
+
+  const deny = safetyDeny(config);
+  const evidencePath = relative(
+    worktree,
+    resolveEvidencePath(worktree, files ?? [], config),
+  );
+  const evidenceConfig = readEvidenceConfig(worktree, config, files ?? []);
+  const totalStart = Date.now();
+
+  const totalTimeoutItem = (
+    command: string,
+    provenance: typeof VERIFIED_PROVENANCE | typeof AGENT_PROVENANCE,
+  ): EvidenceItem => ({
+    command,
+    status: "timeout",
+    exit_code: null,
+    duration_ms: null,
+    provenance: { ...provenance },
+    note: `total report timeout exceeded ${TOTAL_TIMEOUT_MS}ms`,
+  });
+
+  const elapsed = () => Date.now() - totalStart;
+
+  // Run allowlisted commands (verified provenance)
+  if (evidenceConfig) {
+    for (const entry of evidenceConfig.commands) {
+      if (!isValidEntry(entry)) {
+        items.push({
+          command: String(
+            (entry as { name?: unknown } | null)?.name ?? "(invalid entry)",
+          ),
+          status: "not_run",
+          exit_code: null,
+          duration_ms: null,
+          provenance: { ...VERIFIED_PROVENANCE },
+          note: `invalid entry in ${evidencePath} (cmd must be a non-empty string)`,
+        });
+        continue;
+      }
+
+      if (elapsed() >= TOTAL_TIMEOUT_MS) {
+        items.push(totalTimeoutItem(entry.cmd, VERIFIED_PROVENANCE));
+        continue;
+      }
+
+      // Rule #4: every command through assertSafe before spawn — including
+      // allowlisted ones (the file lives in agent-reachable worktree).
+      try {
+        assertSafe([entry.cmd], deny);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        items.push({
+          command: entry.cmd,
+          status: "failed",
+          exit_code: null,
+          duration_ms: null,
+          provenance: { ...VERIFIED_PROVENANCE },
+          note: msg.slice(0, 200),
+        });
+        continue;
+      }
+
+      // Clamp to remaining budget so a single slow command cannot exceed
+      // the total cap (execSync blocks; the loop-top check alone is not a
+      // hard cap for one long-timeout command).
+      const timeoutMs = Math.min(
+        effectiveTimeout(entry),
+        Math.max(TOTAL_TIMEOUT_MS - elapsed(), 1),
+      );
+      const outcome = runCommand(entry.cmd, worktree, timeoutMs);
+      const { status, note } = statusFor(outcome);
+
+      items.push({
+        command: entry.cmd,
+        status,
+        exit_code: outcome.exit_code,
+        duration_ms: outcome.duration_ms,
+        provenance: { ...VERIFIED_PROVENANCE },
+        note:
+          status === "timeout"
+            ? `exceeded ${timeoutMs}ms`
+            : (note ?? undefined),
+      });
+    }
+  }
+
+  // Agent-proposed commands: recorded as unverified claims, NEVER executed.
+  // `verified:false` means "fapony did not run this" — executing here would
+  // both lie in the provenance and hand arbitrary shell to the caller.
+  if (agentCommands) {
+    for (const cmd of agentCommands) {
+      if (typeof cmd !== "string" || cmd.trim().length === 0) continue;
+      // Already ran as allowlisted — avoid a duplicate item.
+      if (evidenceConfig?.commands.some((e) => e.cmd === cmd)) continue;
+
+      if (elapsed() >= TOTAL_TIMEOUT_MS) {
+        items.push(totalTimeoutItem(cmd, AGENT_PROVENANCE));
+        continue;
+      }
+
+      items.push({
+        command: cmd,
+        status: "unverified",
+        exit_code: null,
+        duration_ms: null,
+        provenance: { ...AGENT_PROVENANCE },
+        note: `proposed by agent — not in ${evidencePath} allowlist, not executed`,
+      });
+    }
+  }
+
+  return items;
+}