fapony 0.7.0 → 0.7.1

package/src/adapters/mcp/tools/index.ts

@@ -1,149 +0,0 @@
-// src/mcp/tools/index.ts — barrel + TOOLS array
-//
-// Every schema here is paid as input tokens in *every* session of *every*
-// client that connects, whether or not the tool is called. Adding one is
-// buying attention with a standing charge; earning it back means the tool
-// saves more than it costs (see CLAUDE.md "Spend tokens smart"). Keep
-// descriptions imperative — say what to send, not why it matters.
-
-export { toolMemAdd, toolMemClose, toolMemFind } from "./mem.js";
-
-// --- Tool definitions ---
-
-export const TOOLS = [
-  {
-    name: "mem_find",
-    description:
-      "Search the project's mem log (.fapony/.memory/log*.jsonl — decisions, " +
-      "bugs, notes, and bookkeeping kinds alike; NO default kind filter). " +
-      "Read-only. Answer 'what was ever decided about this file?' in one call " +
-      "BEFORE editing: pass files[] (repo-relative). Matches the row's stored " +
-      "files[], falling back to a substring of text/spec/ref for rows written " +
-      "without it — a row that names the file nowhere cannot be found. " +
-      "memDir shows which log dir was resolved (walked up from the given " +
-      "worktree — in a monorepo pass the app directory to read its log). " +
-      "Returns {rows, total, filesFound, " +
-      "skipped, memDir}: memDir:null = no mem at all, not 'nothing matched'. " +
-      "A key query that misses adds knownKeys (every key in the log).",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        worktree: {
-          type: "string",
-          description:
-            "Absolute path (git rev-parse --show-toplevel) — required; " +
-            "scope of the mem log to read",
-        },
-        files: {
-          type: "array",
-          items: { type: "string" },
-          description:
-            "Repo-relative paths — matched against the row's files[], else its text",
-        },
-        text: {
-          type: "string",
-          description: "Substring, case-insensitive",
-        },
-        kind: {
-          type: "array",
-          items: { type: "string" },
-          description:
-            "Filter by kind (decision/note/bug/close/…). Omit = every kind — " +
-            "no default filter",
-        },
-        since: {
-          type: "string",
-          description: "ISO date — only rows at or after this time",
-        },
-        limit: {
-          type: "number",
-          description:
-            "Max rows returned (default 20) — total still counts all matches",
-        },
-        open: {
-          type: "boolean",
-          description:
-            "true = unresolved work only: drops close/claim/release/synced rows and work rows already closed. Omit = every row. With kind:[bug] answers 'what bugs remain?'",
-        },
-        key: {
-          type: "string",
-          description:
-            "Exact problem-identity match — miss returns knownKeys (every key in the log). No pattern: a wrong-pattern query must reach the server",
-        },
-      },
-      required: ["worktree"],
-    },
-  },
-  {
-    name: "mem_add",
-    description:
-      "Append a mem row (decision/bug/note/next/hold) with files[]. files is " +
-      "required — a row that does not name the file is unfindable when you " +
-      "touch that file. Returns the row's id, kind, files, and timestamp.",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        worktree: {
-          type: "string",
-          description:
-            "Absolute path (git rev-parse --show-toplevel) — required",
-        },
-        kind: {
-          type: "string",
-          enum: ["next", "bug", "decision", "note", "hold"],
-          description:
-            "Row kind: decision=locked choice, bug=broken thing, note=state " +
-            "next session needs, next=pending work, hold=blocked on spec",
-        },
-        text: {
-          type: "string",
-          description:
-            "Standalone text — read months later, no conversation context",
-        },
-        files: {
-          type: "array",
-          items: { type: "string" },
-          description:
-            "Repo-relative paths this row is about — required, non-empty",
-        },
-        spec: {
-          type: "string",
-          description: "Optional spec/plan .md path",
-        },
-        key: {
-          type: "string",
-          pattern: "^[a-z0-9-]{3,40}(:[a-z0-9-]{1,40})?$",
-          description:
-            "Problem identity (not kind, not files) — same problem, same key; domain:sub (e.g. auth:login) when the repo declares domains",
-        },
-      },
-      required: ["worktree", "kind", "text", "files"],
-    },
-  },
-  {
-    name: "mem_close",
-    description:
-      "Close a mem row by id with a tombstone message (what was done). " +
-      "The write half of closing what mem_find shows as open — id must exist. " +
-      "Returns the ref and timestamp.",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        worktree: {
-          type: "string",
-          description:
-            "Absolute path (git rev-parse --show-toplevel) — required",
-        },
-        id: {
-          type: "string",
-          description: "The row id to close",
-        },
-        text: {
-          type: "string",
-          description: "Tombstone message — what was done (commit sha counts)",
-        },
-      },
-      required: ["worktree", "id", "text"],
-    },
-  },
-];

package/src/adapters/mcp/tools/mem.ts

@@ -1,258 +0,0 @@
-// src/mcp/tools/mem.ts — mem_find (read) + mem_add (write)
-//
-// "writable ≠ readable back" — the write side was CLI-only until now; what was
-// missing is letting an agent append a mem row mid-session without spawning a
-// shell.  files[] is required on the write side: a row that does not name the
-// 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 {
-  type EngineAddResult,
-  type EngineCloseResult,
-  engineAdd,
-  engineClose,
-  engineFind,
-} from "../../../mem/engine.js";
-import { loadKeyRegistry } from "../../../mem/key-registry.js";
-import { initStore, KINDS, type WorkKind } from "../../../mem/store.js";
-import { type MemRow, readMemLog, resolveMemDir } from "../../../memory.js";
-import { errorResult, jsonResult, type ToolResult } from "../types.js";
-
-export interface MemFindResult {
-  rows: MemRow[];
-  total: number;
-  filesFound: number;
-  skipped: number;
-  memDir: string | null;
-  /** Present only when a key query missed — every distinct key in the log. */
-  knownKeys?: string[];
-}
-
-export function memFind(args: {
-  worktree: string;
-  files?: string[];
-  text?: string;
-  kind?: string[];
-  since?: string;
-  limit?: number;
-  open?: boolean;
-  key?: string;
-}): MemFindResult {
-  // Query logic lives in the shared engine (src/mem/engine.ts) — this wrapper
-  // owns only the read (readMemLog sees live + rotated archives via its loose
-  // log*.jsonl regex) and the result shape. No kind default here by contract:
-  // omitting kind returns every kind (locked by test). CLI cmdFind calls the
-  // same engine with its own bookkeeping exclude.
-  const read = readMemLog(args.worktree);
-  const found = engineFind(read.rows, {
-    text: args.text,
-    files: args.files,
-    kind: args.kind,
-    sinceIso: args.since,
-    key: args.key,
-    limit: args.limit,
-    open: args.open,
-  });
-  return {
-    rows: found.rows,
-    total: found.total,
-    filesFound: read.filesFound,
-    skipped: read.skipped,
-    // memDir separates "no mem at all" from "nothing matched" (spec §3) and
-    // makes the monorepo single-log limit visible (spec §5.1).
-    memDir: resolveMemDir(args.worktree),
-    ...(found.knownKeys ? { knownKeys: found.knownKeys } : {}),
-  };
-}
-
-export function toolMemFind(args: Record<string, unknown>): ToolResult {
-  const worktree =
-    typeof args.worktree === "string" ? args.worktree.trim() : "";
-  if (!worktree) {
-    return errorResult(
-      "worktree is required and must be an absolute path " +
-        "(git rev-parse --show-toplevel) — an empty result without it would be " +
-        "misread as 'no history'",
-    );
-  }
-  if (!worktree.startsWith("/")) {
-    return errorResult(
-      `worktree must be an absolute path, got: ${worktree} — a bare name scopes to nothing`,
-    );
-  }
-  const files = Array.isArray(args.files)
-    ? args.files.filter(
-        (f): f is string => typeof f === "string" && f.length > 0,
-      )
-    : undefined;
-  const kind = Array.isArray(args.kind)
-    ? args.kind.filter(
-        (k): k is string => typeof k === "string" && k.length > 0,
-      )
-    : undefined;
-  const text = typeof args.text === "string" ? args.text : undefined;
-  const since = typeof args.since === "string" ? args.since : undefined;
-  if (since !== undefined && Number.isNaN(Date.parse(since))) {
-    return errorResult(
-      `since must be an ISO date (e.g. 2026-09-19T00:00:00.000Z), got: "${since}" — CLI accepts <N>d/YYYY-MM-DD, MCP takes ISO only`,
-    );
-  }
-  const limit = typeof args.limit === "number" ? args.limit : undefined;
-  const open = typeof args.open === "boolean" ? args.open : undefined;
-  // Shape gate like mem_add — a non-string key must not coerce to undefined
-  // (silent drop = reject-without-saying). Pattern is NOT checked here: find
-  // answers a wrong-pattern key with knownKeys, not a reject (SPEC fail example).
-  // A bare domain doubles as a prefix — key:"auth" catches every auth:*.
-  if (args.key !== undefined && typeof args.key !== "string") {
-    return errorResult(
-      'key must be a string matching [a-z0-9-]{3,40}(:[a-z0-9-]{1,40})? — e.g. "fix-stop-dedupe" or "auth:login"',
-    );
-  }
-  const key = typeof args.key === "string" ? args.key : undefined;
-
-  return jsonResult(
-    memFind({ worktree, files, text, kind, since, limit, open, key }),
-  );
-}
-
-// --- mem_add ---
-//
-// Domain rules live in the shared engine (src/mem/engine.ts) — this wrapper
-// owns only store init for its worktree. CLI cmdAdd calls the same engine.
-
-export type MemAddResult = EngineAddResult;
-
-export function memAdd(args: {
-  worktree: string;
-  kind: string;
-  text: string;
-  files: string[];
-  spec?: string;
-  key?: string;
-}): MemAddResult {
-  initStore(args.worktree);
-  // Registry beside the mem log; absent = free-form keys (never reject).
-  // Loaded per call, not at MCP start (initialize budget ≤ ~100ms).
-  const reg = loadKeyRegistry(args.worktree);
-  return engineAdd({
-    kind: args.kind,
-    text: args.text,
-    files: args.files,
-    spec: args.spec,
-    key: args.key,
-    knownDomains: reg.path ? reg.domains : null,
-  });
-}
-
-export function toolMemAdd(args: Record<string, unknown>): ToolResult {
-  const worktree =
-    typeof args.worktree === "string" ? args.worktree.trim() : "";
-  if (!worktree) {
-    return errorResult(
-      "worktree is required and must be an absolute path " +
-        "(git rev-parse --show-toplevel)",
-    );
-  }
-  if (!worktree.startsWith("/")) {
-    return errorResult(`worktree must be an absolute path, got: ${worktree}`);
-  }
-
-  const kind = typeof args.kind === "string" ? args.kind.trim() : "";
-  if (!kind) {
-    return errorResult(`kind is required — one of ${KINDS.join("|")}`);
-  }
-  if (!KINDS.includes(kind as WorkKind)) {
-    return errorResult(
-      `kind must be one of ${KINDS.join("|")} — got "${kind}"`,
-    );
-  }
-
-  const text = typeof args.text === "string" ? args.text.trim() : "";
-  if (!text) {
-    return errorResult("text is required and must not be empty");
-  }
-
-  const files = Array.isArray(args.files)
-    ? args.files
-        .filter((f): f is string => typeof f === "string" && f.length > 0)
-        .map((f) => f.trim().replace(/^\.\//, ""))
-    : [];
-  if (files.length === 0) {
-    return errorResult(
-      "files is required and must contain at least one repo-relative path",
-    );
-  }
-
-  const spec =
-    typeof args.spec === "string" && args.spec.trim().endsWith(".md")
-      ? args.spec.trim()
-      : undefined;
-
-  // Shape gate here, pattern check in engineAdd — a non-string key must not
-  // slip through as undefined (silent drop = reject-without-saying, SPEC §Validation).
-  if (args.key !== undefined && typeof args.key !== "string") {
-    return errorResult(
-      'key must be a string matching [a-z0-9-]{3,40}(:[a-z0-9-]{3,40})? — e.g. "fix-stop-dedupe" or "auth:login"',
-    );
-  }
-  const key = typeof args.key === "string" ? args.key : undefined;
-
-  try {
-    const result = memAdd({ worktree, kind, text, files, spec, key });
-    return jsonResult(result);
-  } catch (e) {
-    return errorResult(e instanceof Error ? e.message : String(e));
-  }
-}
-
-// --- mem_close ---
-//
-// A separate tool on purpose, not kind:"close" inside mem_add: a close row
-// carries {ref, text} with no files[] and no spec, while mem_add requires a
-// non-empty files[] (and a spec for hold) — folding them into one schema
-// would make required fields depend on the value of another field, the shape
-// models call wrong most often. Mirrors CLI `mem close <id> "<msg>"`
-// (commands/write.ts cmdClose): the id must exist; the tombstone voids the
-// claim by itself.
-
-export type MemCloseResult = EngineCloseResult;
-
-export function memClose(args: {
-  worktree: string;
-  id: string;
-  text: string;
-}): MemCloseResult {
-  initStore(args.worktree);
-  return engineClose({ id: args.id, text: args.text });
-}
-
-export function toolMemClose(args: Record<string, unknown>): ToolResult {
-  const worktree =
-    typeof args.worktree === "string" ? args.worktree.trim() : "";
-  if (!worktree) {
-    return errorResult(
-      "worktree is required and must be an absolute path " +
-        "(git rev-parse --show-toplevel)",
-    );
-  }
-  if (!worktree.startsWith("/")) {
-    return errorResult(`worktree must be an absolute path, got: ${worktree}`);
-  }
-
-  const id = typeof args.id === "string" ? args.id.trim() : "";
-  if (!id) {
-    return errorResult("id is required — the row id to close");
-  }
-
-  const text = typeof args.text === "string" ? args.text.trim() : "";
-  if (!text) {
-    return errorResult("text is required and must not be empty");
-  }
-
-  try {
-    const result = memClose({ worktree, id, text });
-    return jsonResult(result);
-  } catch (e) {
-    return errorResult(e instanceof Error ? e.message : String(e));
-  }
-}

package/src/adapters/mcp/transport.ts

@@ -1,147 +0,0 @@
-// src/mcp/transport.ts — JSON-RPC dispatch + stdio entry point
-
-import { createInterface } from "node:readline";
-import { getServerSha } from "./primitives.js";
-import { TOOLS, toolMemAdd, toolMemClose, toolMemFind } from "./tools/index.js";
-import { errorResult, type ToolResult } from "./types.js";
-
-// --- Server instructions ---
-//
-// MCP's initialize response carries an `instructions` string that clients
-// inject into the model's context. This is the vendor-neutral place for the
-// habit fapony depends on — a user should never have to paste rules
-// into their own CLAUDE.md (or AGENTS.md, or a hook) to make the tools work,
-// and a rule pasted there would only cover one client anyway.
-//
-// Kept short on purpose: this text is spent on every session of every user.
-// Both habits degrade silently — an agent that ignores them still gets
-// correct answers from every tool, just a thinner history.
-
-const SERVER_INSTRUCTIONS = `fapony records decisions, bugs, and notes about this project so the next session (or the next agent) knows what happened and what to watch out for.
-
-When you finish a unit of work, record a mem row: fapony mem add <decision|bug|note> "what happened" --files <files> <path/to/PLAN.md>. files[] is required — a row without it is unfindable when you touch that file next session. Name a known problem with --key <domain:sub> and recall every row for it via mem_find key.
-
-worktree must be the absolute path (git rev-parse --show-toplevel): every query scopes by it, so a bare name or none files the row where nothing reads it, and nothing errors to say so. Write the note standalone — it is read months later with no access to this conversation.
-
-Skip it and every tool still answers correctly, on a thinner history.`;
-
-// --- MCP protocol constants ---
-
-const MCP_PROTOCOL_VERSION = "2025-03-26";
-const SERVER_NAME = "fapony-handcheck";
-const SERVER_VERSION = "0.3.0";
-
-// --- JSON-RPC dispatch ---
-
-export function dispatch(
-  method: string,
-  params: unknown,
-): object | ToolResult | null {
-  switch (method) {
-    case "initialize":
-      return {
-        protocolVersion: MCP_PROTOCOL_VERSION,
-        capabilities: { tools: {} },
-        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
-        instructions: SERVER_INSTRUCTIONS,
-      };
-    case "notifications/initialized":
-      return null; // no response needed
-    case "tools/list":
-      return { tools: TOOLS };
-    case "tools/call":
-      return dispatchToolCall(
-        params as { name: string; arguments?: Record<string, unknown> },
-      );
-    default:
-      return {
-        code: -32601,
-        message: `method not found: ${method}`,
-      };
-  }
-}
-
-function dispatchToolCall(params: {
-  name: string;
-  arguments?: Record<string, unknown>;
-}): ToolResult {
-  const args = params.arguments ?? {};
-  let result: ToolResult;
-  switch (params.name) {
-    case "mem_find":
-      result = toolMemFind(args);
-      break;
-    case "mem_add":
-      result = toolMemAdd(args);
-      break;
-    case "mem_close":
-      result = toolMemClose(args);
-      break;
-    default:
-      return errorResult(`unknown tool: ${params.name}`);
-  }
-  return result;
-}
-
-// --- Entry point ---
-
-export function cmdMcp(): void {
-  getServerSha(); // cache while the process is still fresh, not on first report call
-  const rl = createInterface({ input: process.stdin });
-
-  rl.on("line", (line) => {
-    const trimmed = line.trim();
-    if (!trimmed) return;
-
-    let msg: { id?: number; method: string; params?: unknown };
-    try {
-      msg = JSON.parse(trimmed);
-    } catch {
-      // Invalid JSON — send error
-      const resp = {
-        jsonrpc: "2.0",
-        id: null,
-        error: { code: -32700, message: "Parse error" },
-      };
-      process.stdout.write(`${JSON.stringify(resp)}\n`);
-      return;
-    }
-
-    const result = dispatch(msg.method, msg.params ?? {});
-
-    // notifications don't get a response
-    if (result === null) return;
-
-    const resp: Record<string, unknown> = {
-      jsonrpc: "2.0",
-      id: msg.id ?? null,
-    };
-
-    if (
-      result &&
-      typeof result === "object" &&
-      "content" in result &&
-      "isError" in result
-    ) {
-      // Tool result
-      resp.result = result;
-    } else if (
-      result &&
-      typeof result === "object" &&
-      "code" in result &&
-      "message" in result
-    ) {
-      // Error response
-      resp.error = result;
-    } else {
-      // Normal result
-      resp.result = result;
-    }
-
-    process.stdout.write(`${JSON.stringify(resp)}\n`);
-  });
-
-  rl.on("close", () => {
-    process.exit(0);
-  });
-}