caveat-cli 0.3.0 → 0.5.0

package/dist/index.js

@@ -12976,7 +12976,7 @@ import { Command } from "commander";
 
 // src/context.ts
 import { homedir } from "node:os";
-import { join as join7 } from "node:path";
+import { join as join9 } from "node:path";
 
 // ../../packages/core/dist/db.js
 import { DatabaseSync } from "node:sqlite";
@@ -16139,7 +16139,7 @@ function resolvePaths(caveatHome, knowledgeRepo, userHome) {
 
 // ../../packages/core/dist/config.js
 import { existsSync as existsSync5, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "node:fs";
-var SHARED_REPO_URL = "https://github.com/kitepon-rgb/caveats-quo";
+var SHARED_REPO_URL = "https://github.com/kitepon-rgb/Caveat";
 var DEFAULT_CONFIG = {
   knowledgeRepo: "own",
   semverKeys: ["driver", "cuda", "node"],
@@ -21228,15 +21228,246 @@ function stopReminderText() {
   return [
     "[caveat] \u3053\u306E\u30BB\u30C3\u30B7\u30E7\u30F3\u3067\u5916\u90E8\u4ED5\u69D8\u306E\u7F60\uFF08GPU/\u30C9\u30E9\u30A4\u30D0/\u30C4\u30FC\u30EB\u30D0\u30FC\u30B8\u30E7\u30F3/IDE/\u518D\u73FE\u6027\uFF09\u3092\u8E0F\u307F\u3001\u6B21\u56DE\u306E\u81EA\u5206\u306E\u8ABF\u67FB\u304C\u77ED\u7E2E\u3067\u304D\u305D\u3046\u306A\u3089 mcp__caveat__caveat_record \u3067\u767B\u9332\u3092\u691C\u8A0E\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
     "\u89E3\u6C7A\u3057\u305F\u30B1\u30FC\u30B9\u3060\u3051\u3067\u306A\u304F\u3001\u300C\u73FE\u72B6\u306E\u5236\u7D04\u3067\u306F\u4E0D\u53EF\u80FD\u3068\u5224\u5B9A\u3057\u305F\u300D\u7D50\u8AD6\u3082 outcome: impossible \u3068\u3057\u3066\u8A18\u9332\u5BFE\u8C61\u3002\u6B21\u56DE\u540C\u3058 3 \u6642\u9593\u3092\u6EB6\u304B\u3055\u306A\u3044\u305F\u3081\u306B\u3002",
-    "\u65E2\u306B\u540C\u7B49\u306E caveat \u304C\u3042\u308B\u5834\u5408\u306F caveat_update \u3067\u4E0A\u66F8\u304D\u3001\u307E\u305F\u306F last_verified \u3060\u3051\u66F4\u65B0\u3002"
+    "\u65E2\u306B\u540C\u7B49\u306E caveat \u304C\u3042\u308B\u5834\u5408\u306F caveat_update \u3067\u4E0A\u66F8\u304D\u3001\u307E\u305F\u306F last_verified \u3060\u3051\u66F4\u65B0\u3002",
+    "\u8A18\u9332\u3057\u305F\u7F60\u304C\u4ED6\u306E\u30E6\u30FC\u30B6\u306B\u3082\u518D\u5229\u7528\u4FA1\u5024\u304C\u3042\u308B\u306A\u3089 mcp__caveat__caveat_push \u3067\u5171\u6709 DB \u306B PR \u3092\u6295\u3052\u308B\u3053\u3068\u3082\u691C\u8A0E\uFF08\u500B\u4EBA\u30D7\u30ED\u30B8\u30A7\u30AF\u30C8\u56FA\u6709\u306E\u7269\u306F push \u3057\u306A\u3044\uFF09\u3002"
   ].join("\n");
 }
 
+// ../../packages/core/dist/push.js
+import { spawnSync } from "node:child_process";
+import {
+  copyFileSync,
+  existsSync as existsSync7,
+  mkdirSync as mkdirSync3,
+  readdirSync as readdirSync4,
+  readFileSync as readFileSync5
+} from "node:fs";
+import { dirname as dirname4, join as join7, relative as relative2 } from "node:path";
+async function pushEntry(opts) {
+  if (!checkGhAvailable()) {
+    return {
+      status: "gh-missing",
+      detail: "gh (GitHub CLI) is required. Install: https://cli.github.com/"
+    };
+  }
+  if (!checkGhAuthed()) {
+    return {
+      status: "gh-unauthed",
+      detail: "gh is not authenticated. Run `gh auth login`."
+    };
+  }
+  const validation = validateCommunityUrl(opts.sharedRepoUrl);
+  if (!validation.valid) {
+    return { status: "failed", detail: `sharedRepo URL invalid: ${validation.reason}` };
+  }
+  const [sharedOwner, sharedName] = parseOwnerRepo(opts.sharedRepoUrl);
+  if (!sharedOwner || !sharedName) {
+    return { status: "failed", detail: `cannot parse owner/repo from ${opts.sharedRepoUrl}` };
+  }
+  const owned = findOwnedEntry(opts.entriesDir, opts.id);
+  if (!owned) {
+    return {
+      status: "not-found",
+      detail: `entry id=${opts.id} not found under ${opts.entriesDir}`
+    };
+  }
+  const ghUser = resolveGhUser();
+  if (!ghUser) {
+    return { status: "failed", detail: "gh api user failed" };
+  }
+  if (opts.dryRun) {
+    return {
+      status: "dry-run",
+      plannedSteps: [
+        `fork ${sharedOwner}/${sharedName} as ${ghUser}/${sharedName}`,
+        `clone fork \u2192 ${forkStagingDir(opts.caveatHome)}`,
+        `copy entry \u2192 entries/${owned.relPath}`,
+        "commit, push branch, open PR against main"
+      ]
+    };
+  }
+  try {
+    ensureFork(sharedOwner, sharedName);
+    const stagingDir = forkStagingDir(opts.caveatHome);
+    ensureStagingClone(stagingDir, ghUser, sharedName, sharedOwner);
+    const branch = `caveat-push-${owned.id}-${Date.now().toString(36)}`;
+    run("git", ["checkout", "-b", branch], { cwd: stagingDir });
+    const destPath = join7(stagingDir, "entries", owned.relPath);
+    mkdirSync3(dirname4(destPath), { recursive: true });
+    copyFileSync(owned.absPath, destPath);
+    run("git", ["add", join7("entries", owned.relPath)], { cwd: stagingDir });
+    const isUpdate = upstreamAlreadyHas(stagingDir, "entries/" + owned.relPath);
+    const verb = isUpdate ? "update" : "add";
+    const commitMsg = `${verb}: ${owned.title}`;
+    run("git", ["commit", "-m", commitMsg], { cwd: stagingDir });
+    run("git", ["push", "--set-upstream", "origin", branch], { cwd: stagingDir });
+    const prTitle = `${verb}: ${owned.title}`;
+    const prBody = [
+      `Contribution of caveat \`${owned.id}\` via \`caveat push\`.`,
+      "",
+      `- entry path: \`entries/${owned.relPath}\``,
+      `- action: ${verb}`,
+      "",
+      "Merged PRs will appear in subscribers' repos on their next `caveat pull`."
+    ].join("\n");
+    const pr = spawnSync(
+      "gh",
+      [
+        "pr",
+        "create",
+        "--repo",
+        `${sharedOwner}/${sharedName}`,
+        "--base",
+        "main",
+        "--head",
+        `${ghUser}:${branch}`,
+        "--title",
+        prTitle,
+        "--body",
+        prBody
+      ],
+      { cwd: stagingDir, encoding: "utf-8", shell: true }
+    );
+    if (pr.status !== 0) {
+      return {
+        status: "failed",
+        detail: (typeof pr.stderr === "string" ? pr.stderr : String(pr.stderr ?? "")).trim() || "gh pr create failed"
+      };
+    }
+    const prUrl = (typeof pr.stdout === "string" ? pr.stdout : String(pr.stdout ?? "")).trim();
+    return { status: "ok", prUrl };
+  } catch (err) {
+    return {
+      status: "failed",
+      detail: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function checkGhAvailable() {
+  const r2 = spawnSync("gh", ["--version"], { encoding: "utf-8", shell: true });
+  return r2.status === 0;
+}
+function checkGhAuthed() {
+  const r2 = spawnSync("gh", ["auth", "status"], { encoding: "utf-8", shell: true });
+  return r2.status === 0;
+}
+function resolveGhUser() {
+  const r2 = spawnSync("gh", ["api", "user", "--jq", ".login"], {
+    encoding: "utf-8",
+    shell: true
+  });
+  if (r2.status !== 0) return void 0;
+  return typeof r2.stdout === "string" ? r2.stdout.trim() : "";
+}
+function parseOwnerRepo(url) {
+  const m = /^https:\/\/github\.com\/([^/]+)\/([^/]+?)(\.git)?\/?$/.exec(url);
+  if (!m) return [void 0, void 0];
+  return [m[1], m[2]];
+}
+function findOwnedEntry(entriesDir, id) {
+  if (!existsSync7(entriesDir)) return void 0;
+  for (const categoryDirent of readdirSync4(entriesDir, { withFileTypes: true })) {
+    if (!categoryDirent.isDirectory()) continue;
+    const categoryDir = join7(entriesDir, categoryDirent.name);
+    for (const fileDirent of readdirSync4(categoryDir, { withFileTypes: true })) {
+      if (!fileDirent.isFile() || !fileDirent.name.endsWith(".md")) continue;
+      const absPath = join7(categoryDir, fileDirent.name);
+      const raw2 = readFileSync5(absPath, "utf-8");
+      try {
+        const parsed = parseMarkdown(raw2);
+        if (parsed.frontmatter.id === id) {
+          const relPath = relative2(entriesDir, absPath).replace(/\\/g, "/");
+          return { id, title: parsed.frontmatter.title, absPath, relPath };
+        }
+      } catch {
+      }
+    }
+  }
+  return void 0;
+}
+function forkStagingDir(caveatHome) {
+  return join7(caveatHome, "push-fork");
+}
+function ensureFork(owner, repo) {
+  spawnSync(
+    "gh",
+    ["repo", "fork", `${owner}/${repo}`, "--clone=false", "--remote=false"],
+    { encoding: "utf-8", shell: true }
+  );
+}
+function ensureStagingClone(stagingDir, ghUser, sharedName, upstreamOwner) {
+  if (!existsSync7(stagingDir)) {
+    mkdirSync3(dirname4(stagingDir), { recursive: true });
+    const forkUrl = `https://github.com/${ghUser}/${sharedName}.git`;
+    run("git", ["clone", "--depth", "30", forkUrl, stagingDir]);
+    run(
+      "git",
+      ["remote", "add", "upstream", `https://github.com/${upstreamOwner}/${sharedName}.git`],
+      { cwd: stagingDir }
+    );
+  } else {
+    run("git", ["checkout", "main"], { cwd: stagingDir });
+    run("git", ["fetch", "upstream", "main"], { cwd: stagingDir });
+    run("git", ["reset", "--hard", "upstream/main"], { cwd: stagingDir });
+    run("git", ["push", "origin", "main", "--force-with-lease"], { cwd: stagingDir });
+  }
+}
+function upstreamAlreadyHas(stagingDir, relFromRoot) {
+  return existsSync7(join7(stagingDir, relFromRoot));
+}
+function run(command, args, opts = {}) {
+  const r2 = spawnSync(command, args, {
+    encoding: "utf-8",
+    cwd: opts.cwd,
+    shell: true
+  });
+  if (r2.status !== 0) {
+    const stderr = typeof r2.stderr === "string" ? r2.stderr : String(r2.stderr ?? "");
+    const stdout = typeof r2.stdout === "string" ? r2.stdout : String(r2.stdout ?? "");
+    throw new Error(`${command} ${args.join(" ")} failed: ${(stderr || stdout || "unknown").trim()}`);
+  }
+}
+
+// ../../packages/core/dist/pullShared.js
+import { existsSync as existsSync8, readdirSync as readdirSync5 } from "node:fs";
+import { join as join8 } from "node:path";
+async function pullShared(opts) {
+  const result = { pulled: [], indexed: [] };
+  if (!existsSync8(opts.communityDir)) {
+    return result;
+  }
+  const pulls = await communityPull({
+    communityDir: opts.communityDir,
+    logger: opts.logger
+  });
+  for (const p2 of pulls) {
+    result.pulled.push({
+      handle: p2.handle,
+      status: p2.status,
+      message: p2.message
+    });
+  }
+  rebuildAll(opts.db);
+  if (existsSync8(opts.entriesDir)) {
+    const own = scanSource({ db: opts.db, source: "own", entriesRoot: opts.entriesDir });
+    result.indexed.push({ source: "own", ...own });
+  }
+  for (const entry of readdirSync5(opts.communityDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const source = `community/${entry.name}`;
+    const root = join8(opts.communityDir, entry.name, "entries");
+    if (!existsSync8(root)) continue;
+    const scan = scanSource({ db: opts.db, source, entriesRoot: root });
+    result.indexed.push({ source, ...scan });
+  }
+  return result;
+}
+
 // src/context.ts
 function buildContext(logger, overrides = {}) {
   const userHome = overrides.userHome ?? homedir();
   const caveatHome = overrides.caveatHome ?? findCaveatHome(userHome);
-  const userConfigPath = join7(userHome, ".caveatrc.json");
+  const userConfigPath = join9(userHome, ".caveatrc.json");
   const config3 = loadConfig(userConfigPath);
   const paths = resolvePaths(caveatHome, config3.knowledgeRepo, userHome);
   return { caveatHome, userHome, userConfigPath, config: config3, paths, logger };
@@ -21253,13 +21484,13 @@ var stdoutLogger = {
 };
 
 // src/commands/init.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync4, readdirSync as readdirSync4, writeFileSync as writeFileSync5 } from "node:fs";
-import { join as join9 } from "node:path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync5, readdirSync as readdirSync6, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join11 } from "node:path";
 
 // src/claudeInstall.ts
-import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "node:fs";
-import { dirname as dirname4, join as join8 } from "node:path";
+import { spawnSync as spawnSync2 } from "node:child_process";
+import { copyFileSync as copyFileSync2, existsSync as existsSync9, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname5, join as join10 } from "node:path";
 var EVENT_USER_PROMPT_SUBMIT = "UserPromptSubmit";
 var EVENT_STOP = "Stop";
 function quote(p2) {
@@ -21293,16 +21524,16 @@ function removeHook(settings, event, command) {
   return true;
 }
 function readSettings(path) {
-  if (!existsSync7(path)) return {};
-  return JSON.parse(readFileSync5(path, "utf-8"));
+  if (!existsSync9(path)) return {};
+  return JSON.parse(readFileSync6(path, "utf-8"));
 }
 function writeSettings(path, settings) {
-  const dir = dirname4(path);
-  if (!existsSync7(dir)) mkdirSync3(dir, { recursive: true });
+  const dir = dirname5(path);
+  if (!existsSync9(dir)) mkdirSync4(dir, { recursive: true });
   let backupPath = "";
-  if (existsSync7(path)) {
+  if (existsSync9(path)) {
     backupPath = `${path}.caveat-backup-${Date.now()}`;
-    copyFileSync(path, backupPath);
+    copyFileSync2(path, backupPath);
   }
   writeFileSync4(path, JSON.stringify(settings, null, 2) + "\n", "utf-8");
   return backupPath;
@@ -21313,7 +21544,7 @@ function shellQuote(s) {
 }
 function runClaude(args) {
   const line = [CLAUDE_BIN, ...args].map(shellQuote).join(" ");
-  return spawnSync(line, { shell: true, encoding: "utf-8" });
+  return spawnSync2(line, { shell: true, encoding: "utf-8" });
 }
 function registerMcp(nodePath, cliScriptPath, dryRun, logger) {
   const args = mcpArgs(cliScriptPath);
@@ -21363,7 +21594,7 @@ function unregisterMcp(dryRun, logger) {
   return { action: "skipped", detail: "not registered or removal failed" };
 }
 function installClaudeIntegration(opts) {
-  const settingsPath = join8(opts.claudeDir, "settings.json");
+  const settingsPath = join10(opts.claudeDir, "settings.json");
   const settings = readSettings(settingsPath);
   const usCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "user-prompt-submit");
   const stopCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "stop");
@@ -21382,7 +21613,7 @@ function installClaudeIntegration(opts) {
   return { mcp, hooks: { userPromptSubmit, stop }, backupPath };
 }
 function uninstallClaudeIntegration(opts) {
-  const settingsPath = join8(opts.claudeDir, "settings.json");
+  const settingsPath = join10(opts.claudeDir, "settings.json");
   const settings = readSettings(settingsPath);
   const usCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "user-prompt-submit");
   const stopCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "stop");
@@ -21422,15 +21653,15 @@ var KNOWLEDGE_GITIGNORE = [
 async function runInit(ctx, opts = { skipClaude: false, skipShared: false, dryRun: false }) {
   ensureUserConfig(ctx.userConfigPath);
   ctx.logger.info(`user config: ${ctx.userConfigPath}`);
-  if (!existsSync8(ctx.paths.knowledgeRepo)) {
-    mkdirSync4(ctx.paths.knowledgeRepo, { recursive: true });
-    mkdirSync4(ctx.paths.entriesDir, { recursive: true });
+  if (!existsSync10(ctx.paths.knowledgeRepo)) {
+    mkdirSync5(ctx.paths.knowledgeRepo, { recursive: true });
+    mkdirSync5(ctx.paths.entriesDir, { recursive: true });
     ctx.logger.info(`knowledge repo scaffolded: ${ctx.paths.knowledgeRepo}`);
   } else {
     ctx.logger.info(`knowledge repo: ${ctx.paths.knowledgeRepo}`);
   }
-  const gitignorePath = join9(ctx.paths.knowledgeRepo, ".gitignore");
-  if (!existsSync8(gitignorePath)) {
+  const gitignorePath = join11(ctx.paths.knowledgeRepo, ".gitignore");
+  if (!existsSync10(gitignorePath)) {
     writeFileSync5(gitignorePath, KNOWLEDGE_GITIGNORE, "utf-8");
     ctx.logger.info(`.gitignore created: ${gitignorePath}`);
   }
@@ -21457,7 +21688,7 @@ async function runInit(ctx, opts = { skipClaude: false, skipShared: false, dryRu
     return;
   }
   const result = installClaudeIntegration({
-    claudeDir: join9(ctx.userHome, ".claude"),
+    claudeDir: join11(ctx.userHome, ".claude"),
     cliScriptPath,
     nodePath: process.execPath,
     dryRun: opts.dryRun,
@@ -21475,10 +21706,10 @@ async function subscribeSharedRepo(ctx, db) {
     return;
   }
   const handle = validation.handle;
-  const target = join9(ctx.paths.communityDir, handle);
-  if (!existsSync8(target)) {
-    if (!existsSync8(ctx.paths.communityDir)) {
-      mkdirSync4(ctx.paths.communityDir, { recursive: true });
+  const target = join11(ctx.paths.communityDir, handle);
+  if (!existsSync10(target)) {
+    if (!existsSync10(ctx.paths.communityDir)) {
+      mkdirSync5(ctx.paths.communityDir, { recursive: true });
     }
     try {
       await communityAdd({
@@ -21496,16 +21727,16 @@ async function subscribeSharedRepo(ctx, db) {
   } else {
     ctx.logger.info(`shared community DB already subscribed: community/${handle}/`);
   }
-  if (existsSync8(ctx.paths.communityDir)) {
+  if (existsSync10(ctx.paths.communityDir)) {
     rebuildAll(db);
-    if (existsSync8(ctx.paths.entriesDir)) {
+    if (existsSync10(ctx.paths.entriesDir)) {
       scanSource({ db, source: "own", entriesRoot: ctx.paths.entriesDir });
     }
-    for (const entry of readdirSync4(ctx.paths.communityDir, { withFileTypes: true })) {
+    for (const entry of readdirSync6(ctx.paths.communityDir, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
       const source = `community/${entry.name}`;
-      const root = join9(ctx.paths.communityDir, entry.name, "entries");
-      if (!existsSync8(root)) continue;
+      const root = join11(ctx.paths.communityDir, entry.name, "entries");
+      if (!existsSync10(root)) continue;
       const result = scanSource({ db, source, entriesRoot: root });
       ctx.logger.info(`indexed ${source}: +${result.added}`);
     }
@@ -21518,7 +21749,7 @@ function runUninstall(ctx, opts) {
     process.exit(1);
   }
   const result = uninstallClaudeIntegration({
-    claudeDir: join9(ctx.userHome, ".claude"),
+    claudeDir: join11(ctx.userHome, ".claude"),
     cliScriptPath,
     nodePath: process.execPath,
     dryRun: opts.dryRun,
@@ -21555,29 +21786,29 @@ function reportInstallResult(ctx, result, dryRun) {
 }
 
 // src/commands/indexCmd.ts
-import { existsSync as existsSync9, readdirSync as readdirSync5, mkdirSync as mkdirSync5 } from "node:fs";
-import { dirname as dirname5, join as join10 } from "node:path";
+import { existsSync as existsSync11, readdirSync as readdirSync7, mkdirSync as mkdirSync6 } from "node:fs";
+import { dirname as dirname6, join as join12 } from "node:path";
 function runIndex(ctx, opts) {
-  const dbDir = dirname5(ctx.paths.dbPath);
-  if (!existsSync9(dbDir)) mkdirSync5(dbDir, { recursive: true });
+  const dbDir = dirname6(ctx.paths.dbPath);
+  if (!existsSync11(dbDir)) mkdirSync6(dbDir, { recursive: true });
   const db = openDb({ path: ctx.paths.dbPath, logger: ctx.logger });
   try {
     if (opts.full) {
       ctx.logger.info("full rebuild: DELETE FROM entries");
       rebuildAll(db);
     }
-    if (existsSync9(ctx.paths.entriesDir)) {
+    if (existsSync11(ctx.paths.entriesDir)) {
       const result = scanSource({ db, source: "own", entriesRoot: ctx.paths.entriesDir });
       ctx.logger.info(`own: +${result.added} ~${result.updated} -${result.deleted}`);
     } else {
       ctx.logger.warn(`entries dir not found: ${ctx.paths.entriesDir}`);
     }
-    if (existsSync9(ctx.paths.communityDir)) {
-      for (const entry of readdirSync5(ctx.paths.communityDir, { withFileTypes: true })) {
+    if (existsSync11(ctx.paths.communityDir)) {
+      for (const entry of readdirSync7(ctx.paths.communityDir, { withFileTypes: true })) {
         if (!entry.isDirectory()) continue;
         const source = `community/${entry.name}`;
-        const root = join10(ctx.paths.communityDir, entry.name, "entries");
-        if (!existsSync9(root)) continue;
+        const root = join12(ctx.paths.communityDir, entry.name, "entries");
+        if (!existsSync11(root)) continue;
         const result = scanSource({ db, source, entriesRoot: root });
         ctx.logger.info(`${source}: +${result.added} ~${result.updated} -${result.deleted}`);
       }
@@ -22351,11 +22582,11 @@ var serve = (options2, listeningListener) => {
 
 // ../web/dist/context.js
 import { homedir as homedir2 } from "node:os";
-import { join as join11 } from "node:path";
+import { join as join13 } from "node:path";
 function buildWebContext(overrides = {}) {
   const userHome = overrides.userHome ?? homedir2();
   const caveatHome = overrides.caveatHome ?? findCaveatHome(userHome);
-  const userConfigPath = join11(userHome, ".caveatrc.json");
+  const userConfigPath = join13(userHome, ".caveatrc.json");
   const logger = overrides.logger ?? stderrLogger;
   const config3 = loadConfig(userConfigPath);
   const paths = resolvePaths(caveatHome, config3.knowledgeRepo, userHome);
@@ -30082,14 +30313,14 @@ function createDetailRoute(ctx) {
 }
 
 // ../web/dist/routes/community.js
-import { existsSync as existsSync10, readdirSync as readdirSync6, statSync as statSync4 } from "node:fs";
-import { join as join12 } from "node:path";
+import { existsSync as existsSync12, readdirSync as readdirSync8, statSync as statSync4 } from "node:fs";
+import { join as join14 } from "node:path";
 function listCommunity(communityDir, db) {
-  if (!existsSync10(communityDir)) return [];
+  if (!existsSync12(communityDir)) return [];
   const handles = [];
-  for (const entry of readdirSync6(communityDir, { withFileTypes: true })) {
+  for (const entry of readdirSync8(communityDir, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
-    const handlePath = join12(communityDir, entry.name);
+    const handlePath = join14(communityDir, entry.name);
     const countRow = db.prepare("SELECT COUNT(*) AS n FROM entries WHERE source = ?").get(`community/${entry.name}`);
     handles.push({
       handle: entry.name,
@@ -44387,11 +44618,11 @@ var StdioServerTransport = class {
 
 // ../mcp/dist/context.js
 import { homedir as homedir3 } from "node:os";
-import { join as join13 } from "node:path";
+import { join as join15 } from "node:path";
 function buildMcpContext(overrides = {}) {
   const userHome = overrides.userHome ?? homedir3();
   const caveatHome = overrides.caveatHome ?? findCaveatHome(userHome);
-  const userConfigPath = join13(userHome, ".caveatrc.json");
+  const userConfigPath = join15(userHome, ".caveatrc.json");
   const logger = overrides.logger ?? stderrLogger;
   const config3 = loadConfig(userConfigPath);
   const paths = resolvePaths(caveatHome, config3.knowledgeRepo, userHome);
@@ -44540,6 +44771,48 @@ function handleIngestResearch(ctx, args) {
   );
 }
 
+// ../mcp/dist/tools/pull.js
+var pullInputShape = {};
+async function handlePull(ctx, _args = {}) {
+  const result = await pullShared({
+    communityDir: ctx.paths.communityDir,
+    entriesDir: ctx.paths.entriesDir,
+    db: ctx.db,
+    logger: ctx.logger
+  });
+  return {
+    pulled: result.pulled,
+    indexed: result.indexed.map((i2) => ({
+      source: i2.source,
+      added: i2.added,
+      updated: i2.updated,
+      deleted: i2.deleted
+    }))
+  };
+}
+
+// ../mcp/dist/tools/push.js
+var pushInputShape = {
+  id: external_exports.string().min(1).describe("Entry id (frontmatter.id) to push to the shared community DB"),
+  dry_run: external_exports.boolean().optional().describe("If true, compute the plan but do not modify GitHub or local git state")
+};
+async function handlePush(ctx, args) {
+  const result = await pushEntry({
+    entriesDir: ctx.paths.entriesDir,
+    caveatHome: ctx.caveatHome,
+    sharedRepoUrl: ctx.config.sharedRepo,
+    id: args.id,
+    dryRun: args.dry_run ?? false,
+    logger: ctx.logger
+  });
+  return {
+    status: result.status,
+    detail: result.detail,
+    pr_url: result.prUrl,
+    planned_steps: result.plannedSteps
+  };
+}
+
 // ../mcp/dist/registerTools.js
 function jsonResult(data) {
   return {
@@ -44615,6 +44888,24 @@ function registerAllTools(server, ctx) {
     },
     async (args) => jsonResult(handleIngestResearch(ctx, args))
   );
+  server.registerTool(
+    "caveat_pull",
+    {
+      title: "caveat_pull",
+      description: "git-pull all subscribed community caveat repos (incl. the shared DB) and re-index. Call this when the user asks if others have documented a similar trap, or at the start of a session that might benefit from fresh external knowledge. Safe and idempotent \u2014 re-running is cheap.",
+      inputSchema: pullInputShape
+    },
+    async (args) => jsonResult(await handlePull(ctx, args))
+  );
+  server.registerTool(
+    "caveat_push",
+    {
+      title: "caveat_push",
+      description: "Contribute a user-owned caveat to the shared community DB via fork + PR. Call this after caveat_record when the entry looks genuinely reusable by others (not a one-off project tie-in, not duplicated by existing community entries). Requires the `gh` CLI on the user's machine; returns status=gh-missing or gh-unauthed when unavailable. Use dry_run=true to preview without touching GitHub.",
+      inputSchema: pushInputShape
+    },
+    async (args) => jsonResult(await handlePush(ctx, args))
+  );
 }
 
 // ../mcp/dist/server.js
@@ -44707,40 +44998,31 @@ async function runHook(name) {
 }
 
 // src/commands/pull.ts
-import { existsSync as existsSync11, readdirSync as readdirSync7 } from "node:fs";
-import { join as join14 } from "node:path";
+import { existsSync as existsSync13 } from "node:fs";
 async function runPull(ctx) {
-  if (!existsSync11(ctx.paths.communityDir)) {
+  if (!existsSync13(ctx.paths.communityDir)) {
     ctx.logger.info(
       "no community repos yet \u2014 did you run `caveat init`? You can also `caveat community add <url>` manually."
     );
     return;
   }
-  const results = await communityPull({
-    communityDir: ctx.paths.communityDir,
-    logger: ctx.logger
-  });
-  for (const r2 of results) {
-    if (r2.status === "ok") {
-      ctx.logger.info(`${r2.handle}: pulled`);
-    } else {
-      ctx.logger.warn(`${r2.handle}: FAILED \u2014 ${r2.message ?? "unknown"}`);
-    }
-  }
   const db = openDb({ path: ctx.paths.dbPath, logger: ctx.logger });
   try {
-    rebuildAll(db);
-    if (existsSync11(ctx.paths.entriesDir)) {
-      const ownResult = scanSource({ db, source: "own", entriesRoot: ctx.paths.entriesDir });
-      ctx.logger.info(`own: +${ownResult.added}`);
+    const result = await pullShared({
+      communityDir: ctx.paths.communityDir,
+      entriesDir: ctx.paths.entriesDir,
+      db,
+      logger: ctx.logger
+    });
+    for (const p2 of result.pulled) {
+      if (p2.status === "ok") {
+        ctx.logger.info(`${p2.handle}: pulled`);
+      } else {
+        ctx.logger.warn(`${p2.handle}: FAILED \u2014 ${p2.message ?? "unknown"}`);
+      }
     }
-    for (const entry of readdirSync7(ctx.paths.communityDir, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      const source = `community/${entry.name}`;
-      const root = join14(ctx.paths.communityDir, entry.name, "entries");
-      if (!existsSync11(root)) continue;
-      const scan = scanSource({ db, source, entriesRoot: root });
-      ctx.logger.info(`${source}: +${scan.added}`);
+    for (const i2 of result.indexed) {
+      ctx.logger.info(`${i2.source}: +${i2.added}`);
     }
   } finally {
     db.close();
@@ -44748,220 +45030,44 @@ async function runPull(ctx) {
 }
 
 // src/commands/push.ts
-import { spawnSync as spawnSync2 } from "node:child_process";
-import {
-  copyFileSync as copyFileSync2,
-  existsSync as existsSync12,
-  mkdirSync as mkdirSync6,
-  readdirSync as readdirSync8,
-  readFileSync as readFileSync6,
-  statSync as statSync5
-} from "node:fs";
-import { dirname as dirname6, join as join15, relative as relative2 } from "node:path";
 async function runPush(ctx, opts) {
-  const ghOk = checkGhAvailable(ctx);
-  if (!ghOk) return;
-  const sharedValidation = validateCommunityUrl(ctx.config.sharedRepo);
-  if (!sharedValidation.valid) {
-    ctx.logger.error(
-      `sharedRepo is not a valid GitHub URL: ${ctx.config.sharedRepo} (${sharedValidation.reason})`
-    );
-    process.exitCode = 1;
-    return;
-  }
-  const [sharedOwner, sharedName] = parseOwnerRepo(ctx.config.sharedRepo);
-  if (!sharedOwner || !sharedName) {
-    ctx.logger.error(`cannot parse sharedRepo owner/repo: ${ctx.config.sharedRepo}`);
-    process.exitCode = 1;
-    return;
-  }
-  const owned = findOwnedEntry(ctx, opts.id);
-  if (!owned) {
-    ctx.logger.error(
-      `entry not found in ${ctx.paths.entriesDir}: id=${opts.id}. List with \`caveat list\`, or write the md file and index first.`
-    );
-    process.exitCode = 1;
-    return;
-  }
-  const ghUser = resolveGhUser(ctx);
-  if (!ghUser) return;
-  if (opts.dryRun) {
-    ctx.logger.info(`[dry-run] would push entry ${owned.id} (${owned.title})`);
-    ctx.logger.info(`[dry-run]   1. fork ${sharedOwner}/${sharedName} as ${ghUser}/${sharedName}`);
-    ctx.logger.info(`[dry-run]   2. clone fork \u2192 ${forkStagingDir(ctx)}`);
-    ctx.logger.info(`[dry-run]   3. copy entry \u2192 entries/${owned.relPath}`);
-    ctx.logger.info("[dry-run]   4. commit, push branch, open PR against main");
-    return;
-  }
-  ensureFork(ctx, sharedOwner, sharedName, ghUser);
-  const stagingDir = forkStagingDir(ctx);
-  ensureStagingClone(ctx, stagingDir, ghUser, sharedName, sharedOwner);
-  const branch = `caveat-push-${owned.id}-${Date.now().toString(36)}`;
-  run(ctx, "git", ["checkout", "-b", branch], { cwd: stagingDir });
-  const destPath = join15(stagingDir, "entries", owned.relPath);
-  mkdirSync6(dirname6(destPath), { recursive: true });
-  copyFileSync2(owned.absPath, destPath);
-  run(ctx, "git", ["add", join15("entries", owned.relPath)], { cwd: stagingDir });
-  const verb = existsInUpstream(stagingDir, "entries/" + owned.relPath) ? "update" : "add";
-  const commitMsg = `${verb}: ${owned.title}`;
-  run(ctx, "git", ["commit", "-m", commitMsg], { cwd: stagingDir });
-  run(ctx, "git", ["push", "--set-upstream", "origin", branch], { cwd: stagingDir });
-  const prTitle = `${verb}: ${owned.title}`;
-  const prBody = [
-    `Contribution of caveat \`${owned.id}\` via \`caveat push\`.`,
-    "",
-    `- entry path: \`entries/${owned.relPath}\``,
-    `- action: ${verb}`,
-    "",
-    "Merged PRs will appear in subscribers' repos on their next `caveat pull`."
-  ].join("\n");
-  const prResult = runClaim(
-    ctx,
-    "gh",
-    [
-      "pr",
-      "create",
-      "--repo",
-      `${sharedOwner}/${sharedName}`,
-      "--base",
-      "main",
-      "--head",
-      `${ghUser}:${branch}`,
-      "--title",
-      prTitle,
-      "--body",
-      prBody
-    ],
-    { cwd: stagingDir }
-  );
-  if (prResult.status === 0) {
-    const url = prResult.stdout.trim();
-    ctx.logger.info(`PR opened: ${url}`);
-    ctx.logger.info(
-      "Once merged, other subscribers will see your entry after their next `caveat pull`."
-    );
-  } else {
-    ctx.logger.error(
-      `gh pr create failed: ${(prResult.stderr || prResult.stdout || "").trim()}`
-    );
-    process.exitCode = 1;
-  }
-}
-function checkGhAvailable(ctx) {
-  const r2 = spawnSync2("gh", ["--version"], { encoding: "utf-8", shell: true });
-  if (r2.status !== 0) {
-    ctx.logger.error(
-      "gh (GitHub CLI) is required for `caveat push`. Install: https://cli.github.com/"
-    );
-    process.exitCode = 1;
-    return false;
-  }
-  const auth = spawnSync2("gh", ["auth", "status"], { encoding: "utf-8", shell: true });
-  if (auth.status !== 0) {
-    ctx.logger.error("gh is not authenticated. Run `gh auth login` first.");
-    process.exitCode = 1;
-    return false;
-  }
-  return true;
-}
-function resolveGhUser(ctx) {
-  const r2 = spawnSync2("gh", ["api", "user", "--jq", ".login"], {
-    encoding: "utf-8",
-    shell: true
+  const result = await pushEntry({
+    entriesDir: ctx.paths.entriesDir,
+    caveatHome: ctx.caveatHome,
+    sharedRepoUrl: ctx.config.sharedRepo,
+    id: opts.id,
+    dryRun: opts.dryRun,
+    logger: ctx.logger
   });
-  if (r2.status !== 0) {
-    ctx.logger.error(`gh api user failed: ${(r2.stderr || r2.stdout).trim()}`);
-    process.exitCode = 1;
-    return void 0;
-  }
-  return r2.stdout.trim();
-}
-function parseOwnerRepo(url) {
-  const m = /^https:\/\/github\.com\/([^/]+)\/([^/]+?)(\.git)?\/?$/.exec(url);
-  if (!m) return [void 0, void 0];
-  return [m[1], m[2]];
-}
-function findOwnedEntry(ctx, id) {
-  if (!existsSync12(ctx.paths.entriesDir)) return void 0;
-  for (const categoryDirent of readdirSync8(ctx.paths.entriesDir, { withFileTypes: true })) {
-    if (!categoryDirent.isDirectory()) continue;
-    const categoryDir = join15(ctx.paths.entriesDir, categoryDirent.name);
-    for (const fileDirent of readdirSync8(categoryDir, { withFileTypes: true })) {
-      if (!fileDirent.isFile() || !fileDirent.name.endsWith(".md")) continue;
-      const absPath = join15(categoryDir, fileDirent.name);
-      const raw2 = readFileSync6(absPath, "utf-8");
-      try {
-        const parsed = parseMarkdown(raw2);
-        if (parsed.frontmatter.id === id) {
-          const relPath = relative2(ctx.paths.entriesDir, absPath).replace(/\\/g, "/");
-          return {
-            id,
-            title: parsed.frontmatter.title,
-            absPath,
-            relPath
-          };
-        }
-      } catch {
+  switch (result.status) {
+    case "ok":
+      ctx.logger.info(`PR opened: ${result.prUrl ?? ""}`);
+      ctx.logger.info(
+        "Once merged, other subscribers will see your entry after their next `caveat pull`."
+      );
+      break;
+    case "dry-run":
+      for (const [i2, step] of (result.plannedSteps ?? []).entries()) {
+        ctx.logger.info(`[dry-run] ${i2 + 1}. ${step}`);
       }
-    }
-  }
-  return void 0;
-}
-function forkStagingDir(ctx) {
-  return join15(ctx.caveatHome, "push-fork");
-}
-function ensureFork(ctx, owner, repo, ghUser) {
-  const r2 = spawnSync2(
-    "gh",
-    ["repo", "fork", `${owner}/${repo}`, "--clone=false", "--remote=false"],
-    { encoding: "utf-8", shell: true }
-  );
-  if (r2.status !== 0 && !(r2.stderr || "").includes("already exists")) {
-    ctx.logger.warn(`gh repo fork stderr: ${r2.stderr.trim()}`);
-  }
-  void ghUser;
-}
-function ensureStagingClone(ctx, stagingDir, ghUser, sharedName, upstreamOwner) {
-  if (!existsSync12(stagingDir)) {
-    mkdirSync6(dirname6(stagingDir), { recursive: true });
-    const forkUrl = `https://github.com/${ghUser}/${sharedName}.git`;
-    run(ctx, "git", ["clone", "--depth", "30", forkUrl, stagingDir]);
-    run(ctx, "git", ["remote", "add", "upstream", `https://github.com/${upstreamOwner}/${sharedName}.git`], {
-      cwd: stagingDir
-    });
-  } else {
-    run(ctx, "git", ["checkout", "main"], { cwd: stagingDir });
-    run(ctx, "git", ["fetch", "upstream", "main"], { cwd: stagingDir });
-    run(ctx, "git", ["reset", "--hard", "upstream/main"], { cwd: stagingDir });
-    run(ctx, "git", ["push", "origin", "main", "--force-with-lease"], { cwd: stagingDir });
-  }
-}
-function existsInUpstream(stagingDir, relFromRoot) {
-  return existsSync12(join15(stagingDir, relFromRoot));
-}
-function run(ctx, command, args, opts = {}) {
-  const r2 = spawnSync2(command, args, {
-    encoding: "utf-8",
-    cwd: opts.cwd,
-    shell: true
-  });
-  if (r2.status !== 0) {
-    const msg = (r2.stderr || r2.stdout || "unknown").trim();
-    throw new Error(`${command} ${args.join(" ")} failed: ${msg}`);
+      break;
+    case "not-found":
+      ctx.logger.error(
+        `${result.detail}. List entries with \`caveat list\` or write + index first.`
+      );
+      process.exitCode = 1;
+      break;
+    case "gh-missing":
+    case "gh-unauthed":
+      ctx.logger.error(result.detail ?? "gh CLI issue");
+      process.exitCode = 1;
+      break;
+    case "failed":
+      ctx.logger.error(result.detail ?? "unknown failure");
+      process.exitCode = 1;
+      break;
   }
 }
-function runClaim(ctx, command, args, opts = {}) {
-  const r2 = spawnSync2(command, args, {
-    encoding: "utf-8",
-    cwd: opts.cwd,
-    shell: true
-  });
-  return {
-    status: r2.status,
-    stdout: typeof r2.stdout === "string" ? r2.stdout : "",
-    stderr: typeof r2.stderr === "string" ? r2.stderr : ""
-  };
-}
 
 // src/commands/community.ts
 async function runCommunityAdd(ctx, url) {
@@ -45015,7 +45121,7 @@ function runCommunityList(ctx) {
 
 // src/index.ts
 var program = new Command();
-program.name("caveat").description("External spec gotcha knowledge base CLI").version("0.3.0");
+program.name("caveat").description("External spec gotcha knowledge base CLI").version("0.5.0");
 program.command("init").description(
   "Initialize ~/.caveatrc.json, ~/.caveat/, subscribe to the shared community DB, and register Claude Code integration"
 ).option("--skip-claude", "skip Claude Code MCP + hook registration", false).option("--skip-shared", "skip subscribing to the shared community DB", false).option("--dry-run", "show planned changes without writing", false).action(async (opts) => {