fapony 0.3.6 → 0.5.0

package/src/install/opencode.ts

@@ -2,7 +2,13 @@
 //
 // Adds mcp.fapony config to ~/.config/opencode/opencode.json or opencode.jsonc.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { claudeSkillsDir, linkSkills, reportSkills } from "./skills.js";
@@ -84,6 +90,11 @@ function isConfigured(mcp: Record<string, unknown> | undefined): boolean {
 export interface OpencodeInstallOpts {
   /** Opt-in only: write the git-autonomy rewrite plugin. Never default. */
   gitAutonomy?: boolean;
+  /** Refresh only the generated plugin bodies — skip the opencode.json write
+   *  and the skills symlink entirely. This is `fapony update`'s post-pull
+   *  refresh: it must touch only fapony-owned plugin files, never the user's
+   *  config (rule 6c — overwriting what exists = ask first, or refuse). */
+  pluginsOnly?: boolean;
 }
 
 export function cmdInstallOpencode(
@@ -94,6 +105,21 @@ export function cmdInstallOpencode(
   const exitFn = deps.exit ?? defaultExit;
   const getHome = deps.homedir ?? homedir;
 
+  const installPlugins = (): void => {
+    installReadHintPlugin(dryRun, getHome);
+    installCommitHintPlugin(dryRun, getHome);
+    installEditHintPlugin(dryRun, getHome);
+    installSessionStartPlugin(dryRun, getHome);
+    if (opts.gitAutonomy) installGitAutonomyPlugin(dryRun, getHome);
+  };
+
+  // Refresh path: plugin bodies only — returns before findOpencodeConfig, so
+  // neither opencode.json nor the skills symlink is read or written.
+  if (opts.pluginsOnly) {
+    installPlugins();
+    return;
+  }
+
   const configPath = findOpencodeConfig(getHome);
   let before: Record<string, unknown>;
   let isNew = false;
@@ -117,11 +143,7 @@ export function cmdInstallOpencode(
     if (configPath) console.error(`  (${configPath})`);
     const skillsDir = claudeSkillsDir(getHome);
     reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
-    installReadHintPlugin(dryRun, getHome);
-    installCommitHintPlugin(dryRun, getHome);
-    installEditHintPlugin(dryRun, getHome);
-    installSessionStartPlugin(dryRun, getHome);
-    if (opts.gitAutonomy) installGitAutonomyPlugin(dryRun, getHome);
+    installPlugins();
     return;
   }
 
@@ -143,11 +165,7 @@ export function cmdInstallOpencode(
       console.error(`  (${configPath})`);
     }
     console.log(computeDiff(before, after));
-    installReadHintPlugin(dryRun, getHome);
-    installCommitHintPlugin(dryRun, getHome);
-    installEditHintPlugin(dryRun, getHome);
-    installSessionStartPlugin(dryRun, getHome);
-    if (opts.gitAutonomy) installGitAutonomyPlugin(dryRun, getHome);
+    installPlugins();
     return;
   }
 
@@ -167,11 +185,7 @@ export function cmdInstallOpencode(
   console.error(`  restart opencode to load the MCP server`);
   const skillsDir = claudeSkillsDir(getHome);
   reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
-  installReadHintPlugin(dryRun, getHome);
-  installCommitHintPlugin(dryRun, getHome);
-  installEditHintPlugin(dryRun, getHome);
-  installSessionStartPlugin(dryRun, getHome);
-  if (opts.gitAutonomy) installGitAutonomyPlugin(dryRun, getHome);
+  installPlugins();
 }
 
 /**
@@ -257,6 +271,9 @@ export const FaponyReadHint = async ({ directory }) => {
           if (ctx.memLines.length > 0) {
             recordHintFire({ ts: new Date().toISOString(), worktree: ctx.worktree, surface: "mem", file: rel, count: ctx.memLines.length });
           }
+          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 });
+          }
         }
       } catch {
         // a hint must never break a read
@@ -398,6 +415,9 @@ export const FaponyEditHint = async ({ directory }) => {
               if (ctx?.memLines?.length) {
                 recordHintFire({ ts: new Date().toISOString(), worktree, surface: "mem", file: rel, count: ctx.memLines.length });
               }
+              if (ctx?.openBugIds?.length) {
+                recordHintFire({ ts: new Date().toISOString(), worktree, surface: "open-bug", file: rel, count: ctx.openBugIds.length, ids: ctx.openBugIds });
+              }
             }
           } catch {
             // best-effort
@@ -412,102 +432,102 @@ export const FaponyEditHint = async ({ directory }) => {
 `;
 }
 
-function installReadHintPlugin(dryRun: boolean, getHome: () => string): void {
+/**
+ * Write one generated OpenCode plugin file, refreshing our own older copy.
+ *
+ * Ownership is the exported plugin name (`FaponyReadHint`, …) — the one token
+ * every generated body carries. A file without it is someone's own plugin and
+ * is never touched, same rule as the skill symlinks. A file *with* it but
+ * different content is ours and stale: the plugin body is baked at install
+ * time, so a `git pull` updates the imported logic (src/hook.ts) but never this
+ * file. Refusing to overwrite it is how an old hook stays reachable forever —
+ * the Thai-only bug marker survived exactly that way — so ours gets rewritten
+ * in place, and only a foreign file is reported and left alone.
+ */
+function installPluginFile(
+  dryRun: boolean,
+  getHome: () => string,
+  fileName: string,
+  label: string,
+  ownedName: string,
+  desired: string,
+): void {
   const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
-  const pluginPath = join(pluginsDir, "fapony-read-hint.ts");
-  if (existsSync(pluginPath)) {
-    let current = "";
+  const pluginPath = join(pluginsDir, fileName);
+  const write = (): boolean => {
+    if (dryRun) return true;
     try {
-      current = readFileSync(pluginPath, "utf-8");
-    } catch {
-      current = "";
+      mkdirSync(pluginsDir, { recursive: true });
+      writeFileSync(pluginPath, desired, "utf-8");
+      return true;
+    } catch (e) {
+      console.error(`  ${label}: failed to write — ${(e as Error).message}`);
+      return false;
     }
-    if (current.includes("readHintFor")) {
-      console.error(`  read hint: already installed — no change`);
-      return;
+  };
+
+  if (!existsSync(pluginPath)) {
+    if (write()) {
+      console.error(
+        `  ${label}: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+      );
     }
+    return;
+  }
+
+  let current = "";
+  try {
+    current = readFileSync(pluginPath, "utf-8");
+  } catch {
+    current = "";
+  }
+  if (current === desired) {
+    console.error(`  ${label}: already installed — no change`);
+    return;
+  }
+  if (!current.includes(ownedName)) {
     console.error(
-      `  read hint: ${pluginPath} exists but isn't fapony's — not overwriting.`,
+      `  ${label}: ${pluginPath} exists but isn't fapony's — not overwriting.`,
     );
     return;
   }
-  if (!dryRun) {
-    try {
-      mkdirSync(pluginsDir, { recursive: true });
-      writeFileSync(pluginPath, readHintPluginSource(INSTALL_ROOT), "utf-8");
-    } catch (e) {
-      console.error(`  read hint: failed to write — ${(e as Error).message}`);
-      return;
-    }
+  if (write()) {
+    console.error(
+      `  ${label}: ${dryRun ? "would update" : "updated"} ${pluginPath}`,
+    );
   }
-  console.error(
-    `  read hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+}
+
+function installReadHintPlugin(dryRun: boolean, getHome: () => string): void {
+  installPluginFile(
+    dryRun,
+    getHome,
+    "fapony-read-hint.ts",
+    "read hint",
+    "FaponyReadHint",
+    readHintPluginSource(INSTALL_ROOT),
   );
 }
 
 function installCommitHintPlugin(dryRun: boolean, getHome: () => string): void {
-  const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
-  const pluginPath = join(pluginsDir, "fapony-commit-hint.ts");
-  if (existsSync(pluginPath)) {
-    let current = "";
-    try {
-      current = readFileSync(pluginPath, "utf-8");
-    } catch {
-      current = "";
-    }
-    if (current.includes("commitHintFor")) {
-      console.error(`  commit hint: already installed — no change`);
-      return;
-    }
-    console.error(
-      `  commit hint: ${pluginPath} exists but isn't fapony's — not overwriting.`,
-    );
-    return;
-  }
-  if (!dryRun) {
-    try {
-      mkdirSync(pluginsDir, { recursive: true });
-      writeFileSync(pluginPath, commitHintPluginSource(INSTALL_ROOT), "utf-8");
-    } catch (e) {
-      console.error(`  commit hint: failed to write — ${(e as Error).message}`);
-      return;
-    }
-  }
-  console.error(
-    `  commit hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+  installPluginFile(
+    dryRun,
+    getHome,
+    "fapony-commit-hint.ts",
+    "commit hint",
+    "FaponyCommitHint",
+    commitHintPluginSource(INSTALL_ROOT),
   );
 }
 
 function installEditHintPlugin(dryRun: boolean, getHome: () => string): void {
-  const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
-  const pluginPath = join(pluginsDir, "fapony-edit-hint.ts");
-  if (existsSync(pluginPath)) {
-    let current = "";
-    try {
-      current = readFileSync(pluginPath, "utf-8");
-    } catch {
-      current = "";
-    }
-    if (current.includes("editHintFor")) {
-      console.error(`  edit hint: already installed — no change`);
-      return;
-    }
-    console.error(
-      `  edit hint: ${pluginPath} exists but isn't fapony's — not overwriting.`,
-    );
-    return;
-  }
-  if (!dryRun) {
-    try {
-      mkdirSync(pluginsDir, { recursive: true });
-      writeFileSync(pluginPath, editHintPluginSource(INSTALL_ROOT), "utf-8");
-    } catch (e) {
-      console.error(`  edit hint: failed to write — ${(e as Error).message}`);
-      return;
-    }
-  }
-  console.error(
-    `  edit hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+  installPluginFile(
+    dryRun,
+    getHome,
+    "fapony-edit-hint.ts",
+    "edit hint",
+    "FaponyEditHint",
+    editHintPluginSource(INSTALL_ROOT),
   );
 }
 
@@ -571,50 +591,13 @@ function installSessionStartPlugin(
   dryRun: boolean,
   getHome: () => string,
 ): void {
-  const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
-  const pluginPath = join(pluginsDir, "fapony-session-start.ts");
-  if (existsSync(pluginPath)) {
-    let current = "";
-    try {
-      current = readFileSync(pluginPath, "utf-8");
-    } catch {
-      current = "";
-    }
-    if (current.includes("FaponySessionStart")) {
-      // Ours — and generated, so never overwritten. A file baked by an older
-      // fapony differs from what we generate now: say so instead of "no change",
-      // which is how the pre-hook plugin (mub2ezhi) would have been kept.
-      if (current !== sessionStartPluginSource(INSTALL_ROOT)) {
-        console.error(
-          `  session start: stale fapony plugin — delete ${pluginPath} and re-run install`,
-        );
-        return;
-      }
-      console.error(`  session start: already installed — no change`);
-      return;
-    }
-    console.error(
-      `  session start: ${pluginPath} exists but isn't fapony's — not overwriting.`,
-    );
-    return;
-  }
-  if (!dryRun) {
-    try {
-      mkdirSync(pluginsDir, { recursive: true });
-      writeFileSync(
-        pluginPath,
-        sessionStartPluginSource(INSTALL_ROOT),
-        "utf-8",
-      );
-    } catch (e) {
-      console.error(
-        `  session start: failed to write — ${(e as Error).message}`,
-      );
-      return;
-    }
-  }
-  console.error(
-    `  session start: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+  installPluginFile(
+    dryRun,
+    getHome,
+    "fapony-session-start.ts",
+    "session start",
+    "FaponySessionStart",
+    sessionStartPluginSource(INSTALL_ROOT),
   );
 }
 
@@ -680,45 +663,27 @@ function installGitAutonomyPlugin(
   dryRun: boolean,
   getHome: () => string,
 ): void {
+  installPluginFile(
+    dryRun,
+    getHome,
+    "fapony-git-autonomy.ts",
+    "git-autonomy",
+    "FaponyGitAutonomy",
+    gitAutonomyPluginSource(INSTALL_ROOT),
+  );
+}
+
+/** The fapony-generated plugin files present in an OpenCode install. Empty =
+ *  OpenCode has none, so `fapony update` must not install into a client the user
+ *  never opted into. Callers also use it to tell whether the opt-in git-autonomy
+ *  plugin is installed, so an update can refresh it without ever creating it. */
+export function opencodePluginFiles(getHome: () => string = homedir): string[] {
   const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
-  const pluginPath = join(pluginsDir, "fapony-git-autonomy.ts");
-  if (existsSync(pluginPath)) {
-    let current = "";
-    try {
-      current = readFileSync(pluginPath, "utf-8");
-    } catch {
-      current = "";
-    }
-    if (current.includes("FaponyGitAutonomy")) {
-      // Ours — and generated, so never overwritten. Same stale-check shape
-      // as the session-start plugin: an older generation must say so instead
-      // of "no change", or a fixed rewrite never reaches the client.
-      if (current !== gitAutonomyPluginSource(INSTALL_ROOT)) {
-        console.error(
-          `  git-autonomy: stale fapony plugin — delete ${pluginPath} and re-run install --git-autonomy`,
-        );
-        return;
-      }
-      console.error(`  git-autonomy: already installed — no change`);
-      return;
-    }
-    console.error(
-      `  git-autonomy: ${pluginPath} exists but isn't fapony's — not overwriting.`,
+  try {
+    return readdirSync(pluginsDir).filter(
+      (f) => f.startsWith("fapony-") && f.endsWith(".ts"),
     );
-    return;
+  } catch {
+    return [];
   }
-  if (!dryRun) {
-    try {
-      mkdirSync(pluginsDir, { recursive: true });
-      writeFileSync(pluginPath, gitAutonomyPluginSource(INSTALL_ROOT), "utf-8");
-    } catch (e) {
-      console.error(
-        `  git-autonomy: failed to write — ${(e as Error).message}`,
-      );
-      return;
-    }
-  }
-  console.error(
-    `  git-autonomy: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
-  );
 }

package/src/install.ts

@@ -1,4 +1,4 @@
-// src/install.ts — `fapony install --platform opencode|claude|cursor|zcode|codex` command.
+// src/install.ts — `fapony install --platform antigravity|agy|opencode|claude|cursor|zcode|codex` command.
 // opencode: adds mcp.fapony config to ~/.config/opencode/opencode.json or opencode.jsonc.
 // claude: shells out to `claude mcp add` (never parses/writes ~/.claude.json directly).
 // cursor: writes mcpServers.fapony to ~/.cursor/mcp.json directly and merges the
@@ -39,7 +39,9 @@ export {
   editHintPluginSource,
   gitAutonomyPluginSource,
   type OpencodeInstallOpts,
+  opencodePluginFiles,
   readHintPluginSource,
+  sessionStartPluginSource,
 } from "./install/opencode.js";
 export {
   agentsSkillsDir,
@@ -57,13 +59,17 @@ export async function cmdInstall(
   args: string[],
   deps: InstallDeps = {},
 ): Promise<void> {
-  const platform = args.find((a) => !a.startsWith("--"));
+  const platformArg = args.find((a) => !a.startsWith("--"));
+  // `agy` = Antigravity's CLI name — alias, same provider.
+  const platform = platformArg === "agy" ? "antigravity" : platformArg;
   const dryRun = args.includes("--dry-run");
   const installAll = args.includes("--all");
   // Opt-in only: the git-autonomy rewrite is an opinion (commit-as-you-go),
   // not a utility — never installed unless this flag rides along, including
   // via --all. Opencode-only; other platforms ignore it.
   const gitAutonomy = args.includes("--git-autonomy");
+  // Refresh-only seam for `fapony update`: plugin bodies, never opencode.json.
+  const pluginsOnly = args.includes("--plugins-only");
 
   // --- explicit platform: original behavior, unchanged ---
   if (platform === "antigravity") {
@@ -87,15 +93,15 @@ export async function cmdInstall(
     return;
   }
   if (platform === "opencode") {
-    cmdInstallOpencode(dryRun, deps, { gitAutonomy });
+    cmdInstallOpencode(dryRun, deps, { gitAutonomy, pluginsOnly });
     return;
   }
   if (platform !== undefined) {
     console.error(
-      `usage: fapony install --platform antigravity|opencode|claude|cursor|zcode|codex [--dry-run] [--git-autonomy]`,
+      `usage: fapony install --platform antigravity|agy|opencode|claude|cursor|zcode|codex [--dry-run] [--git-autonomy] [--plugins-only]`,
     );
     console.error(
-      `  supported platforms: antigravity, opencode, claude, cursor, zcode, codex`,
+      `  supported platforms: antigravity (agy), opencode, claude, cursor, zcode, codex`,
     );
     (deps.exit ?? defaultExit)(1);
     return;
@@ -131,7 +137,10 @@ export async function cmdInstall(
   if (installAll) {
     console.error();
     for (const client of found) {
-      installPlatform(client.platform, dryRun, deps, { gitAutonomy });
+      installPlatform(client.platform, dryRun, deps, {
+        gitAutonomy,
+        pluginsOnly,
+      });
     }
     return;
   }
@@ -160,7 +169,10 @@ export async function cmdInstall(
     for (const client of found) {
       const answer = await askFn(`install into ${client.platform}?`, "Y");
       if (isAffirmative(answer)) {
-        installPlatform(client.platform, dryRun, deps, { gitAutonomy });
+        installPlatform(client.platform, dryRun, deps, {
+          gitAutonomy,
+          pluginsOnly,
+        });
       }
     }
   } finally {
@@ -172,7 +184,7 @@ function installPlatform(
   platform: string,
   dryRun: boolean,
   deps: InstallDeps,
-  opts: { gitAutonomy?: boolean } = {},
+  opts: { gitAutonomy?: boolean; pluginsOnly?: boolean } = {},
 ): void {
   switch (platform) {
     case "antigravity":

package/src/mem/commands/plan.ts

@@ -190,6 +190,68 @@ export const collectDepIssues = (active: string[]): string[] => {
   return issues;
 };
 
+// W1: status header says not-started but chunks are ticked.
+// W2: all chunks ticked but header never marked shipped.
+// WARN-level only — counted separately from issues, never changes exit code.
+//
+// Vocab measured from .fapony/{plan,done}/*.md (2026-09-23):
+//   in-progress 8 · done 4 · shipped/✅ shipped 6 · draft 1
+//   frontmatter status: shipped 8 · blocked 2
+const NOT_STARTED =
+  /(?:^|\n)>\s*\*?\*?Status:?\*?\*?\s+.*(?:draft|drafted|not[\s-]started)/i;
+const SHIPPED_RE =
+  /(?:^|\n)>\s*✅|(?:^|\n)>\s*\*?\*?Status:?\*?\*?\s+.*(?:shipped|done)/i;
+const FM_SHIPPED = /^status:\s*shipped\b/m;
+
+export const collectDriftWarns = (active: string[]): string[] => {
+  const warns: string[] = [];
+  for (const f of active) {
+    const fm = parsePlanFrontmatter(f);
+    // Skip plans whose frontmatter already says shipped/blocked/superseded or
+    // is a tracker — these have their own handling elsewhere.
+    if (FM_SHIPPED.test("") && fm.status === "shipped") continue;
+    if (fm.status === "blocked" || fm.status === "superseded") continue;
+    if (fm.kind === "tracker") continue;
+    // frontmatter status: shipped = already done
+    if (fm.status === "shipped") continue;
+
+    const text = readFileSync(f, "utf8");
+    const relPath = relative(planBase, f);
+    const { checked, unchecked } = countFirstSection(f);
+    const total = checked + unchecked;
+    if (total === 0) continue;
+
+    // W1: header says not-started but chunks are ticked
+    const head = text.slice(0, 2048);
+    if (
+      checked > 0 &&
+      NOT_STARTED.test(head) &&
+      !SHIPPED_RE.test(head) &&
+      !FM_SHIPPED.test(text)
+    ) {
+      // Extract the status value for the message
+      const statusMatch = />\s*\*?\*?Status:?\*?\*?\s+(.+)/i.exec(head);
+      const statusVal = statusMatch?.[1]?.replace(/\*\*/g, "").trim() ?? "?";
+      warns.push(
+        `${relPath} — status header says "${statusVal}" but ${checked} chunk(s) are ticked\n   fix: update the header to 🚧 in-progress or ✅ shipped`,
+      );
+    }
+
+    // W2: all chunks ticked but header never marked shipped
+    if (
+      checked > 0 &&
+      unchecked === 0 &&
+      !SHIPPED_RE.test(head) &&
+      !FM_SHIPPED.test(text)
+    ) {
+      warns.push(
+        `${relPath} — all ${checked} chunk(s) ticked but header never marked shipped\n   fix: add ✅ shipped to the header or run ${planSweepCmd} ${basename(f)} --apply`,
+      );
+    }
+  }
+  return warns;
+};
+
 // status:blocked with every first-section chunk ticked = deferred doc debt:
 // the work reads done but the plan stays in plan/ forever (shippedNotMoved
 // never lists it — HELD excludes it). Trackers never finish, so they are out.
@@ -735,6 +797,10 @@ export const cmdPlanCheck = (a: string[]) => {
   //    (HELD excludes it), so without this flag it sits in plan/ silently.
   for (const issue of collectBlockedTickedIssues(active)) issues.push(issue);
 
+  // 7) Drift warns — W1 (not-started header + ticks) and W2 (all ticked +
+  //    not shipped). WARN-only: counted separately, never changes exit code.
+  const driftWarns = collectDriftWarns(active);
+
   if (!quiet) {
     console.log(
       `closed chunks: ${closed} · citing a commit: ${citing} · verified: ${verified}`,
@@ -759,6 +825,10 @@ export const cmdPlanCheck = (a: string[]) => {
         );
       }
     }
+    if (driftWarns.length > 0) {
+      console.log(`\n⚠ ${driftWarns.length} drift warning(s) (not blocking):`);
+      for (const w of driftWarns) console.log(`- ${w}`);
+    }
   }
 
   if (issues.length === 0) {