fapony 0.3.3 → 0.3.5

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

@@ -0,0 +1,195 @@
+// src/adapters/hooks/edit-hint.ts — Edit hint: importer count + once-per-session dedupe
+//
+// Split from src/hook.ts (PLAN-lib-layer chunk 3). Attaches importer count
+// when editing a source file.
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, relative, sep } from "node:path";
+import { buildGraphCached, SCAN_EXTS } from "../../analyze.js";
+import { recordHintFire } from "../../core/hint-log.js";
+import { sessionKey } from "../../core/hook-helpers.js";
+import { readContextData } from "./context-data.js";
+
+const EDIT_TRACK_DIR = "edit-track";
+
+export interface EditTrackRow {
+  ts: string;
+  path: string;
+}
+
+/** Directory holding one edit log per session. */
+function editTrackDir(): string {
+  const base =
+    process.env.FAPONY_STATE_DIR || join(homedir(), ".config", "fapony");
+  return join(base, EDIT_TRACK_DIR);
+}
+
+/** Absolute path of a session's edit log — may not exist. */
+export function editTrackPath(session: string): string {
+  return join(editTrackDir(), `${sessionKey(session)}.jsonl`);
+}
+
+function editTrackPaths(session: string): Set<string> {
+  const p = editTrackPath(session);
+  if (!existsSync(p)) return new Set();
+  const out = new Set<string>();
+  for (const line of readFileSync(p, "utf-8").split("\n")) {
+    if (!line) continue;
+    try {
+      const r = JSON.parse(line) as EditTrackRow;
+      if (typeof r.path === "string") out.add(r.path);
+    } catch {
+      // a torn line must not lose the rest of the log
+    }
+  }
+  return out;
+}
+
+function appendEditTrackRow(session: string, row: EditTrackRow): void {
+  const dir = editTrackDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  appendFileSync(editTrackPath(session), `${JSON.stringify(row)}\n`, "utf-8");
+}
+
+export interface EditHintInput {
+  filePath: unknown;
+  cwd: string;
+  session?: unknown;
+}
+
+/**
+ * Factual one-liner for editing a source file that has importers, or null.
+ * Every unknown resolves to null — a hint must never fire on a guess.
+ */
+export function editHintFor(opts: EditHintInput): string | null {
+  try {
+    if (typeof opts.filePath !== "string" || opts.filePath === "") return null;
+    const dot = opts.filePath.lastIndexOf(".");
+    if (dot < 0 || !SCAN_EXTS.has(opts.filePath.slice(dot))) return null;
+    const git = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+      cwd: opts.cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (git.exitCode !== 0) return null;
+    const worktree = realpathSync(git.stdout.toString().trim());
+    const abs = (() => {
+      const p = opts.filePath.startsWith("/")
+        ? opts.filePath
+        : join(opts.cwd, opts.filePath);
+      try {
+        return realpathSync(p);
+      } catch {
+        return null;
+      }
+    })();
+    if (!abs) return null;
+    const rel = relative(worktree, abs).split(sep).join("/");
+    if (rel.startsWith("..") || rel === "") return null;
+
+    const importers = buildGraphCached(worktree).dependents.get(rel);
+    if (!importers || importers.size === 0) return null;
+
+    if (typeof opts.session === "string" && opts.session !== "") {
+      if (editTrackPaths(opts.session).has(abs)) return null;
+      appendEditTrackRow(opts.session, {
+        ts: new Date().toISOString(),
+        path: abs,
+      });
+    }
+
+    const n = importers.size;
+    return (
+      `fapony: ${rel} has ${n} importer${n === 1 ? "" : "s"} — ` +
+      `review-seed --files ${rel} lists them (add --callers <export> for one ` +
+      `export's callers); check before changing its shape (skill /lookup-before-edit)`
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Claude Code PreToolUse (matcher Edit): stdin JSON in, additionalContext out. */
+export async function cmdHookEditHint(): Promise<void> {
+  try {
+    const raw = JSON.parse(await Bun.stdin.text()) as {
+      cwd?: string;
+      transcript_path?: string;
+      session_id?: string;
+      tool_input?: {
+        file_path?: unknown;
+      };
+    };
+    const cwd = raw.cwd ?? process.cwd();
+    const filePath = raw.tool_input?.file_path;
+    const session = raw.transcript_path ?? raw.session_id;
+    const parts: string[] = [];
+    const hint = editHintFor({ filePath, cwd, session });
+    if (hint) parts.push(hint);
+    const ctx = readContextData(filePath, cwd);
+    if (ctx) {
+      for (const line of [...ctx.debtLines, ...ctx.memLines]) {
+        parts.push(line);
+      }
+    }
+    if (parts.length > 0) {
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            additionalContext: parts.join("\n"),
+          },
+        }),
+      );
+    }
+
+    // --- hint-fire log ---
+    if (hint) {
+      try {
+        const g = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+          cwd,
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        if (g.exitCode === 0) {
+          const worktree = realpathSync(g.stdout.toString().trim());
+          const abs =
+            typeof filePath === "string"
+              ? (() => {
+                  try {
+                    return realpathSync(
+                      filePath.startsWith("/")
+                        ? filePath
+                        : join(worktree, filePath),
+                    );
+                  } catch {
+                    return null;
+                  }
+                })()
+              : null;
+          const rel = abs
+            ? relative(worktree, abs).split("\\").join("/")
+            : null;
+          recordHintFire({
+            ts: new Date().toISOString(),
+            worktree,
+            surface: "edit",
+            file: rel && !rel.startsWith("..") ? rel : null,
+            count: 1,
+          });
+        }
+      } catch {
+        // best-effort — swallow
+      }
+    }
+  } catch {
+    // any failure = no hint; a hook must never block an edit over a hint
+  }
+}

package/src/adapters/hooks/git-autonomy.ts

@@ -0,0 +1,178 @@
+// src/adapters/hooks/git-autonomy.ts — git-autonomy rewrites as shared logic.
+//
+// A personal opencode plugin (~/.config/opencode/plugins/git-autonomy.ts)
+// rewrote opencode's built-in "never commit unless asked" policy on two
+// surfaces: the system prompt (experimental.chat.system.transform) and the
+// bash tool description (tool.definition). This module is that file's logic,
+// extracted so `fapony install --platform opencode --git-autonomy` can
+// generate a thin plugin that imports it — one copy, updated by `git pull`,
+// same shape as the read/commit/edit/session-start hints.
+//
+// Opt-in only: the installer never writes this unless the flag is passed.
+// The rewrite itself is an opinion (commit-as-you-go), not a utility, so it
+// must never ride the default install path.
+//
+// Stale-regex guard (the "rots silently" problem): upstream text lives in the
+// opencode binary, not in a file, so a reword upstream makes a pattern stop
+// matching with no error. Every rewrite carries `required`; `gitAutonomyStatus`
+// reports required ids that hit nothing — the analyze-like help for this
+// feature. The tone-example cut is required:false: versions without those
+// examples are fine, a missing commit policy is not.
+
+/** Commit-as-you-go policy replacing opencode's ask-first rule. */
+export const GIT_AUTONOMY_COMMIT_POLICY =
+  "Commit each finished unit of work as you go — do not wait to be asked. If the user wants to review before a commit they will say so.";
+
+/** Same policy, bash-tool-description surface. */
+export const GIT_AUTONOMY_TOOL_POLICY =
+  "Commit finished work as you go — do not wait to be asked; never amend published commits or force-push.";
+
+export const GIT_AUTONOMY_PLUGIN_FILE = "fapony-git-autonomy.ts";
+export const GIT_AUTONOMY_PLUGIN_NAME = "FaponyGitAutonomy";
+
+export interface GitAutonomyRewrite {
+  /** Stable id used by gitAutonomyStatus to name the stale pattern. */
+  id: string;
+  pattern: RegExp;
+  replacement: string;
+  /** False = a miss is fine (upstream dropped that text). True = a miss is rot. */
+  required: boolean;
+}
+
+export const GIT_AUTONOMY_SYSTEM_REWRITES: GitAutonomyRewrite[] = [
+  {
+    id: "system-commit-full",
+    pattern: /NEVER commit changes[\s\S]{0,500}?too proactive\./g,
+    replacement: GIT_AUTONOMY_COMMIT_POLICY,
+    required: true,
+  },
+  {
+    id: "system-commit-fallback",
+    pattern: /NEVER commit changes[^.]*\./g,
+    replacement: GIT_AUTONOMY_COMMIT_POLICY,
+    required: true,
+  },
+  {
+    id: "system-bash-desc",
+    pattern:
+      /- Only commit, amend, push, or create PRs when explicitly requested\./g,
+    replacement:
+      "- Commit and push finished work as you go, and open a PR when a branch is ready. Do not amend published commits or force-push.",
+    required: true,
+  },
+  {
+    // "# Tone and style" few-shot examples: from the intro down to the next
+    // heading. Anchored on the unique intro so no other <example> block is
+    // touched. Pure token rent — the surrounding sentences already state the
+    // terseness rules.
+    id: "system-tone-examples",
+    pattern:
+      /Here are some examples to demonstrate appropriate verbosity:[\s\S]*?(?=\n# )/g,
+    replacement: "",
+    required: false,
+  },
+];
+
+export interface GitAutonomyToolRewrite extends GitAutonomyRewrite {
+  toolID: string;
+}
+
+export const GIT_AUTONOMY_TOOL_REWRITES: GitAutonomyToolRewrite[] = [
+  {
+    id: "tool-bash-commit",
+    toolID: "bash",
+    pattern:
+      /- Only commit, amend, push, or create PRs when explicitly requested\./g,
+    replacement: `- ${GIT_AUTONOMY_TOOL_POLICY}`,
+    required: true,
+  },
+];
+
+function fresh(re: RegExp): RegExp {
+  // /g patterns are stateful via lastIndex — clone so repeated calls and
+  // .test-then-.replace sequences never skip a match.
+  return new RegExp(re.source, re.flags);
+}
+
+/**
+ * Apply the system-prompt rewrites. Returns the rewritten text plus the ids
+ * that fired, in order — the caller (plugin) ignores the second half, tests
+ * and gitAutonomyStatus use it to tell "rewrote" from "silently missed".
+ */
+export function rewriteGitAutonomySystem(text: string): {
+  text: string;
+  matched: string[];
+} {
+  const matched: string[] = [];
+  let out = text;
+  for (const r of GIT_AUTONOMY_SYSTEM_REWRITES) {
+    const re = fresh(r.pattern);
+    if (re.test(out)) {
+      matched.push(r.id);
+      out = out.replace(fresh(r.pattern), r.replacement);
+      // The loose fallback must never run once the full block was replaced.
+      if (r.id === "system-commit-full") break;
+    }
+  }
+  return { text: out, matched };
+}
+
+/** Apply the tool.description rewrites for one toolID. */
+export function rewriteGitAutonomyTool(
+  toolID: string,
+  description: string,
+): { description: string; matched: string[] } {
+  const matched: string[] = [];
+  let out = description;
+  for (const r of GIT_AUTONOMY_TOOL_REWRITES) {
+    if (r.toolID !== toolID) continue;
+    const re = fresh(r.pattern);
+    if (re.test(out)) {
+      matched.push(r.id);
+      out = out.replace(fresh(r.pattern), r.replacement);
+    }
+  }
+  return { description: out, matched };
+}
+
+export interface GitAutonomyStatus {
+  /** Required ids that fired at least once across the inputs. */
+  hits: string[];
+  /** Required ids that hit nothing — upstream reworded or moved the text. */
+  stale: string[];
+  /** True when no required pattern is stale. */
+  ok: boolean;
+}
+
+/**
+ * Analyze-like help for this feature: feed the current opencode system lines
+ * + tool descriptions, get back which required patterns are stale. Optional
+ * rewrites (tone examples) never appear in `stale` — their absence is fine.
+ */
+export function gitAutonomyStatus(
+  systemTexts: string[],
+  toolDescs: Record<string, string>,
+): GitAutonomyStatus {
+  const seen = new Set<string>();
+  for (const t of systemTexts) {
+    for (const id of rewriteGitAutonomySystem(t).matched) seen.add(id);
+  }
+  for (const [toolID, desc] of Object.entries(toolDescs)) {
+    for (const id of rewriteGitAutonomyTool(toolID, desc).matched) seen.add(id);
+  }
+  const requiredIds = new Set<string>();
+  for (const r of GIT_AUTONOMY_SYSTEM_REWRITES)
+    if (r.required) requiredIds.add(r.id);
+  for (const r of GIT_AUTONOMY_TOOL_REWRITES)
+    if (r.required) requiredIds.add(r.id);
+  // system-commit-full and system-commit-fallback are two spellings of one
+  // policy: either hit means the policy landed, only both missing is stale.
+  const commitHit =
+    seen.has("system-commit-full") || seen.has("system-commit-fallback");
+  const hits = [...seen].filter((id) => requiredIds.has(id));
+  const stale: string[] = [];
+  if (!commitHit) stale.push("system-commit");
+  if (!seen.has("system-bash-desc")) stale.push("system-bash-desc");
+  if (!seen.has("tool-bash-commit")) stale.push("tool-bash-commit");
+  return { hits, stale, ok: stale.length === 0 };
+}

package/src/adapters/hooks/index.ts

@@ -0,0 +1,80 @@
+// src/adapters/hooks/index.ts — re-export all hook adapters
+
+// Re-export hint-log for backwards compatibility.
+export {
+  type HintFireRow,
+  type HintImpact,
+  hintLogDir,
+  hintLogPath,
+  recordHintFire,
+  worktreeKey,
+} from "../../core/hint-log.js";
+// Re-export pure helpers from core for backwards compatibility.
+export {
+  hookTsMs,
+  sessionKey,
+  utcStamp,
+} from "../../core/hook-helpers.js";
+export { computeHintImpact } from "./compute-hint-impact.js";
+export {
+  type ContextLineData,
+  readContextData,
+  readContextLines,
+} from "./context-data.js";
+export {
+  cmdHookEditHint,
+  type EditHintInput,
+  type EditTrackRow,
+  editHintFor,
+  editTrackPath,
+} from "./edit-hint.js";
+export {
+  GIT_AUTONOMY_COMMIT_POLICY,
+  GIT_AUTONOMY_PLUGIN_FILE,
+  GIT_AUTONOMY_PLUGIN_NAME,
+  GIT_AUTONOMY_SYSTEM_REWRITES,
+  GIT_AUTONOMY_TOOL_POLICY,
+  GIT_AUTONOMY_TOOL_REWRITES,
+  type GitAutonomyRewrite,
+  type GitAutonomyStatus,
+  type GitAutonomyToolRewrite,
+  gitAutonomyStatus,
+  rewriteGitAutonomySystem,
+  rewriteGitAutonomyTool,
+} from "./git-autonomy.js";
+export { cmdHookMvGuard, mvGuardDecision } from "./mv-guard.js";
+export {
+  COMMIT_HINT_MIN_COMMITS,
+  type CommitHintInput,
+  cmdHookReadHint,
+  commitHintFor,
+  READ_HINT_MIN_BYTES,
+  READ_HINT_MIN_LIMIT,
+  type ReadHintInput,
+  type ReadTrackRow,
+  type RereadHintInput,
+  readHintFor,
+  readTrackPath,
+  rereadHintFor,
+} from "./read-hint.js";
+export {
+  capContext,
+  cmdHookSessionStart,
+  SESSION_START_MAX_CHARS,
+  sessionStartContext,
+} from "./session-start.js";
+export {
+  bugSignalFromTranscript,
+  cmdHookStop,
+  cursorTranscriptPath,
+  decideStop,
+  isCodexPayload,
+  isCursorPayload,
+  type NormalizedStopInput,
+  normalizeStopInput,
+  type RawStopPayload,
+  type StopClient,
+  stopBlockedBefore,
+  stopBlockPath,
+  stopOutput,
+} from "./stop.js";

package/src/adapters/hooks/mv-guard.ts

@@ -0,0 +1,52 @@
+// src/adapters/hooks/mv-guard.ts — PreToolUse Bash guard: deny a raw `git mv`
+// of a plan file into a done/ directory, point at `fapony mem plan-sweep
+// --apply` instead.
+//
+// Manual `git mv` skips the link rewrite plan-sweep does — that produced two
+// rounds of dangling links (mem mtjn3ldk, mtl15q4y) and once, a plan moved to
+// a path that doesn't exist (.fapony/plan/done/ instead of .fapony/done/).
+// Every other fapony hook only annotates; this one denies, because asking
+// ("should use plan-sweep") measurably does not change agent behavior —
+// only required/reject and Stop-style blocks do (CLAUDE.md rule 9).
+//
+// Claude-only: OpenCode's tool.execute.after fires after the mv already ran,
+// so there is nothing left to deny by the time that hook sees it.
+
+const MV_PATTERN =
+  /git\s+mv\s+(?:-\S+\s+)*["']?([^"'\s]*\.fapony\/(?:[^/\s]+\/)*plan\/PLAN-[^"'\s]+\.md)["']?\s+["']?([^"'\s]*\bdone\/?)["']?/;
+
+/** Deny reason for a raw `git mv <plan>.md <...done/>` command, or null to allow. */
+export function mvGuardDecision(command: unknown): string | null {
+  if (typeof command !== "string" || command === "") return null;
+  const m = MV_PATTERN.exec(command);
+  if (!m) return null;
+  const [, src] = m;
+  return (
+    `fapony: raw \`git mv\` of a plan into done/ skips the link rewrite — ` +
+    `run \`fapony mem plan-sweep --apply ${src}\` instead, it moves the file ` +
+    `and fixes inbound/outbound links together.`
+  );
+}
+
+/** Claude Code PreToolUse (matcher Bash): stdin JSON in, deny decision out. */
+export async function cmdHookMvGuard(): Promise<void> {
+  try {
+    const raw = JSON.parse(await Bun.stdin.text()) as {
+      tool_input?: { command?: unknown };
+    };
+    const reason = mvGuardDecision(raw.tool_input?.command);
+    if (reason) {
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: reason,
+          },
+        }),
+      );
+    }
+  } catch {
+    // a parse failure must never block a command — silence, not deny
+  }
+}