@vpxa/kb 0.1.1

package/packages/tools/dist/parse-output.d.ts

@@ -0,0 +1,80 @@
+/**
+ * kb_parse_output — Structured parsers for common build tool output.
+ *
+ * Converts noisy text output from tsc, vitest, biome, and git status
+ * into structured JSON that LLM agents can act on directly.
+ */
+export interface ParsedError {
+    file: string;
+    line?: number;
+    column?: number;
+    severity: 'error' | 'warning' | 'info';
+    code?: string;
+    message: string;
+}
+export interface ParsedTestResult {
+    name: string;
+    file?: string;
+    status: 'pass' | 'fail' | 'skip';
+    duration?: number;
+    error?: string;
+}
+export interface ParsedTestSummary {
+    tests: ParsedTestResult[];
+    passed: number;
+    failed: number;
+    skipped: number;
+    duration?: number;
+    suites?: number;
+}
+export interface ParsedGitStatus {
+    staged: Array<{
+        status: string;
+        file: string;
+    }>;
+    unstaged: Array<{
+        status: string;
+        file: string;
+    }>;
+    untracked: string[];
+    branch?: string;
+}
+export type ParsedOutput = {
+    tool: 'tsc';
+    errors: ParsedError[];
+} | {
+    tool: 'vitest';
+    summary: ParsedTestSummary;
+} | {
+    tool: 'biome';
+    errors: ParsedError[];
+} | {
+    tool: 'git-status';
+    status: ParsedGitStatus;
+};
+/**
+ * Parse `tsc` output into structured errors.
+ *
+ * Example line: `src/foo.ts(10,5): error TS2339: Property 'x' does not exist`
+ */
+export declare function parseTsc(output: string): ParsedError[];
+/**
+ * Parse vitest run output into structured test results.
+ */
+export declare function parseVitest(output: string): ParsedTestSummary;
+/**
+ * Parse biome check/lint output into structured errors.
+ *
+ * Example: `src/foo.ts:10:5 lint/suspicious/noDoubleEquals ━━━`
+ *          `  × Use === instead of ==`
+ */
+export declare function parseBiome(output: string): ParsedError[];
+/**
+ * Parse `git status --porcelain=v1 -b` output into structured status.
+ */
+export declare function parseGitStatus(output: string): ParsedGitStatus;
+/**
+ * Auto-detect the tool from output content and parse accordingly.
+ */
+export declare function parseOutput(output: string, tool?: string): ParsedOutput;
+//# sourceMappingURL=parse-output.d.ts.map

package/packages/tools/dist/parse-output.js

@@ -0,0 +1,158 @@
+function parseTsc(output) {
+  const errors = [];
+  const parenRegex = /^(.+?)\((\d+),(\d+)\):\s+(error|warning)\s+(TS\d+):\s+(.+)$/gm;
+  for (const match of output.matchAll(parenRegex)) {
+    errors.push({
+      file: match[1],
+      line: Number.parseInt(match[2], 10),
+      column: Number.parseInt(match[3], 10),
+      severity: match[4],
+      code: match[5],
+      message: match[6]
+    });
+  }
+  if (errors.length === 0) {
+    const colonRegex = /^(.+?):(\d+):(\d+)\s+-\s+(error|warning)\s+(TS\d+):\s+(.+)$/gm;
+    for (const match of output.matchAll(colonRegex)) {
+      errors.push({
+        file: match[1],
+        line: Number.parseInt(match[2], 10),
+        column: Number.parseInt(match[3], 10),
+        severity: match[4],
+        code: match[5],
+        message: match[6]
+      });
+    }
+  }
+  return errors;
+}
+function parseVitest(output) {
+  const tests = [];
+  const testRegex = /^\s*([✓✕×-])\s+(.+?)(?:\s+(\d+)ms)?$/gm;
+  for (const match of output.matchAll(testRegex)) {
+    const symbol = match[1];
+    const status = symbol === "\u2713" ? "pass" : symbol === "-" ? "skip" : "fail";
+    tests.push({
+      name: match[2].trim(),
+      status,
+      duration: match[3] ? Number.parseInt(match[3], 10) : void 0
+    });
+  }
+  const fileRegex = /^\s*([✓✕×])\s+(\S+\.test\.\w+)\s+\((\d+)\s+tests?\)\s*(\d+ms)?$/gm;
+  for (const match of output.matchAll(fileRegex)) {
+    const symbol = match[1];
+    const status = symbol === "\u2713" ? "pass" : "fail";
+    tests.push({
+      name: match[2],
+      file: match[2],
+      status,
+      duration: match[4] ? Number.parseInt(match[4], 10) : void 0
+    });
+  }
+  const summaryRegex = /Tests\s+(?:(\d+)\s+passed)?(?:\s*\|\s*)?(?:(\d+)\s+failed)?(?:\s*\|\s*)?(?:(\d+)\s+skipped)?\s*\((\d+)\)/;
+  const summaryMatch = summaryRegex.exec(output);
+  const passed = summaryMatch ? Number.parseInt(summaryMatch[1] ?? "0", 10) : tests.filter((t) => t.status === "pass").length;
+  const failed = summaryMatch ? Number.parseInt(summaryMatch[2] ?? "0", 10) : tests.filter((t) => t.status === "fail").length;
+  const skipped = summaryMatch ? Number.parseInt(summaryMatch[3] ?? "0", 10) : tests.filter((t) => t.status === "skip").length;
+  const durationRegex = /Duration\s+(\d+(?:\.\d+)?)(?:ms|s)/;
+  const durationMatch = durationRegex.exec(output);
+  const duration = durationMatch ? durationMatch[0].includes("s") && !durationMatch[0].includes("ms") ? Number.parseFloat(durationMatch[1]) * 1e3 : Number.parseFloat(durationMatch[1]) : void 0;
+  const suitesRegex = /Test Files\s+(\d+)\s+passed/;
+  const suitesMatch = suitesRegex.exec(output);
+  return {
+    tests,
+    passed,
+    failed,
+    skipped,
+    duration,
+    suites: suitesMatch ? Number.parseInt(suitesMatch[1], 10) : void 0
+  };
+}
+function parseBiome(output) {
+  const errors = [];
+  const blockRegex = /^(.+?):(\d+):(\d+)\s+([\w/]+)\s+━+$/gm;
+  for (const match of output.matchAll(blockRegex)) {
+    const file = match[1];
+    const line = Number.parseInt(match[2], 10);
+    const column = Number.parseInt(match[3], 10);
+    const code = match[4];
+    const afterBlock = output.slice(
+      (match.index ?? 0) + match[0].length,
+      (match.index ?? 0) + match[0].length + 500
+    );
+    const msgMatch = /^\s*[×!i]\s+(.+)$/m.exec(afterBlock);
+    const message = msgMatch ? msgMatch[1].trim() : code;
+    const severity = code.includes("lint") ? "warning" : "error";
+    errors.push({ file, line, column, severity, code, message });
+  }
+  return errors;
+}
+function parseGitStatus(output) {
+  const staged = [];
+  const unstaged = [];
+  const untracked = [];
+  let branch;
+  for (const line of output.split("\n")) {
+    if (!line) continue;
+    if (line.startsWith("## ")) {
+      branch = line.slice(3).split("...")[0];
+      continue;
+    }
+    const x = line[0];
+    const y = line[1];
+    const file = line.slice(3).trim();
+    if (x === "?" && y === "?") {
+      untracked.push(file);
+    } else {
+      if (x !== " " && x !== "?") {
+        staged.push({ status: statusLabel(x), file });
+      }
+      if (y !== " " && y !== "?") {
+        unstaged.push({ status: statusLabel(y), file });
+      }
+    }
+  }
+  return { staged, unstaged, untracked, branch };
+}
+function statusLabel(code) {
+  const labels = {
+    M: "modified",
+    A: "added",
+    D: "deleted",
+    R: "renamed",
+    C: "copied",
+    U: "unmerged"
+  };
+  return labels[code] ?? code;
+}
+function parseOutput(output, tool) {
+  const detected = tool ?? detectTool(output);
+  switch (detected) {
+    case "tsc":
+      return { tool: "tsc", errors: parseTsc(output) };
+    case "vitest":
+      return { tool: "vitest", summary: parseVitest(output) };
+    case "biome":
+      return { tool: "biome", errors: parseBiome(output) };
+    case "git-status":
+      return { tool: "git-status", status: parseGitStatus(output) };
+    default:
+      throw new Error(`Unknown tool: ${detected}. Supported: tsc, vitest, biome, git-status`);
+  }
+}
+function detectTool(output) {
+  if (output.includes("error TS") || /\(\d+,\d+\):\s+error/.test(output)) return "tsc";
+  if (output.includes("vitest") || output.includes("Test Files") || output.includes("\u2713"))
+    return "vitest";
+  if (output.includes("biome") || /\w+\/\w+\s+━+/.test(output)) return "biome";
+  if (/^##\s/.test(output) || /^[MADRCU?! ]{2}\s/.test(output)) return "git-status";
+  return "unknown";
+}
+export {
+  parseBiome,
+  parseGitStatus,
+  parseOutput,
+  parseTsc,
+  parseVitest
+};
+//# sourceMappingURL=parse-output.js.map

package/packages/tools/dist/process-manager.d.ts

@@ -0,0 +1,18 @@
+export interface ManagedProcess {
+    id: string;
+    command: string;
+    args: string[];
+    pid?: number;
+    status: 'running' | 'stopped' | 'error';
+    startedAt: string;
+    exitCode?: number;
+    logs: string[];
+}
+export declare function processStart(id: string, command: string, args?: string[], options?: {
+    cwd?: string;
+}): ManagedProcess;
+export declare function processStop(id: string): ManagedProcess | undefined;
+export declare function processStatus(id: string): ManagedProcess | undefined;
+export declare function processList(): ManagedProcess[];
+export declare function processLogs(id: string, tail?: number): string[];
+//# sourceMappingURL=process-manager.d.ts.map

package/packages/tools/dist/process-manager.js

@@ -0,0 +1,69 @@
+import { spawn } from "node:child_process";
+const processes = /* @__PURE__ */ new Map();
+const MAX_LOG_LINES = 200;
+function processStart(id, command, args = [], options) {
+  if (processes.has(id)) {
+    throw new Error(`Process "${id}" is already running. Stop it first.`);
+  }
+  const proc = spawn(command, args, {
+    cwd: options?.cwd ?? process.cwd(),
+    shell: true,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  const info = {
+    id,
+    command,
+    args,
+    pid: proc.pid ?? void 0,
+    status: "running",
+    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    logs: []
+  };
+  const appendLog = (data) => {
+    const lines = data.toString().split(/\r?\n/).filter(Boolean);
+    info.logs.push(...lines);
+    if (info.logs.length > MAX_LOG_LINES) {
+      info.logs = info.logs.slice(-MAX_LOG_LINES);
+    }
+  };
+  proc.stdout?.on("data", appendLog);
+  proc.stderr?.on("data", appendLog);
+  proc.on("exit", (code) => {
+    info.status = code === 0 ? "stopped" : "error";
+    info.exitCode = code ?? void 0;
+  });
+  proc.on("error", (err) => {
+    info.status = "error";
+    info.logs.push(`[error] ${err.message}`);
+  });
+  processes.set(id, { proc, info });
+  return info;
+}
+function processStop(id) {
+  const entry = processes.get(id);
+  if (!entry) return void 0;
+  entry.proc.kill("SIGTERM");
+  entry.info.status = "stopped";
+  processes.delete(id);
+  return entry.info;
+}
+function processStatus(id) {
+  return processes.get(id)?.info;
+}
+function processList() {
+  return [...processes.values()].map((entry) => entry.info);
+}
+function processLogs(id, tail) {
+  const entry = processes.get(id);
+  if (!entry) return [];
+  if (tail) return entry.info.logs.slice(-tail);
+  return entry.info.logs;
+}
+export {
+  processList,
+  processLogs,
+  processStart,
+  processStatus,
+  processStop
+};
+//# sourceMappingURL=process-manager.js.map

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

@@ -0,0 +1,38 @@
+export interface QueueItem {
+    id: string;
+    title: string;
+    status: 'pending' | 'in-progress' | 'done' | 'failed';
+    data?: unknown;
+    createdAt: string;
+    updatedAt: string;
+    error?: string;
+}
+export interface QueueState {
+    name: string;
+    items: QueueItem[];
+}
+/** Create a new named queue. */
+export declare function queueCreate(name: string, cwd?: string): QueueState;
+/** Push an item onto a queue. Creates the queue if it doesn't exist. */
+export declare function queuePush(name: string, title: string, data?: unknown, cwd?: string): QueueItem;
+/** Take the next pending item from a queue and mark it in-progress. */
+export declare function queueNext(name: string, cwd?: string): QueueItem | null;
+/** Mark a queue item as done. */
+export declare function queueDone(name: string, id: string, cwd?: string): QueueItem;
+/** Mark a queue item as failed with an error message. */
+export declare function queueFail(name: string, id: string, error: string, cwd?: string): QueueItem;
+/** Get the current state of a queue. */
+export declare function queueGet(name: string, cwd?: string): QueueState | null;
+/** List all queues with their item counts. */
+export declare function queueList(cwd?: string): Array<{
+    name: string;
+    pending: number;
+    done: number;
+    failed: number;
+    total: number;
+}>;
+/** Clear completed items from a queue. */
+export declare function queueClear(name: string, cwd?: string): number;
+/** Delete a queue entirely. */
+export declare function queueDelete(name: string, cwd?: string): boolean;
+//# sourceMappingURL=queue.d.ts.map

package/packages/tools/dist/queue.js

@@ -0,0 +1,126 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+const QUEUE_DIR = ".kb-state";
+const QUEUE_FILE = "queue.json";
+function queuePath(cwd) {
+  return resolve(cwd ?? process.cwd(), QUEUE_DIR, QUEUE_FILE);
+}
+function loadQueues(cwd) {
+  const path = queuePath(cwd);
+  if (!existsSync(path)) return {};
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+function saveQueues(data, cwd) {
+  const path = queuePath(cwd);
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}
+`, "utf-8");
+}
+function generateId() {
+  return `q_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+}
+function queueCreate(name, cwd) {
+  const queues = loadQueues(cwd);
+  if (queues[name]) {
+    throw new Error(`Queue "${name}" already exists`);
+  }
+  const queue = { name, items: [] };
+  queues[name] = queue;
+  saveQueues(queues, cwd);
+  return queue;
+}
+function queuePush(name, title, data, cwd) {
+  const queues = loadQueues(cwd);
+  if (!queues[name]) {
+    queues[name] = { name, items: [] };
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const item = {
+    id: generateId(),
+    title,
+    status: "pending",
+    data,
+    createdAt: now,
+    updatedAt: now
+  };
+  queues[name].items.push(item);
+  saveQueues(queues, cwd);
+  return item;
+}
+function queueNext(name, cwd) {
+  const queues = loadQueues(cwd);
+  const queue = queues[name];
+  if (!queue) throw new Error(`Queue "${name}" does not exist`);
+  const item = queue.items.find((i) => i.status === "pending");
+  if (!item) return null;
+  item.status = "in-progress";
+  item.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  saveQueues(queues, cwd);
+  return item;
+}
+function queueDone(name, id, cwd) {
+  const queues = loadQueues(cwd);
+  const queue = queues[name];
+  if (!queue) throw new Error(`Queue "${name}" does not exist`);
+  const item = queue.items.find((i) => i.id === id);
+  if (!item) throw new Error(`Item "${id}" not found in queue "${name}"`);
+  item.status = "done";
+  item.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  saveQueues(queues, cwd);
+  return item;
+}
+function queueFail(name, id, error, cwd) {
+  const queues = loadQueues(cwd);
+  const queue = queues[name];
+  if (!queue) throw new Error(`Queue "${name}" does not exist`);
+  const item = queue.items.find((i) => i.id === id);
+  if (!item) throw new Error(`Item "${id}" not found in queue "${name}"`);
+  item.status = "failed";
+  item.error = error;
+  item.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  saveQueues(queues, cwd);
+  return item;
+}
+function queueGet(name, cwd) {
+  return loadQueues(cwd)[name] ?? null;
+}
+function queueList(cwd) {
+  const queues = loadQueues(cwd);
+  return Object.values(queues).map((q) => ({
+    name: q.name,
+    pending: q.items.filter((i) => i.status === "pending").length,
+    done: q.items.filter((i) => i.status === "done").length,
+    failed: q.items.filter((i) => i.status === "failed").length,
+    total: q.items.length
+  }));
+}
+function queueClear(name, cwd) {
+  const queues = loadQueues(cwd);
+  const queue = queues[name];
+  if (!queue) throw new Error(`Queue "${name}" does not exist`);
+  const before = queue.items.length;
+  queue.items = queue.items.filter((i) => i.status === "pending" || i.status === "in-progress");
+  const removed = before - queue.items.length;
+  saveQueues(queues, cwd);
+  return removed;
+}
+function queueDelete(name, cwd) {
+  const queues = loadQueues(cwd);
+  if (!queues[name]) return false;
+  delete queues[name];
+  saveQueues(queues, cwd);
+  return true;
+}
+export {
+  queueClear,
+  queueCreate,
+  queueDelete,
+  queueDone,
+  queueFail,
+  queueGet,
+  queueList,
+  queueNext,
+  queuePush
+};
+//# sourceMappingURL=queue.js.map

package/packages/tools/dist/regex-test.d.ts

@@ -0,0 +1,31 @@
+/**
+ * kb_regex_test — Test regex patterns against sample strings.
+ */
+export interface RegexTestOptions {
+    pattern: string;
+    flags?: string;
+    testStrings: string[];
+    mode?: 'match' | 'replace' | 'split';
+    replacement?: string;
+}
+export interface RegexMatchInfo {
+    full: string;
+    groups: (string | undefined)[];
+    index: number;
+}
+export interface RegexTestStringResult {
+    input: string;
+    matched: boolean;
+    matches?: RegexMatchInfo[];
+    replaced?: string;
+    split?: string[];
+}
+export interface RegexTestResult {
+    pattern: string;
+    flags: string;
+    results: RegexTestStringResult[];
+    valid: boolean;
+    error?: string;
+}
+export declare function regexTest(options: RegexTestOptions): RegexTestResult;
+//# sourceMappingURL=regex-test.d.ts.map

package/packages/tools/dist/regex-test.js

@@ -0,0 +1,39 @@
+function regexTest(options) {
+  const { pattern, flags = "", testStrings, mode = "match", replacement = "" } = options;
+  try {
+    const regex = new RegExp(pattern, flags);
+    const results = testStrings.map((input) => {
+      const matched = regex.test(input);
+      switch (mode) {
+        case "match": {
+          const globalFlags = flags.includes("g") ? flags : `${flags}g`;
+          const allMatches = [...input.matchAll(new RegExp(pattern, globalFlags))];
+          return {
+            input,
+            matched,
+            matches: allMatches.map((m) => ({
+              full: m[0],
+              groups: [...m.slice(1)],
+              index: m.index ?? 0
+            }))
+          };
+        }
+        case "replace":
+          return {
+            input,
+            matched,
+            replaced: input.replace(new RegExp(pattern, flags), replacement)
+          };
+        default:
+          return { input, matched, split: input.split(new RegExp(pattern, flags)) };
+      }
+    });
+    return { pattern, flags, results, valid: true };
+  } catch (err) {
+    return { pattern, flags, results: [], valid: false, error: err.message };
+  }
+}
+export {
+  regexTest
+};
+//# sourceMappingURL=regex-test.js.map

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

@@ -0,0 +1,29 @@
+export interface RenameOptions {
+    /** Symbol to rename */
+    oldName: string;
+    /** New symbol name */
+    newName: string;
+    /** Root directory to search in */
+    rootPath: string;
+    /** File extensions to process (default: .ts, .tsx, .js, .jsx) */
+    extensions?: string[];
+    /** Glob patterns to exclude */
+    exclude?: string[];
+    /** Dry run — don't write changes */
+    dryRun?: boolean;
+}
+export interface RenameChange {
+    path: string;
+    line: number;
+    before: string;
+    after: string;
+}
+export interface RenameResult {
+    oldName: string;
+    newName: string;
+    changes: RenameChange[];
+    filesModified: number;
+    dryRun: boolean;
+}
+export declare function rename(options: RenameOptions): Promise<RenameResult>;
+//# sourceMappingURL=rename.d.ts.map

package/packages/tools/dist/rename.js

@@ -0,0 +1,70 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { DEFAULT_TOOL_EXTENSIONS, walkFiles } from "./file-walk.js";
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizePath(path) {
+  return path.replace(/\\/g, "/");
+}
+function createWholeWordPattern(name) {
+  return new RegExp(`(^|[^A-Za-z0-9_$])(${escapeRegex(name)})(?=[^A-Za-z0-9_$]|$)`, "g");
+}
+async function rename(options) {
+  const {
+    oldName,
+    newName,
+    rootPath,
+    extensions = DEFAULT_TOOL_EXTENSIONS,
+    exclude = [],
+    dryRun = false
+  } = options;
+  if (!oldName.trim()) {
+    throw new Error("oldName must not be empty");
+  }
+  const pattern = createWholeWordPattern(oldName);
+  const filePaths = await walkFiles(rootPath, extensions, exclude);
+  const changes = [];
+  let filesModified = 0;
+  for (const filePath of filePaths) {
+    const originalContent = await readFile(filePath, "utf-8");
+    const lines = originalContent.split(/\r?\n/);
+    let fileChanged = false;
+    for (let index = 0; index < lines.length; index++) {
+      const before = lines[index];
+      pattern.lastIndex = 0;
+      const after = before.replace(pattern, (_match, prefix) => {
+        fileChanged = true;
+        return `${prefix}${newName}`;
+      });
+      if (before === after) {
+        continue;
+      }
+      lines[index] = after;
+      changes.push({
+        path: normalizePath(relative(rootPath, filePath)),
+        line: index + 1,
+        before,
+        after
+      });
+    }
+    if (!fileChanged) {
+      continue;
+    }
+    filesModified += 1;
+    if (!dryRun) {
+      await writeFile(filePath, lines.join("\n"), "utf-8");
+    }
+  }
+  return {
+    oldName,
+    newName,
+    changes,
+    filesModified,
+    dryRun
+  };
+}
+export {
+  rename
+};
+//# sourceMappingURL=rename.js.map