fapony 0.6.0 → 0.6.2

package/README.md

@@ -4,7 +4,7 @@
 
 # fapony
 
-[![npm](https://img.shields.io/npm/v/fapony.svg)](https://www.npmjs.com/package/fapony)
+[![npm](https://img.shields.io/npm/v/fapony.svg)](https://www.npmjs.com/package/fapony) [![GitHub](https://img.shields.io/github/stars/kire21b/fapony.svg)](https://github.com/kire21b/fapony)
 
 **See what your coding agents actually cost.** fapony reads the session logs Claude Code, Codex,
 OpenCode and ZCode already write, and puts them all on one yardstick — tokens, cost and time per
@@ -99,7 +99,11 @@ fapony install --all        # skip the prompt, wire everything detected
 # 4. Turn on the memory layer (per project you want it in)
 fapony init /path/to/your-worktree
 #    creates .fapony/ — .memory/ (the mem log the 3 MCP tools read and write)
-#    and conventions.json for `fapony debt` (shared rules: commit them)
+#    and conventions.json for `fapony debt` (shared rules: commit them),
+#    then offers to write the memory rules into CLAUDE.md / AGENTS.md
+#    (none yet = AGENTS.md + a CLAUDE.md that imports it) — agents only log
+#    what the rules they already read tell them to
+fapony init /path/to/your-worktree --rules --yes   # repo already set up: rules only, no prompt
 ```
 
 …or add it manually to any MCP client: `{ "mcpServers": { "fapony": { "command": "fapony", "args": ["mcp"] } } }`. Full protocol and adapter examples: [docs/mcp-handcheck.md](https://github.com/kire21b/fapony/blob/main/docs/mcp-handcheck.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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)",

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

@@ -19,6 +19,8 @@ export interface ContextLineData {
   memLines: string[];
   /** Ids of open bugs actually emitted as OPEN BUG lines above (for the fire log). */
   openBugIds: string[];
+  /** Ids of every mem row emitted in memLines (open bugs first) — joined to authors offline. */
+  memIds: string[];
 }
 
 /** Structured data behind readContextLines — used by cmdHookReadHint for logging. */
@@ -45,6 +47,7 @@ export function readContextData(
     const debtLines: string[] = [];
     const memLines: string[] = [];
     const openBugIds: string[] = [];
+    const memIds: string[] = [];
 
     // convention debt — source files only, fresh from the repo. The scope
     // pairs the git root (repo-relative `where`) with the nearest
@@ -112,13 +115,15 @@ export function readContextData(
         .filter((r) => !(r.id && emitted.has(r.id)))
         .slice(0, MEM_HINT_MAX - openLines.length);
       for (const line of openLines) memLines.push(line);
+      memIds.push(...openBugIds);
       for (const r of rest) {
+        if (r.id) memIds.push(r.id);
         memLines.push(
           `fapony mem: ${r.ts.slice(0, 10)} ${r.kind} — ${r.text.slice(0, MEM_TEXT_MAX)}`,
         );
       }
     }
-    return { worktree, debtIds, debtLines, memLines, openBugIds };
+    return { worktree, debtIds, debtLines, memLines, openBugIds, memIds };
   } catch {
     return null;
   }

package/src/adapters/hooks/edit-hint.ts

@@ -184,6 +184,16 @@ export async function cmdHookEditHint(): Promise<void> {
             file: rel && !rel.startsWith("..") ? rel : null,
             count: 1,
           });
+          if (ctx && ctx.memLines.length > 0) {
+            recordHintFire({
+              ts: new Date().toISOString(),
+              worktree,
+              surface: "mem",
+              file: rel && !rel.startsWith("..") ? rel : null,
+              count: ctx.memLines.length,
+              ids: ctx.memIds,
+            });
+          }
           if (ctx && ctx.openBugIds.length > 0) {
             recordHintFire({
               ts: new Date().toISOString(),

package/src/adapters/hooks/read-hint.ts

@@ -390,6 +390,7 @@ export async function cmdHookReadHint(): Promise<void> {
           surface: "mem",
           file: rel,
           count: ctx.memLines.length,
+          ids: ctx.memIds,
         });
       }
       if (ctx && ctx.openBugIds.length > 0) {

package/src/adapters/mcp/evidence.ts

@@ -156,9 +156,17 @@ function runCommand(
   timeoutMs: number,
 ): CommandOutcome {
   const start = Date.now();
+  // A bare `pytest` otherwise hits a global one whose editable install may
+  // point at another worktree — tests the wrong code, silently.
+  // ponytail: .venv only; poetry/uv/conda when someone asks.
+  const venvBin = join(worktree, ".venv", "bin");
+  const env = existsSync(venvBin)
+    ? { ...process.env, PATH: `${venvBin}:${process.env.PATH ?? ""}` }
+    : undefined;
   try {
     execSync(cmd, {
       cwd: worktree,
+      env,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
       timeout: timeoutMs,

package/src/analyze/diagnose.ts

@@ -66,7 +66,7 @@ export function diagnose(
   for (const f of graph.files) {
     const deps = graph.dependents.get(f) ?? new Set<string>();
     if (deps.size === 0) {
-      if (!isEntryPoint(f) && !isTestFile(f)) {
+      if (!isEntryPoint(f) && !graph.entries?.has(f) && !isTestFile(f)) {
         findings.push({
           kind: "orphan",
           file: f,

package/src/analyze/graph.ts

@@ -5,7 +5,7 @@
 // Same module also serves handoff_check / verification_report: blastRadius()
 // (see blast.ts) turns facts.files[] into per-file { dependents, tested } facts.
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 
 import { isBarrelSource } from "./criteria.js";
@@ -20,6 +20,49 @@ import {
 import { IMPORT_TYPE_RE, REQUIRE_RE, resolveRelative } from "./resolve-ts.js";
 import type { ImportGraph } from "./types.js";
 
+// Root pyproject.toml only: declared deps (normalized to import-name guesses)
+// and `[project.scripts]` targets. A dist whose import name differs
+// (scikit-learn → sklearn) stays unresolved — fail-safe toward "don't know".
+function readPyproject(absDir: string): {
+  deps: Set<string>;
+  scripts: string[];
+} {
+  const deps = new Set<string>();
+  const scripts: string[] = [];
+  const path = join(absDir, "pyproject.toml");
+  if (!existsSync(path)) return { deps, scripts };
+  let project: {
+    dependencies?: unknown;
+    "optional-dependencies"?: Record<string, unknown>;
+    scripts?: Record<string, unknown>;
+  };
+  try {
+    project =
+      (
+        Bun.TOML.parse(readFileSync(path, "utf-8")) as {
+          project?: typeof project;
+        }
+      ).project ?? {};
+  } catch {
+    return { deps, scripts };
+  }
+  const specs = [
+    project.dependencies,
+    ...Object.values(project["optional-dependencies"] ?? {}),
+  ].flatMap((v) => (Array.isArray(v) ? v : []));
+  for (const spec of specs) {
+    const name =
+      typeof spec === "string" && spec.match(/^\s*([A-Za-z0-9._-]+)/)?.[1];
+    if (name) deps.add(name.toLowerCase().replace(/[-.]/g, "_"));
+  }
+  for (const target of Object.values(project.scripts ?? {})) {
+    if (typeof target === "string") scripts.push(target.split(":")[0].trim());
+  }
+  return { deps, scripts };
+}
+
+const PY_MAIN_RE = /^if\s+__name__\s*==\s*["']__main__["']\s*:/m;
+
 export function buildGraph(dir: string): ImportGraph {
   const absDir = resolve(dir);
   const files = collectSourceFiles(absDir);
@@ -32,6 +75,8 @@ export function buildGraph(dir: string): ImportGraph {
   let external = 0;
   // Built lazily — a TS-only repo never pays for it.
   let pyIndex: Map<string, string> | null = null;
+  let pyproject: ReturnType<typeof readPyproject> | null = null;
+  const entries = new Set<string>();
 
   const transpiler = new Bun.Transpiler({ loader: "ts" });
 
@@ -50,11 +95,18 @@ export function buildGraph(dir: string): ImportGraph {
       // against the module index. An absolute miss whose root is in PY_STDLIB
       // is external; a third-party package or a real miss stays unresolved.
       pyIndex ??= buildPyModuleIndex(filesSet);
+      pyproject ??= readPyproject(absDir);
+      if (PY_MAIN_RE.test(content)) entries.add(rel);
       const pyEdges = new Set<string>();
       for (const imp of scanPythonImports(content)) {
         const hits = resolvePythonImport(rel, imp, filesSet, pyIndex);
         if (hits.size > 0) for (const h of hits) pyEdges.add(h);
-        else if (!imp.dots && imp.mod && PY_STDLIB.has(pyRootSegment(imp.mod)))
+        else if (
+          !imp.dots &&
+          imp.mod &&
+          (PY_STDLIB.has(pyRootSegment(imp.mod)) ||
+            pyproject.deps.has(pyRootSegment(imp.mod).toLowerCase()))
+        )
           external++;
         else unresolved++;
       }
@@ -107,5 +159,12 @@ export function buildGraph(dir: string): ImportGraph {
     }
   }
 
-  return { files, deps, dependents, unresolved, external, barrels };
+  if (pyIndex && pyproject) {
+    for (const mod of pyproject.scripts) {
+      const hit = pyIndex.get(mod);
+      if (hit) entries.add(hit);
+    }
+  }
+
+  return { files, deps, dependents, unresolved, external, barrels, entries };
 }

package/src/analyze/types.ts

@@ -19,6 +19,9 @@ export interface ImportGraph {
   external: number;
   /** Files that only re-export (`export ... from`) — they hide the real importer. */
   barrels: Set<string>;
+  /** Python files that run on their own: `__main__` block or `[project.scripts]`.
+   * Optional — the graph cache doesn't carry it; only diagnose reads it. */
+  entries?: Set<string>;
 }
 
 export type FindingKind =

package/src/init.ts

@@ -8,6 +8,7 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  realpathSync,
   writeFileSync,
 } from "node:fs";
 import { dirname, join, relative } from "node:path";
@@ -58,22 +59,23 @@ const EVIDENCE_JSON = `{
 }
 `;
 
-// Rules snippet for the user's own agent-rules file. Printed, never written:
-// nothing writes log.<person>.jsonl on its own — an agent does, because the rules
-// file it already reads says to. That file is the user's (CLAUDE.md / AGENTS.md /
-// opencode.json instructions), so fapony hands over the text and stays out of it.
-// Not in SERVER_INSTRUCTIONS either: that reaches every MCP session of every user,
-// and most of them never ran `fapony init` — it would tell them to run a command
-// that does not exist.
-const RULES_SNIPPET =
-  () => `## Memory: .fapony/.memory/log.<you>.jsonl (append-only)
+// Rules snippet for the user's own agent-rules file. Nothing writes
+// log.<person>.jsonl on its own — an agent does, because the rules file it already
+// reads says to. That file is the user's, so init asks before writing it (rule 6c)
+// and never writes it twice (RULES_MARKER). Not in SERVER_INSTRUCTIONS either: that
+// reaches every MCP session of every user, and most of them never ran `fapony init`
+// — it would tell them to run a command that does not exist.
+const RULES_MARKER = "## Memory: .fapony/.memory";
+const RULES_SNIPPET = () => `${RULES_MARKER}/log.<you>.jsonl (append-only)
 
 The log is this project's shared brain — it lives in git, so anyone who clones the
 repo gets every decision, bug and note with it. The filename comes from
 \`git config user.name\` — one file per person, and \`*.jsonl merge=union\` in
 .gitattributes keeps both sides when two people end up sharing a name anyway.
 
-Log as you work — do not wait to be asked. Nothing writes it for you:
+Log as you work — do not wait to be asked. Nothing writes it for you. With the
+fapony MCP server connected, call mem_add / mem_find / mem_close directly;
+otherwise the CLI:
 
     fapony mem kickoff <plan.md>      # start a session with this
     fapony mem add decision "what was locked, and why" --files src/x.ts
@@ -82,6 +84,14 @@ Log as you work — do not wait to be asked. Nothing writes it for you:
     fapony mem close <id> "fixed in <sha>"
     fapony mem find "<text>"
 
+What goes in — would someone cloning this repo tomorrow need it, and can they not
+find it anywhere else?
+- bug — something broken, even when found mid-task on something else: add it now,
+  not at the end. Once fixed, close it — only close closes a bug.
+- decision — something agreed or locked that git and the plan do not say, with why.
+- note — state the next session needs (where a chunk stopped, what is half-done).
+Before ending a turn that committed work: at least one row about it.
+
 Write each entry standalone — it is read months later with no chat to refer to.
 --files is required: rows that name no file cannot be recalled when that file is
 touched later (add refuses without it).
@@ -188,64 +198,124 @@ export function initProject(targetPath: string, config?: Config): void {
   );
   console.log(`\nNext: add "${targetPath}" to fapony.config.json worktrees`);
   console.log(
-    `\nThen paste this into your agent-rules file (CLAUDE.md / AGENTS.md / opencode.json\ninstructions) — the memory log only fills up if the rules your agent already reads\ntell it to write:\n`,
+    `\nThe memory log only fills up if the rules your agent already reads tell it\nto write — these go into CLAUDE.md / AGENTS.md next:\n`,
   );
   console.log(RULES_SNIPPET());
 }
 
 const AGENT_RULE_FILES = ["CLAUDE.md", "AGENTS.md"];
 
-export async function cmdInit(args: string[]): Promise<void> {
-  const targetPath = args[0];
-  if (!targetPath) {
-    console.error("usage: fapony init <path>");
-    process.exit(1);
+/** Which rules files init would touch: existing ones lacking the rules, or create. */
+export function rulesTargets(targetPath: string): {
+  create: boolean;
+  append: string[];
+} {
+  // one real file per entry: AGENTS.md -> CLAUDE.md symlinks are common, and
+  // appending through both names wrote the rules twice (wt-falsify 2026-09-24)
+  const seen = new Set<string>();
+  const found = AGENT_RULE_FILES.map((f) => join(targetPath, f)).filter((f) => {
+    if (!existsSync(f)) return false;
+    const real = realpathSync(f);
+    if (seen.has(real)) return false;
+    seen.add(real);
+    return true;
+  });
+  const has = (f: string) => readFileSync(f, "utf-8").includes(RULES_MARKER);
+  const agents = join(targetPath, "AGENTS.md");
+  // a CLAUDE.md that imports a rules-carrying AGENTS.md already has them
+  const covered = (f: string) =>
+    has(f) ||
+    (/^@AGENTS\.md\s*$/m.test(readFileSync(f, "utf-8")) &&
+      existsSync(agents) &&
+      has(agents));
+  return {
+    create: found.length === 0,
+    append: found.filter((f) => !covered(f)),
+  };
+}
+
+/**
+ * Write the memory rules into the agent-rules files. No file yet = AGENTS.md
+ * (read by OpenCode/Codex/Cursor) + a CLAUDE.md that imports it, so the rules
+ * exist once. Files that already carry the rules are left alone.
+ */
+export function writeRules(targetPath: string): void {
+  const { create, append } = rulesTargets(targetPath);
+  if (create) {
+    writeFileSync(join(targetPath, "AGENTS.md"), `${RULES_SNIPPET()}\n`);
+    writeFileSync(join(targetPath, "CLAUDE.md"), "@AGENTS.md\n");
+    console.log("  + AGENTS.md (memory rules) · CLAUDE.md → @AGENTS.md");
+    return;
   }
-  try {
-    initProject(targetPath);
-  } catch (e) {
-    console.error((e as Error).message);
-    process.exit(1);
+  for (const f of append) {
+    const body = readFileSync(f, "utf-8");
+    appendFileSync(
+      f,
+      `${body.endsWith("\n") ? "\n" : "\n\n"}${RULES_SNIPPET()}\n`,
+    );
+    console.log(`  appended memory rules to ${relative(targetPath, f)}`);
   }
+}
 
-  // --- conventions.json fill-signal (PLAN-convention-debt chunk 2) ---
-  // eslint no-restricted-* rows carry their checker; the wrapper detector adds
-  // live-migration candidates. Nothing derivable = empty file, never an error.
-  const seed = await seedConventionsFile(targetPath);
-  if (seed.kept) {
-    console.log(
-      `  ${relative(targetPath, seed.file)} — already exists, left untouched`,
-    );
-  } else {
-    console.log(
-      `  ${relative(targetPath, seed.file)} — ${seed.eslintRows} from eslint, ${seed.wrapperRows} from wrappers`,
-    );
-    console.log(
-      `    'fapony debt' reads it; commit it (!**/.fapony/conventions.json in .gitignore)`,
+export async function cmdInit(args: string[]): Promise<void> {
+  const rulesOnly = args.includes("--rules");
+  const yes = args.includes("--yes");
+  const targetPath = args.find((a) => !a.startsWith("--"));
+  if (!targetPath) {
+    console.error("usage: fapony init <path> [--rules] [--yes]");
+    console.error(
+      "  --rules  only write the memory rules into CLAUDE.md / AGENTS.md (repo already set up)",
     );
+    console.error("  --yes    write them without asking");
+    process.exit(1);
   }
-  for (const s of seed.skipped) console.log(`    ⚠ eslint config ${s}`);
+  if (!rulesOnly) {
+    try {
+      initProject(targetPath);
+    } catch (e) {
+      console.error((e as Error).message);
+      process.exit(1);
+    }
 
-  const found = AGENT_RULE_FILES.map((f) => join(targetPath, f)).filter(
-    existsSync,
-  );
-  if (found.length === 0) return;
+    // --- conventions.json fill-signal (PLAN-convention-debt chunk 2) ---
+    // eslint no-restricted-* rows carry their checker; the wrapper detector adds
+    // live-migration candidates. Nothing derivable = empty file, never an error.
+    const seed = await seedConventionsFile(targetPath);
+    if (seed.kept) {
+      console.log(
+        `  ${relative(targetPath, seed.file)} — already exists, left untouched`,
+      );
+    } else {
+      console.log(
+        `  ${relative(targetPath, seed.file)} — ${seed.eslintRows} from eslint, ${seed.wrapperRows} from wrappers`,
+      );
+      console.log(
+        `    'fapony debt' reads it; commit it (!**/.fapony/conventions.json in .gitignore)`,
+      );
+    }
+    for (const s of seed.skipped) console.log(`    ⚠ eslint config ${s}`);
+  }
 
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const answer = await new Promise<string>((resolve) => {
-    rl.question(
-      `\nAppend the memory-logging rules above to ${found.map((f) => relative(targetPath, f)).join(" and ")}? [y/N] `,
-      (a) => {
+  const { create, append } = rulesTargets(targetPath);
+  if (!create && append.length === 0) {
+    console.log("  memory rules already in the agent-rules file");
+    return;
+  }
+  if (!yes) {
+    const what = create
+      ? "Create AGENTS.md with the memory-logging rules (+ CLAUDE.md → @AGENTS.md)"
+      : `Append the memory-logging rules to ${append.map((f) => relative(targetPath, f)).join(" and ")}`;
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    const answer = await new Promise<string>((resolve) => {
+      rl.question(`\n${what}? [y/N] `, (a) => {
         rl.close();
         resolve(a.trim());
-      },
-    );
-  });
-  if (!isAffirmative(answer)) return;
-
-  const snippet = `\n\n${RULES_SNIPPET()}\n`;
-  for (const f of found) {
-    appendFileSync(f, snippet);
-    console.log(`  appended to ${relative(targetPath, f)}`);
+      });
+    });
+    if (!isAffirmative(answer)) return;
   }
+  writeRules(targetPath);
 }

package/src/install/opencode.ts

@@ -269,7 +269,7 @@ export const FaponyReadHint = async ({ directory }) => {
             recordHintFire({ ts: new Date().toISOString(), worktree: ctx.worktree, surface: "debt", file: rel, count: ctx.debtIds.length, ids: ctx.debtIds });
           }
           if (ctx.memLines.length > 0) {
-            recordHintFire({ ts: new Date().toISOString(), worktree: ctx.worktree, surface: "mem", file: rel, count: ctx.memLines.length });
+            recordHintFire({ ts: new Date().toISOString(), worktree: ctx.worktree, surface: "mem", file: rel, count: ctx.memLines.length, ids: ctx.memIds });
           }
           if (ctx.openBugIds.length > 0) {
             recordHintFire({ ts: new Date().toISOString(), worktree: ctx.worktree, surface: "open-bug", file: rel, count: ctx.openBugIds.length, ids: ctx.openBugIds });
@@ -413,7 +413,7 @@ export const FaponyEditHint = async ({ directory }) => {
                 recordHintFire({ ts: new Date().toISOString(), worktree, surface: "debt", file: rel, count: ctx.debtIds.length, ids: ctx.debtIds });
               }
               if (ctx?.memLines?.length) {
-                recordHintFire({ ts: new Date().toISOString(), worktree, surface: "mem", file: rel, count: ctx.memLines.length });
+                recordHintFire({ ts: new Date().toISOString(), worktree, surface: "mem", file: rel, count: ctx.memLines.length, ids: ctx.memIds });
               }
               if (ctx?.openBugIds?.length) {
                 recordHintFire({ ts: new Date().toISOString(), worktree, surface: "open-bug", file: rel, count: ctx.openBugIds.length, ids: ctx.openBugIds });