@vpxa/kb 0.1.1

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

@@ -0,0 +1,203 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+const MAPS_DIR = ".kb-state";
+const MAPS_FILE = "evidence-maps.json";
+function mapsPath(cwd) {
+  const root = cwd ?? process.cwd();
+  return resolve(root, MAPS_DIR, MAPS_FILE);
+}
+function loadMaps(cwd) {
+  const path = mapsPath(cwd);
+  if (!existsSync(path)) return {};
+  const raw = readFileSync(path, "utf-8");
+  return JSON.parse(raw);
+}
+function saveMaps(data, cwd) {
+  const path = mapsPath(cwd);
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}
+`, "utf-8");
+}
+function requireMap(taskId, cwd) {
+  const maps = loadMaps(cwd);
+  const state = maps[taskId];
+  if (!state) {
+    throw new Error(`Evidence map not found: ${taskId}`);
+  }
+  return { maps, state };
+}
+function nextEntryId(entries) {
+  return entries.reduce((maxId, entry) => Math.max(maxId, entry.id), 0) + 1;
+}
+function validateClaim(claim) {
+  const trimmed = claim.trim();
+  if (!trimmed) {
+    throw new Error("Claim is required");
+  }
+  if (/\r?\n/.test(trimmed)) {
+    throw new Error("Claim must be a single line");
+  }
+  return trimmed;
+}
+function escapeTableCell(value) {
+  return (value ?? "").replace(/\r?\n/g, " ").replace(/\|/g, "\\|");
+}
+function formatEvidenceMap(state) {
+  const lines = [
+    "| # | Claim | Status | Receipt | Critical | Type |",
+    "|---|-------|--------|---------|----------|------|"
+  ];
+  for (const entry of state.entries) {
+    lines.push(
+      `| ${entry.id} | ${escapeTableCell(entry.claim)} | ${entry.status} | ${escapeTableCell(entry.receipt)} | ${entry.criticalPath ? "yes" : "no"} | ${escapeTableCell(entry.unknownType)} |`
+    );
+  }
+  return lines.join("\n");
+}
+function buildStats(entries) {
+  return {
+    total: entries.length,
+    verified: entries.filter((entry) => entry.status === "V").length,
+    assumed: entries.filter((entry) => entry.status === "A").length,
+    unresolved: entries.filter((entry) => entry.status === "U").length
+  };
+}
+function buildWarnings(state) {
+  const warnings = [];
+  for (const entry of state.entries) {
+    if (entry.status === "V" && entry.receipt.trim() === "") {
+      warnings.push("V entry without receipt");
+    }
+    if (entry.status === "A" && state.tier === "critical" && entry.unknownType === "contract") {
+      warnings.push("Assumed contract at Critical tier \u2014 should be Verified");
+    }
+  }
+  return warnings;
+}
+function buildForcedDeliveryAnnotation(entries) {
+  const unresolved = entries.filter((entry) => entry.status === "U");
+  const summary = unresolved.map((entry) => `#${entry.id} ${entry.claim}`).join("; ");
+  return `FORCED DELIVERY annotation: unresolved entries remain -> ${summary}`;
+}
+function evaluateGate(state, retryCount = 0) {
+  const unresolvedCritical = state.entries.filter(
+    (entry) => entry.criticalPath && entry.status === "U"
+  );
+  const warnings = buildWarnings(state);
+  const stats = buildStats(state.entries);
+  const unresolvedContract = unresolvedCritical.find((entry) => entry.unknownType === "contract");
+  if (unresolvedContract) {
+    return {
+      decision: "HARD_BLOCK",
+      reason: "Unresolved contract unknown on critical path",
+      unresolvedCritical,
+      warnings,
+      stats
+    };
+  }
+  if (unresolvedCritical.length > 0 && retryCount === 0) {
+    return {
+      decision: "HOLD",
+      reason: "Unresolved critical-path unknown \u2014 retry available",
+      unresolvedCritical,
+      warnings,
+      stats
+    };
+  }
+  if (unresolvedCritical.length > 0 && retryCount >= 1) {
+    return {
+      decision: "FORCED_DELIVERY",
+      reason: "Unresolved critical-path unknown after retry",
+      unresolvedCritical,
+      warnings,
+      stats,
+      annotation: buildForcedDeliveryAnnotation(state.entries)
+    };
+  }
+  return {
+    decision: "YIELD",
+    reason: "All critical-path claims satisfy gate rules",
+    unresolvedCritical: [],
+    warnings,
+    stats
+  };
+}
+function evidenceMap(action, cwd) {
+  switch (action.action) {
+    case "create": {
+      const maps = loadMaps(cwd);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const state = {
+        taskId: action.taskId,
+        tier: action.tier,
+        entries: [],
+        createdAt: now,
+        updatedAt: now
+      };
+      maps[action.taskId] = state;
+      saveMaps(maps, cwd);
+      return { state, formattedMap: formatEvidenceMap(state) };
+    }
+    case "add": {
+      const { maps, state } = requireMap(action.taskId, cwd);
+      const entry = {
+        id: nextEntryId(state.entries),
+        claim: validateClaim(action.claim),
+        status: action.status,
+        receipt: action.receipt,
+        criticalPath: action.criticalPath ?? false,
+        unknownType: action.unknownType
+      };
+      state.entries.push(entry);
+      state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      maps[action.taskId] = state;
+      saveMaps(maps, cwd);
+      return { state, entry, formattedMap: formatEvidenceMap(state) };
+    }
+    case "update": {
+      const { maps, state } = requireMap(action.taskId, cwd);
+      const entry = state.entries.find((candidate) => candidate.id === action.id);
+      if (!entry) {
+        throw new Error(`Evidence entry not found: ${action.id}`);
+      }
+      entry.status = action.status;
+      entry.receipt = action.receipt;
+      state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      maps[action.taskId] = state;
+      saveMaps(maps, cwd);
+      return { state, entry, formattedMap: formatEvidenceMap(state) };
+    }
+    case "get": {
+      const { state } = requireMap(action.taskId, cwd);
+      return { state, formattedMap: formatEvidenceMap(state) };
+    }
+    case "gate": {
+      const { state } = requireMap(action.taskId, cwd);
+      return {
+        state,
+        gate: evaluateGate(state, action.retryCount ?? 0),
+        formattedMap: formatEvidenceMap(state)
+      };
+    }
+    case "list": {
+      const states = Object.values(loadMaps(cwd)).sort(
+        (left, right) => left.createdAt.localeCompare(right.createdAt)
+      );
+      return { states };
+    }
+    case "delete": {
+      const maps = loadMaps(cwd);
+      if (!(action.taskId in maps)) {
+        return { deleted: false };
+      }
+      delete maps[action.taskId];
+      saveMaps(maps, cwd);
+      return { deleted: true };
+    }
+  }
+}
+export {
+  evidenceMap
+};
+//# sourceMappingURL=evidence-map.js.map

package/packages/tools/dist/file-summary.d.ts

@@ -0,0 +1,32 @@
+export interface FileSummaryOptions {
+    path: string;
+    previewLines?: number;
+}
+export interface FileSummaryResult {
+    path: string;
+    lines: number;
+    language: string;
+    imports: string[];
+    exports: string[];
+    functions: Array<{
+        name: string;
+        line: number;
+        exported: boolean;
+    }>;
+    classes: Array<{
+        name: string;
+        line: number;
+        exported: boolean;
+    }>;
+    interfaces: Array<{
+        name: string;
+        line: number;
+    }>;
+    types: Array<{
+        name: string;
+        line: number;
+    }>;
+    estimatedTokens: number;
+}
+export declare function fileSummary(options: FileSummaryOptions): Promise<FileSummaryResult>;
+//# sourceMappingURL=file-summary.d.ts.map

package/packages/tools/dist/file-summary.js

@@ -0,0 +1,106 @@
+import { readFile } from "node:fs/promises";
+async function fileSummary(options) {
+  const { path, previewLines: _previewLines = 3 } = options;
+  const content = await readFile(path, "utf-8");
+  const lines = content.split("\n");
+  const extension = path.split(".").pop() ?? "";
+  const imports = [];
+  const exports = [];
+  const functions = [];
+  const classes = [];
+  const interfaces = [];
+  const types = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const lineNumber = index + 1;
+    if (/^import\s+.+/.test(line)) {
+      imports.push(line.trim());
+      continue;
+    }
+    const exportedFunctionMatch = line.match(/^export\s+(?:async\s+)?function\s+(\w+)/);
+    if (exportedFunctionMatch) {
+      functions.push({ name: exportedFunctionMatch[1], line: lineNumber, exported: true });
+      exports.push(exportedFunctionMatch[1]);
+      continue;
+    }
+    const functionMatch = line.match(/^(?:async\s+)?function\s+(\w+)/);
+    if (functionMatch) {
+      functions.push({ name: functionMatch[1], line: lineNumber, exported: false });
+      continue;
+    }
+    const constFunctionMatch = line.match(/^(export\s+)?const\s+(\w+)\s*=.*(?:=>|\bfunction\b)/);
+    if (constFunctionMatch) {
+      const exported = Boolean(constFunctionMatch[1]);
+      functions.push({ name: constFunctionMatch[2], line: lineNumber, exported });
+      if (exported) exports.push(constFunctionMatch[2]);
+      continue;
+    }
+    const exportConstMatch = line.match(/^export\s+const\s+(\w+)\s*=/);
+    if (exportConstMatch) {
+      exports.push(exportConstMatch[1]);
+      continue;
+    }
+    const classMatch = line.match(/^(export\s+)?(?:abstract\s+)?class\s+(\w+)/);
+    if (classMatch) {
+      const exported = Boolean(classMatch[1]);
+      classes.push({ name: classMatch[2], line: lineNumber, exported });
+      if (exported) exports.push(classMatch[2]);
+      continue;
+    }
+    const interfaceMatch = line.match(/^(?:export\s+)?interface\s+(\w+)/);
+    if (interfaceMatch) {
+      interfaces.push({ name: interfaceMatch[1], line: lineNumber });
+      continue;
+    }
+    const typeMatch = line.match(/^(?:export\s+)?type\s+(\w+)/);
+    if (typeMatch) {
+      types.push({ name: typeMatch[1], line: lineNumber });
+      continue;
+    }
+    const reExportMatch = line.match(/^export\s+\{(.+)\}/);
+    if (reExportMatch) {
+      const names = reExportMatch[1].split(",").map(
+        (name) => name.trim().split(/\s+as\s+/).pop()?.trim() ?? ""
+      ).filter(Boolean);
+      exports.push(...names);
+    }
+  }
+  return {
+    path,
+    lines: lines.length,
+    language: detectLanguage(extension),
+    imports,
+    exports,
+    functions,
+    classes,
+    interfaces,
+    types,
+    estimatedTokens: Math.ceil(content.length / 4)
+  };
+}
+function detectLanguage(extension) {
+  const map = {
+    ts: "typescript",
+    tsx: "typescript-jsx",
+    js: "javascript",
+    jsx: "javascript-jsx",
+    py: "python",
+    rs: "rust",
+    go: "go",
+    java: "java",
+    rb: "ruby",
+    md: "markdown",
+    json: "json",
+    yaml: "yaml",
+    yml: "yaml",
+    css: "css",
+    html: "html",
+    sh: "shell",
+    bash: "shell"
+  };
+  return map[extension] ?? extension;
+}
+export {
+  fileSummary
+};
+//# sourceMappingURL=file-summary.js.map

package/packages/tools/dist/file-walk.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_TOOL_EXTENSIONS: string[];
+export declare function matchesGlobPattern(path: string, pattern: string): boolean;
+export declare function walkFiles(rootPath: string, extensions: string[], exclude: string[]): Promise<string[]>;
+//# sourceMappingURL=file-walk.d.ts.map

package/packages/tools/dist/file-walk.js

@@ -0,0 +1,75 @@
+import { readdir, stat } from "node:fs/promises";
+import { extname, join, relative } from "node:path";
+const DEFAULT_TOOL_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
+const DEFAULT_WALK_EXCLUDES = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+  ".turbo",
+  ".cache",
+  "cdk.out",
+  ".kb-state"
+]);
+function normalizePath(path) {
+  return path.replace(/\\/g, "/");
+}
+function escapeRegex(value) {
+  return value.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+}
+function matchesGlobPattern(path, pattern) {
+  const normalizedPath = normalizePath(path);
+  const normalizedPattern = normalizePath(pattern).trim();
+  if (!normalizedPattern) {
+    return false;
+  }
+  const regexSource = escapeRegex(normalizedPattern).replace(/\*\*/g, "::DOUBLE_STAR::").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(/::DOUBLE_STAR::/g, ".*");
+  const regex = new RegExp(`^${regexSource}$`);
+  return regex.test(normalizedPath);
+}
+function isExcluded(path, exclude, isDirectory) {
+  return exclude.some((pattern) => {
+    if (matchesGlobPattern(path, pattern)) {
+      return true;
+    }
+    if (isDirectory) {
+      return matchesGlobPattern(`${path}/`, pattern);
+    }
+    return false;
+  });
+}
+async function walkFiles(rootPath, extensions, exclude) {
+  const matchedFiles = [];
+  const normalizedExtensions = extensions.map((extension) => extension.toLowerCase());
+  async function visit(currentPath) {
+    const entries = await readdir(currentPath);
+    for (const entry of entries) {
+      if (DEFAULT_WALK_EXCLUDES.has(entry)) continue;
+      const absolutePath = join(currentPath, entry);
+      const entryStat = await stat(absolutePath);
+      const relativePath = normalizePath(relative(rootPath, absolutePath));
+      if (entryStat.isDirectory()) {
+        if (!isExcluded(relativePath, exclude, true)) {
+          await visit(absolutePath);
+        }
+        continue;
+      }
+      if (isExcluded(relativePath, exclude, false)) {
+        continue;
+      }
+      if (normalizedExtensions.includes(extname(entry).toLowerCase())) {
+        matchedFiles.push(absolutePath);
+      }
+    }
+  }
+  await visit(rootPath);
+  matchedFiles.sort((left, right) => left.localeCompare(right));
+  return matchedFiles;
+}
+export {
+  DEFAULT_TOOL_EXTENSIONS,
+  matchesGlobPattern,
+  walkFiles
+};
+//# sourceMappingURL=file-walk.js.map

package/packages/tools/dist/find-examples.d.ts

@@ -0,0 +1,25 @@
+import type { IEmbedder } from '@kb/embeddings';
+import type { IKnowledgeStore } from '@kb/store';
+export interface FindExamplesOptions {
+    /** Symbol or pattern to find examples of */
+    query: string;
+    /** Max examples to return (default: 5) */
+    limit?: number;
+    /** Filter by content type */
+    contentType?: string;
+}
+export interface Example {
+    path: string;
+    startLine: number;
+    endLine: number;
+    content: string;
+    relevance: number;
+    context: string;
+}
+export interface FindExamplesResult {
+    query: string;
+    examples: Example[];
+    totalFound: number;
+}
+export declare function findExamples(embedder: IEmbedder, store: IKnowledgeStore, options: FindExamplesOptions): Promise<FindExamplesResult>;
+//# sourceMappingURL=find-examples.d.ts.map

package/packages/tools/dist/find-examples.js

@@ -0,0 +1,48 @@
+async function findExamples(embedder, store, options) {
+  const { query, limit = 5, contentType } = options;
+  const usageQuery = `usage example of ${query}`;
+  const vector = await embedder.embed(usageQuery);
+  const results = await store.search(vector, {
+    limit: limit * 3,
+    contentType
+  });
+  const queryPattern = new RegExp(`\\b${escapeRegExp(query)}\\b`, "i");
+  const matching = results.filter((result) => queryPattern.test(result.record.content));
+  const examples = matching.map((result) => {
+    const content = result.record.content;
+    const isDefinition = /export\s+(?:async\s+)?(?:function|class|const|interface|type)\s/.test(
+      content
+    );
+    const isImport = /^\s*import\s/m.test(content);
+    const isTest = /(?:^|[\\/])(test|tests|__tests__|spec)(?:[\\/]|$)/i.test(result.record.sourcePath) || /\.(test|spec)\.[jt]sx?$/i.test(result.record.sourcePath);
+    let relevanceBoost = 0;
+    if (!isDefinition) relevanceBoost += 0.1;
+    if (!isImport) relevanceBoost += 0.05;
+    if (isTest) relevanceBoost += 0.05;
+    const lines = content.split("\n");
+    const matchLine = lines.findIndex((line) => queryPattern.test(line));
+    const contextStart = Math.max(0, matchLine - 2);
+    const contextEnd = Math.min(lines.length, matchLine + 5);
+    const context = lines.slice(contextStart, contextEnd).join("\n");
+    return {
+      path: result.record.sourcePath,
+      startLine: result.record.startLine,
+      endLine: result.record.endLine,
+      content: context || content.slice(0, 300),
+      relevance: Math.min(1, result.score + relevanceBoost),
+      context: isTest ? "test" : isDefinition ? "definition" : "usage"
+    };
+  }).sort((left, right) => right.relevance - left.relevance).slice(0, limit);
+  return {
+    query,
+    examples,
+    totalFound: matching.length
+  };
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export {
+  findExamples
+};
+//# sourceMappingURL=find-examples.js.map

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

@@ -0,0 +1,47 @@
+/**
+ * kb_find — Federated search across vector similarity, keyword (FTS), and file glob.
+ *
+ * Combines multiple search strategies in a single call, deduplicates,
+ * and returns unified results with source attribution.
+ */
+import type { IEmbedder } from '@kb/embeddings';
+import type { IKnowledgeStore } from '@kb/store';
+export interface FindOptions {
+    /** Semantic search query (optional) */
+    query?: string;
+    /** File glob pattern (optional) */
+    glob?: string;
+    /** Keyword/regex pattern for text search (optional) */
+    pattern?: string;
+    /** Max results per strategy (default: 10) */
+    limit?: number;
+    /** Filter by content type */
+    contentType?: string;
+    /** Working directory for glob resolution (default: cwd) */
+    cwd?: string;
+}
+export interface FindResult {
+    /** File path (relative to cwd) */
+    path: string;
+    /** How this result was found */
+    source: 'vector' | 'keyword' | 'glob' | 'pattern';
+    /** Relevance score (0-1 for vector/keyword, 1 for glob/pattern matches) */
+    score: number;
+    /** Line range if from KB search */
+    lineRange?: {
+        start: number;
+        end: number;
+    };
+    /** Content preview */
+    preview?: string;
+}
+export interface FindResults {
+    results: FindResult[];
+    strategies: string[];
+    totalFound: number;
+}
+/**
+ * Run federated search across multiple strategies.
+ */
+export declare function find(embedder: IEmbedder, store: IKnowledgeStore, options: FindOptions): Promise<FindResults>;
+//# sourceMappingURL=find.d.ts.map

package/packages/tools/dist/find.js

@@ -0,0 +1,120 @@
+async function find(embedder, store, options) {
+  const {
+    query,
+    glob: globPattern,
+    pattern,
+    limit = 10,
+    contentType,
+    cwd = process.cwd()
+  } = options;
+  const strategies = [];
+  const allResults = [];
+  const seen = /* @__PURE__ */ new Set();
+  if (query) {
+    strategies.push("vector");
+    const queryVector = await embedder.embed(query);
+    const searchOpts = { limit, contentType };
+    const vectorResults = await store.search(queryVector, searchOpts);
+    for (const r of vectorResults) {
+      const key = `${r.record.sourcePath}:${r.record.startLine}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        allResults.push({
+          path: r.record.sourcePath,
+          source: "vector",
+          score: r.score,
+          lineRange: { start: r.record.startLine, end: r.record.endLine },
+          preview: r.record.content.slice(0, 200)
+        });
+      }
+    }
+  }
+  if (query) {
+    strategies.push("keyword");
+    try {
+      const ftsResults = await store.ftsSearch(query, { limit, contentType });
+      for (const r of ftsResults) {
+        const key = `${r.record.sourcePath}:${r.record.startLine}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          allResults.push({
+            path: r.record.sourcePath,
+            source: "keyword",
+            score: r.score,
+            lineRange: { start: r.record.startLine, end: r.record.endLine },
+            preview: r.record.content.slice(0, 200)
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  if (globPattern) {
+    strategies.push("glob");
+    try {
+      const { globSync: nodeGlob } = await import("node:fs");
+      const files = nodeGlob(globPattern, { cwd });
+      const GLOB_EXCLUDES = /* @__PURE__ */ new Set([
+        "node_modules",
+        ".git",
+        "dist",
+        "build",
+        "coverage",
+        ".turbo",
+        ".cache",
+        "cdk.out",
+        ".kb-state",
+        ".kb-data"
+      ]);
+      const filtered = files.filter((f) => {
+        const segments = f.replace(/\\/g, "/").split("/");
+        return !segments.some((s) => GLOB_EXCLUDES.has(s));
+      });
+      for (const file of filtered.slice(0, limit)) {
+        const key = `glob:${file}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          allResults.push({
+            path: file,
+            source: "glob",
+            score: 1
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  if (pattern) {
+    strategies.push("pattern");
+    try {
+      const regex = new RegExp(pattern, "i");
+      const ftsResults = await store.ftsSearch(pattern, { limit: limit * 2, contentType });
+      for (const r of ftsResults) {
+        if (regex.test(r.record.content)) {
+          const key = `${r.record.sourcePath}:${r.record.startLine}`;
+          if (!seen.has(key)) {
+            seen.add(key);
+            allResults.push({
+              path: r.record.sourcePath,
+              source: "pattern",
+              score: r.score,
+              lineRange: { start: r.record.startLine, end: r.record.endLine },
+              preview: r.record.content.slice(0, 200)
+            });
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  allResults.sort((a, b) => b.score - a.score);
+  return {
+    results: allResults.slice(0, limit),
+    strategies,
+    totalFound: allResults.length
+  };
+}
+export {
+  find
+};
+//# sourceMappingURL=find.js.map