fapony 0.3.3 → 0.3.5

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}`);
+    }
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,142 @@
+// src/core/types.ts — shared pure types + constants (no runtime deps)
+
+export interface ModelRates {
+  input: number;
+  output: number;
+  cacheRead: number;
+  /** null = the table does not provide it → use the input rate instead (see calcCost) */
+  cacheWrite: number | null;
+}
+
+export interface PriceTable {
+  fetched_at: string;
+  models: Record<string, ModelRates>;
+}
+
+export interface ModelBreakdown {
+  provider: string;
+  model: string;
+  session_count: number;
+  tokens_input: number;
+  tokens_output: number;
+  tokens_reasoning: number;
+  tokens_cache_read: number;
+  tokens_cache_write: number;
+  cost: number;
+}
+
+export interface SessionDetail {
+  session_id: string;
+  model: string;
+  steps: number;
+  tools: Record<string, number>;
+}
+
+export interface ToolLatencyStat {
+  count: number;
+  avgMs: number;
+}
+
+export interface StepTimingSummary {
+  /** step-finish row count (mirrors UsageDetail.steps for SQLite providers). */
+  steps: number;
+  /** Mean per-part duration from embedded data.time (row-timestamp fallback when absent). */
+  avgStepMs: number | null;
+  /** How many durations were actually measured (vs. steps with no time signal). */
+  stepSamples: number;
+  /** Mean per-step tokens — averages only, never summed (sums overlap). */
+  avgStepInput: number | null;
+  avgStepOutput: number | null;
+  avgStepCost: number | null;
+  /** Mean tool latency grouped by tool name (from data.state.time). */
+  toolLatencyMsByType: Record<string, ToolLatencyStat>;
+  note: string;
+}
+
+export interface StaleReadFile {
+  file: string;
+  /** How many distinct sessions read this file (diversity, not just count). */
+  sessions: number;
+  /** Total Read calls across those sessions. */
+  reads: number;
+}
+
+export interface UsageDetail {
+  /** Global tool-call counts across the filtered sessions (activity signal, not quality). */
+  tool_breakdown: Record<string, number>;
+  /** Context bytes per tool — size of tool_result content blocks. */
+  bytes_by_tool?: Record<string, number>;
+  /** Total step-finish parts across the filtered sessions. */
+  steps: number;
+  /** Per-session breakdown (SQL-aggregated, never raw part rows). */
+  by_session: SessionDetail[];
+  stale_reads?: StaleReadFile[];
+  note: string;
+  /** Per-step timing/token/latency signal — present only when detail:true was requested. */
+  timing?: StepTimingSummary | null;
+}
+
+export interface PassiveUsageResult {
+  total_tokens_input: number;
+  total_tokens_output: number;
+  total_tokens_reasoning: number;
+  total_tokens_cache_read: number;
+  total_tokens_cache_write: number;
+  total_cost: number;
+  session_count: number;
+  by_model: ModelBreakdown[];
+  detail?: UsageDetail | null;
+  zcode?: PassiveUsageResult | null;
+  claude_code?: PassiveUsageResult | null;
+  error?: string;
+}
+
+export const EMPTY_RESULT: PassiveUsageResult = {
+  total_tokens_input: 0,
+  total_tokens_output: 0,
+  total_tokens_reasoning: 0,
+  total_tokens_cache_read: 0,
+  total_tokens_cache_write: 0,
+  total_cost: 0,
+  session_count: 0,
+  by_model: [],
+};
+
+/** Common shape every client reader implements — see registry.ts. */
+export type PassiveUsageReader = (
+  worktree?: string,
+  since?: number,
+  until?: number,
+  detail?: boolean,
+  full?: boolean,
+) => PassiveUsageResult;
+
+export const STEP_TOKENS_NOTE =
+  "step tokens overlap (per-step context window) — SUM(step tokens) != session tokens; steps is a count only";
+
+export const TIMING_NOTE =
+  "timing from embedded part fields only (data.time/data.state.time/step-finish tokens) with row-timestamp fallback; averages, never raw I/O";
+
+// --- Tool result types (PLAN-lib-layer chunk 2d) ---
+
+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);
+}

package/src/core/util.ts

@@ -0,0 +1,105 @@
+// 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;
+}
+
+/** 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";
+}
+
+// --- 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;
+}
+
+// --- 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/src/db/store.ts

@@ -1,7 +1,7 @@
 import { Database } from "bun:sqlite";
 import { existsSync, mkdirSync } from "node:fs";
-import { faponyDir } from "./load.js";
-import type { Config, Event, Run, RunStatus } from "./types.js";
+import type { Config, Event, Run, RunStatus } from "../core/config.js";
+import { faponyDir } from "../core/config.js";
 
 /**
  * Schema version for state.db — tracked via `PRAGMA user_version`.

package/src/debt/cli.ts

@@ -4,7 +4,7 @@
 
 import { existsSync, realpathSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
-import { CONVENTIONS_FILE } from "../db/defaults.js";
+import { CONVENTIONS_FILE } from "../core/config.js";
 import { formatDebt } from "./format.js";
 import { loadConventions } from "./load.js";
 import { findPromotions, formatPromotions } from "./promotion.js";

package/src/debt/format.ts

@@ -1,107 +1,2 @@
-// src/debt/format.ts — report rendering: zone grouping + text output.
-
-import { dirname } from "node:path";
-import { type DebtReport, ZONE_CAP, ZONE_DEPTH } from "./types.js";
-
-/** The zone of a file: its directory path, capped at `depth` segments. */
-function zoneOf(file: string, depth: number): string {
-  const parts = dirname(file)
-    .split("/")
-    .filter((p) => p && p !== ".");
-  return parts.slice(0, depth).join("/") || ".";
-}
-
-/** Group files by their directory zone (see `zoneOf`). */
-function groupFilesByZone(
-  files: string[],
-  depth: number,
-): Map<string, string[]> {
-  const zones = new Map<string, string[]>();
-  for (const f of files) {
-    const zone = zoneOf(f, depth);
-    const cur = zones.get(zone) ?? [];
-    cur.push(f);
-    zones.set(zone, cur);
-  }
-  // Sort zones by file count descending, then alphabetically
-  return new Map(
-    [...zones.entries()].sort((a, b) => {
-      const d = b[1].length - a[1].length;
-      return d !== 0 ? d : a[0].localeCompare(b[0]);
-    }),
-  );
-}
-
-/** Escape a regex source for use in a shell grep command. */
-function shellEscapeRe(src: string): string {
-  return src.replace(/'/g, "'\\''");
-}
-
-export function formatDebt(report: DebtReport, showAll = false): string {
-  const lines: string[] = [];
-  lines.push(
-    `fapony debt — ${report.entries.length + report.declared.length + report.checkedCount} convention(s), ` +
-      `${report.scannedFiles} files scanned, ${report.ms}ms — derived fresh, not stored`,
-  );
-  for (const e of report.entries) {
-    const moved =
-      e.movedCount !== null && e.files.length > 0
-        ? ` · moved ${e.movedCount} (${Math.round((e.movedCount / (e.files.length + e.movedCount)) * 100)}%)`
-        : e.movedCount !== null
-          ? ` · moved ${e.movedCount}`
-          : "";
-    lines.push(`\n${e.conv.id} — ${e.conv.rule}`);
-    // Show the patterns actually used
-    const patterns: string[] = [];
-    if (e.conv.stale) patterns.push(`stale: ${e.conv.stale}`);
-    if (e.conv.ok) patterns.push(`ok: ${e.conv.ok}`);
-    if (e.conv.guard) patterns.push(`guard: ${e.conv.guard}`);
-    patterns.push(`where ${e.conv.where}`);
-    lines.push(`  ${patterns.join("  ·  ")}`);
-    if (e.files.length === 0) {
-      lines.push(`  debt 0${moved} — clean`);
-      continue;
-    }
-    lines.push(`  debt ${e.files.length}${moved}`);
-    // Verify command derived from stale
-    if (e.conv.stale) {
-      lines.push(`  verify: grep -rn '${shellEscapeRe(e.conv.stale)}' <zone>`);
-    }
-    // Zone grouping
-    const zones = groupFilesByZone(e.files, ZONE_DEPTH);
-    const zoneEntries = [...zones.entries()];
-    const cap = showAll
-      ? zoneEntries.length
-      : Math.min(zoneEntries.length, ZONE_CAP);
-    let totalCapped = 0;
-    for (let i = 0; i < cap; i++) {
-      const [zone, zoneFiles] = zoneEntries[i];
-      const pad = " ".repeat(Math.max(0, 42 - zone.length));
-      lines.push(`\n  ${zone}${pad}${zoneFiles.length} ไฟล์`);
-      lines.push(`    ${zoneFiles.map((f) => f.split("/").pop()).join(" · ")}`);
-      totalCapped += zoneFiles.length;
-    }
-    if (zoneEntries.length > cap) {
-      const remaining = e.files.length - totalCapped;
-      const remainingZones = zoneEntries.length - cap;
-      lines.push(
-        `\n  … อีก ${remainingZones} โซน (${remaining} ไฟล์) — fapony debt --id ${e.conv.id} --all`,
-      );
-    }
-  }
-  for (const c of report.declared) {
-    lines.push(`\n${c.id} — ${c.rule} (where ${c.where})`);
-    lines.push(
-      `  declared, no checker, stale not filled in — fill "stale" in conventions.json`,
-    );
-  }
-  if (report.checkedCount > 0) {
-    lines.push(
-      `\n${report.checkedCount} convention(s) have a checker — fapony stays silent, the checker reports`,
-    );
-  }
-  for (const d of report.dropped) {
-    lines.push(`⚠ ${d.id}: ${d.reason}`);
-  }
-  return lines.join("\n");
-}
+// shim — moved to src/core/debt-format.ts
+export { formatDebt } from "../core/debt-format.js";

package/src/debt/load.ts

@@ -10,7 +10,7 @@ import {
   CONVENTIONS_FILE,
   CONVENTIONS_FILENAME,
   FAPONY_DIR,
-} from "../db/defaults.js";
+} from "../core/config.js";
 import { resolveMemDir } from "../memory.js";
 import type { Convention, LoadedConventions } from "./types.js";
 

package/src/debt/promotion.ts

@@ -11,7 +11,7 @@
 // ≥ 6 chars from stale such as toLocaleString/useMutation — "throw"/"Error" are too
 // short and don't count, to avoid over-matching)
 
-import { openDb } from "../db/index.js";
+import { openDb } from "../db/store.js";
 import { readMemLog } from "../memory.js";
 import {
   type Convention,