@vpxa/kb 0.1.1

package/packages/store/dist/store.interface.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Knowledge store abstraction — allows swapping vector DB backends.
+ */
+import type { IndexStats, KnowledgeRecord, SearchResult } from '@kb/core';
+/** Options for searching the store */
+export interface SearchOptions {
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Minimum similarity score (0-1) */
+    minScore?: number;
+    /** Filter by content type */
+    contentType?: string;
+    /** Filter by origin */
+    origin?: string;
+    /** Filter by category */
+    category?: string;
+    /** Filter by tags (any match) */
+    tags?: string[];
+}
+export interface IKnowledgeStore {
+    /** Initialize the store (create tables, etc.) */
+    initialize(): Promise<void>;
+    /** Add or update records with their embedding vectors */
+    upsert(records: KnowledgeRecord[], vectors: Float32Array[]): Promise<void>;
+    /** Search by vector similarity */
+    search(queryVector: Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Get a specific record by ID */
+    getById(id: string): Promise<KnowledgeRecord | null>;
+    /** Delete records by source path (used during re-indexing) */
+    deleteBySourcePath(sourcePath: string): Promise<number>;
+    /** Delete a specific record by ID */
+    deleteById(id: string): Promise<boolean>;
+    /** Get all records for a source path */
+    getBySourcePath(sourcePath: string): Promise<KnowledgeRecord[]>;
+    /** Get index statistics */
+    getStats(): Promise<IndexStats>;
+    /** List all unique source paths in the store */
+    listSourcePaths(): Promise<string[]>;
+    /** Create a full-text search index on the content column for keyword search */
+    createFtsIndex(): Promise<void>;
+    /** Full-text keyword search (requires FTS index) */
+    ftsSearch(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Drop the backing table entirely — used for hard resets (e.g. dimension changes) */
+    dropTable(): Promise<void>;
+    /** Close the store connection */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=store.interface.d.ts.map

package/packages/store/dist/store.interface.js

@@ -0,0 +1 @@
+//# sourceMappingURL=store.interface.js.map

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

@@ -0,0 +1,21 @@
+export interface BatchOperation {
+    /** Unique ID for this operation */
+    id: string;
+    /** Operation type */
+    type: string;
+    /** Arguments for the operation */
+    args: Record<string, unknown>;
+}
+export interface BatchResult {
+    id: string;
+    status: 'success' | 'error';
+    result?: unknown;
+    error?: string;
+    durationMs: number;
+}
+export interface BatchOptions {
+    /** Max concurrent operations (default: 4) */
+    concurrency?: number;
+}
+export declare function batch(operations: BatchOperation[], executor: (op: BatchOperation) => Promise<unknown>, options?: BatchOptions): Promise<BatchResult[]>;
+//# sourceMappingURL=batch.d.ts.map

package/packages/tools/dist/batch.js

@@ -0,0 +1,45 @@
+async function batch(operations, executor, options = {}) {
+  const concurrency = Math.max(1, options.concurrency ?? 4);
+  const results = [];
+  const pending = [...operations];
+  async function runOne(op) {
+    const start = Date.now();
+    try {
+      const result = await executor(op);
+      return {
+        id: op.id,
+        status: "success",
+        result,
+        durationMs: Date.now() - start
+      };
+    } catch (error) {
+      return {
+        id: op.id,
+        status: "error",
+        error: error instanceof Error ? error.message : String(error),
+        durationMs: Date.now() - start
+      };
+    }
+  }
+  while (pending.length > 0) {
+    const chunk = pending.splice(0, concurrency);
+    const chunkResults = await Promise.allSettled(chunk.map((operation) => runOne(operation)));
+    for (const result of chunkResults) {
+      if (result.status === "fulfilled") {
+        results.push(result.value);
+        continue;
+      }
+      results.push({
+        id: "unknown",
+        status: "error",
+        error: result.reason instanceof Error ? result.reason.message : "Promise rejected",
+        durationMs: 0
+      });
+    }
+  }
+  return results;
+}
+export {
+  batch
+};
+//# sourceMappingURL=batch.js.map

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

@@ -0,0 +1,34 @@
+/**
+ * kb_changelog — Generate a changelog from git history.
+ */
+export type ChangelogFormat = 'grouped' | 'chronological' | 'per-scope';
+export interface ChangelogOptions {
+    from: string;
+    to?: string;
+    format?: ChangelogFormat;
+    includeBreaking?: boolean;
+    cwd?: string;
+}
+export interface ChangelogEntry {
+    hash: string;
+    type: string;
+    scope: string;
+    subject: string;
+    body: string;
+    author: string;
+    date: string;
+    breaking: boolean;
+}
+export interface ChangelogResult {
+    entries: ChangelogEntry[];
+    markdown: string;
+    stats: {
+        total: number;
+        breaking: number;
+        types: Record<string, number>;
+    };
+}
+export declare function changelog(options: ChangelogOptions): ChangelogResult;
+/** Exported for testing */
+export declare function formatChangelog(entries: ChangelogEntry[], format: ChangelogFormat, includeBreaking: boolean): string;
+//# sourceMappingURL=changelog.d.ts.map

package/packages/tools/dist/changelog.js

@@ -0,0 +1,112 @@
+import { execSync } from "node:child_process";
+const SAFE_REF = /^[a-zA-Z0-9_./\-~^@{}]+$/;
+function changelog(options) {
+  const {
+    from,
+    to = "HEAD",
+    format = "grouped",
+    includeBreaking = true,
+    cwd = process.cwd()
+  } = options;
+  if (!SAFE_REF.test(from)) throw new Error(`Invalid git ref: ${from}`);
+  if (!SAFE_REF.test(to)) throw new Error(`Invalid git ref: ${to}`);
+  const FIELD = "";
+  const ENTRY = "";
+  const gitFormat = `%H${FIELD}%s${FIELD}%b${FIELD}%an${FIELD}%ai${ENTRY}`;
+  let output;
+  try {
+    output = execSync(`git log "${from}..${to}" --format="${gitFormat}"`, {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: 10 * 1024 * 1024
+    });
+  } catch {
+    throw new Error(`Git log failed. Ensure "${from}" and "${to}" are valid refs.`);
+  }
+  const entries = output.split(ENTRY).map((b) => b.trim()).filter(Boolean).map((block) => {
+    const [hash = "", subject = "", body = "", author = "", date = ""] = block.split(FIELD);
+    const m = subject.match(/^(\w+)(?:\(([^)]*)\))?(!)?:\s*(.+)/);
+    return {
+      hash: hash.slice(0, 8),
+      type: m?.[1] ?? "other",
+      scope: m?.[2] ?? "",
+      subject: m?.[4] ?? subject,
+      body: body.trim(),
+      author: author.trim(),
+      date: date.trim().split(" ")[0],
+      breaking: !!(m?.[3] || /BREAKING[\s-]CHANGE/i.test(body))
+    };
+  });
+  const types = {};
+  let breakingCount = 0;
+  for (const e of entries) {
+    types[e.type] = (types[e.type] ?? 0) + 1;
+    if (e.breaking) breakingCount++;
+  }
+  return {
+    entries,
+    markdown: formatChangelog(entries, format, includeBreaking),
+    stats: { total: entries.length, breaking: breakingCount, types }
+  };
+}
+function formatChangelog(entries, format, includeBreaking) {
+  const lines = ["# Changelog", ""];
+  if (includeBreaking) {
+    const breaking = entries.filter((e) => e.breaking);
+    if (breaking.length > 0) {
+      lines.push("## Breaking Changes", "");
+      for (const e of breaking) lines.push(`- ${e.subject} (${e.hash})`);
+      lines.push("");
+    }
+  }
+  if (format === "grouped") {
+    const groups = {};
+    for (const e of entries) {
+      if (!groups[e.type]) groups[e.type] = [];
+      groups[e.type].push(e);
+    }
+    const order = ["feat", "fix", "refactor", "perf", "test", "docs", "chore"];
+    const labels = {
+      feat: "Features",
+      fix: "Bug Fixes",
+      refactor: "Refactoring",
+      perf: "Performance",
+      test: "Tests",
+      docs: "Documentation",
+      chore: "Chores",
+      other: "Other"
+    };
+    for (const type of [...order, ...Object.keys(groups).filter((k) => !order.includes(k))]) {
+      if (!groups[type]?.length) continue;
+      lines.push(`## ${labels[type] ?? type}`, "");
+      for (const e of groups[type]) {
+        const scope = e.scope ? `**${e.scope}:** ` : "";
+        lines.push(`- ${scope}${e.subject} (${e.hash})`);
+      }
+      lines.push("");
+    }
+  } else if (format === "chronological") {
+    for (const e of entries) {
+      const scope = e.scope ? `(${e.scope}) ` : "";
+      lines.push(`- \`${e.date}\` ${e.type}: ${scope}${e.subject} (${e.hash})`);
+    }
+  } else {
+    const byScope = {};
+    for (const e of entries) {
+      const key = e.scope || "general";
+      if (!byScope[key]) byScope[key] = [];
+      byScope[key].push(e);
+    }
+    for (const [scope, scopeEntries] of Object.entries(byScope)) {
+      lines.push(`## ${scope}`, "");
+      for (const e of scopeEntries) lines.push(`- ${e.type}: ${e.subject} (${e.hash})`);
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+export {
+  changelog,
+  formatChangelog
+};
+//# sourceMappingURL=changelog.js.map

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

@@ -0,0 +1,26 @@
+import { type ParsedError } from './parse-output.js';
+export interface CheckOptions {
+    /** Specific files to check (if empty, checks all) */
+    files?: string[];
+    /** Working directory */
+    cwd?: string;
+    /** Skip typecheck */
+    skipTypes?: boolean;
+    /** Skip lint */
+    skipLint?: boolean;
+}
+export interface CheckResult {
+    tsc: {
+        errors: ParsedError[];
+        passed: boolean;
+        raw?: string;
+    };
+    biome: {
+        errors: ParsedError[];
+        passed: boolean;
+        raw?: string;
+    };
+    passed: boolean;
+}
+export declare function check(options?: CheckOptions): Promise<CheckResult>;
+//# sourceMappingURL=check.d.ts.map

package/packages/tools/dist/check.js

@@ -0,0 +1,59 @@
+import { execFile } from "node:child_process";
+import { readFile as readFileAsync } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { parseBiome, parseTsc } from "./parse-output.js";
+const execFileAsync = promisify(execFile);
+function getProcessOutput(error) {
+  const candidate = error;
+  const stdout = candidate.stdout?.toString() ?? "";
+  const stderr = candidate.stderr?.toString() ?? "";
+  return [stdout, stderr].filter(Boolean).join("\n").trim() || candidate.message || "Command failed";
+}
+async function check(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const tscResult = { errors: [], passed: true, raw: "" };
+  const biomeResult = { errors: [], passed: true, raw: "" };
+  if (!options.skipTypes) {
+    try {
+      const pkgPath = join(cwd, "package.json");
+      let useProjectScript = false;
+      try {
+        const pkg = JSON.parse(await readFileAsync(pkgPath, "utf-8"));
+        useProjectScript = !!pkg.scripts?.typecheck;
+      } catch {
+      }
+      if (useProjectScript && !options.files?.length) {
+        await execFileAsync("npx", ["turbo", "run", "typecheck"], { cwd, shell: true });
+      } else {
+        const args = ["--noEmit"];
+        if (options.files?.length) args.push(...options.files);
+        await execFileAsync("npx", ["tsc", ...args], { cwd, shell: true });
+      }
+    } catch (error) {
+      tscResult.raw = getProcessOutput(error);
+      tscResult.errors = parseTsc(tscResult.raw);
+      tscResult.passed = tscResult.errors.length === 0;
+    }
+  }
+  if (!options.skipLint) {
+    try {
+      const args = ["check"];
+      if (options.files?.length) args.push(...options.files);
+      await execFileAsync("npx", ["biome", ...args], { cwd, shell: true });
+    } catch (error) {
+      biomeResult.raw = getProcessOutput(error);
+      biomeResult.errors = parseBiome(biomeResult.raw);
+      biomeResult.passed = biomeResult.errors.length === 0;
+    }
+  }
+  return {
+    tsc: tscResult,
+    biome: biomeResult,
+    passed: tscResult.passed && biomeResult.passed
+  };
+}
+export {
+  check
+};
+//# sourceMappingURL=check.js.map

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

@@ -0,0 +1,17 @@
+export interface Checkpoint {
+    id: string;
+    label: string;
+    createdAt: string;
+    data: Record<string, unknown>;
+    files?: string[];
+    notes?: string;
+}
+export declare function checkpointSave(label: string, data: Record<string, unknown>, options?: {
+    files?: string[];
+    notes?: string;
+    cwd?: string;
+}): Checkpoint;
+export declare function checkpointLoad(id: string, cwd?: string): Checkpoint | undefined;
+export declare function checkpointList(cwd?: string): Checkpoint[];
+export declare function checkpointLatest(cwd?: string): Checkpoint | undefined;
+//# sourceMappingURL=checkpoint.d.ts.map

package/packages/tools/dist/checkpoint.js

@@ -0,0 +1,43 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+const CHECKPOINT_DIR = ".kb-state/checkpoints";
+function checkpointDir(cwd) {
+  const root = cwd ?? process.cwd();
+  const dir = resolve(root, CHECKPOINT_DIR);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+function checkpointSave(label, data, options) {
+  const slug = label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "checkpoint";
+  const checkpoint = {
+    id: `${Date.now()}-${slug}`,
+    label,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    data,
+    files: options?.files,
+    notes: options?.notes
+  };
+  const filePath = resolve(checkpointDir(options?.cwd), `${checkpoint.id}.json`);
+  writeFileSync(filePath, `${JSON.stringify(checkpoint, null, 2)}
+`, "utf-8");
+  return checkpoint;
+}
+function checkpointLoad(id, cwd) {
+  const filePath = resolve(checkpointDir(cwd), `${id}.json`);
+  if (!existsSync(filePath)) return void 0;
+  return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+function checkpointList(cwd) {
+  const dir = checkpointDir(cwd);
+  return readdirSync(dir).filter((file) => file.endsWith(".json")).map((file) => JSON.parse(readFileSync(resolve(dir, file), "utf-8"))).sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+function checkpointLatest(cwd) {
+  return checkpointList(cwd)[0];
+}
+export {
+  checkpointLatest,
+  checkpointList,
+  checkpointLoad,
+  checkpointSave
+};
+//# sourceMappingURL=checkpoint.js.map

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

@@ -0,0 +1,37 @@
+export interface CodemodRule {
+    /** Description of what this rule does */
+    description: string;
+    /** Regex pattern to match (string form, will be compiled) */
+    pattern: string;
+    /** Replacement string (supports $1, $2 capture groups) */
+    replacement: string;
+    /** Optional: only apply to files matching this glob */
+    fileFilter?: string;
+}
+export interface CodemodOptions {
+    /** Root directory to apply codemod in */
+    rootPath: string;
+    /** Rules to apply */
+    rules: CodemodRule[];
+    /** File extensions to process */
+    extensions?: string[];
+    /** Exclude patterns */
+    exclude?: string[];
+    /** Dry run */
+    dryRun?: boolean;
+}
+export interface CodemodChange {
+    rule: string;
+    path: string;
+    line: number;
+    before: string;
+    after: string;
+}
+export interface CodemodResult {
+    changes: CodemodChange[];
+    rulesApplied: number;
+    filesModified: number;
+    dryRun: boolean;
+}
+export declare function codemod(options: CodemodOptions): Promise<CodemodResult>;
+//# sourceMappingURL=codemod.d.ts.map

package/packages/tools/dist/codemod.js

@@ -0,0 +1,69 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { DEFAULT_TOOL_EXTENSIONS, matchesGlobPattern, walkFiles } from "./file-walk.js";
+function normalizePath(path) {
+  return path.replace(/\\/g, "/");
+}
+async function codemod(options) {
+  const {
+    rootPath,
+    rules,
+    extensions = DEFAULT_TOOL_EXTENSIONS,
+    exclude = [],
+    dryRun = false
+  } = options;
+  const compiledRules = rules.map((rule) => ({
+    ...rule,
+    regex: new RegExp(rule.pattern, "g")
+  }));
+  const filePaths = await walkFiles(rootPath, extensions, exclude);
+  const changes = [];
+  const appliedRules = /* @__PURE__ */ new Set();
+  let filesModified = 0;
+  for (const filePath of filePaths) {
+    const relativePath = normalizePath(relative(rootPath, filePath));
+    const originalContent = await readFile(filePath, "utf-8");
+    const lines = originalContent.split(/\r?\n/);
+    let fileChanged = false;
+    for (const [ruleIndex, rule] of compiledRules.entries()) {
+      if (rule.fileFilter && !matchesGlobPattern(relativePath, rule.fileFilter)) {
+        continue;
+      }
+      for (let index = 0; index < lines.length; index++) {
+        const before = lines[index];
+        rule.regex.lastIndex = 0;
+        const after = before.replace(rule.regex, rule.replacement);
+        if (before === after) {
+          continue;
+        }
+        lines[index] = after;
+        fileChanged = true;
+        appliedRules.add(ruleIndex);
+        changes.push({
+          rule: rule.description,
+          path: relativePath,
+          line: index + 1,
+          before,
+          after
+        });
+      }
+    }
+    if (!fileChanged) {
+      continue;
+    }
+    filesModified += 1;
+    if (!dryRun) {
+      await writeFile(filePath, lines.join("\n"), "utf-8");
+    }
+  }
+  return {
+    changes,
+    rulesApplied: appliedRules.size,
+    filesModified,
+    dryRun
+  };
+}
+export {
+  codemod
+};
+//# sourceMappingURL=codemod.js.map

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

@@ -0,0 +1,41 @@
+/**
+ * kb_compact — Extractive context compression.
+ *
+ * Takes a large text and a focus query, then extracts the most relevant
+ * sentences/paragraphs using the embedder for similarity scoring.
+ * No LLM needed — pure ONNX inference.
+ *
+ * Use case: compress a 50K-token file read down to the 2K tokens
+ * that actually matter for the current task.
+ */
+import type { IEmbedder } from '@kb/embeddings';
+export interface CompactOptions {
+    /** The text to compress */
+    text: string;
+    /** The focus query — what are we trying to understand? */
+    query: string;
+    /** Target output size in characters (default: 3000) */
+    maxChars?: number;
+    /** Minimum similarity score to include a segment (0-1, default: 0.3) */
+    minScore?: number;
+    /** Segmentation strategy (default: 'paragraph') */
+    segmentation?: 'paragraph' | 'sentence' | 'line';
+}
+export interface CompactResult {
+    /** The compressed text */
+    text: string;
+    /** Original size in chars */
+    originalChars: number;
+    /** Compressed size in chars */
+    compressedChars: number;
+    /** Compression ratio (0-1, lower = more compressed) */
+    ratio: number;
+    /** Number of segments kept / total */
+    segmentsKept: number;
+    segmentsTotal: number;
+}
+/**
+ * Compress text by extracting segments most relevant to a query.
+ */
+export declare function compact(embedder: IEmbedder, options: CompactOptions): Promise<CompactResult>;
+//# sourceMappingURL=compact.d.ts.map

package/packages/tools/dist/compact.js

@@ -0,0 +1,60 @@
+import { cosineSimilarity, segment } from "./text-utils.js";
+async function compact(embedder, options) {
+  const { text, query, maxChars = 3e3, minScore = 0.3, segmentation = "paragraph" } = options;
+  if (text.length <= maxChars) {
+    return {
+      text,
+      originalChars: text.length,
+      compressedChars: text.length,
+      ratio: 1,
+      segmentsKept: 1,
+      segmentsTotal: 1
+    };
+  }
+  const segments = segment(text, segmentation);
+  if (segments.length === 0) {
+    return {
+      text: "",
+      originalChars: text.length,
+      compressedChars: 0,
+      ratio: 0,
+      segmentsKept: 0,
+      segmentsTotal: 0
+    };
+  }
+  const queryVector = await embedder.embed(query);
+  const scored = [];
+  for (let i = 0; i < segments.length; i++) {
+    const segVector = await embedder.embed(segments[i]);
+    const score = cosineSimilarity(queryVector, segVector);
+    scored.push({ text: segments[i], score, index: i });
+  }
+  const sorted = scored.filter((s) => s.score >= minScore).sort((a, b) => b.score - a.score);
+  const selected = [];
+  let totalChars = 0;
+  for (const seg of sorted) {
+    if (totalChars + seg.text.length > maxChars) {
+      if (totalChars === 0) {
+        selected.push({ ...seg, text: seg.text.slice(0, maxChars) });
+        totalChars = maxChars;
+      }
+      break;
+    }
+    selected.push(seg);
+    totalChars += seg.text.length + 2;
+  }
+  selected.sort((a, b) => a.index - b.index);
+  const compressedText = selected.map((s) => s.text).join("\n\n");
+  return {
+    text: compressedText,
+    originalChars: text.length,
+    compressedChars: compressedText.length,
+    ratio: compressedText.length / text.length,
+    segmentsKept: selected.length,
+    segmentsTotal: segments.length
+  };
+}
+export {
+  compact
+};
+//# sourceMappingURL=compact.js.map

package/packages/tools/dist/data-transform.d.ts

@@ -0,0 +1,10 @@
+export interface TransformOptions {
+    input: unknown;
+    expression: string;
+}
+export interface TransformResult {
+    output: unknown;
+    outputString: string;
+}
+export declare function dataTransform(options: TransformOptions): TransformResult;
+//# sourceMappingURL=data-transform.d.ts.map