caveat-cli 0.10.0 → 0.11.0

package/dist/index.js

@@ -21339,6 +21339,10 @@ function stopReminderText(signals, related) {
   if (signals.durationMinutes > 0) {
     lines.push(`- \u7D4C\u904E\u6642\u9593: ${signals.durationMinutes} \u5206`);
   }
+  const externalLookup = signals.webSearchCount + signals.webFetchCount > 0;
+  lines.push(
+    `- \u5206\u985E\u30D2\u30F3\u30C8: ${externalLookup ? "\u5916\u90E8\u4ED5\u69D8\u8ABF\u67FB\u3042\u308A \u2192 public \u5BC4\u308A" : "\u5916\u90E8\u8ABF\u67FB\u306A\u3057 \u2192 private \u5BC4\u308A"}`
+  );
   lines.push("");
   if (related.length > 0) {
     lines.push(
@@ -21356,6 +21360,9 @@ function stopReminderText(signals, related) {
       "\u65E2\u5B58\u7F60\u306B\u8A72\u5F53\u306A\u3057\u3002\u5916\u90E8\u4ED5\u69D8\u306E\u7F60\u306B\u82E6\u6226\u3057\u3066\u3044\u305F\u306A\u3089 mcp__caveat__caveat_record \u3067\u767B\u9332\u3057\u3066\u304F\u3060\u3055\u3044\u3002outcome: impossible \u3082\u8A18\u9332\u5BFE\u8C61\u3002"
     );
   }
+  lines.push(
+    "\u8A18\u9332\u6642\u306F tool \u8AAC\u660E\u306E\u4E8C\u9805\u57FA\u6E96\u3067 visibility \u3092\u9078\u3076\uFF08public = \u7B2C\u4E09\u8005\u518D\u73FE\u53EF\u80FD / private = repo \u56FA\u6709\uFF09\u3002\u8FF7\u3063\u305F\u3089 private\u3002"
+  );
   return lines.join("\n");
 }
 
@@ -21513,6 +21520,48 @@ function drainPendingReminders(caveatHome, sessionId) {
   return out;
 }
 
+// ../../packages/core/dist/markHit.js
+function markHit(db, keys, now = () => (/* @__PURE__ */ new Date()).toISOString()) {
+  if (keys.length === 0) return;
+  const ts = now();
+  const stmt = db.prepare(
+    "UPDATE entries SET last_hit_at = ? WHERE source = ? AND id = ?"
+  );
+  for (const k2 of keys) {
+    stmt.run(ts, k2.source, k2.id);
+  }
+}
+
+// ../../packages/core/dist/stale.js
+function listStale(db, opts = {}) {
+  const days = opts.days ?? 90;
+  const limit = opts.limit ?? 50;
+  const now = (opts.now ?? (() => /* @__PURE__ */ new Date()))();
+  const cutoff = new Date(now.getTime() - days * 24 * 60 * 60 * 1e3).toISOString();
+  const conditions = ["(last_hit_at IS NULL OR last_hit_at < ?)"];
+  const params = [cutoff];
+  if (opts.visibility === "public" || opts.visibility === "private") {
+    conditions.push("visibility = ?");
+    params.push(opts.visibility);
+  }
+  const sql = `
+    SELECT id, source, title, visibility, last_hit_at
+    FROM entries
+    WHERE ${conditions.join(" AND ")}
+    ORDER BY last_hit_at IS NULL DESC, last_hit_at ASC
+    LIMIT ?
+  `;
+  params.push(limit);
+  const rows = db.prepare(sql).all(...params);
+  return rows.map((r2) => ({
+    id: r2.id,
+    source: r2.source,
+    title: r2.title,
+    visibility: r2.visibility ?? "public",
+    last_hit_at: r2.last_hit_at
+  }));
+}
+
 // src/context.ts
 function buildContext(logger, overrides = {}) {
   const userHome = overrides.userHome ?? homedir();
@@ -21906,6 +21955,29 @@ function runList(ctx, opts) {
   }
 }
 
+// src/commands/stale.ts
+function runStale(ctx, opts) {
+  const db = openDb({ path: ctx.paths.dbPath, logger: ctx.logger });
+  try {
+    const rows = listStale(db, {
+      days: opts.days,
+      visibility: opts.visibility,
+      limit: opts.limit
+    });
+    if (rows.length === 0) {
+      process.stdout.write("(no stale entries)\n");
+      return;
+    }
+    for (const r2 of rows) {
+      const age = r2.last_hit_at ?? "never";
+      process.stdout.write(`${r2.id} [${r2.source}] (${r2.visibility}) ${age} \u2014 ${r2.title}
+`);
+    }
+  } finally {
+    db.close();
+  }
+}
+
 // src/commands/show.ts
 function runShow(ctx, opts) {
   const db = openDb({ path: ctx.paths.dbPath, logger: ctx.logger });
@@ -44694,12 +44766,24 @@ function buildMcpContext(overrides = {}) {
 // ../mcp/dist/tools/search.js
 var sourceFilter = external_exports.enum(["own", "community", "all"]);
 var confidenceSchema = external_exports.enum(["confirmed", "reproduced", "tentative"]);
+var visibilityFilter = external_exports.enum(["public", "private", "all"]);
 var searchInputShape = {
   query: external_exports.string().describe("FTS query (3+ chars for trigram). Empty string lists without text filter."),
   filters: external_exports.object({
     tags: external_exports.array(external_exports.string()).optional(),
     confidence: external_exports.array(confidenceSchema).optional(),
-    source: sourceFilter.optional()
+    source: sourceFilter.optional(),
+    visibility: visibilityFilter.optional().describe(
+      [
+        "Narrow by publish tier.",
+        "'public' = external-spec gotchas reproducible by any third party (PyInstaller, Stripe, Claude Code hook behavior, etc).",
+        "'private' = your own cross-project notes (repo-specific, your workflow, intentional non-standard design).",
+        "'all' (or omit) = both tiers.",
+        "Use 'public' when drafting externally-visible output (PR descriptions, public docs, answers to third parties) so private notes do not bleed into external content.",
+        "Use 'private' when specifically recalling your own past decisions.",
+        "Default to omitting this filter \u2014 narrowing too aggressively hides relevant entries."
+      ].join(" ")
+    )
   }).optional(),
   limit: external_exports.number().int().min(1).max(200).optional()
 };
@@ -44709,6 +44793,7 @@ function handleSearch(ctx, args) {
     filters: args.filters,
     limit: args.limit
   });
+  if (results.length > 0) markHit(ctx.db, results);
   return results;
 }
 
@@ -44740,7 +44825,14 @@ var recordInputShape = {
   confidence: confidenceSchema2.optional(),
   outcome: outcomeSchema.optional(),
   visibility: visibilitySchema.describe(
-    'REQUIRED. Ask the user "public (share to community) or private (keep local only)?" before calling \u2014 never auto-classify. The user owns the knowledge; they decide its reach.'
+    [
+      "REQUIRED. Classify using this binary criterion:",
+      "- 'public' if a third party running the same external tool/spec could reproduce this gotcha (external-spec trap, e.g. PyInstaller/Stripe/Podman/Claude Code hook behavior).",
+      "- 'private' if it is specific to your repo, your workflow, an intentional non-standard design, or context that only exists in this project.",
+      "- When unclear, prefer 'private' (leak-safety).",
+      `Exception: if the user explicitly asks to record it as private/public (e.g. "save this as private", "\u3053\u308C\u306F\u81EA\u5206\u7528\u306B\u30E1\u30E2\u3057\u3066"), follow the user's instruction regardless of the criterion \u2014 explicit user intent overrides auto-classification.`,
+      "When recording with visibility: 'private', always include repo-specific identifiers (function names, file paths, class names, custom terminology) in the body so the entry can be retrieved later by co-occurrence FTS when you touch that area again."
+    ].join(" ")
   ),
   tags: external_exports.array(external_exports.string()).optional(),
   environment: external_exports.record(external_exports.string(), external_exports.string()).optional(),
@@ -44761,7 +44853,13 @@ var patchFrontmatterSchema = external_exports.object({
   title: external_exports.string().optional(),
   confidence: confidenceSchema3.optional(),
   outcome: outcomeSchema2.optional(),
-  visibility: visibilitySchema2.optional(),
+  visibility: visibilitySchema2.optional().describe(
+    [
+      "Change the publish tier. Use the same binary criterion as caveat_record:",
+      "'public' if third-party reproducible, 'private' if repo-specific/your-workflow-specific.",
+      "When unclear, prefer 'private'. Explicit user instruction overrides auto-classification."
+    ].join(" ")
+  ),
   tags: external_exports.array(external_exports.string()).optional(),
   environment: external_exports.record(external_exports.string(), external_exports.string()).optional(),
   last_verified: external_exports.string().optional()
@@ -44982,7 +45080,17 @@ function searchCaveatsFromTextSafely(text2) {
     const ctx = buildContextSafely();
     if (!ctx || !existsSync14(ctx.paths.dbPath)) return [];
     db = openDb({ path: ctx.paths.dbPath });
-    return findCaveatsForPrompt(db, text2);
+    const hits = findCaveatsForPrompt(db, text2);
+    if (hits.length > 0) {
+      try {
+        markHit(db, hits);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[caveat:hook] markHit error: ${msg}
+`);
+      }
+    }
+    return hits;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`[caveat:hook] search error: ${msg}
@@ -45312,6 +45420,13 @@ program.command("list").description("List caveats by updated_at DESC").option("-
   const ctx = buildContext(stdoutLogger);
   runList(ctx, { limit: opts.recent });
 });
+program.command("stale").description(
+  "List entries not surfaced by retrieval for N days (default 90). Use this to find private caveats that may be buried \u2014 if a 3-month-old private entry never surfaces, rewrite its body to include repo-specific identifiers, or delete it."
+).option("--days <n>", "age threshold in days", (v) => Number(v), 90).option("--visibility <v>", "public | private").option("--limit <n>", "max rows", (v) => Number(v), 50).action((opts) => {
+  const ctx = buildContext(stdoutLogger);
+  const vis = opts.visibility === "public" || opts.visibility === "private" ? opts.visibility : void 0;
+  runStale(ctx, { days: opts.days, visibility: vis, limit: opts.limit });
+});
 program.command("show").description("Show full caveat by id").argument("<id>", "entry id").option("--source <source>", "own or community/<handle>", "own").action((id, opts) => {
   const ctx = buildContext(stdoutLogger);
   runShow(ctx, { id, source: opts.source });