fapony 0.3.3 → 0.3.4

package/src/adapters/hooks/session-start.ts

@@ -0,0 +1,101 @@
+// src/adapters/hooks/session-start.ts — SessionStart hook: emit mem kickoff
+// as context.
+//
+// Split from src/hook.ts (PLAN-lib-layer chunk 3). sessionStartContext is the
+// one copy shared by Claude/Codex CLI and the generated OpenCode plugin.
+
+import { whereMemDir } from "../../memory.js";
+
+/** Cap on injected context — kickoff is short, a broken repo's output is not. */
+export const SESSION_START_MAX_CHARS = 4_000;
+
+const TRUNCATED = "… truncated — run `fapony mem find <word>` for the rest";
+
+/** Trim to whole lines, keeping the marker's line boundary intact. */
+function headLines(text: string, max: number): string {
+  const cut = text.slice(0, max);
+  const lastNl = cut.lastIndexOf("\n");
+  return (lastNl > 0 ? cut.slice(0, lastNl) : cut).trimEnd();
+}
+
+/**
+ * Trim to whole lines within the cap, with an honest truncation marker.
+ *
+ * Kickoff's ordering is: ranked rows → "## next up" → "## recent". The
+ * most actionable content is at the top (bugs, diff-matched) and in "## next
+ * up". A plain head-cut drops the suggestions — so we try to keep "## next up"
+ * visible. When "## recent" exists, we cut it first; otherwise fall back to
+ * keeping "## next up" at the tail.
+ */
+export function capContext(
+  text: string,
+  max = SESSION_START_MAX_CHARS,
+): string {
+  if (text.length <= max) return text;
+  const recentIdx = text.indexOf("\n## recent");
+  if (recentIdx > 0) {
+    const head = text.slice(0, recentIdx).trimEnd();
+    if (head.length <= max) return head;
+    const nextIdx = head.lastIndexOf("\n## next up");
+    if (nextIdx > 0) {
+      const beforeNext = head.slice(0, nextIdx).trimEnd();
+      const nextTail = head.slice(nextIdx).trimEnd();
+      if (nextTail.length < max / 2) {
+        return `${headLines(beforeNext, max - nextTail.length)}\n${TRUNCATED}\n${nextTail}`;
+      }
+    }
+    return `${headLines(head, max)}\n${TRUNCATED}`;
+  }
+  const at = text.lastIndexOf("\n## next up");
+  const tail = at > 0 ? text.slice(at).trimEnd() : "";
+  if (tail && tail.length < max / 2) {
+    return `${headLines(text, max - tail.length)}\n${TRUNCATED}\n${tail}`;
+  }
+  return `${headLines(text, max)}\n${TRUNCATED}`;
+}
+
+/**
+ * Kickoff output for `cwd`'s mem log, capped — or null when there is no log in
+ * scope, the command fails, or it prints nothing. The single implementation
+ * behind both cmdHookSessionStart (Claude/Codex) and the generated OpenCode
+ * plugin, so a pull of INSTALL_ROOT updates all three.
+ *
+ * `faponyTs` is where the CLI lives. The hook defaults to `Bun.main` (itself,
+ * when run as `bun <root>/fapony.ts hook-session-start`); the OpenCode plugin
+ * must pass its baked path because `Bun.main` inside OpenCode is OpenCode's own
+ * entry, not fapony's.
+ */
+export function sessionStartContext(
+  cwd: string,
+  faponyTs: string = Bun.main,
+): string | null {
+  if (!whereMemDir(cwd).dir) return null;
+  const p = Bun.spawnSync([process.execPath, faponyTs, "mem", "kickoff"], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const out = p.stdout.toString().trim();
+  if (p.exitCode !== 0 || !out) return null;
+  return capContext(out);
+}
+
+/** SessionStart hook: emit sessionStartContext as Claude/Codex JSON. */
+export async function cmdHookSessionStart(): Promise<void> {
+  try {
+    const raw = JSON.parse(await Bun.stdin.text()) as { cwd?: string };
+    const cwd = raw.cwd ?? process.cwd();
+    const ctx = sessionStartContext(cwd);
+    if (!ctx) return;
+    console.log(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: ctx,
+        },
+      }),
+    );
+  } catch {
+    // any failure = no context, never a broken session start
+  }
+}

package/src/adapters/hooks/stop.ts

@@ -0,0 +1,302 @@
+// src/adapters/hooks/stop.ts — Stop hook: refuse to end a turn that produced
+// commits but no mem row.
+//
+// Split from src/hook.ts (PLAN-lib-layer chunk 3). Pure helpers (utcStamp,
+// hookTsMs, sessionKey) live in core/hook-helpers.ts.
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { hookTsMs, sessionKey, utcStamp } from "../../core/hook-helpers.js";
+import { readMemLog, whereMemDir } from "../../memory.js";
+
+// --- Types ---
+
+export interface RawStopPayload {
+  // Claude Code
+  cwd?: string;
+  transcript_path?: string | null;
+  stop_hook_active?: boolean;
+  // Cursor — common schema (https://cursor.com/docs/agent/hooks)
+  workspace_roots?: string[];
+  conversation_id?: string;
+  loop_count?: number;
+  status?: string;
+  // Codex — hooks contract (https://learn.chatgpt.com/docs/hooks)
+  session_id?: string;
+  model?: string;
+  permission_mode?: string;
+}
+
+export type StopClient = "claude" | "cursor" | "codex";
+
+export interface NormalizedStopInput {
+  client: StopClient;
+  cwd: string;
+  transcriptPath: string | null;
+  stopHookActive: boolean;
+}
+
+// --- Pure helpers ---
+
+/** Cursor transcript location derived from the conversation id. */
+export function cursorTranscriptPath(
+  home: string,
+  cwd: string,
+  conversationId: string,
+): string {
+  const slug = cwd.replace(/^\//, "").replace(/\//g, "-");
+  return join(
+    home,
+    ".cursor",
+    "projects",
+    slug,
+    "agent-transcripts",
+    conversationId,
+    `${conversationId}.jsonl`,
+  );
+}
+
+export function isCursorPayload(raw: RawStopPayload): boolean {
+  return (
+    Array.isArray(raw.workspace_roots) ||
+    typeof raw.conversation_id === "string"
+  );
+}
+
+/** Codex sends permission_mode and/or model — fields neither Claude nor Cursor include in Stop. */
+export function isCodexPayload(raw: RawStopPayload): boolean {
+  return (
+    typeof raw.permission_mode === "string" ||
+    (typeof raw.model === "string" && !isCursorPayload(raw))
+  );
+}
+
+/** Field-mapping only — all three clients feed the same decideStop below. */
+export function normalizeStopInput(
+  raw: RawStopPayload,
+  home: string,
+): NormalizedStopInput {
+  if (isCodexPayload(raw)) {
+    return {
+      client: "codex",
+      cwd: raw.cwd ?? process.cwd(),
+      transcriptPath:
+        typeof raw.transcript_path === "string" && raw.transcript_path
+          ? raw.transcript_path
+          : null,
+      stopHookActive: raw.stop_hook_active === true,
+    };
+  }
+  if (isCursorPayload(raw)) {
+    const cwd = raw.workspace_roots?.[0] ?? raw.cwd ?? process.cwd();
+    let transcriptPath =
+      typeof raw.transcript_path === "string" && raw.transcript_path
+        ? raw.transcript_path
+        : null;
+    if (!transcriptPath && raw.conversation_id) {
+      transcriptPath = cursorTranscriptPath(home, cwd, raw.conversation_id);
+    }
+    return {
+      client: "cursor",
+      cwd,
+      transcriptPath,
+      stopHookActive: (raw.loop_count ?? 0) > 0,
+    };
+  }
+  return {
+    client: "claude",
+    cwd: raw.cwd ?? process.cwd(),
+    transcriptPath: raw.transcript_path ?? null,
+    stopHookActive: raw.stop_hook_active === true,
+  };
+}
+
+/**
+ * Pure decision: block when this session produced commits but no mem row
+ * newer than session start exists.
+ */
+export function decideStop(opts: {
+  stopHookActive: boolean;
+  worktree: string | null;
+  commits: number;
+  since?: string | null;
+  commitList?: string[];
+  memLastTs?: string | null;
+  memCandidates?: string[];
+}): string | null {
+  if (opts.stopHookActive) return null;
+  if (!opts.worktree) return null;
+  if (opts.commits < 1) return null;
+  if (!opts.memLastTs && !opts.memCandidates?.length) return null;
+  if (opts.since && opts.memLastTs) {
+    const sinceMs = hookTsMs(opts.since);
+    const memMs = hookTsMs(opts.memLastTs);
+    if (Number.isNaN(sinceMs) || Number.isNaN(memMs)) return null;
+    if (memMs >= sinceMs) return null;
+  }
+
+  const lines: string[] = [
+    `${opts.commits} commit(s) landed in ${opts.worktree} this session — no mem row recorded for this work.`,
+  ];
+  const list = opts.commitList ?? [];
+  for (const c of list.slice(0, 5)) lines.push(`  ${c}`);
+  if (list.length > 5) lines.push(`  … +${list.length - 5} more`);
+  if (opts.memLastTs) {
+    lines.push(
+      `mem: last row ${opts.memLastTs.slice(0, 10)} — nothing newer this session`,
+    );
+  } else if (opts.memCandidates?.length) {
+    lines.push(
+      `mem: no log in scope from ${opts.worktree} — found ` +
+        `${opts.memCandidates.join(", ")} (run mem commands from there, or --mem-dir)`,
+    );
+  }
+
+  lines.push(
+    `Record a mem row before ending: fapony mem add <decision|bug|note> "what happened" --files <files> ` +
+      `${opts.worktree}/.fapony/plan/PLAN.md (or the relevant plan). ` +
+      `files[] is required — a row without it is unfindable when you touch that file next session.`,
+  );
+  return lines.join("\n");
+}
+
+/** Claude blocks with decision:block; Cursor auto-submits as followup_message;
+ *  Codex continues with decision:block + reason. */
+export function stopOutput(client: StopClient, reason: string): string {
+  if (client === "cursor") return JSON.stringify({ followup_message: reason });
+  if (client === "codex") return JSON.stringify({ decision: "block", reason });
+  return JSON.stringify({ decision: "block", reason });
+}
+
+// --- Block dedupe ---
+
+const STOP_BLOCK_DIR = "stop-block";
+
+interface StopBlockRow {
+  ts: string;
+  worktree: string;
+}
+
+/** Absolute path of a session's block log — may not exist. */
+export function stopBlockPath(session: string): string {
+  const base =
+    process.env.FAPONY_STATE_DIR || join(homedir(), ".config", "fapony");
+  return join(base, STOP_BLOCK_DIR, `${sessionKey(session)}.jsonl`);
+}
+
+/**
+ * True when this session already blocked for this worktree — the caller then
+ * lets the turn end. Records the block when it has not.
+ */
+export function stopBlockedBefore(
+  session: string | null,
+  worktree: string,
+): boolean {
+  if (!session) return false;
+  const path = stopBlockPath(session);
+  try {
+    if (existsSync(path)) {
+      for (const line of readFileSync(path, "utf-8").split("\n")) {
+        if (!line) continue;
+        try {
+          if ((JSON.parse(line) as StopBlockRow).worktree === worktree) {
+            return true;
+          }
+        } catch {
+          // a torn line must not lose the rest of the log
+        }
+      }
+    }
+    const dir = join(path, "..");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const row: StopBlockRow = { ts: new Date().toISOString(), worktree };
+    appendFileSync(path, `${JSON.stringify(row)}\n`, "utf-8");
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+function git(args: string[], cwd: string): string | null {
+  try {
+    const p = Bun.spawnSync(["git", ...args], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    return p.exitCode === 0 ? p.stdout.toString().trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Reads the Stop-hook JSON on stdin, prints a block decision or nothing. */
+export async function cmdHookStop(): Promise<void> {
+  let reason: string | null = null;
+  let client: StopClient = "claude";
+  try {
+    const raw = JSON.parse(await Bun.stdin.text()) as RawStopPayload;
+    const norm = normalizeStopInput(raw, homedir());
+    client = norm.client;
+    if (client === "cursor" && raw.status !== "completed") return;
+
+    const worktree = git(["rev-parse", "--show-toplevel"], norm.cwd);
+
+    let since: string | null = null;
+    if (norm.transcriptPath) {
+      try {
+        since = utcStamp(statSync(norm.transcriptPath).birthtime);
+      } catch {
+        since = null;
+      }
+    }
+
+    let commits = 0;
+    let commitList: string[] = [];
+    let memLastTs: string | null = null;
+    let memCandidates: string[] = [];
+    if (worktree && since) {
+      const log = git(
+        ["log", "--since", `${since} +0000`, "--format=%h %s"],
+        norm.cwd,
+      );
+      commitList = log ? log.split("\n").filter(Boolean) : [];
+      commits = commitList.length;
+      try {
+        const mem = readMemLog(worktree);
+        memLastTs = mem.rows[0]?.ts ?? null;
+        if (!memLastTs) memCandidates = whereMemDir(worktree).candidates ?? [];
+      } catch {
+        memLastTs = null;
+      }
+    }
+
+    reason = decideStop({
+      stopHookActive: norm.stopHookActive,
+      worktree: since ? worktree : null,
+      commits,
+      since,
+      commitList,
+      memLastTs,
+      memCandidates,
+    });
+    if (
+      reason &&
+      worktree &&
+      stopBlockedBefore(norm.transcriptPath, worktree)
+    ) {
+      reason = null;
+    }
+  } catch {
+    reason = null;
+  }
+
+  if (reason) console.log(stopOutput(client, reason));
+}

package/src/{mcp → adapters/mcp}/evidence.ts

@@ -23,8 +23,8 @@ import {
   evidenceFile,
   FAPONY_DIR,
   safetyDeny,
-} from "../db/index.js";
-import { assertSafe } from "../safety.js";
+} from "../../core/config.js";
+import { assertSafe } from "../../safety.js";
 import type { EvidenceItem, EvidenceStatus } from "./primitives.js";
 
 // --- Config shape (.fapony/evidence.json by default, paths.evidenceFile to move it) ---

package/src/{mcp → adapters/mcp}/primitives.ts

@@ -7,8 +7,8 @@
 // §0 rule: add-only — never remove or rename exported symbols.
 
 import { execSync } from "node:child_process";
-import type { BlastEntry } from "../analyze.js";
-import { ROOT } from "../update.js";
+import type { BlastEntry } from "../../analyze.js";
+import { ROOT } from "../../update.js";
 
 // ─── Server build identity ─────────────────────────────────────────────
 

package/src/{mcp → adapters/mcp}/tools/check.ts

@@ -1,6 +1,6 @@
 // src/mcp/tools/check.ts — handoff_check tool
 
-import { blastRadiusForWorktree } from "../../analyze.js";
+import { blastRadiusForWorktree } from "../../../analyze.js";
 import type { CheckResult } from "../primitives.js";
 import { errorResult, jsonResult, type ToolResult } from "../types.js";
 

package/src/{mcp → adapters/mcp}/tools/collect.ts

@@ -1,7 +1,7 @@
 // src/mcp/tools/collect.ts — handoff_collect tool
 
 import { execSync } from "node:child_process";
-import { isTestFile } from "../../analyze.js";
+import { isTestFile } from "../../../analyze.js";
 import { errorResult, jsonResult, type ToolResult } from "../types.js";
 
 // --- Git helper ---

package/src/{mcp → adapters/mcp}/tools/mem.ts

@@ -6,7 +6,7 @@
 // file is unfindable when you touch that file (fill rate 26% CLI-flag vs 88%
 // MCP-required — schema wins over prose every time, see CLAUDE.md rule 9).
 
-import { openRows } from "../../mem/selectors.js";
+import { openRows } from "../../../mem/selectors.js";
 import {
   initStore,
   KINDS,
@@ -14,8 +14,8 @@ import {
   put,
   rows,
   type WorkKind,
-} from "../../mem/store.js";
-import { type MemRow, readMemLog, resolveMemDir } from "../../memory.js";
+} from "../../../mem/store.js";
+import { type MemRow, readMemLog, resolveMemDir } from "../../../memory.js";
 import { errorResult, jsonResult, type ToolResult } from "../types.js";
 
 export interface MemFindResult {

package/src/{mcp → adapters/mcp}/tools/report.ts

@@ -4,10 +4,10 @@
 // run metrics + verdict into a single VerificationReport.
 // Calls existing primitives — no duplicate parser/conformance logic.
 
-import { blastRadiusForWorktree } from "../../analyze.js";
-import { getEvents, getRun, openDb } from "../../db/index.js";
-import { loadConfig } from "../../db/load.js";
-import { parseGateEventData } from "../../parse.js";
+import { blastRadiusForWorktree } from "../../../analyze.js";
+import { loadConfig } from "../../../core/config.js";
+import { getEvents, getRun, openDb } from "../../../db/store.js";
+import { parseGateEventData } from "../../../parse.js";
 import { collectEvidence } from "../evidence.js";
 import type { CheckResult, VerificationReport } from "../primitives.js";
 import {

package/src/adapters/mcp/types.ts

@@ -0,0 +1,18 @@
+// src/mcp/types.ts — ToolResult, helpers
+// ReasonCode + RegimeCode enums now live in core/enums.ts (PLAN-lib-layer chunk 2c).
+
+// Re-export enums for existing callers.
+export {
+  REASON_CODES,
+  REGIME_CODES,
+  type ReasonCode,
+  type RegimeCode,
+} from "../../core/enums.js";
+
+// Re-export ToolResult types for existing callers.
+export {
+  errorResult,
+  jsonResult,
+  parseToolResult,
+  type ToolResult,
+} from "../../core/types.js";

package/src/{mcp → adapters/mcp}/worktree.ts

@@ -1,6 +1,6 @@
 // src/mcp/worktree.ts — resolve worktree argument to absolute path
 
-import { loadConfig } from "../db/load.js";
+import { loadConfig } from "../../core/config.js";
 
 const SENTINEL_MCP_EXTERNAL = "mcp-external";
 

package/src/analyze.ts

@@ -26,7 +26,7 @@ import {
   normalize as posixNormalize,
 } from "node:path/posix";
 
-import { faponyDir } from "./db/load.js";
+import { faponyDir } from "./core/config.js";
 import { extractExports } from "./map.js";
 
 // --- Types (mirror SPEC-analyze-checkup.md) ---

package/src/conventions-seed.ts

@@ -15,7 +15,7 @@ import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { pathToFileURL } from "node:url";
 import { collectSourceFiles, isSkippedDir, isTestFile } from "./analyze.js";
-import { CONVENTIONS_FILE, FAPONY_DIR } from "./db/index.js";
+import { CONVENTIONS_FILE, FAPONY_DIR } from "./core/config.js";
 import { extractBody, extractExports } from "./map.js";
 
 const RESTRICTED_RULES = new Set([