@vpxa/kb 0.1.1

package/packages/cli/dist/commands/search.js

@@ -0,0 +1,267 @@
+import { find, findDeadSymbols, findExamples, scopeMap, symbol, trace } from "@kb/tools";
+import { ctx } from "../context.js";
+import {
+  extractNumFlag,
+  extractStrFlag,
+  formatFocusRanges,
+  printDeadSymbolsResult,
+  printExamplesResult,
+  printSymbolInfo,
+  printTraceResult,
+  rrf
+} from "../helpers.js";
+const searchCommands = [
+  {
+    name: "search",
+    description: "Search the knowledge base",
+    usage: "kb search <query> [--limit N] [--mode hybrid|semantic|keyword] [--graph-hops 0-3]",
+    run: async (args) => {
+      const limit = extractNumFlag(args, "--limit", 5);
+      const mode = extractStrFlag(args, "--mode", "hybrid");
+      const graphHops = extractNumFlag(args, "--graph-hops", 0);
+      const query = args.join(" ").trim();
+      if (!query) {
+        console.error("Usage: kb search <query>");
+        process.exit(1);
+      }
+      const { embedder, store, graphStore } = await ctx();
+      const queryVector = await embedder.embedQuery(query);
+      let results;
+      if (mode === "keyword") {
+        results = await store.ftsSearch(query, { limit });
+      } else if (mode === "semantic") {
+        results = await store.search(queryVector, { limit });
+      } else {
+        const [vec, fts] = await Promise.all([
+          store.search(queryVector, { limit: limit * 2 }),
+          store.ftsSearch(query, { limit: limit * 2 }).catch(() => [])
+        ]);
+        results = rrf(vec, fts).slice(0, limit);
+      }
+      if (results.length === 0) {
+        console.log("No results found.");
+        return;
+      }
+      for (const { record, score } of results) {
+        console.log(`
+${"\u2500".repeat(60)}`);
+        console.log(
+          `[${(score * 100).toFixed(1)}%] ${record.sourcePath}:${record.startLine}-${record.endLine}`
+        );
+        console.log(`  Type: ${record.contentType} | Origin: ${record.origin}`);
+        if (record.tags.length > 0) console.log(`  Tags: ${record.tags.join(", ")}`);
+        console.log("");
+        const preview = record.content.length > 500 ? `${record.content.slice(0, 500)}...` : record.content;
+        console.log(preview);
+      }
+      console.log(`
+${"\u2500".repeat(60)}`);
+      console.log(`${results.length} result(s) found.`);
+      if (graphHops > 0 && results.length > 0) {
+        try {
+          const { graphAugmentSearch } = await import("@kb/tools");
+          const hits = results.map((r) => ({
+            recordId: r.record.id,
+            score: r.score,
+            sourcePath: r.record.sourcePath
+          }));
+          const augmented = await graphAugmentSearch(graphStore, hits, {
+            hops: graphHops,
+            maxPerHit: 5
+          });
+          const hasContext = augmented.filter((a) => a.graphContext.nodes.length > 0);
+          if (hasContext.length > 0) {
+            console.log(`
+Graph context (${graphHops} hop${graphHops > 1 ? "s" : ""}):
+`);
+            for (const aug of hasContext) {
+              console.log(`  ${aug.sourcePath}:`);
+              for (const n of aug.graphContext.nodes.slice(0, 5)) {
+                console.log(`    \u2192 ${n.name} (${n.type})`);
+              }
+              for (const e of aug.graphContext.edges.slice(0, 5)) {
+                console.log(`    \u2192 ${e.fromId} --[${e.type}]--> ${e.toId}`);
+              }
+            }
+          }
+        } catch (err) {
+          console.error(`[graph] augmentation failed: ${err.message}`);
+        }
+      }
+    }
+  },
+  {
+    name: "find",
+    description: "Run federated search across indexed content and files",
+    usage: "kb find [query] [--glob <pattern>] [--pattern <regex>] [--limit N]",
+    run: async (args) => {
+      const limit = extractNumFlag(args, "--limit", 10);
+      const glob = extractStrFlag(args, "--glob", "").trim() || void 0;
+      const pattern = extractStrFlag(args, "--pattern", "").trim() || void 0;
+      const query = args.join(" ").trim() || void 0;
+      if (!query && !glob && !pattern) {
+        console.error("Usage: kb find [query] [--glob <pattern>] [--pattern <regex>] [--limit N]");
+        process.exit(1);
+      }
+      const { embedder, store } = await ctx();
+      const result = await find(embedder, store, { query, glob, pattern, limit });
+      if (result.results.length === 0) {
+        console.log("No matches found.");
+        return;
+      }
+      console.log(`Strategies: ${result.strategies.join(", ")}`);
+      console.log(`Results: ${result.results.length} shown (${result.totalFound} total)`);
+      for (const match of result.results) {
+        const lineRange = match.lineRange ? `:${match.lineRange.start}-${match.lineRange.end}` : "";
+        console.log(`
+[${match.source}] ${match.path}${lineRange}`);
+        console.log(`  Score: ${(match.score * 100).toFixed(1)}%`);
+        if (match.preview) console.log(`  ${match.preview.replace(/\s+/g, " ").trim()}`);
+      }
+    }
+  },
+  {
+    name: "scope-map",
+    description: "Generate a reading plan for a task",
+    usage: "kb scope-map <task> [--max-files N]",
+    run: async (args) => {
+      const maxFiles = extractNumFlag(args, "--max-files", 15);
+      const task = args.join(" ").trim();
+      if (!task) {
+        console.error("Usage: kb scope-map <task> [--max-files N]");
+        process.exit(1);
+      }
+      const { embedder, store } = await ctx();
+      const result = await scopeMap(embedder, store, { task, maxFiles });
+      console.log(`Task: ${result.task}`);
+      console.log(`Files: ${result.files.length}`);
+      console.log(`Estimated tokens: ${result.totalEstimatedTokens}`);
+      console.log("");
+      console.log("Reading order:");
+      for (const path of result.readingOrder) console.log(`  ${path}`);
+      for (const [index, file] of result.files.entries()) {
+        console.log(`
+${index + 1}. ${file.path}`);
+        console.log(
+          `   Relevance: ${(file.relevance * 100).toFixed(1)}% | Tokens: ${file.estimatedTokens}`
+        );
+        console.log(`   Why: ${file.reason}`);
+        if (file.focusRanges.length > 0) {
+          console.log(`   Focus: ${formatFocusRanges(file.focusRanges)}`);
+        }
+      }
+    }
+  },
+  {
+    name: "symbol",
+    description: "Resolve a symbol definition, imports, and references",
+    usage: "kb symbol <name> [--limit N]",
+    run: async (args) => {
+      const limit = extractNumFlag(args, "--limit", 20);
+      const name = args.join(" ").trim();
+      if (!name) {
+        console.error("Usage: kb symbol <name> [--limit N]");
+        process.exit(1);
+      }
+      const { embedder, store } = await ctx();
+      const result = await symbol(embedder, store, { name, limit });
+      printSymbolInfo(result);
+    }
+  },
+  {
+    name: "trace",
+    description: "Trace forward/backward flow for a symbol or file location",
+    usage: "kb trace <start> [--direction forward|backward|both] [--max-depth N]",
+    run: async (args) => {
+      const directionValue = extractStrFlag(args, "--direction", "both").trim() || "both";
+      const maxDepth = extractNumFlag(args, "--max-depth", 3);
+      const start = args.join(" ").trim();
+      if (!start || !["forward", "backward", "both"].includes(directionValue)) {
+        console.error(
+          "Usage: kb trace <start> [--direction forward|backward|both] [--max-depth N]"
+        );
+        process.exit(1);
+      }
+      const { embedder, store } = await ctx();
+      const result = await trace(embedder, store, {
+        start,
+        direction: directionValue,
+        maxDepth
+      });
+      printTraceResult(result);
+    }
+  },
+  {
+    name: "examples",
+    description: "Find real code examples of a symbol or pattern",
+    usage: "kb examples <query> [--limit N] [--content-type type]",
+    run: async (args) => {
+      const limit = extractNumFlag(args, "--limit", 5);
+      const contentType = extractStrFlag(args, "--content-type", "").trim() || void 0;
+      const query = args.join(" ").trim();
+      if (!query) {
+        console.error("Usage: kb examples <query> [--limit N] [--content-type type]");
+        process.exit(1);
+      }
+      const { embedder, store } = await ctx();
+      const result = await findExamples(embedder, store, { query, limit, contentType });
+      printExamplesResult(result);
+    }
+  },
+  {
+    name: "dead-symbols",
+    description: "Find exported symbols that appear to be unused",
+    usage: "kb dead-symbols [--limit N]",
+    run: async (args) => {
+      const limit = extractNumFlag(args, "--limit", 100);
+      const { embedder, store } = await ctx();
+      const result = await findDeadSymbols(embedder, store, { limit });
+      printDeadSymbolsResult(result);
+    }
+  },
+  {
+    name: "lookup",
+    description: "Look up indexed content by record ID or source path",
+    usage: "kb lookup <id>",
+    run: async (args) => {
+      const key = args.join(" ").trim();
+      if (!key) {
+        console.error("Usage: kb lookup <id>");
+        process.exit(1);
+      }
+      const { store } = await ctx();
+      const record = await store.getById(key);
+      if (record) {
+        console.log(record.id);
+        console.log("\u2500".repeat(60));
+        console.log(`Path: ${record.sourcePath}`);
+        console.log(`Chunk: ${record.chunkIndex + 1}/${record.totalChunks}`);
+        console.log(`Lines: ${record.startLine}-${record.endLine}`);
+        console.log(`Type: ${record.contentType} | Origin: ${record.origin}`);
+        if (record.tags.length > 0) console.log(`Tags: ${record.tags.join(", ")}`);
+        console.log("");
+        console.log(record.content);
+        return;
+      }
+      const records = await store.getBySourcePath(key);
+      if (records.length === 0) {
+        console.log(`No indexed content found for: ${key}`);
+        return;
+      }
+      records.sort((a, b) => a.chunkIndex - b.chunkIndex);
+      console.log(key);
+      console.log("\u2500".repeat(60));
+      console.log(`Chunks: ${records.length} | Type: ${records[0].contentType}`);
+      for (const chunk of records) {
+        const lineInfo = chunk.startLine ? ` (lines ${chunk.startLine}-${chunk.endLine})` : "";
+        console.log(`
+Chunk ${chunk.chunkIndex + 1}/${chunk.totalChunks}${lineInfo}`);
+        console.log(chunk.content);
+      }
+    }
+  }
+];
+export {
+  searchCommands
+};
+//# sourceMappingURL=search.js.map

package/packages/cli/dist/commands/system.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../types.js';
+export declare const systemCommands: Command[];
+//# sourceMappingURL=system.d.ts.map

package/packages/cli/dist/commands/system.js

@@ -0,0 +1,241 @@
+import { fork } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { batch, check, health, replayClear, replayList, replayTrim } from "@kb/tools";
+import { ctx } from "../context.js";
+import {
+  executeCliBatchOperation,
+  extractStrFlag,
+  parseBatchPayload,
+  printCheckResult,
+  readInput
+} from "../helpers.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const systemCommands = [
+  {
+    name: "status",
+    description: "Show knowledge base index status and statistics",
+    run: async () => {
+      const { store } = await ctx();
+      const stats = await store.getStats();
+      const paths = await store.listSourcePaths();
+      console.log("Knowledge Base Status");
+      console.log("\u2500".repeat(40));
+      console.log(`  Records:  ${stats.totalRecords}`);
+      console.log(`  Files:    ${stats.totalFiles}`);
+      console.log(`  Indexed:  ${stats.lastIndexedAt ?? "Never"}`);
+      console.log(`  Backend:  ${stats.storeBackend}`);
+      console.log(`  Model:    ${stats.embeddingModel}`);
+      console.log("");
+      console.log("Content Types:");
+      for (const [type, count] of Object.entries(stats.contentTypeBreakdown)) {
+        console.log(`  ${type}: ${count}`);
+      }
+      if (paths.length > 0) {
+        console.log("");
+        console.log(`Files (${paths.length} total):`);
+        for (const p of paths.slice(0, 20)) console.log(`  ${p}`);
+        if (paths.length > 20) console.log(`  ... and ${paths.length - 20} more`);
+      }
+    }
+  },
+  {
+    name: "reindex",
+    description: "Re-index the knowledge base from configured sources",
+    usage: "kb reindex [--full]",
+    run: async (args) => {
+      const full = args.includes("--full");
+      const { store, indexer, curated, config } = await ctx();
+      console.log("Indexing sources...");
+      const progressCb = (p) => {
+        if (p.phase === "chunking" && p.currentFile) {
+          process.stdout.write(`\r  [${p.filesProcessed + 1}/${p.filesTotal}] ${p.currentFile}`);
+        }
+        if (p.phase === "done") process.stdout.write("\n");
+      };
+      let result;
+      if (full) {
+        console.log("Dropping existing index for full reindex...");
+        result = await indexer.reindexAll(config, progressCb);
+      } else {
+        result = await indexer.index(config, progressCb);
+      }
+      console.log(
+        `Done: ${result.filesProcessed} files, ${result.chunksCreated} chunks in ${(result.durationMs / 1e3).toFixed(1)}s`
+      );
+      console.log("Building FTS index...");
+      await store.createFtsIndex();
+      console.log("Re-indexing curated entries...");
+      const curatedResult = await curated.reindexAll();
+      console.log(`Curated: ${curatedResult.indexed} entries restored`);
+    }
+  },
+  {
+    name: "serve",
+    description: "Start the MCP server (stdio or HTTP)",
+    usage: "kb serve [--transport stdio|http] [--port N]",
+    run: async (args) => {
+      const serverEntry = resolve(__dirname, "..", "..", "..", "server", "dist", "index.js");
+      const transport = extractStrFlag(args, "--transport", "stdio");
+      const port = extractStrFlag(args, "--port", "3210");
+      const child = fork(serverEntry, [], {
+        stdio: transport === "stdio" ? ["pipe", "pipe", "inherit", "ipc"] : "inherit",
+        env: {
+          ...process.env,
+          KB_TRANSPORT: transport,
+          KB_PORT: port
+        }
+      });
+      if (transport === "stdio" && child.stdin && child.stdout) {
+        process.stdin.pipe(child.stdin);
+        child.stdout.pipe(process.stdout);
+      }
+      child.on("exit", (code) => process.exit(code ?? 0));
+      process.on("SIGINT", () => child.kill("SIGINT"));
+      process.on("SIGTERM", () => child.kill("SIGTERM"));
+      await new Promise(() => {
+      });
+    }
+  },
+  {
+    name: "init",
+    description: "Initialize a knowledge base in the current directory",
+    usage: "kb init [--force]",
+    run: async (args) => {
+      const force = args.includes("--force");
+      const { initProject } = await import("./init.js");
+      await initProject({ force });
+    }
+  },
+  {
+    name: "check",
+    description: "Run incremental typecheck and lint",
+    usage: "kb check [--cwd <dir>] [--files f1,f2] [--skip-types] [--skip-lint]",
+    run: async (args) => {
+      const cwd = extractStrFlag(args, "--cwd", "").trim() || void 0;
+      const filesValue = extractStrFlag(args, "--files", "");
+      const files = filesValue.split(",").map((item) => item.trim()).filter(Boolean);
+      let skipTypes = false;
+      if (args.includes("--skip-types")) {
+        args.splice(args.indexOf("--skip-types"), 1);
+        skipTypes = true;
+      }
+      let skipLint = false;
+      if (args.includes("--skip-lint")) {
+        args.splice(args.indexOf("--skip-lint"), 1);
+        skipLint = true;
+      }
+      const result = await check({
+        cwd,
+        files: files.length > 0 ? files : void 0,
+        skipTypes,
+        skipLint
+      });
+      printCheckResult(result);
+      if (!result.passed) process.exitCode = 1;
+    }
+  },
+  {
+    name: "batch",
+    description: "Execute built-in operations from JSON input",
+    usage: "kb batch [--file path] [--concurrency N]",
+    run: async (args) => {
+      const filePath = extractStrFlag(args, "--file", "").trim() || void 0;
+      const overrideConcurrency = (() => {
+        const idx = args.indexOf("--concurrency");
+        if (idx === -1 || idx + 1 >= args.length) return 0;
+        const val = Number.parseInt(args.splice(idx, 2)[1], 10);
+        return Number.isNaN(val) ? 0 : val;
+      })();
+      const input = await readInput(filePath);
+      if (!input.trim()) {
+        console.error("Usage: kb batch [--file path] [--concurrency N]");
+        process.exit(1);
+      }
+      const payload = parseBatchPayload(input);
+      const concurrency = overrideConcurrency > 0 ? overrideConcurrency : payload.concurrency;
+      const needsContext = payload.operations.some((operation) => operation.type !== "check");
+      const context = needsContext ? await ctx() : null;
+      const result = await batch(
+        payload.operations,
+        async (operation) => executeCliBatchOperation(operation, context),
+        { concurrency }
+      );
+      console.log(JSON.stringify(result, null, 2));
+      if (result.some((item) => item.status === "error")) process.exitCode = 1;
+    }
+  },
+  {
+    name: "health",
+    description: "Run project health checks on the current directory",
+    usage: "kb health [path]",
+    run: async (args) => {
+      const targetPath = args.shift();
+      const result = health(targetPath);
+      console.log(`Project Health: ${result.path}`);
+      console.log("\u2500".repeat(50));
+      for (const check2 of result.checks) {
+        const icon = check2.status === "pass" ? "+" : check2.status === "warn" ? "~" : "X";
+        console.log(`  [${icon}] ${check2.name}: ${check2.message}`);
+      }
+      console.log("\u2500".repeat(50));
+      console.log(`Score: ${result.score}% \u2014 ${result.summary}`);
+    }
+  },
+  {
+    name: "replay",
+    description: "Show recent tool invocation audit trail",
+    usage: "kb replay [--last N] [--tool <name>] [--source mcp|cli]",
+    run: async (args) => {
+      const last = Number.parseInt(args[args.indexOf("--last") + 1], 10) || 20;
+      const toolFilter = args.includes("--tool") ? args[args.indexOf("--tool") + 1] : void 0;
+      const sourceFilter = args.includes("--source") ? args[args.indexOf("--source") + 1] : void 0;
+      const entries = replayList({ last, tool: toolFilter, source: sourceFilter });
+      if (entries.length === 0) {
+        console.log("No replay entries. Activity is logged when tools are invoked.");
+        return;
+      }
+      console.log(`Replay Log (${entries.length} entries)
+`);
+      for (const e of entries) {
+        const time = e.ts.split("T")[1]?.split(".")[0] ?? e.ts;
+        const status = e.status === "ok" ? "\u2713" : "\u2717";
+        console.log(`${time} ${status} ${e.tool} (${e.durationMs}ms) [${e.source}]`);
+        console.log(`  in:  ${e.input}`);
+        console.log(`  out: ${e.output}`);
+      }
+      replayTrim();
+    }
+  },
+  {
+    name: "replay-clear",
+    description: "Clear the replay audit trail",
+    run: async () => {
+      replayClear();
+      console.log("Replay log cleared.");
+    }
+  },
+  {
+    name: "tui",
+    description: "Launch interactive terminal dashboard (human monitoring)",
+    run: async () => {
+      try {
+        const { launch } = await import("@kb/tui");
+        const { store, embedder, config } = await ctx();
+        launch({ store, embedder, config });
+      } catch (err) {
+        if (err.code === "ERR_MODULE_NOT_FOUND") {
+          console.error(
+            "TUI requires ink and react. Install them with:\n  pnpm add -D ink react @types/react"
+          );
+          process.exit(1);
+        }
+        throw err;
+      }
+    }
+  }
+];
+export {
+  systemCommands
+};
+//# sourceMappingURL=system.js.map

package/packages/cli/dist/commands/workspace.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../types.js';
+export declare const workspaceCommands: Command[];
+//# sourceMappingURL=workspace.d.ts.map