fapony 0.3.3 → 0.3.5

package/README.md

@@ -476,6 +476,13 @@ fapony mem where                           # show the resolved mem dir and which
 fapony mem done | stale              # views
 fapony debt [--id <convention>] [--where <path>]   # ไฟล์ไหนยังไม่ย้ายไป convention ที่ประกาศไว้ (live, read-only)
 fapony lint-baseline [--cmd ...] [--diff]  # separate "already red" from "I made it red"
+
+# Hooks (wired by `fapony install`, not run by hand)
+fapony hook-stop                        # Stop hook: block turns with commits but no mem row
+fapony hook-read-hint                   # read/re-read annotations
+fapony hook-edit-hint                   # importer count before editing shape
+fapony hook-mv-guard                    # deny raw git mv of plan files into done/
+fapony hook-session-start               # SessionStart: kickoff into context
 ```
 
 *When* to call `mem add` is your project's call, not fapony's — write it in your own
@@ -501,7 +508,6 @@ fapony install --dry-run                  # show what would happen without writi
 fapony setup                             # interactive wizard: config + scaffold in one step
 fapony update                            # self-update via git pull
 fapony telemetry show|send               # opt-in only, default off — see https://github.com/kire21b/fapony/blob/main/TELEMETRY.md
-fapony test                              # self-check
 ```
 
 ## Config

package/fapony.ts

@@ -1,121 +1,8 @@
 #!/usr/bin/env bun
 
 // fapony — measure/verify MCP server for coding agents
-// CLI dispatch: all logic lives in src/
+// CLI dispatch lives in src/adapters/cli.ts
 
-import { existsSync } from "node:fs";
-import { cmdAnalyze } from "./src/analyze.js";
-import { cmdDebt } from "./src/debt/cli.js";
-import { cmdDigest } from "./src/digest/cli.js";
-import {
-  cmdHookEditHint,
-  cmdHookReadHint,
-  cmdHookSessionStart,
-  cmdHookStop,
-} from "./src/hook.js";
-import { cmdInit } from "./src/init.js";
-import { cmdInitMem } from "./src/init-mem.js";
-import { cmdInstall } from "./src/install.js";
-import { cmdLintBaseline } from "./src/lint-baseline.js";
-import { cmdMcp } from "./src/mcp/transport.js";
-import { cmdMem } from "./src/mem/index.js";
-import { initStore } from "./src/mem/store.js";
-import { cmdPriceScan } from "./src/price/index.js";
-import { cmdReport, cmdReportWeb } from "./src/report/index.js";
-import { cmdPlanSeed } from "./src/seed/plan-seed.js";
-import { cmdReviewSeed } from "./src/seed/review-seed.js";
-import { cmdSetup } from "./src/setup.js";
-import { cmdStats } from "./src/stats/index.js";
-import { cmdTelemetry } from "./src/telemetry.js";
-import { cmdUpdate } from "./src/update.js";
-import { cmdUsageScan, cmdUsageWeb } from "./src/usage/index.js";
+import { cliMain } from "./src/adapters/cli.js";
 
-const [cmd, ...a] = process.argv.slice(2);
-
-if (cmd === "analyze") {
-  cmdAnalyze(a);
-} else if (cmd === "debt") {
-  cmdDebt(a);
-} else if (cmd === "lint-baseline") {
-  cmdLintBaseline(a);
-} else if (cmd === "plan-seed") {
-  cmdPlanSeed(a);
-} else if (cmd === "review-seed") {
-  cmdReviewSeed(a);
-} else if (cmd === "digest") {
-  await cmdDigest(a);
-} else if (cmd === "stats") {
-  cmdStats(a);
-} else if (cmd === "telemetry") {
-  await cmdTelemetry(a);
-} else if (cmd === "init-mem") {
-  cmdInitMem(a);
-} else if (cmd === "mem") {
-  // `--mem-dir <path>` is global to `mem` and must reach both the writer
-  // (initStore) and the resolver behind `mem where` — parse it once and thread
-  // it through, never strip it and forget.
-  const memDirIdx = a.indexOf("--mem-dir");
-  let overrideMemDir: string | undefined;
-  let rest = a;
-  if (memDirIdx !== -1) {
-    overrideMemDir = a[memDirIdx + 1];
-    if (!overrideMemDir || overrideMemDir.startsWith("--")) {
-      console.error("fapony mem: --mem-dir needs a value");
-      process.exit(1);
-    }
-    if (!existsSync(overrideMemDir)) {
-      console.error(
-        `fapony mem: --mem-dir path does not exist: ${overrideMemDir}`,
-      );
-      process.exit(1);
-    }
-    rest = a.filter((_, i) => i !== memDirIdx && i !== memDirIdx + 1);
-  }
-  initStore(process.cwd(), overrideMemDir);
-  try {
-    await cmdMem(rest, overrideMemDir);
-  } catch (e) {
-    console.error(`fapony mem: ${e instanceof Error ? e.message : String(e)}`);
-    process.exit(1);
-  }
-} else if (cmd === "init") {
-  await cmdInit(a);
-} else if (cmd === "install") {
-  await cmdInstall(a);
-} else if (cmd === "setup") {
-  await cmdSetup();
-} else if (cmd === "update") {
-  await cmdUpdate();
-} else if (cmd === "hook-stop") {
-  await cmdHookStop();
-} else if (cmd === "hook-read-hint") {
-  await cmdHookReadHint();
-} else if (cmd === "hook-edit-hint") {
-  await cmdHookEditHint();
-} else if (cmd === "hook-session-start") {
-  await cmdHookSessionStart();
-} else if (cmd === "mcp") {
-  cmdMcp();
-} else if (cmd === "report") {
-  cmdReport(a);
-} else if (cmd === "report-web") {
-  cmdReportWeb(a);
-} else if (cmd === "usage-scan") {
-  cmdUsageScan(a);
-} else if (cmd === "price-scan") {
-  await cmdPriceScan(a);
-} else if (cmd === "usage-web") {
-  cmdUsageWeb(a);
-} else if (cmd === "test") {
-  // dynamic: src/test.js re-exports test/index.js, which the npm package
-  // doesn't ship (repo self-check only, not a published command) — a static
-  // import here would fail module load for every command, not just this one
-  const { cmdTest } = await import("./src/test.js");
-  await cmdTest();
-} else {
-  console.error(`fapony: unknown command "${cmd ?? ""}"`);
-  console.error(
-    "usage: fapony <setup|update|stats|telemetry|init|init-mem|mem|install|report|report-web|usage-scan|usage-web|price-scan|analyze|debt|lint-baseline|plan-seed|review-seed|digest|mcp|hook-stop|hook-read-hint|hook-edit-hint|hook-session-start|test> [args]",
-  );
-  process.exit(1);
-}
+cliMain();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Token usage across Claude Code, OpenCode, Codex & ZCode on one yardstick — plus a project mem log and convention-debt tracker agents query via 3 MCP tools. No server, your data stays local",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",
@@ -18,7 +18,7 @@
     "coding-agent"
   ],
   "bin": {
-    "fapony": "./fapony.ts"
+    "fapony": "fapony.ts"
   },
   "files": [
     "fapony.ts",
@@ -29,11 +29,10 @@
   "scripts": {
     "lint": "biome check .",
     "typecheck": "tsc --noEmit",
-    "test": "bun fapony.ts test",
-    "test:fast": "SKIP_SLOW=1 bun fapony.ts test",
-    "test:one": "bun scripts/test-one.ts",
+    "test": "bun test --timeout 20000 --parallel",
+    "test:changed": "bun test --timeout 20000 --changed",
     "knip": "bunx knip@6 --exclude types,nsTypes || true",
-    "check": "bun run lint && bun run typecheck && bun fapony.ts test",
+    "check": "bun run lint && bun run typecheck && bun test --timeout 20000 --parallel",
     "prepublishOnly": "bash scripts/smoke-publish.sh",
     "release": "git checkout main && git pull --ff-only && npm version patch -m 'release v%s' && git push origin main --follow-tags",
     "overview": "bun fapony.ts report-web /tmp/fapony-overview.html && open /tmp/fapony-overview.html"

package/skill/move-to-done/SKILL.md

@@ -40,8 +40,9 @@ You are about to move a PLAN that has been shipped to the archive.
    of `done/`, which is what `plan-sweep` and `kickoff` go by.
 
 2. **Run `plan-sweep --apply`** — this does the `git mv`, rewrites markdown links inside the
-   file and inbound links from other plan files, warns about plain-text mentions, and logs
-   a decision row — all in one call:
+   file and inbound links from every `.md` under `.fapony/` (`plan/`, `done/`, `spec/`),
+   warns about plain-text mentions and about tracked files outside `.fapony/` that still
+   name the file (both detect-only), and logs a decision row — all in one call:
    ```bash
    fapony mem plan-sweep <PLAN-foo.md> --apply
    ```

package/src/adapters/cli.ts

@@ -0,0 +1,128 @@
+// src/adapters/cli.ts — CLI dispatch: parse argv and route to feature modules
+//
+// Extracted from fapony.ts (PLAN-lib-layer chunk 3). The entry point
+// (fapony.ts) calls cliMain(); this file owns all feature imports and the
+// argv routing.
+
+import { existsSync } from "node:fs";
+import { cmdAnalyze } from "../analyze.js";
+import { renderUsage, suggestCommand } from "../commands.js";
+import { cmdDebt } from "../debt/cli.js";
+import { cmdDigest } from "../digest/cli.js";
+import { cmdInit } from "../init.js";
+import { cmdInitMem } from "../init-mem.js";
+import { cmdInstall } from "../install.js";
+import { cmdLintBaseline } from "../lint-baseline.js";
+import { cmdMem, MEM_SUBCOMMANDS } from "../mem/index.js";
+import { initStore } from "../mem/store.js";
+import { cmdPriceScan } from "../price/index.js";
+import { cmdReport, cmdReportWeb } from "../report/index.js";
+import { cmdPlanSeed } from "../seed/plan-seed.js";
+import { cmdReviewSeed } from "../seed/review-seed.js";
+import { cmdSetup } from "../setup.js";
+import { cmdStats } from "../stats/index.js";
+import { cmdTelemetry } from "../telemetry.js";
+import { cmdUpdate } from "../update.js";
+import { cmdUsageScan, cmdUsageWeb } from "../usage/index.js";
+import {
+  cmdHookEditHint,
+  cmdHookMvGuard,
+  cmdHookReadHint,
+  cmdHookSessionStart,
+  cmdHookStop,
+} from "./hooks/index.js";
+import { cmdMcp } from "./mcp/transport.js";
+
+export async function cliMain(): Promise<void> {
+  const [cmd, ...a] = process.argv.slice(2);
+
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    console.log(renderUsage());
+    return;
+  }
+
+  if (cmd === "analyze") {
+    cmdAnalyze(a);
+  } else if (cmd === "debt") {
+    cmdDebt(a);
+  } else if (cmd === "lint-baseline") {
+    cmdLintBaseline(a);
+  } else if (cmd === "plan-seed") {
+    cmdPlanSeed(a);
+  } else if (cmd === "review-seed") {
+    cmdReviewSeed(a);
+  } else if (cmd === "digest") {
+    await cmdDigest(a);
+  } else if (cmd === "stats") {
+    cmdStats(a);
+  } else if (cmd === "telemetry") {
+    await cmdTelemetry(a);
+  } else if (cmd === "init-mem") {
+    cmdInitMem(a);
+  } else if (cmd === "mem") {
+    const memDirIdx = a.indexOf("--mem-dir");
+    let overrideMemDir: string | undefined;
+    let rest = a;
+    if (memDirIdx !== -1) {
+      overrideMemDir = a[memDirIdx + 1];
+      if (!overrideMemDir || overrideMemDir.startsWith("--")) {
+        console.error("fapony mem: --mem-dir needs a value");
+        process.exit(1);
+      }
+      if (!existsSync(overrideMemDir)) {
+        console.error(
+          `fapony mem: --mem-dir path does not exist: ${overrideMemDir}`,
+        );
+        process.exit(1);
+      }
+      rest = a.filter((_, i) => i !== memDirIdx && i !== memDirIdx + 1);
+    }
+    initStore(process.cwd(), overrideMemDir);
+    try {
+      await cmdMem(rest, overrideMemDir);
+    } catch (e) {
+      console.error(
+        `fapony mem: ${e instanceof Error ? e.message : String(e)}`,
+      );
+      process.exit(1);
+    }
+  } else if (cmd === "init") {
+    await cmdInit(a);
+  } else if (cmd === "install") {
+    await cmdInstall(a);
+  } else if (cmd === "setup") {
+    await cmdSetup();
+  } else if (cmd === "update") {
+    await cmdUpdate();
+  } else if (cmd === "hook-stop") {
+    await cmdHookStop();
+  } else if (cmd === "hook-read-hint") {
+    await cmdHookReadHint();
+  } else if (cmd === "hook-edit-hint") {
+    await cmdHookEditHint();
+  } else if (cmd === "hook-mv-guard") {
+    await cmdHookMvGuard();
+  } else if (cmd === "hook-session-start") {
+    await cmdHookSessionStart();
+  } else if (cmd === "mcp") {
+    cmdMcp();
+  } else if (cmd === "report") {
+    cmdReport(a);
+  } else if (cmd === "report-web") {
+    cmdReportWeb(a);
+  } else if (cmd === "usage-scan") {
+    cmdUsageScan(a);
+  } else if (cmd === "price-scan") {
+    await cmdPriceScan(a);
+  } else if (cmd === "usage-web") {
+    cmdUsageWeb(a);
+  } else {
+    console.error(`fapony: unknown command "${cmd ?? ""}"`);
+    const hints = suggestCommand(cmd ?? "", MEM_SUBCOMMANDS);
+    if (hints.length > 0) {
+      console.error(`did you mean ${hints.map((h) => `"${h}"`).join(" or ")}?`);
+    }
+    console.error(`usage: fapony <command> [args] — see "fapony --help"`);
+    process.exit(1);
+  }
+}

package/src/adapters/hooks/compute-hint-impact.ts

@@ -0,0 +1,107 @@
+// src/adapters/hooks/compute-hint-impact.ts — hint-fire impact computation
+//
+// Split from src/hook.ts (PLAN-lib-layer chunk 3). Reads hint log + re-runs
+// debt detection to count resolved vs unresolved hints.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import {
+  type HintFireRow,
+  type HintImpact,
+  hintLogDir,
+  worktreeKey,
+} from "../../core/hint-log.js";
+import { debtForFile, loadConventions } from "../../debt/index.js";
+
+/**
+ * Compute hint-fire impact from the log. `since` is an ISO date string;
+ * omit to scan all rows. `worktree` scopes to one project's log file.
+ */
+export function computeHintImpact(
+  since?: string,
+  worktree?: string,
+): HintImpact {
+  const dir = hintLogDir();
+  const impact: HintImpact = {
+    fired: 0,
+    by_surface: { read: 0, debt: 0, mem: 0, commit: 0, edit: 0 },
+    debt: { shown: 0, resolved: 0, unknown: 0 },
+    window: since ?? null,
+  };
+
+  if (!existsSync(dir)) return impact;
+
+  let files: string[];
+  try {
+    const all = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+    files = worktree
+      ? all.filter((f) => f === `${worktreeKey(worktree)}.jsonl`)
+      : all;
+  } catch {
+    return impact;
+  }
+
+  const debtShown = new Map<string, true>();
+  const debtByFile = new Map<string, string[]>();
+
+  for (const file of files) {
+    let content: string;
+    try {
+      content = readFileSync(join(dir, file), "utf-8");
+    } catch {
+      continue;
+    }
+    for (const line of content.split("\n")) {
+      if (!line) continue;
+      let row: HintFireRow;
+      try {
+        row = JSON.parse(line) as HintFireRow;
+      } catch {
+        continue;
+      }
+      if (since && row.ts < since) continue;
+      impact.fired++;
+      impact.by_surface[row.surface]++;
+
+      if (row.surface === "debt" && row.ids && row.file) {
+        const key = `${row.worktree}\t${row.file}`;
+        const existing = debtByFile.get(key) ?? [];
+        for (const id of row.ids) {
+          const dk = `${row.worktree}\t${row.file}\t${id}`;
+          if (!debtShown.has(dk)) {
+            debtShown.set(dk, true);
+            existing.push(id);
+          }
+        }
+        debtByFile.set(key, existing);
+      }
+    }
+  }
+
+  for (const [key, ids] of debtByFile) {
+    const [worktree, file] = key.split("\t");
+    const absFile = join(worktree, file);
+    let currentIds: Set<string>;
+    try {
+      if (!statSync(absFile).isFile()) {
+        impact.debt.unknown += ids.length;
+        continue;
+      }
+      const convs = debtForFile(worktree, absFile, loadConventions(worktree));
+      currentIds = new Set(convs.map((c) => c.id));
+    } catch {
+      impact.debt.unknown += ids.length;
+      continue;
+    }
+    for (const id of ids) {
+      impact.debt.shown++;
+      if (currentIds.has(id)) {
+        // still present — not resolved
+      } else {
+        impact.debt.resolved++;
+      }
+    }
+  }
+
+  return impact;
+}

package/src/adapters/hooks/context-data.ts

@@ -0,0 +1,102 @@
+// src/adapters/hooks/context-data.ts — shared debt + mem context reader
+//
+// Split from src/hook.ts (PLAN-lib-layer chunk 3). Used by both read-hint and
+// edit-hint adapters to attach debt/mem lines when a file is open.
+
+import { realpathSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { collectSourceFiles, SCAN_EXTS } from "../../analyze.js";
+import { debtForFile, loadConventions } from "../../debt/index.js";
+import { readMemLog } from "../../memory.js";
+
+const DEBT_HINT_MAX = 3;
+const MEM_HINT_MAX = 2;
+const MEM_TEXT_MAX = 120;
+
+export interface ContextLineData {
+  worktree: string;
+  debtIds: string[];
+  debtLines: string[];
+  memLines: string[];
+}
+
+/** Structured data behind readContextLines — used by cmdHookReadHint for logging. */
+export function readContextData(
+  filePath: unknown,
+  cwd: string,
+): ContextLineData | null {
+  try {
+    if (typeof filePath !== "string" || filePath === "") return null;
+    const git = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (git.exitCode !== 0) return null;
+    const worktree = realpathSync(git.stdout.toString().trim());
+    const abs = realpathSync(
+      filePath.startsWith("/") ? filePath : join(worktree, filePath),
+    );
+    const rel = relative(worktree, abs).split("\\").join("/");
+    if (rel.startsWith("..") || rel === "") return null;
+
+    const debtIds: string[] = [];
+    const debtLines: string[] = [];
+    const memLines: string[] = [];
+
+    // convention debt — source files only, fresh from the repo
+    const dot = rel.lastIndexOf(".");
+    if (dot >= 0 && SCAN_EXTS.has(rel.slice(dot))) {
+      for (const c of debtForFile(
+        worktree,
+        abs,
+        loadConventions(worktree),
+      ).slice(0, DEBT_HINT_MAX)) {
+        debtIds.push(c.id);
+        debtLines.push(`fapony debt: [${c.id}] ${c.rule}`);
+      }
+    }
+
+    // mem rows that are about this file
+    const mem = readMemLog(worktree);
+    if (mem.rows.length > 0) {
+      const base = basename(rel);
+      const direct: typeof mem.rows = [];
+      const baseOnly: typeof mem.rows = [];
+      for (const r of mem.rows) {
+        if (r.kind === "claim" || r.kind === "release") continue;
+        const hay = `${r.text}\n${r.spec ?? ""}\n${(r.files ?? []).join(",")}`;
+        if ((r.files ?? []).includes(rel) || hay.includes(rel)) {
+          direct.push(r);
+          continue;
+        }
+        if (base && hay.includes(base)) baseOnly.push(r);
+      }
+      let usableBase = baseOnly;
+      if (baseOnly.length > 0) {
+        const sameName = collectSourceFiles(worktree).filter(
+          (f) => basename(f) === base,
+        ).length;
+        if (sameName !== 1) usableBase = [];
+      }
+      const memHits = [...direct, ...usableBase].slice(0, MEM_HINT_MAX);
+      for (const r of memHits) {
+        memLines.push(
+          `fapony mem: ${r.ts.slice(0, 10)} ${r.kind} — ${r.text.slice(0, MEM_TEXT_MAX)}`,
+        );
+      }
+    }
+    return { worktree, debtIds, debtLines, memLines };
+  } catch {
+    return null;
+  }
+}
+
+export function readContextLines(filePath: unknown, cwd: string): string[] {
+  const data = readContextData(filePath, cwd);
+  if (!data) return [];
+  return [...data.debtLines, ...data.memLines].slice(
+    0,
+    DEBT_HINT_MAX + MEM_HINT_MAX,
+  );
+}