fapony 0.3.3 → 0.3.4

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,

package/src/debt/types.ts

@@ -1,79 +1,14 @@
-// src/debt/types.ts — shared types + caps for `fapony debt`.
-//
-// One convention = pattern to use (ok) + pattern meaning not-yet-migrated
-// (stale) + scope (where) + file condition (guard). Iron rule: checker not
-// null = fapony never reports that debt item — reporting twice with eslint
-// is an abstraction with one implementation (rule 1).
-
-export interface Convention {
-  id: string;
-  rule: string;
-  /** Repo-relative dir scope ("." = whole repo). */
-  where: string;
-  /** Regex source: a match means the file still has the debt. null = not derivable (checker rows) or not filled in yet. */
-  stale: string | null;
-  /** Regex source: files that already moved (informational count). */
-  ok?: string;
-  /** Regex source a file must ALSO match to be in scope (e.g. "extends Base"). */
-  guard?: string;
-  /** Non-null = a checker (eslint rule / script) exists → fapony never reports this debt. */
-  checker?: string | null;
-  /** Human answered "no checker" on the promotion question — never ask again. */
-  decided?: "no-checker" | null;
-}
-
-export interface LoadedConventions {
-  path: string | null;
-  convs: Convention[];
-  /** Rows kept for display but not scannable, plus invalid rows — said out loud, never silent. */
-  warnings: string[];
-}
-
-export interface DebtEntry {
-  conv: Convention;
-  /** Files with the debt (stale match), sorted. */
-  files: string[];
-  /** Files that already moved (ok match) — null when ok is not set. */
-  movedCount: number | null;
-}
-
-export interface DebtReport {
-  worktree: string;
-  scannedFiles: number;
-  ms: number;
-  /** Scannable conventions with their debt list (checker rows never land here). */
-  entries: DebtEntry[];
-  /** Declared but not fillable by fapony: checker null + no stale — the human/agent fills `stale`. */
-  declared: Convention[];
-  /** Skipped-with-reason: checker rows are silent by design (not dropped), these are real drops. */
-  dropped: { id: string; reason: string }[];
-  /** Silent-by-design count: checker non-null — reported as a number, not a list. */
-  checkedCount: number;
-}
-
-export interface Promotion {
-  convId: string;
-  rule: string;
-  occurrences: number;
-  dates: string[];
-  debtCount: number;
-}
-
-// A stale regex matching more than this many files is not a convention — it is
-// a broken/wide regex (stale="e" would flag the repo). SPEC §6: drop the entry
-// and say so, never report 600 files.
-export const DEBT_FILE_CAP = 250;
-
-export const PROMOTION_THRESHOLD = 3;
-export const PROMOTION_MAX = 3;
-/** Identifiers shorter than this are too generic to match prose on ("throw", "Error"). */
-export const WORD_MIN = 6;
-
-// Zone grouping: a zone is a file's *directory*, capped at this many leading
-// segments — never a fixed-depth prefix of the path (which would cut into the
-// filename) and never the filename itself. SPEC §4 shows zones at depth 5
-// (`apps/mdl/src/server/services`) and depth 3 (`packages/cache/src`) in the
-// same report, so the cap must follow the directory, not a constant.
-export const ZONE_DEPTH = 5;
-// Default cap on zones shown per convention — more than this is a wall, not an answer.
-export const ZONE_CAP = 6;
+// shim — moved to src/core/debt-types.ts
+export {
+  type Convention,
+  DEBT_FILE_CAP,
+  type DebtEntry,
+  type DebtReport,
+  type LoadedConventions,
+  PROMOTION_MAX,
+  PROMOTION_THRESHOLD,
+  type Promotion,
+  WORD_MIN,
+  ZONE_CAP,
+  ZONE_DEPTH,
+} from "../core/debt-types.js";

package/src/digest/collect.ts

@@ -10,11 +10,12 @@ import {
   doneDir,
   type Event,
   loadConfig,
-  openDb,
   planDir,
   type Run,
-} from "../db/index.js";
-import { computeHintImpact, type HintImpact, hintLogPath } from "../hook.js";
+} from "../core/config.js";
+import { type HintImpact, hintLogPath } from "../core/hint-log.js";
+import { openDb } from "../db/store.js";
+import { computeHintImpact } from "../hook.js";
 import { type MemRow, readMemLog } from "../memory.js";
 import { isPassFamily, VERDICT_GRADES } from "../parse.js";
 import { imputeResult, loadPrices } from "../price/index.js";

package/src/gate.ts

@@ -1,14 +1,14 @@
 // gateOnce is the core review-verdict logic — still live, called by the CLI
 // wrapper (cmdGate) was removed with the rest of the execute→review→fix loop
 // (Wave 2). The MCP verdict_submit tool was removed in PLAN-verdict-to-mem.
+import { loadConfig } from "./core/config.js";
 import {
   addEvent,
   getRun,
   incrementRound,
-  loadConfig,
   openDb,
   setStatus,
-} from "./db/index.js";
+} from "./db/store.js";
 import { closeMemory, kickoffMemory } from "./memory.js";
 import { isPassFamily, type VerdictGrade } from "./parse.js";
 

package/src/gates.ts

@@ -9,7 +9,7 @@
 // cumulative. Events arrive sorted (run_id, id), so one bucketing pass plus a
 // forward spawn pointer over the disjoint windows is O(events) total.
 
-import type { Event } from "./db/index.js";
+import type { Event } from "./core/config.js";
 import { qualityScore, VERDICT_GRADES, type VerdictGrade } from "./parse.js";
 import {
   findSessionAt,