caveat-cli 0.2.1 → 0.4.0

package/dist/index.js

@@ -9761,49 +9761,49 @@ var require_fast_uri = __commonJS({
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
-    function resolveComponent(base2, relative2, options2, skipNormalization) {
+    function resolveComponent(base2, relative3, options2, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
         base2 = parse4(serialize(base2, options2), options2);
-        relative2 = parse4(serialize(relative2, options2), options2);
+        relative3 = parse4(serialize(relative3, options2), options2);
       }
       options2 = options2 || {};
-      if (!options2.tolerant && relative2.scheme) {
-        target.scheme = relative2.scheme;
-        target.userinfo = relative2.userinfo;
-        target.host = relative2.host;
-        target.port = relative2.port;
-        target.path = removeDotSegments(relative2.path || "");
-        target.query = relative2.query;
+      if (!options2.tolerant && relative3.scheme) {
+        target.scheme = relative3.scheme;
+        target.userinfo = relative3.userinfo;
+        target.host = relative3.host;
+        target.port = relative3.port;
+        target.path = removeDotSegments(relative3.path || "");
+        target.query = relative3.query;
       } else {
-        if (relative2.userinfo !== void 0 || relative2.host !== void 0 || relative2.port !== void 0) {
-          target.userinfo = relative2.userinfo;
-          target.host = relative2.host;
-          target.port = relative2.port;
-          target.path = removeDotSegments(relative2.path || "");
-          target.query = relative2.query;
+        if (relative3.userinfo !== void 0 || relative3.host !== void 0 || relative3.port !== void 0) {
+          target.userinfo = relative3.userinfo;
+          target.host = relative3.host;
+          target.port = relative3.port;
+          target.path = removeDotSegments(relative3.path || "");
+          target.query = relative3.query;
         } else {
-          if (!relative2.path) {
+          if (!relative3.path) {
             target.path = base2.path;
-            if (relative2.query !== void 0) {
-              target.query = relative2.query;
+            if (relative3.query !== void 0) {
+              target.query = relative3.query;
             } else {
               target.query = base2.query;
             }
           } else {
-            if (relative2.path[0] === "/") {
-              target.path = removeDotSegments(relative2.path);
+            if (relative3.path[0] === "/") {
+              target.path = removeDotSegments(relative3.path);
             } else {
               if ((base2.userinfo !== void 0 || base2.host !== void 0 || base2.port !== void 0) && !base2.path) {
-                target.path = "/" + relative2.path;
+                target.path = "/" + relative3.path;
               } else if (!base2.path) {
-                target.path = relative2.path;
+                target.path = relative3.path;
               } else {
-                target.path = base2.path.slice(0, base2.path.lastIndexOf("/") + 1) + relative2.path;
+                target.path = base2.path.slice(0, base2.path.lastIndexOf("/") + 1) + relative3.path;
               }
               target.path = removeDotSegments(target.path);
             }
-            target.query = relative2.query;
+            target.query = relative3.query;
           }
           target.userinfo = base2.userinfo;
           target.host = base2.host;
@@ -9811,7 +9811,7 @@ var require_fast_uri = __commonJS({
         }
         target.scheme = base2.scheme;
       }
-      target.fragment = relative2.fragment;
+      target.fragment = relative3.fragment;
       return target;
     }
     function equal(uriA, uriB, options2) {
@@ -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,10 +16139,12 @@ 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 DEFAULT_CONFIG = {
   knowledgeRepo: "own",
   semverKeys: ["driver", "cuda", "node"],
-  communitySources: []
+  communitySources: [],
+  sharedRepo: SHARED_REPO_URL
 };
 function loadConfig(userConfigPath) {
   const userCfg = existsSync5(userConfigPath) ? JSON.parse(readFileSync4(userConfigPath, "utf-8")) : {};
@@ -21226,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 };
@@ -21251,13 +21484,13 @@ var stdoutLogger = {
 };
 
 // src/commands/init.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync4, 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) {
@@ -21291,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;
@@ -21311,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);
@@ -21361,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");
@@ -21380,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");
@@ -21417,23 +21650,33 @@ var KNOWLEDGE_GITIGNORE = [
   "community/",
   ""
 ].join("\n");
-function runInit(ctx, opts = { skipClaude: false, dryRun: false }) {
+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}`);
   }
   const db = openDb({ path: ctx.paths.dbPath, logger: ctx.logger });
-  db.close();
+  try {
+    if (!opts.skipShared && !opts.dryRun) {
+      await subscribeSharedRepo(ctx, db);
+    } else if (opts.skipShared) {
+      ctx.logger.info("shared community DB subscription skipped (--skip-shared)");
+    } else if (opts.dryRun) {
+      ctx.logger.info(`[dry-run] would subscribe to shared community DB: ${ctx.config.sharedRepo}`);
+    }
+  } finally {
+    db.close();
+  }
   ctx.logger.info(`db initialized: ${ctx.paths.dbPath}`);
   if (opts.skipClaude) {
     ctx.logger.info("Claude Code integration skipped (--skip-claude)");
@@ -21445,7 +21688,7 @@ function runInit(ctx, opts = { skipClaude: false, dryRun: false }) {
     return;
   }
   const result = installClaudeIntegration({
-    claudeDir: join9(ctx.userHome, ".claude"),
+    claudeDir: join11(ctx.userHome, ".claude"),
     cliScriptPath,
     nodePath: process.execPath,
     dryRun: opts.dryRun,
@@ -21453,6 +21696,52 @@ function runInit(ctx, opts = { skipClaude: false, dryRun: false }) {
   });
   reportInstallResult(ctx, result, opts.dryRun);
 }
+async function subscribeSharedRepo(ctx, db) {
+  const url = ctx.config.sharedRepo;
+  const validation = validateCommunityUrl(url);
+  if (!validation.valid) {
+    ctx.logger.warn(
+      `sharedRepo is not a valid GitHub URL \u2014 skipping: ${validation.reason}`
+    );
+    return;
+  }
+  const handle = validation.handle;
+  const target = join11(ctx.paths.communityDir, handle);
+  if (!existsSync10(target)) {
+    if (!existsSync10(ctx.paths.communityDir)) {
+      mkdirSync5(ctx.paths.communityDir, { recursive: true });
+    }
+    try {
+      await communityAdd({
+        url,
+        communityDir: ctx.paths.communityDir,
+        logger: ctx.logger
+      });
+      ctx.logger.info(`shared community DB subscribed: ${url} \u2192 community/${handle}/`);
+    } catch (err) {
+      ctx.logger.warn(
+        `shared community DB subscription failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return;
+    }
+  } else {
+    ctx.logger.info(`shared community DB already subscribed: community/${handle}/`);
+  }
+  if (existsSync10(ctx.paths.communityDir)) {
+    rebuildAll(db);
+    if (existsSync10(ctx.paths.entriesDir)) {
+      scanSource({ db, source: "own", entriesRoot: ctx.paths.entriesDir });
+    }
+    for (const entry of readdirSync6(ctx.paths.communityDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const source = `community/${entry.name}`;
+      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}`);
+    }
+  }
+}
 function runUninstall(ctx, opts) {
   const cliScriptPath = process.argv[1];
   if (!cliScriptPath) {
@@ -21460,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,
@@ -21497,29 +21786,29 @@ function reportInstallResult(ctx, result, dryRun) {
 }
 
 // src/commands/indexCmd.ts
-import { existsSync as existsSync9, readdirSync as readdirSync4, 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 readdirSync4(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}`);
       }
@@ -22293,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);
@@ -30024,14 +30313,14 @@ function createDetailRoute(ctx) {
 }
 
 // ../web/dist/routes/community.js
-import { existsSync as existsSync10, readdirSync as readdirSync5, 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 readdirSync5(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,
@@ -44329,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);
@@ -44482,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 {
@@ -44557,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
@@ -44648,6 +44997,78 @@ async function runHook(name) {
   process.exit(0);
 }
 
+// src/commands/pull.ts
+import { existsSync as existsSync13 } from "node:fs";
+async function runPull(ctx) {
+  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 db = openDb({ path: ctx.paths.dbPath, logger: ctx.logger });
+  try {
+    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 i2 of result.indexed) {
+      ctx.logger.info(`${i2.source}: +${i2.added}`);
+    }
+  } finally {
+    db.close();
+  }
+}
+
+// src/commands/push.ts
+async function runPush(ctx, opts) {
+  const result = await pushEntry({
+    entriesDir: ctx.paths.entriesDir,
+    caveatHome: ctx.caveatHome,
+    sharedRepoUrl: ctx.config.sharedRepo,
+    id: opts.id,
+    dryRun: opts.dryRun,
+    logger: ctx.logger
+  });
+  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}`);
+      }
+      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;
+  }
+}
+
 // src/commands/community.ts
 async function runCommunityAdd(ctx, url) {
   try {
@@ -44700,12 +45121,16 @@ function runCommunityList(ctx) {
 
 // src/index.ts
 var program = new Command();
-program.name("caveat").description("External spec gotcha knowledge base CLI").version("0.2.1");
+program.name("caveat").description("External spec gotcha knowledge base CLI").version("0.4.0");
 program.command("init").description(
-  "Initialize ~/.caveatrc.json, ~/.caveat/, and register Claude Code integration"
-).option("--skip-claude", "skip Claude Code MCP + hook registration", false).option("--dry-run", "show planned changes without writing", false).action((opts) => {
+  "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) => {
   const ctx = buildContext(stdoutLogger);
-  runInit(ctx, { skipClaude: opts.skipClaude, dryRun: opts.dryRun });
+  await runInit(ctx, {
+    skipClaude: opts.skipClaude,
+    skipShared: opts.skipShared,
+    dryRun: opts.dryRun
+  });
 });
 program.command("uninstall").description("Remove Claude Code MCP server and hooks registered by `caveat init`").option("--dry-run", "show planned changes without writing", false).action((opts) => {
   const ctx = buildContext(stdoutLogger);
@@ -44738,6 +45163,16 @@ program.command("stats").description("Show aggregate stats").action(() => {
   const ctx = buildContext(stdoutLogger);
   runStats(ctx);
 });
+program.command("pull").description(
+  "Refresh all subscribed community repos (incl. shared DB) and re-index. Use this to receive contributions others have merged."
+).action(async () => {
+  const ctx = buildContext(stdoutLogger);
+  await runPull(ctx);
+});
+program.command("push").description("Contribute a caveat to the shared community DB via fork + PR (requires gh CLI).").argument("<id>", "entry id (from `caveat list`)").option("--dry-run", "show planned steps without making GitHub changes", false).action(async (id, opts) => {
+  const ctx = buildContext(stdoutLogger);
+  await runPush(ctx, { id, dryRun: opts.dryRun });
+});
 program.command("serve").description("Start the read-only web share portal").option("--port <n>", "port number", (v) => Number(v), 4242).action((opts) => {
   runServe({ port: opts.port });
 });