@vpxa/kb 0.1.1

package/packages/tools/dist/replay.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Replay — append-only audit trail of tool/CLI invocations.
+ *
+ * Captures tool name, arguments (redacted), duration, and result summary
+ * to `.kb-state/replay.jsonl`. Used by `kb replay` CLI, `kb_replay_list` MCP,
+ * and the TUI log panel.
+ */
+export interface ReplayEntry {
+    /** ISO timestamp */
+    ts: string;
+    /** Source: 'mcp' | 'cli' */
+    source: 'mcp' | 'cli';
+    /** Tool or command name */
+    tool: string;
+    /** Redacted input summary (first 200 chars of JSON) */
+    input: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Result status */
+    status: 'ok' | 'error';
+    /** Short result summary (first 200 chars) */
+    output: string;
+}
+export interface ReplayOptions {
+    /** Max entries to return (default: 20) */
+    last?: number;
+    /** Filter by tool name */
+    tool?: string;
+    /** Filter by source */
+    source?: 'mcp' | 'cli';
+    /** Filter entries after this ISO timestamp */
+    since?: string;
+}
+/**
+ * Append a replay entry to the audit log.
+ * Creates the `.kb-state/` directory if it doesn't exist.
+ */
+export declare function replayAppend(entry: ReplayEntry): void;
+/**
+ * Read replay entries with optional filters.
+ */
+export declare function replayList(opts?: ReplayOptions): ReplayEntry[];
+/**
+ * Trim the replay log to MAX_ENTRIES, keeping the most recent.
+ */
+export declare function replayTrim(): number;
+/**
+ * Clear the entire replay log.
+ */
+export declare function replayClear(): void;
+/**
+ * Helper: create a replay entry from a tool invocation.
+ * Use as a wrapper around tool execution.
+ */
+export declare function replayCapture(source: 'mcp' | 'cli', tool: string, input: unknown, fn: () => Promise<unknown>): Promise<unknown>;
+//# sourceMappingURL=replay.d.ts.map

package/packages/tools/dist/replay.js

@@ -0,0 +1,108 @@
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+const MAX_ENTRIES = 5e3;
+const SUMMARY_LEN = 200;
+function getReplayPath() {
+  return resolve(process.cwd(), ".kb-state", "replay.jsonl");
+}
+function truncate(s, maxLen) {
+  if (s.length <= maxLen) return s;
+  return `${s.slice(0, maxLen - 1)}\u2026`;
+}
+function replayAppend(entry) {
+  const p = getReplayPath();
+  mkdirSync(dirname(p), { recursive: true });
+  const safe = {
+    ...entry,
+    input: truncate(entry.input, SUMMARY_LEN),
+    output: truncate(entry.output, SUMMARY_LEN)
+  };
+  appendFileSync(p, `${JSON.stringify(safe)}
+`, "utf-8");
+}
+function replayList(opts = {}) {
+  const p = getReplayPath();
+  let raw;
+  try {
+    raw = readFileSync(p, "utf-8");
+  } catch {
+    return [];
+  }
+  const lines = raw.trim().split("\n").filter(Boolean);
+  let entries = [];
+  for (const line of lines) {
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  if (opts.tool) {
+    entries = entries.filter((e) => e.tool === opts.tool);
+  }
+  if (opts.source) {
+    entries = entries.filter((e) => e.source === opts.source);
+  }
+  if (opts.since) {
+    const since = opts.since;
+    entries = entries.filter((e) => e.ts >= since);
+  }
+  const last = opts.last ?? 20;
+  return entries.slice(-last);
+}
+function replayTrim() {
+  const p = getReplayPath();
+  let raw;
+  try {
+    raw = readFileSync(p, "utf-8");
+  } catch {
+    return 0;
+  }
+  const lines = raw.trim().split("\n").filter(Boolean);
+  if (lines.length <= MAX_ENTRIES) return 0;
+  const trimmed = lines.length - MAX_ENTRIES;
+  const kept = lines.slice(-MAX_ENTRIES);
+  writeFileSync(p, `${kept.join("\n")}
+`, "utf-8");
+  return trimmed;
+}
+function replayClear() {
+  const p = getReplayPath();
+  try {
+    writeFileSync(p, "", "utf-8");
+  } catch {
+  }
+}
+function replayCapture(source, tool, input, fn) {
+  const start = Date.now();
+  return fn().then((result) => {
+    replayAppend({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      source,
+      tool,
+      input: typeof input === "string" ? input : JSON.stringify(input),
+      durationMs: Date.now() - start,
+      status: "ok",
+      output: typeof result === "string" ? result : JSON.stringify(result ?? "")
+    });
+    return result;
+  }).catch((err) => {
+    replayAppend({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      source,
+      tool,
+      input: typeof input === "string" ? input : JSON.stringify(input),
+      durationMs: Date.now() - start,
+      status: "error",
+      output: err instanceof Error ? err.message : String(err)
+    });
+    throw err;
+  });
+}
+export {
+  replayAppend,
+  replayCapture,
+  replayClear,
+  replayList,
+  replayTrim
+};
+//# sourceMappingURL=replay.js.map

package/packages/tools/dist/schema-validate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * kb_schema_validate — Validate data against a JSON Schema (core subset).
+ *
+ * Supports: type, required, properties, additionalProperties, items,
+ * enum, const, pattern, minimum, maximum, minLength, maxLength,
+ * minItems, maxItems.
+ */
+export interface SchemaValidateOptions {
+    data: unknown;
+    schema: Record<string, unknown>;
+}
+export interface ValidationError {
+    path: string;
+    message: string;
+    expected?: string;
+    received?: string;
+}
+export interface SchemaValidateResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+export declare function schemaValidate(options: SchemaValidateOptions): SchemaValidateResult;
+//# sourceMappingURL=schema-validate.d.ts.map

package/packages/tools/dist/schema-validate.js

@@ -0,0 +1,141 @@
+function schemaValidate(options) {
+  const errors = [];
+  validateNode(options.data, options.schema, "$", errors);
+  return { valid: errors.length === 0, errors };
+}
+function validateNode(data, schema, path, errors) {
+  if ("type" in schema) {
+    const expected = schema.type;
+    if (!checkType(data, expected)) {
+      errors.push({
+        path,
+        message: `Expected type "${expected}"`,
+        expected,
+        received: getType(data)
+      });
+      return;
+    }
+  }
+  if ("enum" in schema) {
+    const allowed = schema.enum;
+    if (!allowed.some((v) => JSON.stringify(v) === JSON.stringify(data))) {
+      errors.push({
+        path,
+        message: `Must be one of: ${JSON.stringify(allowed)}`,
+        received: JSON.stringify(data)
+      });
+    }
+  }
+  if ("const" in schema) {
+    if (JSON.stringify(data) !== JSON.stringify(schema.const)) {
+      errors.push({
+        path,
+        message: `Must equal ${JSON.stringify(schema.const)}`,
+        received: JSON.stringify(data)
+      });
+    }
+  }
+  if (typeof data === "string") {
+    if ("minLength" in schema && data.length < schema.minLength) {
+      errors.push({
+        path,
+        message: `String too short (min: ${schema.minLength})`,
+        received: `length ${data.length}`
+      });
+    }
+    if ("maxLength" in schema && data.length > schema.maxLength) {
+      errors.push({
+        path,
+        message: `String too long (max: ${schema.maxLength})`,
+        received: `length ${data.length}`
+      });
+    }
+    if ("pattern" in schema && !new RegExp(schema.pattern).test(data)) {
+      errors.push({ path, message: `Does not match pattern: ${schema.pattern}` });
+    }
+  }
+  if (typeof data === "number") {
+    if ("minimum" in schema && data < schema.minimum) {
+      errors.push({ path, message: `Below minimum (${schema.minimum})`, received: String(data) });
+    }
+    if ("maximum" in schema && data > schema.maximum) {
+      errors.push({ path, message: `Above maximum (${schema.maximum})`, received: String(data) });
+    }
+  }
+  if (Array.isArray(data)) {
+    if ("minItems" in schema && data.length < schema.minItems) {
+      errors.push({
+        path,
+        message: `Too few items (min: ${schema.minItems})`,
+        received: `length ${data.length}`
+      });
+    }
+    if ("maxItems" in schema && data.length > schema.maxItems) {
+      errors.push({
+        path,
+        message: `Too many items (max: ${schema.maxItems})`,
+        received: `length ${data.length}`
+      });
+    }
+    if ("items" in schema) {
+      for (let i = 0; i < data.length; i++) {
+        validateNode(data[i], schema.items, `${path}[${i}]`, errors);
+      }
+    }
+  }
+  if (data && typeof data === "object" && !Array.isArray(data)) {
+    const obj = data;
+    if ("required" in schema) {
+      for (const key of schema.required) {
+        if (!(key in obj)) {
+          errors.push({ path: `${path}.${key}`, message: "Required property missing" });
+        }
+      }
+    }
+    if ("properties" in schema) {
+      const props = schema.properties;
+      for (const [key, propSchema] of Object.entries(props)) {
+        if (key in obj) {
+          validateNode(obj[key], propSchema, `${path}.${key}`, errors);
+        }
+      }
+    }
+    if ("additionalProperties" in schema && schema.additionalProperties === false) {
+      const defined = Object.keys(schema.properties ?? {});
+      for (const key of Object.keys(obj)) {
+        if (!defined.includes(key)) {
+          errors.push({ path: `${path}.${key}`, message: "Additional property not allowed" });
+        }
+      }
+    }
+  }
+}
+function checkType(data, type) {
+  switch (type) {
+    case "string":
+      return typeof data === "string";
+    case "number":
+      return typeof data === "number" && !Number.isNaN(data);
+    case "integer":
+      return typeof data === "number" && Number.isInteger(data);
+    case "boolean":
+      return typeof data === "boolean";
+    case "null":
+      return data === null;
+    case "array":
+      return Array.isArray(data);
+    case "object":
+      return data !== null && typeof data === "object" && !Array.isArray(data);
+    default:
+      return true;
+  }
+}
+function getType(data) {
+  if (data === null) return "null";
+  if (Array.isArray(data)) return "array";
+  return typeof data;
+}
+export {
+  schemaValidate
+};
+//# sourceMappingURL=schema-validate.js.map

package/packages/tools/dist/scope-map.d.ts

@@ -0,0 +1,52 @@
+/**
+ * kb_scope_map — Task-scoped reading plan generator.
+ *
+ * Given a task description, searches the KB to identify which files
+ * and sections are relevant, then produces a prioritized reading plan
+ * with estimated token counts.
+ */
+import type { IEmbedder } from '@kb/embeddings';
+import type { IKnowledgeStore } from '@kb/store';
+export interface ScopeMapOptions {
+    /** Description of the task to scope */
+    task: string;
+    /** Maximum number of files to include (default: 15) */
+    maxFiles?: number;
+    /** Group results by directory (default: true) */
+    groupByDirectory?: boolean;
+    /** Filter by content type */
+    contentType?: string;
+    /** Filter by origin */
+    origin?: string;
+}
+export interface ScopeMapEntry {
+    /** File path */
+    path: string;
+    /** Why this file is relevant (derived from matched chunks) */
+    reason: string;
+    /** Estimated token count (chars / 4 approximation) */
+    estimatedTokens: number;
+    /** Relevance score (0-1) */
+    relevance: number;
+    /** Line ranges to focus on */
+    focusRanges: Array<{
+        start: number;
+        end: number;
+        heading?: string;
+    }>;
+}
+export interface ScopeMapResult {
+    /** The task that was analyzed */
+    task: string;
+    /** Prioritized file list */
+    files: ScopeMapEntry[];
+    /** Total estimated tokens across all files */
+    totalEstimatedTokens: number;
+    /** Suggested reading order (file paths) */
+    readingOrder: string[];
+}
+/**
+ * Generate a task-scoped reading plan.
+ */
+export declare function scopeMap(embedder: IEmbedder, store: IKnowledgeStore, options: ScopeMapOptions): Promise<ScopeMapResult>;
+//# sourceMappingURL=scope-map.d.ts.map

package/packages/tools/dist/scope-map.js

@@ -0,0 +1,72 @@
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+async function scopeMap(embedder, store, options) {
+  const { task, maxFiles = 15, contentType, origin } = options;
+  const queryVector = await embedder.embed(task);
+  const searchOpts = {
+    limit: maxFiles * 3,
+    // Over-fetch to group by file
+    contentType,
+    origin
+  };
+  const results = await store.search(queryVector, searchOpts);
+  const fileMap = /* @__PURE__ */ new Map();
+  for (const result of results) {
+    const path = result.record.sourcePath;
+    const existing = fileMap.get(path);
+    if (existing) {
+      existing.chunks.push(result);
+      existing.totalChars += result.record.content.length;
+      existing.maxScore = Math.max(existing.maxScore, result.score);
+    } else {
+      fileMap.set(path, {
+        chunks: [result],
+        totalChars: result.record.content.length,
+        maxScore: result.score
+      });
+    }
+  }
+  const entries = [...fileMap.entries()].sort(([, a], [, b]) => b.maxScore - a.maxScore).slice(0, maxFiles).map(([path, { chunks, maxScore }]) => {
+    const focusRanges = chunks.sort((a, b) => a.record.startLine - b.record.startLine).map((c) => ({
+      start: c.record.startLine,
+      end: c.record.endLine,
+      heading: c.record.headingPath
+    }));
+    const topChunk = chunks.sort((a, b) => b.score - a.score)[0];
+    const reason = topChunk.record.headingPath ? `Matches: ${topChunk.record.headingPath}` : `Contains relevant ${topChunk.record.contentType} content`;
+    return {
+      path,
+      reason,
+      estimatedTokens: 0,
+      // computed below from actual content
+      relevance: maxScore,
+      focusRanges
+    };
+  });
+  for (const entry of entries) {
+    const fileChunks = fileMap.get(entry.path);
+    if (fileChunks) {
+      entry.estimatedTokens = estimateTokens(
+        fileChunks.chunks.map((c) => c.record.content).join("")
+      );
+    }
+  }
+  const totalEstimatedTokens = entries.reduce((sum, e) => sum + e.estimatedTokens, 0);
+  const readingOrder = [...entries].sort((a, b) => {
+    const aIsConfig = a.path.includes("config") || a.path.includes("types") ? -1 : 0;
+    const bIsConfig = b.path.includes("config") || b.path.includes("types") ? -1 : 0;
+    if (aIsConfig !== bIsConfig) return aIsConfig - bIsConfig;
+    return b.relevance - a.relevance;
+  }).map((e) => e.path);
+  return {
+    task,
+    files: entries,
+    totalEstimatedTokens,
+    readingOrder
+  };
+}
+export {
+  scopeMap
+};
+//# sourceMappingURL=scope-map.js.map

package/packages/tools/dist/snippet.d.ts

@@ -0,0 +1,34 @@
+/**
+ * kb_snippet — Persistent code template storage with search.
+ */
+export interface Snippet {
+    name: string;
+    language: string;
+    code: string;
+    tags: string[];
+    created: string;
+    updated: string;
+}
+export type SnippetAction = 'save' | 'get' | 'list' | 'search' | 'delete';
+export interface SnippetOptions {
+    action: SnippetAction;
+    name?: string;
+    language?: string;
+    code?: string;
+    tags?: string[];
+    query?: string;
+}
+export type SnippetResult = Snippet | {
+    snippets: SnippetSummary[];
+} | {
+    deleted: boolean;
+};
+interface SnippetSummary {
+    name: string;
+    language: string;
+    tags: string[];
+    updated: string;
+}
+export declare function snippet(options: SnippetOptions): SnippetResult;
+export {};
+//# sourceMappingURL=snippet.d.ts.map

package/packages/tools/dist/snippet.js

@@ -0,0 +1,80 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { join } from "node:path";
+const SNIPPETS_DIR = () => join(process.cwd(), ".kb-state", "snippets");
+function ensureDir() {
+  const dir = SNIPPETS_DIR();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+function safeName(name) {
+  const safe = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+  if (!safe) throw new Error("Invalid snippet name");
+  return safe;
+}
+function snippet(options) {
+  switch (options.action) {
+    case "save": {
+      if (!options.name || !options.code) throw new Error("name and code required for save");
+      const dir = ensureDir();
+      const name = safeName(options.name);
+      const filePath = join(dir, `${name}.json`);
+      const existing = existsSync(filePath) ? JSON.parse(readFileSync(filePath, "utf8")) : null;
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const entry = {
+        name: options.name,
+        language: options.language ?? "text",
+        code: options.code,
+        tags: options.tags ?? [],
+        created: existing?.created ?? now,
+        updated: now
+      };
+      writeFileSync(filePath, JSON.stringify(entry, null, 2));
+      return entry;
+    }
+    case "get": {
+      if (!options.name) throw new Error("name required for get");
+      const filePath = join(SNIPPETS_DIR(), `${safeName(options.name)}.json`);
+      if (!existsSync(filePath)) throw new Error(`Snippet not found: ${options.name}`);
+      return JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    case "list": {
+      const dir = ensureDir();
+      const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+      const snippets = files.map((f) => {
+        const data = JSON.parse(readFileSync(join(dir, f), "utf8"));
+        return { name: data.name, language: data.language, tags: data.tags, updated: data.updated };
+      });
+      return { snippets };
+    }
+    case "search": {
+      if (!options.query) throw new Error("query required for search");
+      const q = options.query.toLowerCase();
+      const dir = ensureDir();
+      const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+      const snippets = files.map((f) => JSON.parse(readFileSync(join(dir, f), "utf8"))).filter(
+        (s) => s.name.toLowerCase().includes(q) || s.tags.some((t) => t.toLowerCase().includes(q)) || s.language.toLowerCase().includes(q) || s.code.toLowerCase().includes(q)
+      ).map((s) => ({ name: s.name, language: s.language, tags: s.tags, updated: s.updated }));
+      return { snippets };
+    }
+    case "delete": {
+      if (!options.name) throw new Error("name required for delete");
+      const filePath = join(SNIPPETS_DIR(), `${safeName(options.name)}.json`);
+      if (!existsSync(filePath)) return { deleted: false };
+      unlinkSync(filePath);
+      return { deleted: true };
+    }
+    default:
+      throw new Error(`Unknown action: ${options.action}`);
+  }
+}
+export {
+  snippet
+};
+//# sourceMappingURL=snippet.js.map

package/packages/tools/dist/stash.d.ts

@@ -0,0 +1,12 @@
+export interface StashEntry {
+    key: string;
+    value: unknown;
+    type: string;
+    storedAt: string;
+}
+export declare function stashSet(key: string, value: unknown, cwd?: string): StashEntry;
+export declare function stashGet(key: string, cwd?: string): StashEntry | undefined;
+export declare function stashList(cwd?: string): StashEntry[];
+export declare function stashDelete(key: string, cwd?: string): boolean;
+export declare function stashClear(cwd?: string): number;
+//# sourceMappingURL=stash.d.ts.map

package/packages/tools/dist/stash.js

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+const STASH_DIR = ".kb-state";
+const STASH_FILE = "stash.json";
+function stashPath(cwd) {
+  const root = cwd ?? process.cwd();
+  return resolve(root, STASH_DIR, STASH_FILE);
+}
+function loadStash(cwd) {
+  const path = stashPath(cwd);
+  if (!existsSync(path)) return {};
+  const raw = readFileSync(path, "utf-8");
+  return JSON.parse(raw);
+}
+function saveStash(data, cwd) {
+  const path = stashPath(cwd);
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}
+`, "utf-8");
+}
+function stashSet(key, value, cwd) {
+  const stash = loadStash(cwd);
+  const entry = {
+    key,
+    value,
+    type: typeof value,
+    storedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  stash[key] = entry;
+  saveStash(stash, cwd);
+  return entry;
+}
+function stashGet(key, cwd) {
+  return loadStash(cwd)[key];
+}
+function stashList(cwd) {
+  return Object.values(loadStash(cwd));
+}
+function stashDelete(key, cwd) {
+  const stash = loadStash(cwd);
+  if (!(key in stash)) return false;
+  delete stash[key];
+  saveStash(stash, cwd);
+  return true;
+}
+function stashClear(cwd) {
+  const stash = loadStash(cwd);
+  const count = Object.keys(stash).length;
+  saveStash({}, cwd);
+  return count;
+}
+export {
+  stashClear,
+  stashDelete,
+  stashGet,
+  stashList,
+  stashSet
+};
+//# sourceMappingURL=stash.js.map

package/packages/tools/dist/stratum-card.d.ts

@@ -0,0 +1,31 @@
+/**
+ * kb_stratum_card — STRATUM T1/T2 context card generator.
+ *
+ * Generates compact context cards from files. T1 = structural metadata only
+ * (~100 tokens/file). T2 = T1 + compressed content (~300 tokens/file).
+ * Uses file-summary for structure and embedder for T2 content scoring.
+ */
+import type { IEmbedder } from '@kb/embeddings';
+export interface StratumCardOptions {
+    files: string[];
+    query: string;
+    tier?: 'T1' | 'T2';
+    maxContentChars?: number;
+}
+export interface StratumCard {
+    path: string;
+    tier: 'T1' | 'T2';
+    card: string;
+    unknowns: string[];
+    riskTier: 'low' | 'medium' | 'high';
+    tokenEstimate: number;
+    originalTokenEstimate: number;
+}
+export interface StratumCardResult {
+    cards: StratumCard[];
+    totalTokenEstimate: number;
+    totalOriginalTokenEstimate: number;
+    compressionRatio: number;
+}
+export declare function stratumCard(embedder: IEmbedder, options: StratumCardOptions): Promise<StratumCardResult>;
+//# sourceMappingURL=stratum-card.d.ts.map