fapony 0.3.3 → 0.3.4

package/src/core/config.ts

@@ -0,0 +1,199 @@
+// src/core/config.ts — pure config single source (PLAN-lib-layer chunk 4).
+// Merged from db/{defaults,types,getters,load} (shims removed — 0 importers).
+// db/ keeps only store.ts (bun:sqlite).
+// Pure = node builtins only, no imports back to features/adapters/db-store.
+
+export { DEFAULT_SAFETY_DENY } from "./defaults.js";
+
+// --- Types (ex db/types.ts — ledger frozen, types only, no logic change) ---
+
+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;
+}
+
+// --- Defaults (ex db/defaults.ts) ---
+
+// --- .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,
+};
+
+// --- Getters (ex db/getters.ts — centralized, no hardcode at call site) ---
+
+import { DEFAULT_SAFETY_DENY } from "./defaults.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;
+}
+
+// --- Load (ex db/load.ts — fs/env only, no sqlite) ---
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// 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");
+}
+
+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/core/debt-format.ts

@@ -0,0 +1,107 @@
+// src/debt/format.ts — report rendering: zone grouping + text output.
+
+import { dirname } from "node:path";
+import { type DebtReport, ZONE_CAP, ZONE_DEPTH } from "./debt-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");
+}

package/src/core/debt-types.ts

@@ -0,0 +1,79 @@
+// 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;

package/src/core/defaults.ts

@@ -0,0 +1,8 @@
+// src/core/defaults.ts — shared constants (pure, no db/state deps)
+
+export const DEFAULT_SAFETY_DENY = [
+  "reset\\s+--hard",
+  "clean\\s+-[a-z]*f",
+  "checkout\\s+--\\s",
+  "git\\s+stash",
+];

package/src/core/enums.ts

@@ -0,0 +1,34 @@
+// src/core/enums.ts — ReasonCode + RegimeCode enums (pure constants, no imports)
+//
+// Extracted from src/mcp/types.ts (PLAN-lib-layer chunk 2c) to break the
+// stats→mcp dependency. These enums are used by stats/data.ts, mcp/types.ts,
+// and context/projectHealth.ts — core is the neutral home.
+
+// --- 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];

package/src/core/format.ts

@@ -0,0 +1,33 @@
+// 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); }
+`;

package/src/core/hint-log.ts

@@ -0,0 +1,68 @@
+// src/core/hint-log.ts — hint-fire log path + write + types (pure, no feature imports)
+//
+// Extracted from src/hook.ts (PLAN-lib-layer chunk 2a) to break the
+// digest→hook coupling. computeHintImpact stays in hook.ts because it
+// imports debtForFile (feature layer).
+
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const HINT_LOG_DIR = "hint-log";
+
+/** Stable filename key from an absolute worktree path. */
+export function worktreeKey(worktree: string): string {
+  return worktree.replace(/^\/+/, "").replace(/\//g, "--");
+}
+
+/** Directory holding one hint-fire log file per worktree. */
+export function hintLogDir(): string {
+  const base =
+    process.env.FAPONY_STATE_DIR || join(homedir(), ".config", "fapony");
+  return join(base, HINT_LOG_DIR);
+}
+
+/** Absolute path of a worktree's hint-fire log — may not exist. */
+export function hintLogPath(worktree: string): string {
+  return join(hintLogDir(), `${worktreeKey(worktree)}.jsonl`);
+}
+
+export interface HintFireRow {
+  ts: string;
+  worktree: string;
+  surface: "read" | "debt" | "mem" | "commit" | "edit";
+  file: string | null;
+  count: number;
+  ids?: string[];
+}
+
+/**
+ * Append a hint-fire log row. Best-effort: never throws, never blocks.
+ * Uses $FAPONY_STATE_DIR when set (tests, CI), otherwise ~/.config/fapony.
+ */
+export function recordHintFire(row: HintFireRow): void {
+  try {
+    const dir = hintLogDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    appendFileSync(
+      hintLogPath(row.worktree),
+      `${JSON.stringify(row)}\n`,
+      "utf-8",
+    );
+  } catch {
+    // best-effort — swallow
+  }
+}
+
+export interface HintImpact {
+  fired: number;
+  by_surface: {
+    read: number;
+    debt: number;
+    mem: number;
+    commit: number;
+    edit: number;
+  };
+  debt: { shown: number; resolved: number; unknown: number };
+  window: string | null;
+}

package/src/core/hook-helpers.ts

@@ -0,0 +1,31 @@
+// src/core/hook-helpers.ts — pure helpers shared by hook adapters
+//
+// Extracted from src/hook.ts (PLAN-lib-layer chunk 3). These have zero
+// feature imports and are reused by stop, read-hint, edit-hint, and
+// session-start adapters.
+
+import { basename } from "node:path";
+
+/** UTC 'YYYY-MM-DD HH:MM:SS' — the format events.ts is written in. */
+export function utcStamp(d: Date): string {
+  return d.toISOString().slice(0, 19).replace("T", " ");
+}
+
+/**
+ * Parse either timestamp shape this repo produces: mem rows are ISO
+ * (`new Date().toISOString()`), session start is utcStamp
+ * ('YYYY-MM-DD HH:MM:SS', UTC). Never compare them as strings — 'T' > ' '
+ * makes any same-date mem row read as "newer than session start".
+ */
+export function hookTsMs(ts: string): number {
+  const iso = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(ts)
+    ? `${ts.replace(" ", "T")}Z`
+    : ts;
+  return new Date(iso).getTime();
+}
+
+/** Filename key for a session — basename of a transcript path or a raw id. */
+export function sessionKey(session: string): string {
+  const base = basename(session).replace(/\.[^.]+$/, "");
+  return base.replace(/[^A-Za-z0-9_-]/g, "-") || "unknown";
+}