fapony 0.1.0

package/src/install/codex.ts

@@ -0,0 +1,61 @@
+// src/install/codex.ts — Codex install provider
+//
+// Reads/writes ~/.codex/config.toml directly. Codex has no CLI for MCP config.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CODEX_MCP_ENTRY, defaultExit, type InstallDeps } from "./types.js";
+
+export function findCodexConfig(getHome: () => string): string | null {
+  const p = join(getHome(), ".codex", "config.toml");
+  return existsSync(p) ? p : null;
+}
+
+function isCodexConfigured(content: string): boolean {
+  // Check if [mcp_servers.fapony] section exists with our command
+  const sectionRegex = /\[mcp_servers\.fapony\]/;
+  if (!sectionRegex.test(content)) return false;
+  // Verify it points to fapony
+  return content.includes("fapony.ts") && content.includes("mcp");
+}
+
+export function cmdInstallCodex(dryRun: boolean, deps: InstallDeps = {}): void {
+  const exitFn = deps.exit ?? defaultExit;
+  const configPath = findCodexConfig(deps.homedir ?? homedir);
+
+  if (!configPath) {
+    console.error(
+      `Codex config not found — open Codex at least once to create ~/.codex/config.toml`,
+    );
+    exitFn(1);
+    return;
+  }
+
+  let content: string;
+  try {
+    content = readFileSync(configPath, "utf-8");
+  } catch (e) {
+    console.error(`failed to read ${configPath}: ${(e as Error).message}`);
+    exitFn(1);
+    return;
+  }
+
+  if (isCodexConfigured(content)) {
+    console.error(`✓ mcp_servers.fapony already configured — no change needed`);
+    console.error(`  (${configPath})`);
+    return;
+  }
+
+  if (dryRun) {
+    console.error(`── dry-run: would append to ${configPath} ──`);
+    console.log(CODEX_MCP_ENTRY);
+    return;
+  }
+
+  // Append the fapony MCP server entry to the end of the config file
+  const newContent = `${content.trimEnd()}\n\n${CODEX_MCP_ENTRY}`;
+  writeFileSync(configPath, newContent);
+  console.error(`✓ added mcp_servers.fapony to ${configPath}`);
+  console.error(`  restart Codex to load the MCP server`);
+}

package/src/install/cursor.ts

@@ -0,0 +1,167 @@
+// src/install/cursor.ts — Cursor install provider
+//
+// Writes mcpServers.fapony to ~/.cursor/mcp.json directly (Cursor has no CLI
+// for MCP config) and appends the fapony stop hook to the stop array in
+// ~/.cursor/hooks.json — append, never replace: other tools (e.g.
+// code-review-graph) register hooks in the same file and Cursor runs every
+// entry in the array.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  CURSOR_MCP_ENTRY,
+  defaultExit,
+  INSTALL_ROOT,
+  type InstallDeps,
+  MCP_KEY,
+} from "./types.js";
+
+/** ~/.cursor itself — the app creates it on first run, often before the user
+ *  ever adds an MCP server or hook, so dir-exists is the detect signal. */
+export function findCursorDir(getHome: () => string): string | null {
+  const dir = join(getHome(), ".cursor");
+  return existsSync(dir) ? dir : null;
+}
+
+function isFaponyEntry(entry: unknown): boolean {
+  if (!entry || typeof entry !== "object") return false;
+  const cfg = entry as Record<string, unknown>;
+  return (
+    cfg.command === CURSOR_MCP_ENTRY.command &&
+    JSON.stringify(cfg.args) === JSON.stringify(CURSOR_MCP_ENTRY.args)
+  );
+}
+
+function readJsonObject(path: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+export function cmdInstallCursor(
+  dryRun: boolean,
+  deps: InstallDeps = {},
+): void {
+  const exitFn = deps.exit ?? defaultExit;
+  const getHome = deps.homedir ?? homedir;
+  const cursorDir = findCursorDir(getHome);
+
+  if (!cursorDir) {
+    console.error(
+      `Cursor not found — open Cursor at least once to create ~/.cursor`,
+    );
+    exitFn(1);
+    return;
+  }
+
+  // --- 1. MCP server (mcpServers.fapony in ~/.cursor/mcp.json) ---
+  const mcpPath = join(cursorDir, "mcp.json");
+  let mcp: Record<string, unknown> = {};
+  let mcpIsNew = true;
+  if (existsSync(mcpPath)) {
+    const parsed = readJsonObject(mcpPath);
+    if (!parsed) {
+      console.error(`failed to parse ${mcpPath} — fix or remove it first`);
+      exitFn(1);
+      return;
+    }
+    mcp = parsed;
+    mcpIsNew = false;
+  }
+  const servers = (mcp.mcpServers ?? {}) as Record<string, unknown>;
+  const existing = servers[MCP_KEY];
+  if (existing !== undefined && !isFaponyEntry(existing)) {
+    console.error(
+      `an MCP server named "${MCP_KEY}" exists but points elsewhere — not overwriting.`,
+    );
+    console.error(`  inspect ${mcpPath} and remove it first`);
+    exitFn(1);
+    return;
+  }
+  if (existing !== undefined) {
+    console.error(
+      `✓ mcpServers.${MCP_KEY} already configured — no change needed`,
+    );
+    console.error(`  (${mcpPath})`);
+  } else {
+    const after = {
+      ...mcp,
+      mcpServers: { ...servers, [MCP_KEY]: CURSOR_MCP_ENTRY },
+    };
+    if (dryRun) {
+      console.error(
+        `── dry-run: would ${mcpIsNew ? "create" : "write"} ${mcpPath}${mcpIsNew ? "" : ` (mcpServers.${MCP_KEY})`} ──`,
+      );
+    } else {
+      writeFileSync(mcpPath, `${JSON.stringify(after, null, 2)}\n`, "utf-8");
+      console.error(`✓ added mcpServers.${MCP_KEY} to ${mcpPath}`);
+      console.error(`  restart Cursor to load the MCP server`);
+    }
+  }
+
+  // --- 2. Stop hook (hooks.stop array in ~/.cursor/hooks.json) ---
+  installStopHook(dryRun, cursorDir);
+}
+
+/**
+ * Append `fapony hook-stop` to the stop array in ~/.cursor/hooks.json.
+ * Same policy as Claude's installStopHook: never touch a hook someone else
+ * registered, never fail the install over it. User hooks run from ~/.cursor/,
+ * so the command must be an absolute path.
+ */
+function installStopHook(dryRun: boolean, cursorDir: string): void {
+  const hooksPath = join(cursorDir, "hooks.json");
+  let config: Record<string, unknown> = {};
+  if (existsSync(hooksPath)) {
+    const parsed = readJsonObject(hooksPath);
+    if (!parsed) {
+      console.error(
+        `  stop hook: ${hooksPath} is unreadable or malformed — skipping`,
+      );
+      return;
+    }
+    config = parsed;
+  }
+  const hookMap = config.hooks;
+  if (
+    hookMap !== undefined &&
+    (typeof hookMap !== "object" || Array.isArray(hookMap))
+  ) {
+    console.error(
+      `  stop hook: ${hooksPath} has an unexpected "hooks" shape — skipping`,
+    );
+    return;
+  }
+  const map = (hookMap ?? {}) as Record<string, unknown>;
+  const stop = Array.isArray(map.stop) ? (map.stop as unknown[]) : [];
+  if (JSON.stringify(stop).includes("hook-stop")) {
+    console.error(`  stop hook: already configured in hooks.json — no change`);
+    return;
+  }
+
+  const command = `bun ${join(INSTALL_ROOT, "fapony.ts")} hook-stop`;
+  const after = {
+    ...config,
+    version: typeof config.version === "number" ? config.version : 1,
+    hooks: { ...map, stop: [...stop, { command }] },
+  };
+
+  if (!dryRun) {
+    try {
+      writeFileSync(hooksPath, `${JSON.stringify(after, null, 2)}\n`, "utf-8");
+    } catch (e) {
+      console.error(`  stop hook: failed to write — ${(e as Error).message}`);
+      return;
+    }
+  }
+  console.error(
+    `  stop hook: ${dryRun ? "would write" : "wrote"} hooks.stop → ${hooksPath}`,
+  );
+}

package/src/install/detect.ts

@@ -0,0 +1,78 @@
+// src/install/detect.ts — detect which MCP clients are installed on this machine.
+//
+// Signal per client:
+//   claude   = `command -v claude` (CLI on PATH)
+//   cursor   = ~/.cursor exists (the app creates it on first run)
+//   opencode = ~/.config/opencode/{opencode.json,opencode.jsonc} exists
+//   zcode    = ~/.zcode/cli/config.json or ~/.agents/mcp.json exists
+//   codex    = ~/.codex/config.toml exists
+
+import { homedir } from "node:os";
+import { defaultCheckCmd } from "../setup.js";
+import { findCodexConfig } from "./codex.js";
+import { findCursorDir } from "./cursor.js";
+import { findOpencodeConfig } from "./opencode.js";
+import type { InstallDeps } from "./types.js";
+import { findZcodeConfig } from "./zcode.js";
+
+export interface DetectedClient {
+  platform: string;
+  installed: boolean;
+  why: string;
+}
+
+/**
+ * Detect which MCP clients are available on this machine.
+ * Returns one entry per platform, ordered: claude, cursor, opencode, zcode, codex.
+ *
+ * Uses resolvers from each provider (file/dir-exists check) for
+ * cursor/opencode/zcode/codex, and `command -v claude` for claude — all
+ * through injected deps for testability.
+ */
+export function detectClients(deps: InstallDeps = {}): DetectedClient[] {
+  const getHome = deps.homedir ?? homedir;
+  const checkCmd = deps.checkCmd ?? defaultCheckCmd;
+
+  const claude = checkCmd("claude");
+
+  const cursorDir = findCursorDir(getHome);
+  const opencodePath = findOpencodeConfig(getHome);
+  const zcodeResult = findZcodeConfig(getHome);
+  const codexPath = findCodexConfig(getHome);
+
+  return [
+    {
+      platform: "claude",
+      installed: claude,
+      why: claude ? "claude CLI on PATH" : "claude CLI not found on PATH",
+    },
+    {
+      platform: "cursor",
+      installed: cursorDir !== null,
+      why: cursorDir
+        ? `dir at ${cursorDir}`
+        : "no ~/.cursor directory (open Cursor once)",
+    },
+    {
+      platform: "opencode",
+      installed: opencodePath !== null,
+      why: opencodePath
+        ? `config at ${opencodePath}`
+        : "no config file (~/.config/opencode/{opencode.json,opencode.jsonc})",
+    },
+    {
+      platform: "zcode",
+      installed: zcodeResult !== null,
+      why: zcodeResult
+        ? `config at ${zcodeResult.path}`
+        : "no config file (~/.zcode/cli/config.json or ~/.agents/mcp.json)",
+    },
+    {
+      platform: "codex",
+      installed: codexPath !== null,
+      why: codexPath
+        ? `config at ${codexPath}`
+        : "no config file (~/.codex/config.toml)",
+    },
+  ];
+}

package/src/install/opencode.ts

@@ -0,0 +1,234 @@
+// src/install/opencode.ts — OpenCode install provider
+//
+// Adds mcp.fapony config to ~/.config/opencode/opencode.json or opencode.jsonc.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { claudeSkillsDir, linkSkills, reportSkills } from "./skills.js";
+import {
+  defaultExit,
+  INSTALL_ROOT,
+  type InstallDeps,
+  MCP_CONFIG,
+  MCP_KEY,
+} from "./types.js";
+import { computeDiff } from "./utils.js";
+
+export function findOpencodeConfig(getHome: () => string): string | null {
+  const dir = join(getHome(), ".config", "opencode");
+  for (const name of ["opencode.json", "opencode.jsonc"]) {
+    const p = join(dir, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+function stripJsonc(input: string): string {
+  let out = "";
+  let i = 0;
+  while (i < input.length) {
+    const c = input[i];
+    if (c === "/" && input[i + 1] === "/") {
+      while (i < input.length && input[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && input[i + 1] === "*") {
+      i += 2;
+      while (i < input.length && !(input[i] === "*" && input[i + 1] === "/"))
+        i++;
+      i += 2;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      const quote = c;
+      out += c;
+      i++;
+      while (i < input.length && input[i] !== quote) {
+        if (input[i] === "\\") {
+          out += input[i];
+          i++;
+        }
+        if (i < input.length) {
+          out += input[i];
+          i++;
+        }
+      }
+      if (i < input.length) {
+        out += input[i];
+        i++;
+      }
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+function parseJsonc(text: string): Record<string, unknown> {
+  return JSON.parse(stripJsonc(text)) as Record<string, unknown>;
+}
+
+function isConfigured(mcp: Record<string, unknown> | undefined): boolean {
+  if (!mcp) return false;
+  const entry = mcp[MCP_KEY];
+  if (!entry || typeof entry !== "object") return false;
+  const cfg = entry as Record<string, unknown>;
+  return (
+    cfg.type === MCP_CONFIG.type &&
+    JSON.stringify(cfg.command) === JSON.stringify(MCP_CONFIG.command)
+  );
+}
+
+export function cmdInstallOpencode(
+  dryRun: boolean,
+  deps: InstallDeps = {},
+): void {
+  const exitFn = deps.exit ?? defaultExit;
+  const getHome = deps.homedir ?? homedir;
+
+  const configPath = findOpencodeConfig(getHome);
+  let before: Record<string, unknown>;
+  let isNew = false;
+
+  if (configPath) {
+    try {
+      before = parseJsonc(readFileSync(configPath, "utf-8"));
+    } catch (e) {
+      console.error(`failed to parse ${configPath}: ${(e as Error).message}`);
+      exitFn(1);
+      return;
+    }
+  } else {
+    isNew = true;
+    before = {};
+  }
+
+  const mcp = (before.mcp as Record<string, unknown>) ?? {};
+  if (isConfigured(mcp)) {
+    console.error(`✓ mcp.${MCP_KEY} already configured — no change needed`);
+    if (configPath) console.error(`  (${configPath})`);
+    const skillsDir = claudeSkillsDir(getHome);
+    reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
+    installReadHintPlugin(dryRun, getHome);
+    return;
+  }
+
+  const after = {
+    ...before,
+    mcp: {
+      ...mcp,
+      [MCP_KEY]: MCP_CONFIG,
+    },
+  };
+
+  if (dryRun) {
+    console.error(`── dry-run: would write mcp.${MCP_KEY} ──`);
+    if (isNew) {
+      console.error(
+        `  (new file: ${join(getHome(), ".config", "opencode", "opencode.json")})`,
+      );
+    } else {
+      console.error(`  (${configPath})`);
+    }
+    console.log(computeDiff(before, after));
+    installReadHintPlugin(dryRun, getHome);
+    return;
+  }
+
+  const targetPath =
+    configPath ?? join(getHome(), ".config", "opencode", "opencode.json");
+  const dir = targetPath.split("/").slice(0, -1).join("/");
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  writeFileSync(targetPath, `${JSON.stringify(after, null, 2)}\n`);
+  if (isNew) {
+    console.error(`✓ created ${targetPath} with mcp.${MCP_KEY}`);
+  } else {
+    console.error(`✓ added mcp.${MCP_KEY} to ${configPath}`);
+  }
+  console.error(`  restart opencode to load the MCP server`);
+  const skillsDir = claudeSkillsDir(getHome);
+  reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
+  installReadHintPlugin(dryRun, getHome);
+}
+
+/**
+ * OpenCode plugin — the read hint's in-process shape. `tool.execute.after`
+ * receives `input.args` (the read call's own args) and a mutable
+ * `output.output` string, so one hook computes and appends the hint with no
+ * process spawn per Read. Annotate only: the hook mutates output, never
+ * throws, never dedupes ("you already read this" goes false after context
+ * compaction — a hook that guesses wrong must never trap the agent).
+ *
+ * Logic lives in src/hook.ts (readHintFor) — the plugin imports it from the
+ * install root (path baked at install time), same one-copy-per-client shape
+ * as the skills symlinks: a git pull in INSTALL_ROOT updates every client.
+ * Best-effort, same policy as the claude hooks: an existing file that isn't
+ * fapony's is never overwritten, and a failure never fails the install.
+ */
+export function readHintPluginSource(root: string): string {
+  const hookModule = JSON.stringify(join(root, "src", "hook.ts"));
+  return `// fapony read hint — annotates full-file reads of large source files with a
+// factual review-seed pointer. Annotate only: never blocks, never dedupes.
+// Generated by \`fapony install\` — edit src/hook.ts in the fapony checkout.
+import { readHintFor } from ${hookModule};
+
+export const FaponyReadHint = async ({ directory }) => {
+  return {
+    "tool.execute.after": async (input, output) => {
+      try {
+        if (input.tool !== "read") return;
+        const hint = readHintFor({
+          filePath: input.args?.filePath,
+          offset: input.args?.offset,
+          limit: input.args?.limit,
+          cwd: directory,
+        });
+        if (hint && typeof output.output === "string") {
+          output.output = output.output + "\\n" + hint;
+        }
+      } catch {
+        // a hint must never break a read
+      }
+    },
+  };
+};
+`;
+}
+
+function installReadHintPlugin(dryRun: boolean, getHome: () => string): void {
+  const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
+  const pluginPath = join(pluginsDir, "fapony-read-hint.ts");
+  if (existsSync(pluginPath)) {
+    let current = "";
+    try {
+      current = readFileSync(pluginPath, "utf-8");
+    } catch {
+      current = "";
+    }
+    if (current.includes("readHintFor")) {
+      console.error(`  read hint: already installed — no change`);
+      return;
+    }
+    console.error(
+      `  read hint: ${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;
+    }
+  }
+  console.error(
+    `  read hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+  );
+}

package/src/install/skills.ts

@@ -0,0 +1,106 @@
+// src/install/skills.ts — skill symlink logic for install
+//
+// A copied skill goes stale the moment fapony updates, and every client would
+// need its own copy to refresh. Symlinking the directory means `fapony update`
+// (a git pull in INSTALL_ROOT) reaches every client at once. The <name>/SKILL.md
+// layout is what Claude Code expects, so the link is directory-to-directory.
+//
+// OpenCode reads ~/.claude/skills too, so linking once covers both.
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readlinkSync,
+  symlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { INSTALL_ROOT, type SkillLinkResult } from "./types.js";
+
+export function claudeSkillsDir(getHome: () => string): string {
+  return join(getHome(), ".claude", "skills");
+}
+
+export function agentsSkillsDir(getHome: () => string): string {
+  return join(getHome(), ".agents", "skills");
+}
+
+/**
+ * Link every skill/<name>/ into `skillsDir`.
+ *
+ * Never overwrites: a destination that already exists and is not already our
+ * link is reported as `conflict` and left alone — it may be the user's own
+ * skill, or another tool's, and clobbering it is not ours to decide.
+ */
+export function linkSkills(
+  skillsDir: string,
+  dryRun: boolean,
+): SkillLinkResult[] {
+  const srcRoot = join(INSTALL_ROOT, "skill");
+  if (!existsSync(srcRoot)) return [];
+
+  const names = readdirSync(srcRoot, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+
+  const out: SkillLinkResult[] = [];
+  for (const name of names) {
+    const src = join(srcRoot, name);
+    const dest = join(skillsDir, name);
+
+    // null = nothing there; "" = exists but not a symlink; else = link target.
+    let existing: string | null;
+    try {
+      existing = lstatSync(dest).isSymbolicLink() ? readlinkSync(dest) : "";
+    } catch {
+      existing = null;
+    }
+
+    if (existing === src) {
+      out.push({ name, action: "already" });
+      continue;
+    }
+    if (existing !== null) {
+      out.push({ name, action: "conflict" });
+      continue;
+    }
+    if (!dryRun) {
+      mkdirSync(skillsDir, { recursive: true });
+      symlinkSync(src, dest);
+    }
+    out.push({ name, action: "linked" });
+  }
+  return out;
+}
+
+export function reportSkills(
+  results: SkillLinkResult[],
+  skillsDir: string,
+  dryRun: boolean,
+): void {
+  if (results.length === 0) return;
+
+  const linked = results.filter((r) => r.action === "linked").length;
+  const already = results.filter((r) => r.action === "already").length;
+  const conflicts = results.filter((r) => r.action === "conflict");
+
+  if (linked > 0) {
+    const verb = dryRun ? "would link" : "linked";
+    console.error(
+      `✓ ${verb} ${linked} skill${linked === 1 ? "" : "s"} → ${skillsDir}`,
+    );
+  }
+  if (already > 0) {
+    console.error(`  ${already} already linked — no change`);
+  }
+  for (const c of conflicts) {
+    console.error(
+      `  ! ${c.name} already exists and is not a fapony link — not overwriting`,
+    );
+    console.error(
+      `    to replace: rm -r ${join(skillsDir, c.name)} && ln -s ${join(INSTALL_ROOT, "skill", c.name)} ${join(skillsDir, c.name)}`,
+    );
+  }
+}