fapony 0.5.0 → 0.6.1

package/src/init.ts

@@ -58,22 +58,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 +83,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 +197,117 @@ 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[];
+} {
+  const found = AGENT_RULE_FILES.map((f) => join(targetPath, f)).filter(
+    existsSync,
+  );
+  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/antigravity.ts

@@ -34,7 +34,9 @@ function isFaponyEntry(entry: unknown): boolean {
 
 function readJsonObject(path: string): Record<string, unknown> | null {
   try {
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    const raw = readFileSync(path, "utf-8").trim();
+    if (!raw) return {};
+    const parsed: unknown = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return null;
     }

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

package/src/map.ts

@@ -167,10 +167,230 @@ function braceNames(
 
 const VAR_DECL_RE = /^export\s+(?:const|let|var)\b/;
 
+// --- Python exports (no parser: Bun.Transpiler can't read .py, and shelling
+// out to `python -c "import ast"` was cut — a subprocess per file blows the
+// measured budgets (buildGraph ~50ms/150 files, review-seed 0.31–0.51s
+// uncached) and breaks the Bun-only constraint. Line-based, top level only.)
+
+const PY_DEF_RE = /^(?:async\s+)?def\s+([A-Za-z_]\w*)/;
+const PY_CLASS_RE = /^class\s+([A-Za-z_]\w*)/;
+// `x = …` and `x: T = …` — `=(?!=)` keeps `==`/`!=`/`>=` comparisons out.
+const PY_ASSIGN_RE = /^([A-Za-z_]\w*)\s*(?::\s*[^=;#]+?)?=(?!=)/;
+const PY_FROM_RE = /^from\s+(\S+)\s+import\s+(.+)$/;
+const PY_ALL_RE = /^__all__\s*=/;
+
+// Walk one line tracking quote state; returns the code before a `#` comment.
+// Triple quotes are handled for the single-line case (`x = """a#b"""`) —
+// multi-line strings are skipped by the block tracker below, not here.
+function stripPyComment(line: string): string {
+  let quote: string | null = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === "\\") {
+        i++;
+        continue;
+      }
+      if (line.startsWith(quote, i)) {
+        i += quote.length - 1;
+        quote = null;
+      }
+      continue;
+    }
+    if (c === "#") return line.slice(0, i);
+    if (line.startsWith('"""', i) || line.startsWith("'''", i)) {
+      quote = line.slice(i, i + 3);
+      i += 2;
+    } else if (c === '"' || c === "'") {
+      quote = c;
+    }
+  }
+  return line;
+}
+
+// Blank out triple-quoted string blocks, preserving the line count, so a
+// line-based scan never reads code (`def`, `from .x import y`) out of a
+// docstring or a multi-line string. Code before an opening `"""` on the same
+// line is kept; the block itself and its closing line become empty. Single
+// source of truth for both the export scan (below) and analyze's import scan.
+// First triple quote that is NOT inside a single/double-quoted string on this
+// line — so `x = 'has """ inside'` never opens a block. `stripPyComment` walks
+// the same quote state; this reports where a block actually starts.
+function unquotedTriple(code: string): { at: number; q: string } | null {
+  let quote: string | null = null;
+  for (let i = 0; i < code.length; i++) {
+    const c = code[i];
+    if (quote) {
+      if (c === "\\") {
+        i++;
+        continue;
+      }
+      if (code.startsWith(quote, i)) {
+        i += quote.length - 1;
+        quote = null;
+      }
+      continue;
+    }
+    if (code.startsWith('"""', i) || code.startsWith("'''", i))
+      return { at: i, q: code.slice(i, i + 3) };
+    if (c === '"' || c === "'") quote = c;
+  }
+  return null;
+}
+
+export function maskPyBlocks(source: string): string {
+  const out: string[] = [];
+  let block: string | null = null;
+  for (const raw of source.split("\n")) {
+    if (block) {
+      const end = raw.indexOf(block);
+      if (end < 0) {
+        out.push("");
+        continue;
+      }
+      block = null;
+      out.push(raw.slice(end + 3));
+      continue;
+    }
+    const code = stripPyComment(raw);
+    const triple = unquotedTriple(code);
+    if (triple) {
+      const { at, q } = triple;
+      if (code.indexOf(q, at + 3) < 0) {
+        block = q;
+        out.push(code.slice(0, at));
+        continue;
+      }
+    }
+    out.push(raw);
+  }
+  return out.join("\n");
+}
+
+// String literals inside an `__all__ = [...]` (or `(...)`) assignment,
+// possibly spanning lines. Anything dynamic (`append`, `+=`, a variable)
+// yields nothing — the caller falls back to every top-level name.
+function pyAllNames(text: string): string[] {
+  const open =
+    text.indexOf("[") >= 0 ? "[" : text.indexOf("(") >= 0 ? "(" : null;
+  if (!open) return [];
+  const close = open === "[" ? "]" : ")";
+  const body = text.slice(text.indexOf(open) + 1);
+  if (!body.includes(close)) return [];
+  const out: string[] = [];
+  for (const m of body.matchAll(/["']([A-Za-z_]\w*)["']/g)) out.push(m[1]);
+  return out;
+}
+
+function pyFromNames(rest: string): string[] {
+  const clean = rest.replace(/[()]/g, " ");
+  const out: string[] = [];
+  for (let part of clean.split(",")) {
+    part = part.trim().split("#")[0].trim();
+    if (!part || part === "*") continue;
+    const as = part.split(/\s+as\s+/);
+    const name = as[as.length - 1].trim();
+    if (/^[A-Za-z_]\w*$/.test(name)) out.push(name);
+  }
+  return out;
+}
+
+export function extractPythonExports(source: string): ExportScan {
+  // Blank docstrings/strings first, preserving line numbers — a `def` inside
+  // a docstring is sample text, the same blind spot the TS path closes with
+  // the parse gate.
+  const lines = maskPyBlocks(source).split("\n");
+  const found = new Map<string, { line: number; kind: ExportKind }>();
+  let allNames: string[] = [];
+  let allLine = 0;
+
+  const remember = (name: string, line: number, kind: ExportKind): void => {
+    if (!found.has(name)) found.set(name, { line, kind });
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const code = stripPyComment(raw).trimEnd();
+    if (code === "") continue;
+    if (/^\s/.test(raw)) continue; // indented — not top level
+    const t = code.trim();
+    let m: RegExpMatchArray | null;
+    if ((m = t.match(PY_DEF_RE))) {
+      remember(m[1], i + 1, "fn");
+      continue;
+    }
+    if ((m = t.match(PY_CLASS_RE))) {
+      remember(m[1], i + 1, "class");
+      continue;
+    }
+    if (PY_ALL_RE.test(t)) {
+      // `__all__` may span lines — join until the bracket closes (cap 20).
+      let joined = t;
+      let j = i;
+      while (!/[\])]/.test(joined) && j + 1 < lines.length && j - i < 20) {
+        j++;
+        joined += ` ${stripPyComment(lines[j]).trim()}`;
+      }
+      allNames = pyAllNames(joined);
+      allLine = i + 1;
+      i = j;
+      continue;
+    }
+    if ((m = t.match(PY_FROM_RE))) {
+      // Parenthesized lists often span lines — join until they close (cap 20),
+      // the same shape as the TS brace-block join above.
+      let rest = m[2];
+      let j = i;
+      const unbalanced = (s: string): boolean =>
+        (s.match(/\(/g) ?? []).length > (s.match(/\)/g) ?? []).length;
+      while (unbalanced(rest) && j + 1 < lines.length && j - i < 20) {
+        j++;
+        rest += ` ${stripPyComment(lines[j]).trim()}`;
+      }
+      for (const name of pyFromNames(rest)) remember(name, i + 1, "re-export");
+      i = j;
+      continue;
+    }
+    if (/^import\s+/.test(t)) continue; // graph data, not an export
+    if ((m = t.match(PY_ASSIGN_RE))) {
+      if (m[1] === "__all__") continue;
+      remember(m[1], i + 1, "const");
+    }
+  }
+
+  if (allNames.length > 0) {
+    // `__all__` is authoritative: undocumented underscore names listed there
+    // are public, and anything not listed is not — including real defs.
+    const out: ExportSymbol[] = [];
+    const seen = new Set<string>();
+    for (const name of allNames) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      const f = found.get(name);
+      out.push(
+        f
+          ? { name, line: f.line, kind: f.kind }
+          : { name, line: allLine, kind: "re-export" },
+      );
+    }
+    return { symbols: out, error: null };
+  }
+  // No `__all__`: underscore-prefixed names are private by convention.
+  return {
+    symbols: [...found]
+      .filter(([name]) => !name.startsWith("_"))
+      .map(([name, f]) => ({ name, line: f.line, kind: f.kind })),
+    error: null,
+  };
+}
+
 export function extractExports(
   source: string,
   scanner?: ExportScanner,
+  filename?: string,
 ): ExportScan {
+  if (filename?.endsWith(".py") || filename?.endsWith(".pyi"))
+    return extractPythonExports(source);
   const s = scanner ?? getDefaultScanner();
   const scanned = scanSource(source, s);
   if (scanned.error) return { symbols: [], error: scanned.error };

package/src/mem/selectors.ts

@@ -28,10 +28,13 @@ export const openRows = (all: LogRow[]): WorkRow[] => {
 // Distinct keys on open work rows, sorted — the important-index ingredient
 // (PLAN-mem-keys chunk 3). A key is open while ≥1 keyed row survives the
 // tombstone set; computed live like every other selector, never persisted.
+// Decisions are skipped: nobody closes them, so a keyed decision would sit in
+// the index forever as a fake "open problem".
 export const openKeys = (all: LogRow[]): { key: string; open: number }[] => {
   const counts = new Map<string, number>();
   for (const r of openRows(all)) {
-    if (r.key) counts.set(r.key, (counts.get(r.key) ?? 0) + 1);
+    if (r.key && r.kind !== "decision")
+      counts.set(r.key, (counts.get(r.key) ?? 0) + 1);
   }
   return [...counts.entries()]
     .map(([key, open]) => ({ key, open }))

package/src/seed/plan-seed.ts

@@ -34,7 +34,11 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, join, relative, resolve, sep } from "node:path";
-import { collectSourceFiles, isSkippedDir, SCAN_EXTS } from "../analyze.js";
+import {
+  collectSourceFiles,
+  isSkippedDir,
+  SCAN_EXTS,
+} from "../analyze/index.js";
 import {
   CONFIG_FILENAME,
   type Config,
@@ -221,7 +225,7 @@ function renderExistingInScope(
     } catch {
       continue;
     }
-    const scan = extractExports(source);
+    const scan = extractExports(source, undefined, rel);
     if (scan.error || scan.symbols.length === 0) continue;
     // Re-export-only files scan as one `*` per line — dedupe to a single `*`.
     const names = [
@@ -347,7 +351,7 @@ function fileLines(absFile: string): string[] {
   } catch {
     return ["_(unreadable)_"];
   }
-  const scan = extractExports(source);
+  const scan = extractExports(source, undefined, absFile);
   if (scan.error) return [`⚠ ${scan.error} — symbols not extractable`];
   if (scan.symbols.length === 0) return ["_(no exports)_"];
   let srcLines: string[] = [];

package/src/seed/review-seed.ts

@@ -29,7 +29,7 @@ import {
   isTestedThroughBarrels,
   isTestFile,
   SCAN_EXTS,
-} from "../analyze.js";
+} from "../analyze/index.js";
 import { extractBody, extractExports } from "../map.js";
 import { assertSafe } from "../safety.js";
 import { execGit, gitOk, gitValue, SeedError, SIG_MAX } from "./primitives.js";
@@ -707,7 +707,7 @@ function renderLookup(
       } catch {
         continue;
       }
-      const scan = extractExports(source);
+      const scan = extractExports(source, undefined, path);
       if (scan.error) continue;
       for (const sym of scan.symbols) {
         if (!flags.body.includes(sym.name)) continue;
@@ -902,7 +902,7 @@ export function renderSeed(args: string[], cwd: string): string {
       } catch {
         continue;
       }
-      const scan = extractExports(source);
+      const scan = extractExports(source, undefined, e.path);
       if (scan.error) {
         sigLines.push(`  ${e.path} — ⚠ ${scan.error}`);
         continue;

package/templates/PLAN.md

@@ -51,6 +51,7 @@ Table with 3–5 rows: risk | likelihood | impact | escape hatch
 1. **<Step 1>** — has a clear deliverable
 2. **<Step 2>** — ...
 Each step must be verifiable before moving to the next
+A step needing state the system doesn't store yet must say where it lives, who writes it, who reads it
 
 ## 7. Examples (make it concrete)
 bash examples: before / after — **link into spec/, don't paste it.**