fapony 0.1.3 → 0.2.0

package/src/init-mem.ts

@@ -1,14 +1,19 @@
-// src/init-mem.ts — scaffold the canonical .memory/ system into a new worktree.
-// Source of truth lives in fapony/templates/mem/ — named after the CLI it implements
-// (`mem`), not after where it lands; the destination keeps the .memory name because that
-// is where the log lives.
-// Destination is <worktree>/.fapony/.memory/ (plans/specs/memory all live under
-// .fapony/; run state stays in ~/.config/fapony/state.db, never in the worktree).
-// Re-run to re-sync after editing the template — not automatic, on purpose.
+// src/init-mem.ts — cleanup old .memory/ directories and warn about stale call sites.
+//
+// Before PLAN-agent-one-call, this file scaffolded templates/mem/ into every repo.
+// Now fapony owns the mem code (src/mem/) and calls it directly via `fapony mem`.
+// This command's new job: delete legacy .memory/ dirs + warn about package.json refs.
 
-import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { loadConfig, memoryEntry } from "./db/index.js";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "./db/index.js";
 
 export function copyDir(src: string, dest: string): string[] {
   mkdirSync(dest, { recursive: true });
@@ -27,13 +32,11 @@ export function copyDir(src: string, dest: string): string[] {
 }
 
 export function cmdInitMem(args: string[]): void {
-  const update = args.includes("--update");
+  const force = args.includes("--force");
   const worktreeKey = args.find((x) => !x.startsWith("-"));
   const config = loadConfig();
 
-  // no key given = the repo you are standing in — so `fapony init-mem --update` runs in anyone's project
-  // without registering the worktree first (loadConfig already reads the cwd's fapony.config.json,
-  // so it picks up that project's paths.memoryEntry by itself)
+  // no key given = the repo you are standing in
   const worktree = worktreeKey ? config.worktrees[worktreeKey] : process.cwd();
   if (!worktree) {
     console.error(`unknown worktree key: ${worktreeKey}`);
@@ -41,31 +44,114 @@ export function cmdInitMem(args: string[]): void {
     process.exit(1);
   }
 
-  const templateDir = join(import.meta.dir, "..", "templates", "mem");
-  const memEntry = memoryEntry(config);
-  const destDir = join(worktree, dirname(memEntry));
-  const destFile = join(worktree, memEntry);
+  const gitRoot = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+    cwd: worktree,
+  })
+    .stdout.toString()
+    .trim();
+  const root = gitRoot || worktree;
 
-  if (existsSync(destFile) && !update) {
-    console.error(
-      `${destFile} already exists — re-running would overwrite local edits.\nRun \`fapony init-mem --update\` to refresh it from the template (log.jsonl is kept).`,
+  // 1) Find and delete .memory/ directories (legacy layout)
+  const memoryDirs: string[] = [];
+  const walk = (dir: string, depth = 0) => {
+    if (depth > 4) return;
+    if (existsSync(`${dir}/.memory`)) {
+      memoryDirs.push(`${dir}/.memory`);
+    }
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (
+          entry.isDirectory() &&
+          !entry.name.startsWith(".") &&
+          entry.name !== "node_modules"
+        ) {
+          walk(join(dir, entry.name), depth + 1);
+        }
+      }
+    } catch {
+      // ignore
+    }
+  };
+  walk(root);
+
+  if (memoryDirs.length === 0) {
+    console.log("no legacy .memory/ directories found — already clean");
+  } else {
+    let removed = 0;
+    let kept = 0;
+    for (const d of memoryDirs) {
+      // Any log*.jsonl is history — includes log.<person>.jsonl (the standard
+      // filename) and rotated log.YYYY-MM-DD.jsonl, not just log.jsonl.
+      let logs: string[] = [];
+      try {
+        logs = readdirSync(d).filter(
+          (f) => f === "log.jsonl" || /^log\..*\.jsonl$/.test(f),
+        );
+      } catch {
+        // unreadable dir — fall through and remove
+      }
+      if (logs.length > 0 && !force) {
+        console.log(
+          `keeping ${d} — has ${logs.length} log file(s): ${logs.join(", ")}`,
+        );
+        console.log(
+          `  move them under ${join(d, "..", ".fapony", ".memory")}/, or re-run with --force to delete`,
+        );
+        kept++;
+        continue;
+      }
+      console.log(
+        `deleting ${d}${logs.length > 0 ? ` (--force: ${logs.length} log file(s))` : ""}`,
+      );
+      rmSync(d, { recursive: true, force: true });
+      removed++;
+    }
+    console.log(
+      `\nremoved ${removed} legacy .memory/ director${removed === 1 ? "y" : "ies"}${
+        kept > 0
+          ? ` · kept ${kept} with logs — move them under .fapony/.memory/, then re-run`
+          : ""
+      }`,
     );
-    process.exit(1);
-  }
-  if (update && !existsSync(destFile)) {
-    console.error(`${destFile} not found — run \`fapony init\` first.`);
-    process.exit(1);
   }
 
-  const files = copyDir(templateDir, destDir);
-  if (update) {
-    console.log(`updated ${files.length} files in ${destDir}`);
-    console.log(`(log.jsonl and other data files left untouched)`);
-    return;
-  }
-  console.log(`scaffolded ${files.length} files into ${destDir}`);
-  console.log(`\nAdd to fapony.config.json:`);
-  console.log(
-    `  "memory": {\n    "claim": ["bun", "${memEntry}", "claim", "{id}"],\n    "close": ["bun", "${memEntry}", "close", "{id}", "{msg}"],\n    "add":   ["bun", "${memEntry}", "add", "{kind}", "{text}"],\n    "kickoff": ["bun", "${memEntry}", "kickoff"]\n  }`,
-  );
+  // 2) Warn about package.json call sites still referencing .memory/mem.ts
+  const warnAboutCallSites = (dir: string, depth = 0) => {
+    if (depth > 4) return;
+    const pkg = join(dir, "package.json");
+    if (existsSync(pkg)) {
+      try {
+        const raw = readFileSync(pkg, "utf8");
+        if (raw.includes(".memory/mem.ts")) {
+          console.log(`\n⚠ ${pkg} still references .memory/mem.ts`);
+          console.log(
+            `  update to: "fapony mem <sub>" (e.g. "fapony mem add", "fapony mem close")`,
+          );
+        }
+      } catch {
+        // ignore
+      }
+    }
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (
+          entry.isDirectory() &&
+          !entry.name.startsWith(".") &&
+          entry.name !== "node_modules"
+        ) {
+          warnAboutCallSites(join(dir, entry.name), depth + 1);
+        }
+      }
+    } catch {
+      // ignore
+    }
+  };
+  warnAboutCallSites(root);
+
+  console.log("\nmem commands are now built into fapony:");
+  console.log('  fapony mem add <kind> "<text>" --files <files>');
+  console.log('  fapony mem close <id> "<text>"');
+  console.log("  fapony mem find <word>");
+  console.log("  fapony mem kickoff [id|spec.md]");
+  console.log("  fapony mem now");
 }

package/src/init.ts

@@ -3,7 +3,13 @@
 // state.db stays in ~/.config/fapony/ by design (security boundary — see db.ts),
 // never inside the worktree where agents have full write access.
 
-import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { createInterface } from "node:readline";
 import { seedConventionsFile } from "./conventions-seed.js";
@@ -11,11 +17,10 @@ import {
   type Config,
   doneDir,
   evidenceFile,
-  memoryEntry,
+  memoryDir,
   planDir,
   specDir,
 } from "./db/index.js";
-import { copyDir } from "./init-mem.js";
 import { isAffirmative } from "./util.js";
 
 const FAPONY_README = `# .fapony/ — fapony project dir (plans, specs, memory)
@@ -37,7 +42,7 @@ const FAPONY_README = `# .fapony/ — fapony project dir (plans, specs, memory)
 # running in this worktree cannot rewrite run state / audit trail.
 #
 # Ask your agent for the plan picture instead of listing these by hand:
-#   "run plan_list" — what is active, blocked, untouched, archived
+#   run "fapony mem kickoff" — priority plans, the first unchecked chunk, open bugs
 `;
 
 // Static template — deliberately NOT derived from the repo (reading package.json
@@ -59,22 +64,22 @@ const EVIDENCE_JSON = `{
 // 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 = (
-  memEntry: string,
-) => `## Memory: ${dirname(memEntry)}/log.<you>.jsonl (append-only)
+const RULES_SNIPPET =
+  () => `## Memory: .fapony/.memory/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, so there is nothing to merge.
+\`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:
 
-    bun ${memEntry} kickoff <plan.md>      # start a session with this
-    bun ${memEntry} add decision "what was locked, and why" --files src/x.ts
-    bun ${memEntry} add bug "what is broken" --files src/x.ts
-    bun ${memEntry} add note "state the next session needs" --files src/x.ts
-    bun ${memEntry} close <id> "fixed in <sha>"
-    bun ${memEntry} find "<text>"
+    fapony mem kickoff <plan.md>      # start a session with this
+    fapony mem add decision "what was locked, and why" --files src/x.ts
+    fapony mem add bug "what is broken" --files src/x.ts
+    fapony mem add note "state the next session needs" --files src/x.ts
+    fapony mem close <id> "fixed in <sha>"
+    fapony mem find "<text>"
 
 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
@@ -90,13 +95,13 @@ Finish a chunk, before starting the next:
 1. Tick its checkbox + stamp the TL;DR in the plan file
 2. Commit — separate from other chunks
 3. \`verdict_submit\` (fapony MCP), grading what actually happened
-4. \`bun ${memEntry} add note "what the next chunk needs" --files f1,f2 <path/to/PLAN-x.md>\`
-   — pass the exact same plan path every time; kickoff matches it as a literal string
+4. \`fapony mem add note "what the next chunk needs" --files f1,f2 <path/to/PLAN-x.md>\`
+   — use the same plan path every time
 5. Stop. Do not continue to the next chunk in the same session unless told to.
 
-Next chunk, new session — open with \`bun ${memEntry} kickoff <path/to/PLAN-x.md>\` (same
-path) instead of carrying the old transcript forward. kickoff already filters to the
-rows written against that exact path.`;
+Next chunk, new session — open with \`fapony mem kickoff <path/to/PLAN-x.md>\` instead
+of carrying the old transcript forward. kickoff already filters to the rows for that plan,
+and takes just the filename (\`kickoff PLAN-x.md\`) when you do not want to type the path.`;
 
 export function initProject(targetPath: string, config?: Config): void {
   // Create target root
@@ -112,6 +117,22 @@ export function initProject(targetPath: string, config?: Config): void {
   mkdirSync(faponyDir, { recursive: true });
   writeFileSync(join(faponyDir, "README"), FAPONY_README);
 
+  // --- .gitattributes: union-merge the append-only logs ---
+  //
+  // Every row is one person's append, so both sides of a "conflict" are always
+  // right. Without the line, two people whose git user.name collides (admin /
+  // user / owner — what a fresh OS install offers) resolve a conflict by hand
+  // on every pull. Appended, never rewritten: the file is the repo's, not ours.
+  const attrs = join(targetPath, ".gitattributes");
+  const attrsBody = existsSync(attrs) ? readFileSync(attrs, "utf-8") : "";
+  if (!/^\s*\*\.jsonl\s+merge=union\s*$/m.test(attrsBody)) {
+    appendFileSync(
+      attrs,
+      `${attrsBody && !attrsBody.endsWith("\n") ? "\n" : ""}# append-only memory logs: keep both sides, never hand-resolve\n*.jsonl merge=union\n`,
+    );
+    console.log(`  + ${attrs} — *.jsonl merge=union`);
+  }
+
   // --- evidence.json (verification_report allowlist — see src/mcp/evidence.ts) ---
   const evidencePath = join(targetPath, evidenceFile(config));
   if (existsSync(evidencePath)) {
@@ -141,19 +162,16 @@ export function initProject(targetPath: string, config?: Config): void {
   }
   mkdirSync(specDirAbs, { recursive: true });
 
-  // --- .memory/ (from template) ---
-  const memEntry = memoryEntry(config); // e.g. .fapony/.memory/mem.ts
-  const memoryDir = join(
-    targetPath,
-    memEntry.split("/").slice(0, -1).join("/"),
-  );
-  if (existsSync(join(targetPath, memEntry))) {
-    throw new Error(
-      `${join(targetPath, memEntry)} already exists — delete it first if you want a fresh copy.`,
+  // --- .fapony/.memory/ (empty dir — mem commands are built into fapony now) ---
+  const memoryDirPath = join(targetPath, memoryDir(config));
+  if (existsSync(memoryDirPath)) {
+    console.log(`  ${relative(targetPath, memoryDirPath)}/ — already exists`);
+  } else {
+    mkdirSync(memoryDirPath, { recursive: true });
+    console.log(
+      `  ${relative(targetPath, memoryDirPath)}/ — mem commands are built into fapony (fapony mem ...)`,
     );
   }
-  const templateDir = join(import.meta.dir, "..", "templates", "mem");
-  const files = copyDir(templateDir, memoryDir);
 
   console.log(`scaffolded ${targetPath}/`);
   console.log(
@@ -166,13 +184,13 @@ export function initProject(targetPath: string, config?: Config): void {
     `  ${evidenceFile(config)}    — allowlist for 'fapony report' (edit the cmds!)`,
   );
   console.log(
-    `  ${relative(targetPath, memoryDir)}/ — ${files.length} files from template`,
+    `  ${relative(targetPath, memoryDirPath)}/ — mem commands are built into fapony (fapony mem ...)`,
   );
   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`,
   );
-  console.log(RULES_SNIPPET(memEntry));
+  console.log(RULES_SNIPPET());
 }
 
 const AGENT_RULE_FILES = ["CLAUDE.md", "AGENTS.md"];
@@ -228,8 +246,7 @@ export async function cmdInit(args: string[]): Promise<void> {
   );
   if (!isAffirmative(answer)) return;
 
-  const memEntry = memoryEntry();
-  const snippet = `\n\n${RULES_SNIPPET(memEntry)}\n`;
+  const snippet = `\n\n${RULES_SNIPPET()}\n`;
   for (const f of found) {
     appendFileSync(f, snippet);
     console.log(`  appended to ${relative(targetPath, f)}`);

package/src/install/claude.ts

@@ -345,11 +345,13 @@ function installStopHook(dryRun: boolean, deps: InstallDeps): void {
 }
 
 /**
- * PreToolUse hook on Read: annotates a full-file read of a large source file
- * with one factual line (size + the review-seed command). Annotate only —
- * no permissionDecision is ever returned, the read always proceeds; and no
- * "already read" dedupe (context compaction makes that claim false). The
- * matcher "Read" keeps the spawn off every other tool call.
+ * PreToolUse hook on Read: annotates a full-file read with one factual line —
+ * the size + the review-seed command when the file is large, and the re-read
+ * line when the same path was already read this session and its mtime has not
+ * moved (an unchanged file, so the second read buys nothing; a changed one
+ * stays silent). Annotate only — no permissionDecision is ever returned, the
+ * read always proceeds. The matcher "Read" keeps the spawn off every other
+ * tool call.
  */
 function installReadHintHook(dryRun: boolean, deps: InstallDeps): void {
   ensureClaudeHook(dryRun, deps, {

package/src/install/opencode.ts

@@ -185,27 +185,64 @@ export function readHintPluginSource(root: string): string {
 // factual review-seed pointer, plus any convention debt or mem-log row about
 // the file. Annotate only: never blocks, never dedupes.
 // Generated by \`fapony install\` — edit src/hook.ts in the fapony checkout.
-import { readHintFor, readContextLines } from ${hookModule};
+import { readHintFor, rereadHintFor, readContextData, recordHintFire } from ${hookModule};
 
 export const FaponyReadHint = async ({ directory }) => {
   return {
     "tool.execute.after": async (input, output) => {
       try {
         if (input.tool !== "read") return;
+        const filePath = input.args?.filePath;
         const parts = [];
         const hint = readHintFor({
-          filePath: input.args?.filePath,
+          filePath,
           offset: input.args?.offset,
           limit: input.args?.limit,
           cwd: directory,
         });
         if (hint) parts.push(hint);
-        for (const line of readContextLines(input.args?.filePath, directory)) {
-          parts.push(line);
+        const reread = rereadHintFor({
+          filePath,
+          offset: input.args?.offset,
+          limit: input.args?.limit,
+          cwd: directory,
+          session: input.sessionID,
+        });
+        if (reread) parts.push(reread);
+        const ctx = readContextData(filePath, directory);
+        if (ctx) {
+          for (const line of [...ctx.debtLines, ...ctx.memLines]) {
+            parts.push(line);
+          }
         }
         if (parts.length > 0 && typeof output.output === "string") {
           output.output = output.output + "\\n" + parts.join("\\n");
         }
+
+        // --- hint-fire log (PLAN-feedback-surface chunk 1) ---
+        // After output — best-effort, never block the hint.
+        if (ctx?.worktree) {
+          const rel = typeof filePath === "string" ? (() => {
+            try {
+              const { realpathSync } = require("node:fs");
+              const { relative } = require("node:path");
+              const { join: pjoin } = require("node:path");
+              const wt = ctx.worktree;
+              const abs = realpathSync(filePath.startsWith("/") ? filePath : pjoin(wt, filePath));
+              const r = relative(wt, abs).split("\\\\").join("/");
+              return r.startsWith("..") ? null : r;
+            } catch { return null; }
+          })() : null;
+          if (hint) {
+            recordHintFire({ ts: new Date().toISOString(), worktree: ctx.worktree, surface: "read", file: rel, count: 1 });
+          }
+          if (ctx.debtIds.length > 0) {
+            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 });
+          }
+        }
       } catch {
         // a hint must never break a read
       }
@@ -230,7 +267,7 @@ export function commitHintPluginSource(root: string): string {
 // verdict reminder when commits have no verdict filed yet.
 // Annotate only: never blocks, never dedupes.
 // Generated by \`fapony install\` — edit src/hook.ts in the fapony checkout.
-import { commitHintFor } from ${hookModule};
+import { commitHintFor, recordHintFire } from ${hookModule};
 
 export const FaponyCommitHint = async ({ directory }) => {
   return {
@@ -245,6 +282,23 @@ export const FaponyCommitHint = async ({ directory }) => {
         if (hint && typeof output.output === "string") {
           output.output = output.output + "\\n" + hint;
         }
+
+        // --- hint-fire log (PLAN-feedback-surface chunk 1) ---
+        // After output — best-effort, never block the hint.
+        if (hint) {
+          try {
+            const { spawnSync } = require("node:child_process");
+            const git = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: directory, encoding: "utf-8" });
+            if (git.status === 0) {
+              const worktree = require("node:fs").realpathSync(git.stdout.trim());
+              // Count commits from the hint message (lines starting with "fapony:   ").
+              const commitLines = hint.split("\\n").filter(l => /^fapony:\\s+\\w{7,}/.test(l));
+              recordHintFire({ ts: new Date().toISOString(), worktree, surface: "commit", file: null, count: commitLines.length || 1 });
+            }
+          } catch {
+            // best-effort
+          }
+        }
       } catch {
         // a hint must never break a bash command
       }

package/src/lint-baseline.ts

@@ -12,13 +12,7 @@
 // never blocks — the agent decides whether to fix the old issues too
 
 import { execSync } from "node:child_process";
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { faponyDir } from "./db/load.js";
 import { assertSafe } from "./safety.js";

package/src/mcp/evidence.ts

@@ -41,7 +41,7 @@ const AGENT_PROVENANCE = { verified: false, source: "agent_report" } as const;
 
 // --- App-scoped resolution ---
 
-// Monorepo group dirs — same order as templates/mem/store.ts (first hit wins there;
+// Monorepo group dirs — same order as src/mem/store.ts (first hit wins there;
 // here every file must already agree on one group+app, so order never matters).
 const APP_GROUPS = ["apps", "packages", "services"];