@vkmikc/create-vkm-kit 4.2.0

package/src/hooks/_transcript-cache.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * Shared incremental-scan engine for the transcript-reading hooks (`guard-effort-gate.mjs`,
+ * `stop-vault-close-reminder.mjs`). Installed by create-obsidian-memory — the vkm-kit
+ * installer — alongside them into `~/.claude/hooks/` — NOT a hook itself (Claude Code never
+ * invokes this file directly), just a sibling module the other two import.
+ *
+ * Why: both hooks re-read + re-parse the ENTIRE JSONL transcript on every single gated tool
+ * call. Measured ~75ms on a real 25.8MB/1878-line transcript (41ms read + 34ms parse);
+ * `guard-effort-gate` pays this on every substantive Write/Edit/MultiEdit/NotebookEdit, so a
+ * long session with dozens of edits accumulates real, worsening latency (ADR-0030/0031
+ * explicitly deferred this for v1: "zero extra state to manage"). Since each hook invocation
+ * is a FRESH subprocess (no persistent in-memory state possible), this adds a small sidecar
+ * cache file in the OS temp dir, keyed by the transcript's own path + which hook is asking,
+ * storing the last-consumed byte offset plus the caller's derived accumulator state — so a
+ * later invocation only reads+parses the NEW suffix appended since the last call.
+ *
+ * Correctness over speed on any doubt: a missing, corrupt, or stale (transcript shrank —
+ * detected by comparing the cache's recorded size/mtime against the current stat) cache always
+ * falls back to a full rescan from byte 0. Size/mtime monotonicity alone cannot catch a
+ * transcript that was TRUNCATED AND REPLACED with unrelated content, then appended-to past its
+ * original size before the next call — same-or-larger size, same-or-newer mtime, wrong bytes.
+ * A content fingerprint (hash of the bytes immediately before the cached offset) closes that
+ * gap: it is re-verified against the CURRENT file before trusting a resume, so replaced content
+ * always falls back to a full rescan instead of resuming into the middle of unrelated bytes. A
+ * trailing PARTIAL line (the transcript is being actively appended to mid-write) is never
+ * consumed — only complete lines (ending in `"\n"`) advance the committed offset, so a line can
+ * never be parsed truncated or silently dropped. This is a PERFORMANCE change only: the derived
+ * state for any given transcript content is byte-for-byte identical to what a full rescan would
+ * produce.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+
+/** Test-only instrumentation: how many actual file reads / bytes {@link getIncrementalState}
+ * performed since the last reset. Lets tests assert a resumed scan reads LESS than a full
+ * one — not just that the final derived state ends up correct. Never consulted by the hooks
+ * themselves; purely observational. */
+export const _debugStats = { reads: 0, bytesRead: 0 };
+export function _resetDebugStats() {
+  _debugStats.reads = 0;
+  _debugStats.bytesRead = 0;
+}
+
+function cacheDir() {
+  return path.join(os.tmpdir(), "obsidian-memory-kit-hook-cache");
+}
+
+/** One cache file per (transcript, hook) pair — two different hooks scanning the SAME
+ * transcript (or the same hook across different sessions/transcripts) never collide. */
+function cacheFilePath(transcriptPath, cacheKey) {
+  const digest = crypto.createHash("sha1").update(path.resolve(transcriptPath)).digest("hex");
+  return path.join(cacheDir(), `${digest}.${cacheKey}.json`);
+}
+
+/** How many bytes immediately before the cached offset get hashed into the resume
+ * fingerprint. Small enough to be cheap on every gated call; large enough that a
+ * transcript replacement is astronomically unlikely to hash-collide by chance. */
+const FINGERPRINT_WINDOW = 64;
+
+/** Hash of the up-to-{@link FINGERPRINT_WINDOW} bytes immediately before `offset` in
+ * `transcriptPath`, as currently on disk. `null` if that region can't be read (missing
+ * file, offset beyond EOF, etc.) — treated as "can't verify, don't resume". Offset 0 has
+ * nothing before it to fingerprint, so it hashes the empty buffer (deterministic, always
+ * "matches" — resuming from byte 0 is always safe, there's nothing to have been replaced). */
+function fingerprintBefore(transcriptPath, offset) {
+  let fd;
+  try {
+    fd = fs.openSync(transcriptPath, "r");
+    const start = Math.max(0, offset - FINGERPRINT_WINDOW);
+    const length = offset - start;
+    const buf = Buffer.alloc(length);
+    if (length > 0) fs.readSync(fd, buf, 0, length, start);
+    return crypto.createHash("sha1").update(buf).digest("hex");
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+/** Load + validate a cache file. Returns `null` (triggering a full rescan) on anything that
+ * doesn't look exactly like a cache we could have written for THIS transcript — missing
+ * file, corrupt JSON, wrong shape, or a `transcriptPath` mismatch. Never throws. */
+function readCache(cacheFp, transcriptPath) {
+  try {
+    const raw = fs.readFileSync(cacheFp, "utf8");
+    const cache = JSON.parse(raw);
+    if (
+      cache &&
+      typeof cache === "object" &&
+      cache.transcriptPath === transcriptPath &&
+      typeof cache.offset === "number" &&
+      typeof cache.size === "number" &&
+      typeof cache.mtimeMs === "number" &&
+      typeof cache.fingerprint === "string" &&
+      cache.state &&
+      typeof cache.state === "object"
+    ) {
+      return cache;
+    }
+  } catch {
+    /* missing/corrupt cache -> full rescan */
+  }
+  return null;
+}
+
+/** Best-effort: a failed cache write just means the NEXT call does a full rescan instead of
+ * resuming — never lets a permissions/disk issue break the hook itself. */
+function writeCache(cacheFp, cache) {
+  try {
+    fs.mkdirSync(path.dirname(cacheFp), { recursive: true });
+    fs.writeFileSync(cacheFp, JSON.stringify(cache));
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Read `transcriptPath` from byte offset `fromOffset` to EOF, fold each COMPLETE line into
+ * `state` via `foldLine(state, line)`, and return the byte offset right after the last
+ * complete line consumed (NOT necessarily EOF — a trailing partial line is left for next
+ * time). Never throws: an unreadable file leaves `state`/offset unchanged.
+ * @param {string} transcriptPath
+ * @param {number} fromOffset
+ * @param {object} state
+ * @param {(state: object, line: string) => object} foldLine
+ */
+function scanFromOffset(transcriptPath, fromOffset, state, foldLine) {
+  let fd;
+  try {
+    fd = fs.openSync(transcriptPath, "r");
+    const size = fs.fstatSync(fd).size;
+    if (size <= fromOffset) return { offset: fromOffset, state };
+    const length = size - fromOffset;
+    const buf = Buffer.alloc(length);
+    fs.readSync(fd, buf, 0, length, fromOffset);
+    _debugStats.reads++;
+    _debugStats.bytesRead += length;
+    const chunk = buf.toString("utf8");
+    const lastNewline = chunk.lastIndexOf("\n");
+    if (lastNewline === -1) return { offset: fromOffset, state }; // no complete line yet
+    for (const line of chunk.slice(0, lastNewline).split("\n")) {
+      state = foldLine(state, line);
+    }
+    return { offset: fromOffset + lastNewline + 1, state };
+  } catch {
+    return { offset: fromOffset, state };
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+/**
+ * Get the up-to-date derived state for `transcriptPath`, resuming from the cached offset
+ * when it's SAFE to (cache present, matches this transcript + hook, the file has only grown
+ * since — same-or-larger size, same-or-later mtime — AND the content fingerprint just before
+ * the cached offset still matches what's currently on disk), otherwise doing a full rescan
+ * from byte 0. The fingerprint check is what catches a transcript truncated and replaced with
+ * unrelated content that then grew past its original cached size — size/mtime alone cannot.
+ * Always persists the new offset + state + fingerprint for next time (best-effort, never
+ * fatal). Missing transcript -> the caller's `initialState()`, matching the old
+ * always-full-rescan behavior's fail-open result for that case.
+ * @param {string} transcriptPath
+ * @param {string} cacheKey - identifies which hook this cache belongs to (e.g.
+ *   "effort-gate", "stop-reminder") — the same transcript is scanned by multiple hooks with
+ *   independent accumulator shapes, so each needs its own cache.
+ * @param {() => object} initialState - factory for a fresh accumulator (called on a full
+ *   rescan / cache miss — a fresh object each time, never shared/mutated across calls).
+ * @param {(state: object, line: string) => object} foldLine - folds ONE raw JSONL line into
+ *   `state` (mutate-and-return is fine); must have no cross-line lookback beyond `state`
+ *   itself, so resuming partway through is equivalent to having scanned from the start.
+ * @returns {object} the derived state, fully caught up with the transcript's current
+ *   contents — identical to what a full rescan from byte 0 would produce.
+ */
+export function getIncrementalState(transcriptPath, cacheKey, initialState, foldLine) {
+  let stat;
+  try {
+    stat = fs.statSync(transcriptPath);
+  } catch {
+    return initialState(); // missing transcript -> fail open, same as a full-rescan miss
+  }
+
+  const cacheFp = cacheFilePath(transcriptPath, cacheKey);
+  const cache = readCache(cacheFp, transcriptPath);
+  const sizeAndTimeOk =
+    cache !== null &&
+    cache.size <= stat.size &&
+    cache.offset <= stat.size &&
+    cache.mtimeMs <= stat.mtimeMs;
+  const canResume =
+    sizeAndTimeOk && fingerprintBefore(transcriptPath, cache.offset) === cache.fingerprint;
+
+  const startState = canResume ? cache.state : initialState();
+  const startOffset = canResume ? cache.offset : 0;
+
+  const { offset, state } = scanFromOffset(transcriptPath, startOffset, startState, foldLine);
+
+  writeCache(cacheFp, {
+    transcriptPath,
+    size: stat.size,
+    mtimeMs: stat.mtimeMs,
+    offset,
+    fingerprint: fingerprintBefore(transcriptPath, offset),
+    state
+  });
+
+  return state;
+}

package/src/hooks/compact-mcp-output.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// PostToolUse hook (matcher: mcp__.*) shipped by create-obsidian-memory — the vkm-kit
+// token-saver (ADR-0043), MCP flavor. Pretty-printed JSON responses from MCP servers waste
+// input tokens on pure indentation; this hook re-serializes any text block that parses as
+// JSON into its compact form. STRICTLY whitespace-level: the parsed value is re-emitted
+// unchanged (same keys, same order as JSON.parse preserves, same data), so security
+// envelopes like the vault's `_trust` field survive byte-comparable at the semantic level.
+// Non-JSON text, small payloads, and anything that fails to parse are left untouched; any
+// internal failure fails open (prints nothing → Claude Code keeps the original).
+//
+// Kill switch: set VKM_TOKEN_SAVER=0 to disable without uninstalling.
+import fs from "node:fs";
+import { pathToFileURL } from "node:url";
+
+/** Below this many saved characters the hook stays silent. */
+const MIN_SAVED_CHARS = 200;
+
+/**
+ * Compact one text payload IFF it parses as JSON; returns null when unchanged/not JSON.
+ * @param {string} text
+ */
+export function compactJsonText(text) {
+  if (typeof text !== "string") return null;
+  const trimmed = text.trim();
+  if (!trimmed || (trimmed[0] !== "{" && trimmed[0] !== "[")) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  const compact = JSON.stringify(parsed);
+  return text.length - compact.length >= MIN_SAVED_CHARS ? compact : null;
+}
+
+/**
+ * Compact an MCP `tool_response`, preserving its shape: a bare string is compacted
+ * directly; an object with a `content` array gets each `{type:"text", text}` block
+ * compacted in place (other block types and fields pass through verbatim). Returns null
+ * when nothing changed.
+ * @param {unknown} toolResponse
+ */
+export function compactMcpResponse(toolResponse) {
+  if (typeof toolResponse === "string") return compactJsonText(toolResponse);
+  if (!toolResponse || typeof toolResponse !== "object" || Array.isArray(toolResponse)) {
+    return null;
+  }
+  if (!Array.isArray(toolResponse.content)) return null;
+  let changed = false;
+  const content = toolResponse.content.map((block) => {
+    if (block && typeof block === "object" && block.type === "text") {
+      const compact = compactJsonText(block.text);
+      if (compact !== null) {
+        changed = true;
+        return { ...block, text: compact };
+      }
+    }
+    return block;
+  });
+  return changed ? { ...toolResponse, content } : null;
+}
+
+function main() {
+  if (process.env.VKM_TOKEN_SAVER === "0") return;
+  let payload;
+  try {
+    payload = JSON.parse(fs.readFileSync(0, "utf8"));
+  } catch {
+    return; // fail open
+  }
+  const updated = compactMcpResponse(payload?.tool_response);
+  if (updated === null || updated === undefined) return;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: "PostToolUse", updatedToolOutput: updated }
+    })
+  );
+}
+
+const isEntryPoint = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isEntryPoint) {
+  try {
+    main();
+  } catch {
+    // fail open — a hook crash must never break the tool call
+  }
+}

package/src/hooks/compact-tool-output.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// PostToolUse hook (matcher: Bash) shipped by create-obsidian-memory — the vkm-kit
+// token-saver (ADR-0043). Compacts noisy shell output BEFORE it enters Claude's context:
+// strips ANSI color/cursor codes, keeps only the final repaint of carriage-return progress
+// lines, collapses runs of identical lines, and windows very long logs to head+tail with an
+// elision marker — while HARD-GUARANTEEING that diagnostic lines (error/warn/fail/exception/
+// exit-code patterns) and the final lines of output always survive verbatim. Conservative by
+// design: small or already-clean outputs are left untouched (the hook prints nothing, and
+// Claude Code keeps the original), and ANY internal failure fails open the same way.
+//
+// Kill switch: set VKM_TOKEN_SAVER=0 to disable without uninstalling.
+//
+// stdin:  PostToolUse JSON ({ tool_name, tool_input, tool_response, ... }).
+// stdout: { hookSpecificOutput: { hookEventName: "PostToolUse", updatedToolOutput } } —
+//         same TYPE as the incoming tool_response (string in → string out; object in →
+//         object out with its text fields compacted, other fields preserved verbatim), so a
+//         schema mismatch can never corrupt the tool result (Claude Code ignores values that
+//         don't match the tool's output schema).
+import fs from "node:fs";
+import { pathToFileURL } from "node:url";
+
+/** Diagnostic lines that must NEVER be dropped, whatever else gets compacted. Note the
+ * punctuation-ending alternatives (`err!`, `npm ERR!`) sit OUTSIDE the trailing `\b` group —
+ * `!` followed by a space is not a word boundary — and `\w*` before `error|exception`
+ * catches joined names like `TypeError` / `HttpException`. */
+export const MUST_KEEP_RE =
+  /\b\w*(?:error|exception)s?\b|\berr!|npm ERR!|\b(?:warn|warning|fail|failed|failure|fatal|panic|traceback|assert|denied|refused|timeout|timed out|exit code|exited with)\b|✖|✗|⨯/i;
+
+/** ANSI CSI/OSC escape sequences (colors, cursor movement, titles). */
+const ANSI_RE = new RegExp(
+  // eslint-disable-next-line no-control-regex
+  "[\\u001b\\u009b](?:\\[[0-9;?]*[ -/]*[@-~]|\\][^\\u0007\\u001b]*(?:\\u0007|\\u001b\\\\))",
+  "g"
+);
+
+const DEFAULTS = {
+  /** Outputs at or under this many lines (after cleaning) are never windowed. */
+  maxLines: 200,
+  /** Head/tail window sizes when windowing kicks in. */
+  headLines: 120,
+  tailLines: 60,
+  /** Identical-line runs longer than this collapse to one line + a repeat marker. */
+  repeatThreshold: 3,
+  /** Cap on rescued diagnostic lines re-inserted from an elided middle section. */
+  maxRescued: 40,
+  /** Below this many saved characters the hook stays silent (not worth a rewrite). */
+  minSavedChars: 500
+};
+
+/**
+ * Pure compaction: returns `{ text, changed, stats }`. Never throws on string input.
+ * @param {string} input
+ * @param {Partial<typeof DEFAULTS>} [opts]
+ */
+export function compactText(input, opts = {}) {
+  const cfg = { ...DEFAULTS, ...opts };
+  const original = String(input ?? "");
+  if (!original) return { text: original, changed: false, stats: null };
+
+  // 1. ANSI escapes out; progress repaints: a physical line that was redrawn with `\r`
+  //    only ever shows its final segment in a terminal — keep exactly that.
+  const cleaned = original
+    .replace(ANSI_RE, "")
+    .split("\n")
+    .map((line) => {
+      const i = line.lastIndexOf("\r");
+      return i >= 0 ? line.slice(i + 1) : line;
+    });
+
+  // 2. Collapse runs of identical (trimmed-equal) lines.
+  const collapsed = [];
+  let run = 0;
+  for (let i = 0; i < cleaned.length; i++) {
+    const line = cleaned[i];
+    if (i > 0 && line.trim() === cleaned[i - 1].trim()) {
+      run += 1;
+      continue;
+    }
+    if (run >= cfg.repeatThreshold) {
+      collapsed.push(`  [... repeated ${run} more times]`);
+    } else {
+      for (let r = 0; r < run; r++) collapsed.push(cleaned[i - 1]);
+    }
+    run = 0;
+    collapsed.push(line);
+  }
+  if (run >= cfg.repeatThreshold) collapsed.push(`  [... repeated ${run} more times]`);
+  else for (let r = 0; r < run; r++) collapsed.push(cleaned[cleaned.length - 1]);
+
+  // 3. Head+tail windowing, rescuing diagnostic lines from the elided middle.
+  let windowed = collapsed;
+  if (collapsed.length > cfg.maxLines) {
+    const head = collapsed.slice(0, cfg.headLines);
+    const tail = collapsed.slice(-cfg.tailLines);
+    const middle = collapsed.slice(cfg.headLines, -cfg.tailLines);
+    const rescued = middle.filter((l) => MUST_KEEP_RE.test(l)).slice(0, cfg.maxRescued);
+    const elided = middle.length - rescued.length;
+    windowed = [
+      ...head,
+      `[vkm token-saver: ${elided} low-signal lines elided; ${rescued.length} diagnostic lines preserved below]`,
+      ...rescued,
+      ...tail
+    ];
+  }
+
+  const text = windowed.join("\n");
+  const saved = original.length - text.length;
+  if (saved < cfg.minSavedChars) {
+    return { text: original, changed: false, stats: null };
+  }
+  const stats = {
+    fromChars: original.length,
+    toChars: text.length,
+    fromLines: cleaned.length,
+    toLines: windowed.length
+  };
+  return {
+    text: `${text}\n[vkm token-saver: compacted ${stats.fromChars}→${stats.toChars} chars (${stats.fromLines}→${stats.toLines} lines); diagnostics preserved]`,
+    changed: true,
+    stats
+  };
+}
+
+/**
+ * Compact a PostToolUse `tool_response`, preserving its shape: strings are compacted
+ * directly; plain objects get their known text-bearing fields (`stdout`, `stderr`,
+ * `output`, `text`) compacted and every other field passed through verbatim. Returns
+ * `null` when nothing changed enough to be worth a rewrite.
+ * @param {unknown} toolResponse
+ */
+export function compactToolResponse(toolResponse) {
+  if (typeof toolResponse === "string") {
+    const { text, changed } = compactText(toolResponse);
+    return changed ? text : null;
+  }
+  if (toolResponse && typeof toolResponse === "object" && !Array.isArray(toolResponse)) {
+    const out = { ...toolResponse };
+    let changed = false;
+    for (const field of ["stdout", "stderr", "output", "text"]) {
+      if (typeof out[field] === "string") {
+        const result = compactText(out[field]);
+        if (result.changed) {
+          out[field] = result.text;
+          changed = true;
+        }
+      }
+    }
+    return changed ? out : null;
+  }
+  return null;
+}
+
+function main() {
+  if (process.env.VKM_TOKEN_SAVER === "0") return;
+  let payload;
+  try {
+    payload = JSON.parse(fs.readFileSync(0, "utf8"));
+  } catch {
+    return; // fail open: unreadable stdin → leave the tool output untouched
+  }
+  const updated = compactToolResponse(payload?.tool_response);
+  if (updated === null || updated === undefined) return;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: "PostToolUse", updatedToolOutput: updated }
+    })
+  );
+}
+
+const isEntryPoint = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isEntryPoint) {
+  try {
+    main();
+  } catch {
+    // fail open — a hook crash must never break the tool call
+  }
+}

package/src/hooks/ensure-otel-sink.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// SessionStart hook shipped by create-obsidian-memory (ADR-0044): guarantees the vkm-kit
+// OTLP telemetry sink is alive whenever a Claude Code session starts, with no OS service or
+// scheduled task. Checks the sink lockfile (pid liveness) and, when absent/stale, spawns
+// `vkm-otel-sink` detached and exits immediately — the fast path is a single stat+kill(0)
+// well under 50ms. Fail-open: ANY error exits 0 silently (a telemetry hiccup must never
+// block a session). argv: node <hook> <sink-script-path>.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+function dataDir() {
+  return process.env.VKM_TELEMETRY_DIR || path.join(os.homedir(), ".vkm", "telemetry");
+}
+
+/** True if a live sink already holds the lock. */
+export function sinkAlive(dir = dataDir()) {
+  try {
+    const lock = JSON.parse(fs.readFileSync(path.join(dir, "sink.lock"), "utf8"));
+    process.kill(lock.pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function main() {
+  const sinkScript = process.argv[2];
+  if (!sinkScript || sinkAlive()) return;
+  try {
+    const child = spawn(process.execPath, [sinkScript], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true
+    });
+    child.unref();
+  } catch {
+    // fail open
+  }
+}
+
+const isEntryPoint = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isEntryPoint) {
+  try {
+    main();
+  } catch {
+    // fail open — never block a session over telemetry
+  }
+}