caveat-cli 0.4.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # caveat-cli
 
-External spec gotcha knowledge base CLI — markdown + SQLite FTS5 + MCP server + Claude Code hooks.
+External spec gotcha knowledge base CLI — markdown + SQLite FTS5 + MCP server + Claude Code hooks, with a shared community knowledge DB out of the box.
 
 **Source / full docs**: https://github.com/kitepon-rgb/Caveat
 
@@ -11,22 +11,48 @@ npm install -g caveat-cli
 caveat init
 ```
 
-`caveat init` creates `~/.caveat/`, registers the MCP server with Claude Code (via `claude mcp add --scope user`), and merges `UserPromptSubmit` / `Stop` hooks into `~/.claude/settings.json`. Existing hook entries are preserved; the settings file is backed up before any write. Run `caveat init --dry-run` to preview, or `caveat init --skip-claude` to skip Claude Code wiring.
+`caveat init` (idempotent, `--dry-run` supported) does 4 things:
+
+1. Scaffolds `~/.caveat/own/` (your personal knowledge repo) + `~/.caveat/index/caveat.db`
+2. **Subscribes you to the shared community DB** (`kitepon-rgb/Caveat` by default) — shallow-clones into `~/.caveat/community/Caveat/` and indexes so other users' caveats are immediately searchable
+3. Registers the MCP server with Claude Code (`claude mcp add --scope user`)
+4. Merges `UserPromptSubmit` / `Stop` hooks into `~/.claude/settings.json` (existing entries preserved, backup written before any change)
+
+Opt-out flags: `--skip-claude`, `--skip-shared`. `caveat uninstall` reverses the Claude Code changes without touching `~/.caveat/`.
 
 ## Basic usage
 
 ```sh
-caveat search "rtx"         # FTS against your knowledge repo
+caveat search "rtx"         # FTS across your own entries + the shared community DB
 caveat list                 # recent entries
+caveat pull                 # fetch new community contributions + re-index
+caveat push <entry-id>      # contribute your entry via fork + PR (requires gh CLI)
 caveat serve                # http://localhost:4242 read-only portal
-caveat community add <url>  # shallow-clone another user's caveats repo
+caveat community add <url>  # subscribe to an additional community repo
 caveat uninstall            # reverse `caveat init` Claude integration
 ```
 
+## MCP tools (7)
+
+Exposed to Claude Code via the MCP server that `caveat init` registers:
+
+`caveat_search`, `caveat_get`, `caveat_record`, `caveat_update`, `caveat_list_recent`, `caveat_pull`, `caveat_push`.
+
+Claude can autonomously pull community updates (safe, idempotent) and push your recorded caveats (gated by Claude Code's tool permission prompt for user consent — contribution is a public action).
+
+## Pointing at a different shared DB
+
+For an internal/enterprise shared knowledge pool, override in `~/.caveatrc.json`:
+
+```json
+{ "sharedRepo": "https://github.com/your-org/your-caveats" }
+```
+
 ## Requirements
 
 - Node 22.5+ (for built-in `node:sqlite`)
-- Optional: Claude Code installed for MCP / hooks integration. Without it, `caveat init --skip-claude` still provisions the local knowledge repo + index.
+- `gh` CLI authenticated (`gh auth login`) if you want to use `caveat push`
+- Claude Code installed if you want MCP / hooks integration. Without it, `caveat init --skip-claude` still provisions local state + shared DB
 
 ## License
 

package/dist/index.js

@@ -15948,8 +15948,7 @@ function recordEntry(input, opts) {
     source_session: generateSourceSession(now),
     created_at: ymd,
     updated_at: ymd,
-    last_verified: ymd,
-    ...input.brief_id !== void 0 ? { brief_id: input.brief_id } : {}
+    last_verified: ymd
   };
   const sections = {};
   if (input.context !== void 0) sections["Context"] = input.context;
@@ -15996,8 +15995,7 @@ var IMMUTABLE_KEYS = /* @__PURE__ */ new Set([
   "id",
   "created_at",
   "source_session",
-  "source_project",
-  "brief_id"
+  "source_project"
 ]);
 function updateEntry(id, patch, opts) {
   const source = opts.source ?? "own";
@@ -16035,9 +16033,6 @@ function updateEntry(id, patch, opts) {
   if (patch.frontmatter?.tags !== void 0) {
     mergedFrontmatter.tags = patch.frontmatter.tags;
   }
-  if (parsed.frontmatter.brief_id !== void 0) {
-    mergedFrontmatter.brief_id = parsed.frontmatter.brief_id;
-  }
   const mergedSections = { ...parsed.sections };
   if (patch.sections) {
     for (const [heading2, content] of Object.entries(patch.sections)) {
@@ -16077,39 +16072,6 @@ function formatYmd2(d) {
   return `${yyyy}-${mm}-${dd}`;
 }
 
-// ../../packages/core/dist/brief.js
-function generateBrief(db, topic, limit = 10) {
-  const related = topic.trim().length > 0 ? search(db, { query: topic, limit }) : [];
-  const brief_id = `brf-${Date.now().toString(36)}-${randomHex(8)}`;
-  const lines = [];
-  lines.push(`# \u8ABF\u67FB\u4F9D\u983C: ${topic}`);
-  lines.push("");
-  lines.push("## \u4F9D\u983C\u306E\u80CC\u666F");
-  lines.push(
-    `\u4EE5\u4E0B\u306E\u8A71\u984C\u306B\u3064\u3044\u3066\u3001\u4E00\u6B21\u30BD\u30FC\u30B9\u4E2D\u5FC3\u3067\u8ABF\u67FB\u3057\u3066\u304F\u3060\u3055\u3044: ${topic}`
-  );
-  lines.push("");
-  if (related.length > 0) {
-    lines.push("## \u65E2\u5B58\u306E\u95A2\u9023 caveat\uFF08\u53C2\u8003\uFF09");
-    for (const r2 of related) {
-      lines.push(`- \`${r2.id}\` (${r2.confidence}) ${r2.title}`);
-    }
-    lines.push("");
-  }
-  lines.push("## \u6C42\u3081\u305F\u3044\u60C5\u5831");
-  lines.push("1. \u516C\u5F0F\u4ED5\u69D8 (RFC / \u4ED5\u69D8\u66F8 / \u30D9\u30F3\u30C0\u30FC\u516C\u5F0F\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8) \u2014 \u30D0\u30FC\u30B8\u30E7\u30F3\u660E\u8A18");
-  lines.push("2. \u65E2\u77E5\u306E\u843D\u3068\u3057\u7A74 (\u30D0\u30FC\u30B8\u30E7\u30F3\u4F9D\u5B58\u3001\u30D7\u30E9\u30C3\u30C8\u30D5\u30A9\u30FC\u30E0\u5DEE\u7570\u3001\u65E2\u5831\u306E\u4E0D\u5177\u5408)");
-  lines.push("3. \u56DE\u907F\u7B56\u3068\u4EE3\u66FF\u624B\u6BB5\uFF08\u52B9\u679C\u306E\u88CF\u53D6\u308A\u3064\u304D\uFF09");
-  lines.push("4. \u4E00\u6B21\u30BD\u30FC\u30B9 URL\u3002\u4E8C\u6B21\u30BD\u30FC\u30B9\uFF08\u30D6\u30ED\u30B0\u7B49\uFF09\u306F\u533A\u5225\u3057\u3066\u8A18\u8F09");
-  lines.push("");
-  lines.push("## \u51FA\u529B\u306E\u5F62");
-  lines.push("Symptom / Cause / Resolution / Evidence \u306E 4 \u30BB\u30AF\u30B7\u30E7\u30F3\u3067\u3001\u5F8C\u7D9A\u306E `ingest_research` \u306B\u6E21\u305B\u308B\u5F62\u5F0F\u3067\u8FD4\u3057\u3066\u304F\u3060\u3055\u3044\u3002");
-  lines.push("");
-  lines.push("---");
-  lines.push(`brief_id: ${brief_id}`);
-  return { brief_id, text: lines.join("\n") };
-}
-
 // ../../packages/core/dist/paths.js
 import { existsSync as existsSync4 } from "node:fs";
 import { dirname as dirname3, isAbsolute, join as join5, resolve } from "node:path";
@@ -16139,7 +16101,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"],
@@ -44681,8 +44643,7 @@ var recordInputShape = {
   visibility: visibilitySchema.optional(),
   tags: external_exports.array(external_exports.string()).optional(),
   environment: external_exports.record(external_exports.string(), external_exports.string()).optional(),
-  category: external_exports.string().optional().describe("Directory under entries/ (e.g., gpu, claude-code). Default: misc"),
-  brief_id: external_exports.string().optional()
+  category: external_exports.string().optional().describe("Directory under entries/ (e.g., gpu, claude-code). Default: misc")
 };
 function handleRecord(ctx, args) {
   return recordEntry(args, {
@@ -44729,48 +44690,6 @@ function handleListRecent(ctx, args) {
   return listRecent(ctx.db, args.limit ?? 20);
 }
 
-// ../mcp/dist/tools/nlmBriefFor.js
-var nlmBriefForInputShape = {
-  topic: external_exports.string().min(1),
-  limit: external_exports.number().int().min(1).max(50).optional()
-};
-function handleNlmBriefFor(ctx, args) {
-  return generateBrief(ctx.db, args.topic, args.limit);
-}
-
-// ../mcp/dist/tools/ingestResearch.js
-var ingestResearchInputShape = {
-  title: external_exports.string().min(1),
-  symptom: external_exports.string().min(1),
-  cause: external_exports.string().optional(),
-  resolution: external_exports.string().optional(),
-  evidence: external_exports.array(external_exports.string()).optional(),
-  brief_id: external_exports.string().optional(),
-  tags: external_exports.array(external_exports.string()).optional(),
-  category: external_exports.string().optional()
-};
-function handleIngestResearch(ctx, args) {
-  const evidenceText = args.evidence ? args.evidence.map((line) => `- ${line}`).join("\n") : "";
-  return recordEntry(
-    {
-      title: args.title,
-      symptom: args.symptom,
-      cause: args.cause ?? "",
-      resolution: args.resolution ?? "",
-      evidence: evidenceText,
-      confidence: "tentative",
-      outcome: "resolved",
-      tags: args.tags,
-      category: args.category,
-      brief_id: args.brief_id
-    },
-    {
-      db: ctx.db,
-      entriesRoot: ctx.paths.entriesDir
-    }
-  );
-}
-
 // ../mcp/dist/tools/pull.js
 var pullInputShape = {};
 async function handlePull(ctx, _args = {}) {
@@ -44856,7 +44775,7 @@ function registerAllTools(server, ctx) {
     "caveat_update",
     {
       title: "caveat_update",
-      description: "Patch an existing caveat. Frontmatter shallow-merges (arrays replace). Sections matched by case-insensitive H2 heading. Immutable keys: id, created_at, source_session, source_project, brief_id.",
+      description: "Patch an existing caveat. Frontmatter shallow-merges (arrays replace). Sections matched by case-insensitive H2 heading. Immutable keys: id, created_at, source_session, source_project.",
       inputSchema: updateInputShape
     },
     async (args) => jsonResult(handleUpdate(ctx, args))
@@ -44870,24 +44789,6 @@ function registerAllTools(server, ctx) {
     },
     async (args) => jsonResult(handleListRecent(ctx, args))
   );
-  server.registerTool(
-    "nlm_brief_for",
-    {
-      title: "nlm_brief_for",
-      description: "Generate a NotebookLM research brief for a topic. Returns {brief_id, text}. brief_id can be passed to ingest_research when the NLM output is ready. Stateless \u2014 brief_id is not persisted until ingest_research fires.",
-      inputSchema: nlmBriefForInputShape
-    },
-    async (args) => jsonResult(handleNlmBriefFor(ctx, args))
-  );
-  server.registerTool(
-    "ingest_research",
-    {
-      title: "ingest_research",
-      description: "Create a caveat from NotebookLM research output. Always records with confidence: tentative. Pass brief_id to link back to the originating brief.",
-      inputSchema: ingestResearchInputShape
-    },
-    async (args) => jsonResult(handleIngestResearch(ctx, args))
-  );
   server.registerTool(
     "caveat_pull",
     {
@@ -45121,7 +45022,7 @@ function runCommunityList(ctx) {
 
 // src/index.ts
 var program = new Command();
-program.name("caveat").description("External spec gotcha knowledge base CLI").version("0.4.0");
+program.name("caveat").description("External spec gotcha knowledge base CLI").version("0.6.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) => {