@bartolli/kmd 0.7.0 → 0.9.0

package/dist/kmd.mjs

@@ -150,7 +150,7 @@ ${issues}`);
   }
   return parsed.data;
 }
-var ScopeSchema, KindEntrySchema, WhenSchema, TriggerSchema, TriggersSchema, VaultConfigSchema, BUILT_IN_KINDS;
+var ScopeSchema, KindEntrySchema, WhenSchema, DedupSchema, TriggerSchema, TriggersSchema, BuiltinHooksSchema, VaultConfigSchema, BUILT_IN_KINDS;
 var init_vault_config = __esm({
   "../db/src/vault-config.ts"() {
     "use strict";
@@ -177,6 +177,10 @@ var init_vault_config = __esm({
         than: z.array(z.string().min(1)).min(1)
       })
     ]);
+    DedupSchema = z.union([
+      z.enum(["session", "never"]),
+      z.strictObject({ minutes: z.number().int().positive() })
+    ]);
     TriggerSchema = z.strictObject({
       id: z.string().min(1).describe("Unique per scope list; duplicates keep the first occurrence."),
       on: z.enum(["prompt", "pretool"]),
@@ -190,7 +194,10 @@ var init_vault_config = __esm({
         "Precondition \u2014 the gate fires only when it is UNMET. newer-than: the newest page matching fresh must carry frontmatter updated at or after the newest matching than."
       ),
       text: z.string().optional().describe("Required for inject and warn \u2014 the line emitted."),
-      reason: z.string().optional().describe("Required for block \u2014 the denial the agent reads.")
+      reason: z.string().optional().describe("Required for block \u2014 the denial the agent reads."),
+      dedup: DedupSchema.optional().describe(
+        "Re-fire policy: session (default, once per session), never, or {minutes: N} for at most once per bucket. Rejected on block triggers \u2014 blocks are dedup-exempt."
+      )
     }).superRefine((trigger, ctx) => {
       if (trigger.on === "prompt" && !trigger.keywords?.length && !trigger.intent?.length) {
         ctx.addIssue({
@@ -210,6 +217,12 @@ var init_vault_config = __esm({
           message: `trigger "${trigger.id}": files applies to pretool triggers only`
         });
       }
+      if (trigger.enforce === "block" && trigger.dedup !== void 0) {
+        ctx.addIssue({
+          code: "custom",
+          message: `block trigger "${trigger.id}" may not set dedup \u2014 blocks fire on every matching event`
+        });
+      }
       if (trigger.enforce === "block" ? trigger.reason === void 0 : trigger.text === void 0) {
         ctx.addIssue({
           code: "custom",
@@ -228,6 +241,15 @@ var init_vault_config = __esm({
       }
     });
     TriggersSchema = z.record(z.string(), z.array(TriggerSchema));
+    BuiltinHooksSchema = z.strictObject({
+      resync: z.strictObject({
+        reason: z.string().min(1).optional().describe("Validate-errors preamble; the engine appends the error lines."),
+        text: z.string().min(1).optional().describe("Sync-failed note.")
+      }).optional(),
+      "handoff-gate": z.strictObject({
+        reason: z.string().min(1).optional().describe("Stop-block preamble; the engine appends the error lines.")
+      }).optional()
+    });
     VaultConfigSchema = z.strictObject({
       scopes: z.record(z.string(), ScopeSchema).describe("Scope name \u2192 entry; key = directory name under projects/."),
       kinds: z.array(KindEntrySchema).describe(
@@ -246,6 +268,9 @@ var init_vault_config = __esm({
       triggers: TriggersSchema.optional().describe(
         'Full-replace of the trigger base per scope \u2014 escape hatch. "_all" is reserved for triggers_extra.'
       ),
+      builtin_hooks: BuiltinHooksSchema.optional().describe(
+        "Message overrides for the fixed-function hooks (resync, handoff-gate) by public id."
+      ),
       triggers_extra: TriggersSchema.optional().describe(
         'Appended per scope after the engine defaults; the reserved "_all" key fires in every session.'
       )
@@ -1737,7 +1762,7 @@ var init_authoring = __esm({
     ].join("\n");
     DEFAULT_SYNC_PROTOCOL = [
       "Edit the smallest set of files that reflects the change. A milestone tick is plan-only; don't cascade to index.md unless phase or status changed. Controlled-vocabulary edits (`vault.yaml`) need explicit user approval.",
-      "After editing wiki pages, run `kmd validate` and fix findings before `kmd sync` \u2014 it checks frontmatter shape, vocabulary membership, and link integrity."
+      "Harnesses with the posttool hook validate and sync automatically on every vault write. Check `kmd config`: if the `synced` line did not advance past your edits, the hook is not wired \u2014 run `kmd validate`, fix findings, then `kmd sync`."
     ].join("\n");
     CANONICAL_STATUS_FLOW = ["draft", "active", "superseded", "archived"];
   }
@@ -2343,12 +2368,15 @@ __export(hook_exports, {
   matchPromptTriggers: () => matchPromptTriggers,
   parsePretoolEvent: () => parsePretoolEvent,
   parsePromptEvent: () => parsePromptEvent,
+  parseStopEvent: () => parseStopEvent,
   renderPosttool: () => renderPosttool,
   renderPretool: () => renderPretool,
+  renderStop: () => renderStop,
   resolveScope: () => resolveScope,
   runHookPosttool: () => runHookPosttool,
   runHookPretool: () => runHookPretool,
   runHookPrompt: () => runHookPrompt,
+  runHookStop: () => runHookStop,
   vaultPathTouched: () => vaultPathTouched
 });
 import { mkdirSync as mkdirSync4, readdirSync as readdirSync2, readFileSync, rmSync as rmSync2, statSync, writeFileSync } from "node:fs";
@@ -2455,7 +2483,11 @@ function matchPromptTriggers(prompt, triggers) {
         hit = trigger.intent.some((pattern) => new RegExp(pattern, "i").test(prompt));
       }
       if (hit) {
-        matches.push({ id: trigger.id, text: trigger.text });
+        matches.push({
+          id: trigger.id,
+          text: trigger.text,
+          ...trigger.dedup !== void 0 && { dedup: trigger.dedup }
+        });
       }
     }
   } finally {
@@ -2521,7 +2553,7 @@ function matchPretoolTriggers(toolName, toolInput, triggers, cwd) {
       if (!new RegExp(trigger.args_match).test(serialized)) continue;
     }
     if (trigger.files !== void 0 && trigger.files.length > 0) {
-      const candidates = pathCandidates(toolInput, cwd);
+      const candidates = [...pathCandidates(toolInput, cwd), ...patchPaths(toolInput)];
       const hit = trigger.files.some((glob) => {
         const regex = globToRegExp(glob);
         return candidates.some((candidate) => regex.test(candidate));
@@ -2534,7 +2566,8 @@ function matchPretoolTriggers(toolName, toolInput, triggers, cwd) {
       id: trigger.id,
       enforce: trigger.enforce,
       text,
-      ...trigger.when !== void 0 && { when: trigger.when }
+      ...trigger.when !== void 0 && { when: trigger.when },
+      ...trigger.dedup !== void 0 && { dedup: trigger.dedup }
     });
   }
   return matches;
@@ -2638,25 +2671,46 @@ function vaultPathTouched(toolInput, vaultRoot2, cwd) {
     return absolute === root || absolute.startsWith(`${root}/`);
   });
 }
-function renderPosttool(findings, synced, format) {
+function renderPosttool(findings, synced, format, messages = {}) {
   if (findings.length === 0 && synced) return null;
   const lines = findings.map((f) => `${f.severity}: ${f.path} [${f.rule}] ${f.message}`);
   if (format === "claude") {
     if (hasErrors(findings)) {
       return JSON.stringify({
         decision: "block",
-        reason: `kmd validate failed \u2014 fix before the index syncs:
+        reason: `${messages.reason ?? RESYNC_REASON}:
 ${lines.join("\n")}`
       });
     }
     const hookSpecificOutput = { hookEventName: "PostToolUse" };
     const notes = [...lines];
-    if (!synced) notes.push("kmd sync failed \u2014 index not updated; see hook stderr");
+    if (!synced) notes.push(messages.text ?? RESYNC_TEXT);
     hookSpecificOutput.additionalContext = notes.join("\n");
     return JSON.stringify({ hookSpecificOutput });
   }
   return JSON.stringify({ findings, synced });
 }
+function parseStopEvent(raw) {
+  const fields = eventFields(raw);
+  if (fields === null) return null;
+  const { session_id, cwd, stop_hook_active } = fields;
+  if (typeof session_id !== "string") return null;
+  return {
+    session_id,
+    ...typeof cwd === "string" && { cwd },
+    ...typeof stop_hook_active === "boolean" && { stop_hook_active }
+  };
+}
+function renderStop(findings, reason) {
+  const errors = findings.filter((finding) => finding.severity === "error");
+  if (errors.length === 0) return null;
+  const lines = errors.map((f) => `${f.severity}: ${f.path} [${f.rule}] ${f.message}`);
+  return JSON.stringify({
+    decision: "block",
+    reason: `${reason ?? HANDOFF_GATE_REASON}:
+${lines.join("\n")}`
+  });
+}
 function dedupePretoolMatches(stateDir, sessionId, matches) {
   const blocks = matches.filter((match) => match.enforce === "block");
   const rest = matches.filter((match) => match.enforce !== "block");
@@ -2666,15 +2720,26 @@ function dedupePretoolMatches(stateDir, sessionId, matches) {
 function hookStateDir() {
   return join10(kmdHome(), "state", "hook");
 }
-function dedupeMatches(stateDir, sessionId, matches) {
+function dedupeMatches(stateDir, sessionId, matches, now = Date.now()) {
   if (matches.length === 0) return [];
   const file = join10(stateDir, `${sessionId.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
   const fired = readFired(file);
-  const fresh = matches.filter((match) => !fired.has(match.id));
-  if (fresh.length > 0) {
+  const fresh = [];
+  const record = [];
+  for (const match of matches) {
+    if (match.dedup === "never") {
+      fresh.push(match);
+      continue;
+    }
+    const key = typeof match.dedup === "object" ? `${match.id}@${Math.floor(now / (match.dedup.minutes * 6e4))}` : match.id;
+    if (fired.has(key)) continue;
+    fresh.push(match);
+    record.push(key);
+  }
+  if (record.length > 0) {
     mkdirSync4(stateDir, { recursive: true });
-    for (const match of fresh) {
-      fired.add(match.id);
+    for (const key of record) {
+      fired.add(key);
     }
     writeFileSync(file, JSON.stringify([...fired]));
     pruneStale(stateDir, file);
@@ -2830,6 +2895,7 @@ async function runHookPosttool() {
       return;
     }
     if (!vaultPathTouched(event.tool_input, invocation.vaultRoot, event.cwd)) return;
+    const config = await loadVaultConfig(invocation.vaultRoot);
     const findings = await validateVault(invocation.vaultRoot);
     let synced = false;
     if (!hasErrors(findings)) {
@@ -2840,7 +2906,7 @@ async function runHookPosttool() {
         diag2(`sync failed: ${err instanceof Error ? err.message : String(err)}`);
       }
     }
-    const rendered = renderPosttool(findings, synced, format);
+    const rendered = renderPosttool(findings, synced, format, config.builtin_hooks?.resync ?? {});
     if (rendered !== null) {
       console.log(rendered);
     }
@@ -2848,6 +2914,31 @@ async function runHookPosttool() {
     diag2(err instanceof Error ? err.message : String(err));
   }
 }
+async function runHookStop() {
+  try {
+    const invocation = hookInvocation();
+    if (invocation === null) return;
+    const event = parseStopEvent(await readStdin());
+    if (event === null) {
+      diag2("stdin is not a stop event ({session_id})");
+      return;
+    }
+    if (event.stop_hook_active === true) return;
+    const config = await loadVaultConfig(invocation.vaultRoot);
+    const scope = invocation.scope ?? resolveScope(config, event.cwd);
+    if (scope === void 0) return;
+    const rendered = renderStop(
+      await validateVault(invocation.vaultRoot),
+      config.builtin_hooks?.["handoff-gate"]?.reason
+    );
+    if (rendered === null) return;
+    const fired = dedupeMatches(hookStateDir(), event.session_id, [{ id: "handoff-gate" }]);
+    if (fired.length === 0) return;
+    console.log(rendered);
+  } catch (err) {
+    diag2(err instanceof Error ? err.message : String(err));
+  }
+}
 async function readStdin() {
   process.stdin.setEncoding("utf8");
   let input = "";
@@ -2859,7 +2950,7 @@ async function readStdin() {
 function diag2(message) {
   console.error(`kmd hook: ${message}`);
 }
-var DEFAULT_TRIGGERS, SESSION_STATE_MAX_AGE_MS, KIRO_IDE_BUCKET_MS, ALL_SCOPES_KEY, PATCH_FILE_RE;
+var DEFAULT_TRIGGERS, SESSION_STATE_MAX_AGE_MS, KIRO_IDE_BUCKET_MS, ALL_SCOPES_KEY, PATCH_FILE_RE, RESYNC_REASON, RESYNC_TEXT, HANDOFF_GATE_REASON;
 var init_hook = __esm({
   "../cli/src/hook.ts"() {
     "use strict";
@@ -2873,6 +2964,9 @@ var init_hook = __esm({
     KIRO_IDE_BUCKET_MS = 30 * 60 * 1e3;
     ALL_SCOPES_KEY = "_all";
     PATCH_FILE_RE = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm;
+    RESYNC_REASON = "Edit landed; the index sync is held until these validate errors are fixed";
+    RESYNC_TEXT = "kmd sync failed \u2014 index not updated; see hook stderr";
+    HANDOFF_GATE_REASON = "Validate errors are outstanding and the index sync is held \u2014 fix them, let the resync run, then finish";
   }
 });
 
@@ -2893,9 +2987,10 @@ commands:
   mcp [<vault-root>]       start the stdio MCP server (default: $WIKI_VAULT)
   config [<vault-root>]    print vault + index resolution; with no vault, list known vaults
   db reset [<vault-root>]  delete the vault's index (default: $WIKI_VAULT)
-  hook <prompt|pretool|posttool> [<vault-root>] [--scope <s>] [--harness <claude|kiro-ide>] [--triggers <file>]
+  hook <prompt|pretool|posttool|stop> [<vault-root>] [--scope <s>] [--harness <claude|kiro-ide>] [--triggers <file>]
                            harness gate engine: JSON event on stdin, decision/context on stdout;
-                           posttool auto-runs validate + sync after a vault write
+                           posttool auto-runs validate + sync after a vault write;
+                           stop blocks the handoff once while validate errors hold the sync
 
 options:
   --version   print version
@@ -2970,11 +3065,14 @@ async function run() {
       } else if (sub === "posttool") {
         const { runHookPosttool: runHookPosttool2 } = await Promise.resolve().then(() => (init_hook(), hook_exports));
         await runHookPosttool2();
+      } else if (sub === "stop") {
+        const { runHookStop: runHookStop2 } = await Promise.resolve().then(() => (init_hook(), hook_exports));
+        await runHookStop2();
       } else if (sub) {
         console.error(`kmd hook: unknown event: ${sub}`);
       } else {
         console.error(
-          "usage: kmd hook <prompt|pretool|posttool> [<vault-root>] [--scope <scope>] [--harness <claude|kiro-ide>]"
+          "usage: kmd hook <prompt|pretool|posttool|stop> [<vault-root>] [--scope <scope>] [--harness <claude|kiro-ide>]"
         );
         process.exit(2);
       }