fapony 0.3.0 → 0.3.4

package/src/core/mem-log.ts

@@ -0,0 +1,357 @@
+// src/core/mem-log.ts — mem-log reader: directory discovery + JSONL parsing (pure, no feature imports)
+//
+// Extracted from src/memory.ts (PLAN-lib-layer chunk 2b). Shell adapter
+// helpers (closeMemory, kickoffMemory, claimMemory) stay in memory.ts.
+
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import {
+  CONFIG_FILENAME,
+  DEFAULT_MEM_DIR,
+  FAPONY_DIR,
+  loadConfig,
+} from "./config.js";
+
+export interface MemRow {
+  ts: string;
+  agent: string;
+  kind: string;
+  text: string;
+  spec?: string;
+  id?: string;
+  ref?: string;
+  /** Files the row is about — written by `mem add --files` (PLAN-convention-debt chunk 3). */
+  files?: string[];
+}
+
+interface RawMemRow {
+  ts?: string;
+  agent?: string;
+  kind?: string;
+  text?: string;
+  spec?: string;
+  id?: string;
+  ref?: string;
+  files?: unknown;
+}
+
+/**
+ * A directory is a mem dir only when it holds a `log.jsonl` or a named
+ * `log.<person>.jsonl` (rotated `log.YYYY-MM-DD.jsonl` archives count too).
+ * A `.fapony/.memory/` scaffolded empty by `fapony init` is not a candidate —
+ * otherwise it would shadow an ancestor that holds the real log (SPEC §1).
+ */
+function hasMemLogs(dir: string): boolean {
+  try {
+    return readdirSync(dir).some(
+      (f) => f === "log.jsonl" || /^log\.[A-Za-z0-9._-]+\.jsonl$/.test(f),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Physical path (symlinks resolved) so start and repo root compare like with
+ *  like; falls back to a lexical resolve when the path does not exist yet. */
+function physical(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+/** `git rev-parse --show-toplevel` from a directory, or null outside a repo. */
+function gitRootOf(fromDir: string): string | null {
+  try {
+    const { execSync } =
+      require("node:child_process") as typeof import("node:child_process");
+    const root = execSync("git rev-parse --show-toplevel", {
+      cwd: fromDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return root || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The lexical ancestor of `fromDir` that is the git repo root, or null outside
+ * a repo. `git rev-parse` returns a physical path (it resolves /var → /private/
+ * var on macOS), so the walk compares `physical(dir)` against it and returns the
+ * path in the caller's own lexical form — the returned dir must match what the
+ * caller passed in, not a canonicalized stranger.
+ */
+function repoRootOf(fromDir: string): string | null {
+  const start = resolve(fromDir);
+  const gitRoot = gitRootOf(start);
+  if (!gitRoot) return null;
+  const physicalRoot = physical(gitRoot);
+  let dir = start;
+  while (true) {
+    if (physical(dir) === physicalRoot) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Locate the nearest `.fapony/.memory/` by walking up from `fromDir`.
+ *
+ * The walk stops at the git repo root (SPEC §1) — a mem dir in a parent
+ * checkout is never ours. Outside a repo it stops at the filesystem root.
+ * `acceptEmpty` is for the default-wiring check, which only needs the dir the
+ * writer will use (log or not); the resolver itself requires a real log.
+ */
+export function walkUpForMemDir(
+  fromDir: string,
+  acceptEmpty: boolean,
+): string | null {
+  const start = resolve(fromDir);
+  const boundary = repoRootOf(start) ?? "/";
+  let dir = start;
+  while (true) {
+    const candidate = join(dir, DEFAULT_MEM_DIR);
+    if (existsSync(candidate) && (acceptEmpty || hasMemLogs(candidate))) {
+      return candidate;
+    }
+    if (dir === boundary) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export interface MemDirResult {
+  dir: string | null;
+  step: "flag" | "config" | "walk-up" | "repo-root" | "ambiguous" | "none";
+  candidates?: string[];
+}
+
+// Dirs that never hold a project mem log and are expensive to walk.
+const SCAN_SKIP = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+  "vendor",
+  "out",
+  "target",
+  ".next",
+  ".turbo",
+  ".cache",
+]);
+
+/**
+ * Every `.fapony/.memory/` under `root` that holds a real log, bounded to a
+ * shallow walk. Used only to detect the ambiguous monorepo layout (SPEC §1
+ * fail example): if two or more app-scoped logs exist and nothing at/above cwd
+ * holds one, the caller must refuse rather than start a third log at the root.
+ */
+function findMemDirsUnder(root: string): string[] {
+  const found: string[] = [];
+  const walk = (dir: string, depth: number): void => {
+    if (depth > 5) return;
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (e.name === FAPONY_DIR) {
+        const candidate = join(dir, DEFAULT_MEM_DIR);
+        if (hasMemLogs(candidate)) found.push(candidate);
+        continue;
+      }
+      if (e.name.startsWith(".") || SCAN_SKIP.has(e.name)) continue;
+      walk(join(dir, e.name), depth + 1);
+    }
+  };
+  walk(root, 0);
+  return found;
+}
+
+/**
+ * The single resolver: returns the mem dir and which step won.
+ *
+ * Resolution order (SPEC §1):
+ *   1. `--mem-dir <path>` (wins over everything)
+ *   2. `paths.memDir` in the **repo-root** `fapony.config.json` (relative to root)
+ *   3. walk up from cwd for the first `.fapony/.memory/` that holds a real log
+ *   4. `<repo root>/.fapony/.memory/`
+ */
+function resolveMemDirFrom(
+  fromDir: string,
+  explicitOverride?: string,
+): MemDirResult {
+  // Step 1: --mem-dir flag
+  if (explicitOverride) {
+    return {
+      dir: existsSync(explicitOverride) ? resolve(explicitOverride) : null,
+      step: "flag",
+    };
+  }
+
+  const cwd = resolve(fromDir);
+  const root = repoRootOf(cwd);
+
+  // Step 2: paths.memDir in the repo-root config
+  const configDir = root ?? cwd;
+  try {
+    const configPath = join(configDir, CONFIG_FILENAME);
+    if (existsSync(configPath)) {
+      const config = loadConfig(configPath);
+      if (config?.paths?.memDir) {
+        const absCfg = isAbsolute(config.paths.memDir)
+          ? config.paths.memDir
+          : join(configDir, config.paths.memDir);
+        if (existsSync(absCfg)) return { dir: absCfg, step: "config" };
+      }
+    }
+  } catch {
+    // no config or unreadable — continue
+  }
+
+  // Step 3: walk up from cwd, only a dir with a real log counts
+  const walked = walkUpForMemDir(cwd, false);
+  if (walked) return { dir: walked, step: "walk-up" };
+
+  // Guard (SPEC §1 fail example)
+  const candidates = root ? findMemDirsUnder(root) : [];
+  if (candidates.length >= 2) {
+    return { dir: null, step: "ambiguous", candidates };
+  }
+  const outOfScope = candidates.length ? { candidates } : {};
+
+  // Step 4: <repo root>/.fapony/.memory/
+  if (root) {
+    const rootDir = join(root, DEFAULT_MEM_DIR);
+    if (existsSync(rootDir)) {
+      return { dir: rootDir, step: "repo-root", ...outOfScope };
+    }
+  }
+
+  return { dir: null, step: "none", ...outOfScope };
+}
+
+export function resolveMemDir(
+  worktree?: string,
+  explicitOverride?: string,
+): string | null {
+  return resolveMemDirFrom(worktree ?? process.cwd(), explicitOverride).dir;
+}
+
+/** Resolve and report which step won — for `fapony mem where`. */
+export function whereMemDir(
+  fromDir?: string,
+  explicitOverride?: string,
+): MemDirResult {
+  return resolveMemDirFrom(fromDir ?? process.cwd(), explicitOverride);
+}
+
+/**
+ * Read every `log*.jsonl` row under the worktree's memory dir, newest first.
+ * `sinceIso` (exclusive) drops older rows; omit it to read the whole log.
+ * Malformed/unreadable rows are counted, never thrown — a corrupt line must
+ * not take down the caller.
+ */
+export function readMemLog(
+  worktree: string,
+  sinceIso?: string,
+): { rows: MemRow[]; skipped: number; filesFound: number } {
+  const dir = resolveMemDir(worktree);
+  if (!dir) return { rows: [], skipped: 0, filesFound: 0 };
+
+  const isLogFile = (f: string): boolean =>
+    f === "log.jsonl" || /^log\.[A-Za-z0-9._-]+\.jsonl$/.test(f);
+
+  let files: string[];
+  try {
+    files = readdirSync(dir)
+      .filter(isLogFile)
+      .sort()
+      .map((f) => join(dir, f));
+  } catch {
+    return { rows: [], skipped: 0, filesFound: 0 };
+  }
+
+  if (files.length === 0) return { rows: [], skipped: 0, filesFound: 0 };
+
+  let skipped = 0;
+  const all: MemRow[] = [];
+
+  for (const file of files) {
+    let raw: string;
+    try {
+      raw = readFileSync(file, "utf-8");
+    } catch {
+      continue;
+    }
+    const lines = raw.split("\n").filter(Boolean);
+    for (const line of lines) {
+      let parsed: RawMemRow;
+      try {
+        parsed = JSON.parse(line) as RawMemRow;
+      } catch {
+        skipped++;
+        continue;
+      }
+      if (!parsed.ts || !parsed.kind) {
+        skipped++;
+        continue;
+      }
+      if (sinceIso && parsed.ts < sinceIso) continue;
+      all.push({
+        ts: parsed.ts,
+        agent: parsed.agent ?? "unknown",
+        kind: parsed.kind,
+        text: parsed.text ?? "",
+        spec: parsed.spec,
+        id: parsed.id,
+        ref: parsed.ref,
+        ...(Array.isArray(parsed.files)
+          ? { files: parsed.files.filter((f) => typeof f === "string") }
+          : {}),
+      });
+    }
+  }
+
+  all.sort((a, b) => b.ts.localeCompare(a.ts)); // newest first
+  return { rows: all, skipped, filesFound: files.length };
+}
+
+/**
+ * Decisions for the pre-edit context summary — newest first, capped at `limit`.
+ */
+export function readRecentMemDecisions(
+  worktree: string,
+  limit: number,
+  keywords?: string[],
+): MemRow[] {
+  let decisions: MemRow[];
+  try {
+    decisions = readMemLog(worktree).rows.filter((r) => r.kind === "decision");
+  } catch {
+    return [];
+  }
+  if (decisions.length === 0) return [];
+
+  const kws = (keywords ?? [])
+    .map((k) => k.toLowerCase())
+    .filter((k) => k.length > 0);
+  if (kws.length > 0) {
+    const hits = decisions.filter((r) => {
+      const hay = `${r.text}\n${r.spec ?? ""}`.toLowerCase();
+      return kws.some((k) => hay.includes(k));
+    });
+    if (hits.length > 0) return hits.slice(0, limit);
+  }
+  return decisions.slice(0, limit);
+}

package/src/core/parse.ts

@@ -0,0 +1,71 @@
+// src/parse.ts — grades, scores, and gate-event JSON parsing.
+// Marker-text parsers (parseGateVerdict/parsePlanUpdate) were removed with the
+// CLI loop: nothing produces VERDICT:/NEXT-PROMPT/FILE_DONE stdout anymore —
+// gate events are JSON, read via parseGateEventData.
+
+/** Locked grade vocabulary — additive-only (append, never rename/remove). */
+export type VerdictGrade =
+  | "pass-excellent"
+  | "pass-good"
+  | "pass-adequate"
+  | "pass"
+  | "fail"
+  | "uncertain";
+
+export const VERDICT_GRADES: ReadonlySet<string> = new Set<VerdictGrade>([
+  "pass-excellent",
+  "pass-good",
+  "pass-adequate",
+  "pass",
+  "fail",
+  "uncertain",
+]);
+
+/** True when verdict belongs to the pass family (any pass-* variant). */
+export function isPassFamily(v: string): v is VerdictGrade {
+  return v.startsWith("pass");
+}
+
+/**
+ * Locked qualityScore mapping — read-time only (never written to events).
+ * Values from SPEC-verdict-protocol §qualityScore (additive-only, never change).
+ */
+const SCORE_MAP: Record<VerdictGrade, number> = {
+  "pass-excellent": 5,
+  "pass-good": 4,
+  "pass-adequate": 3,
+  pass: 3,
+  fail: 0,
+  uncertain: 1,
+};
+
+export function qualityScore(grade: VerdictGrade): number {
+  return SCORE_MAP[grade] ?? 0;
+}
+
+export interface GateVerdict {
+  verdict: VerdictGrade;
+  note: string;
+}
+
+/**
+ * Read a verdict back from a stored gate event (`kind='gate'`).
+ * Gate events are JSON (`{verdict, note, round}` from gateOnce) — NOT
+ * reviewer stdout. Returns null for missing/unparseable data or unknown grades.
+ */
+export function parseGateEventData(data: string | null): GateVerdict | null {
+  if (!data) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const { verdict, note } = parsed as { verdict?: unknown; note?: unknown };
+  if (typeof verdict !== "string" || !VERDICT_GRADES.has(verdict)) return null;
+  return {
+    verdict: verdict as VerdictGrade,
+    note: typeof note === "string" ? note : "",
+  };
+}

package/src/core/pricing.ts

@@ -0,0 +1,217 @@
+// src/price/resolve.ts — normalize model id + compute list-price equivalent
+//
+// Hard rule: an unmappable model must be unpriced, never silently counted as 0 (the main failure mode
+// of this feature) · free only applies to things that truly cost 0 (local / :free rows in the table)
+
+import type {
+  ModelBreakdown,
+  ModelRates,
+  PassiveUsageResult,
+  PriceTable,
+} from "./types.js";
+
+export type PriceStatus = "priced" | "free" | "unpriced";
+
+export interface PriceResolution {
+  status: PriceStatus;
+  rates: ModelRates | null;
+}
+
+/** client prefix prepended to every model id — strip it, then look up again */
+const CLIENT_PREFIXES = ["openrouter/", "opencode-go/", "opencode/"];
+
+/** OpenRouter's trailing tier — :free is a genuinely free endpoint, :batch is a discount */
+function stripTier(id: string): string {
+  return id.endsWith(":free") || id.endsWith(":batch")
+    ? id.slice(0, id.lastIndexOf(":"))
+    : id;
+}
+
+/**
+ * Candidate ids ordered by specificity: exact first, broad later
+ * (an exact match always wins — the bare slug is the broadest match and goes last)
+ */
+export function candidateIds(provider: string, model: string): string[] {
+  const full = provider ? `${provider}/${model}` : model;
+  const out: string[] = [full];
+  let rest = full;
+  for (const p of CLIENT_PREFIXES) {
+    if (rest.startsWith(p)) {
+      rest = rest.slice(p.length);
+      out.push(rest);
+      break;
+    }
+  }
+  // opencode appends -free to the slug of a free model (deepseek-v4-flash-free)
+  if (rest.endsWith("-free")) out.push(rest.slice(0, -"-free".length));
+  return out;
+}
+
+/**
+ * Find rates for one model — null only for local, which skips the table
+ * (local never had a price to begin with, it is not "not found")
+ */
+function isLocalProvider(provider: string): boolean {
+  return provider === "lmstudio_local";
+}
+
+export function resolvePrice(
+  provider: string,
+  model: string,
+  table: PriceTable,
+): PriceResolution {
+  if (!model || model === "(no model id)" || model === "(unknown)")
+    return { status: "unpriced", rates: null };
+  if (isLocalProvider(provider)) return { status: "free", rates: null };
+  // ends with :free or -free = used a free endpoint / the client's free model
+  // the real price is 0 (not list price), whether or not OpenRouter maps it
+  if (model.endsWith(":free") || model.endsWith("-free"))
+    return { status: "free", rates: null };
+  for (const id of candidateIds(provider, model)) {
+    const rates = table.models[id] ?? table.models[stripTier(id)];
+    if (rates) {
+      // an all-zero rate row (:free / free model) = genuinely free, not unpriced
+      if (
+        rates.input === 0 &&
+        rates.output === 0 &&
+        rates.cacheRead === 0 &&
+        (rates.cacheWrite ?? 0) === 0
+      )
+        return { status: "free", rates };
+      return { status: "priced", rates };
+    }
+  }
+  // zcode stores only the slug with no vendor (GLM-5.3-Flash) — compare the suffix / exact
+  // case-insensitive match (exact, not fuzzy: the whole string must be equal in length)
+  // the table side strips the tier (:free/:batch) before comparing — so a bare slug hits the :free
+  // row that is truly 0 (e.g. ling-3.0-flash-fin) and becomes free, not unpriced
+  const slug = stripTier(
+    candidateIds(provider, model).at(-1) ?? "",
+  ).toLowerCase();
+  if (slug) {
+    const ids = Object.keys(table.models).sort();
+    for (const id of ids) {
+      const rawSuffix = id.includes("/")
+        ? id.slice(id.lastIndexOf("/") + 1)
+        : id;
+      if (stripTier(rawSuffix).toLowerCase() === slug) {
+        const rates = table.models[id];
+        if (
+          rates.input === 0 &&
+          rates.output === 0 &&
+          rates.cacheRead === 0 &&
+          (rates.cacheWrite ?? 0) === 0
+        )
+          return { status: "free", rates };
+        return { status: "priced", rates };
+      }
+    }
+  }
+  return { status: "unpriced", rates: null };
+}
+
+export interface TokenCounts {
+  input: number;
+  cacheRead: number;
+  cacheWrite: number;
+  output: number;
+}
+
+/**
+ * Pure costing: separate rates for input / cache-read / cache-write — never one rate for all
+ *
+ * reasoning is not multiplied separately: Anthropic-family thinking is already included in output
+ * (the reader keeps it separately just for visibility); multiplying separately = double counting · cache_write absent from the table
+ * → fall back to the input rate (writing cache costs more than or equal to a fresh read, never less)
+ */
+export function calcCost(t: TokenCounts, rates: ModelRates): number {
+  return (
+    t.input * rates.input +
+    t.cacheRead * rates.cacheRead +
+    t.cacheWrite * (rates.cacheWrite ?? rates.input) +
+    t.output * rates.output
+  );
+}
+
+export interface ImputedModel {
+  provider: string;
+  model: string;
+  session_count: number;
+  tokens_input: number;
+  tokens_output: number;
+  tokens_cache_read: number;
+  tokens_cache_write: number;
+  status: PriceStatus;
+  /** dollars at list-price — 0 when free/unpriced (check status, do not read the number alone) */
+  imputed_cost: number;
+}
+
+export interface ImputeSummary {
+  total_imputed: number;
+  priced_sessions: number;
+  free_sessions: number;
+  unpriced_sessions: number;
+  unpriced_tokens: number;
+  by_model: ImputedModel[];
+}
+
+/**
+ * Price an entire PassiveUsageResult — works on live results (stats/usage) or cache rows
+ * (usage-web) alike, because it only takes tokens per model
+ */
+export function imputeResult(
+  result: PassiveUsageResult,
+  table: PriceTable,
+): ImputeSummary {
+  const by_model: ImputedModel[] = [];
+  let total_imputed = 0;
+  let priced_sessions = 0;
+  let free_sessions = 0;
+  let unpriced_sessions = 0;
+  let unpriced_tokens = 0;
+  for (const m of result.by_model as ModelBreakdown[]) {
+    const r = resolvePrice(m.provider, m.model, table);
+    let cost = 0;
+    if (r.status === "priced" && r.rates) {
+      cost = calcCost(
+        {
+          input: m.tokens_input,
+          cacheRead: m.tokens_cache_read,
+          cacheWrite: m.tokens_cache_write,
+          output: m.tokens_output,
+        },
+        r.rates,
+      );
+      total_imputed += cost;
+      priced_sessions += m.session_count;
+    } else if (r.status === "free") {
+      free_sessions += m.session_count;
+    } else {
+      unpriced_sessions += m.session_count;
+      unpriced_tokens +=
+        m.tokens_input +
+        m.tokens_output +
+        m.tokens_cache_read +
+        m.tokens_cache_write;
+    }
+    by_model.push({
+      provider: m.provider,
+      model: m.model,
+      session_count: m.session_count,
+      tokens_input: m.tokens_input,
+      tokens_output: m.tokens_output,
+      tokens_cache_read: m.tokens_cache_read,
+      tokens_cache_write: m.tokens_cache_write,
+      status: r.status,
+      imputed_cost: cost,
+    });
+  }
+  return {
+    total_imputed,
+    priced_sessions,
+    free_sessions,
+    unpriced_sessions,
+    unpriced_tokens,
+    by_model,
+  };
+}

package/src/core/safety.ts

@@ -0,0 +1,18 @@
+// src/safety.ts — deny-list for dangerous git commands.
+// Rule: assertSafe() must be called on every command before spawn, including
+// ones built from config templates (memory claim/close/add, evidence
+// collector commands, install's `claude mcp add`).
+// Patterns come from config.safety.deny (regex sources); built-in default
+// covers the 4 known-destructive git invocations.
+
+import { DEFAULT_SAFETY_DENY } from "./defaults.js";
+
+export function assertSafe(argv: string[], denySources?: string[]): void {
+  const sources = denySources ?? DEFAULT_SAFETY_DENY;
+  const joined = argv.join(" ");
+  for (const src of sources) {
+    if (new RegExp(src).test(joined)) {
+      throw new Error(`refusing to run dangerous command: ${joined}`);
+    }
+  }
+}