@vpxa/kb 0.1.1

package/packages/tools/dist/graph-query.d.ts

@@ -0,0 +1,89 @@
+/**
+ * kb_graph — Knowledge graph query tools.
+ *
+ * Query, traverse, and manage the entity-relationship knowledge graph.
+ * The graph complements vector search with structural reasoning:
+ * vector search finds similar content, graph traversal finds connected concepts.
+ */
+import type { GraphEdge, GraphNode, GraphStats, GraphTraversalResult, IGraphStore } from '@kb/store';
+export interface GraphQueryOptions {
+    /** Action: query nodes, traverse from a node, get stats, or add data */
+    action: 'find_nodes' | 'find_edges' | 'neighbors' | 'traverse' | 'stats' | 'add' | 'delete' | 'clear';
+    /** Node type filter (for find_nodes) */
+    nodeType?: string;
+    /** Name pattern (LIKE %pattern%) for find_nodes */
+    namePattern?: string;
+    /** Source path filter */
+    sourcePath?: string;
+    /** Node ID for neighbors/traverse/delete */
+    nodeId?: string;
+    /** Edge type filter */
+    edgeType?: string;
+    /** From node ID (for find_edges) */
+    fromId?: string;
+    /** To node ID (for find_edges) */
+    toId?: string;
+    /** Traversal direction */
+    direction?: 'outgoing' | 'incoming' | 'both';
+    /** Max traversal depth (default: 2) */
+    maxDepth?: number;
+    /** Max results (default: 50) */
+    limit?: number;
+    /** Nodes to add (for action=add) */
+    nodes?: Array<{
+        id?: string;
+        type: string;
+        name: string;
+        properties?: Record<string, unknown>;
+        sourceRecordId?: string;
+        sourcePath?: string;
+    }>;
+    /** Edges to add (for action=add) */
+    edges?: Array<{
+        id?: string;
+        fromId: string;
+        toId: string;
+        type: string;
+        weight?: number;
+        properties?: Record<string, unknown>;
+    }>;
+}
+export interface GraphQueryResult {
+    action: string;
+    nodes?: GraphNode[];
+    edges?: GraphEdge[];
+    stats?: GraphStats;
+    nodesAdded?: number;
+    edgesAdded?: number;
+    deleted?: number;
+    summary: string;
+}
+export declare function graphQuery(graphStore: IGraphStore, options: GraphQueryOptions): Promise<GraphQueryResult>;
+export interface GraphAugmentOptions {
+    /** Max graph hops from each vector hit (default: 1) */
+    hops?: number;
+    /** Edge type filter for graph expansion */
+    edgeType?: string;
+    /** Max graph nodes per vector hit (default: 5) */
+    maxPerHit?: number;
+}
+export interface GraphAugmentedResult {
+    /** Original search result record ID */
+    recordId: string;
+    /** Original similarity score */
+    score: number;
+    /** Source path of the matched record */
+    sourcePath: string;
+    /** Graph nodes connected to this record (via sourceRecordId) */
+    graphContext: GraphTraversalResult;
+}
+/**
+ * Augment vector search results with graph context.
+ * For each search hit, finds linked graph nodes and traverses their connections.
+ */
+export declare function graphAugmentSearch(graphStore: IGraphStore, hits: Array<{
+    recordId: string;
+    score: number;
+    sourcePath: string;
+}>, options?: GraphAugmentOptions): Promise<GraphAugmentedResult[]>;
+//# sourceMappingURL=graph-query.d.ts.map

package/packages/tools/dist/graph-query.js

@@ -0,0 +1,194 @@
+import { createHash } from "node:crypto";
+function generateId(prefix, ...parts) {
+  return `${prefix}_${createHash("sha256").update(parts.join("|")).digest("hex").slice(0, 12)}`;
+}
+async function graphQuery(graphStore, options) {
+  const { action } = options;
+  switch (action) {
+    case "find_nodes": {
+      const nodes = await graphStore.findNodes({
+        type: options.nodeType,
+        namePattern: options.namePattern,
+        sourcePath: options.sourcePath,
+        limit: options.limit
+      });
+      return {
+        action,
+        nodes,
+        summary: `Found ${nodes.length} node(s)${options.nodeType ? ` of type "${options.nodeType}"` : ""}${options.namePattern ? ` matching "${options.namePattern}"` : ""}`
+      };
+    }
+    case "find_edges": {
+      const edges = await graphStore.findEdges({
+        type: options.edgeType,
+        fromId: options.fromId,
+        toId: options.toId,
+        limit: options.limit
+      });
+      return {
+        action,
+        edges,
+        summary: `Found ${edges.length} edge(s)${options.edgeType ? ` of type "${options.edgeType}"` : ""}`
+      };
+    }
+    case "neighbors": {
+      if (!options.nodeId) {
+        return { action, summary: "Error: nodeId is required for neighbors action" };
+      }
+      const result = await graphStore.getNeighbors(options.nodeId, {
+        edgeType: options.edgeType,
+        direction: options.direction,
+        limit: options.limit
+      });
+      return {
+        action,
+        nodes: result.nodes,
+        edges: result.edges,
+        summary: `Found ${result.nodes.length} neighbor(s) and ${result.edges.length} edge(s) for node "${options.nodeId}"`
+      };
+    }
+    case "traverse": {
+      if (!options.nodeId) {
+        return { action, summary: "Error: nodeId is required for traverse action" };
+      }
+      const result = await graphStore.traverse(options.nodeId, {
+        edgeType: options.edgeType,
+        maxDepth: options.maxDepth,
+        direction: options.direction,
+        limit: options.limit
+      });
+      return {
+        action,
+        nodes: result.nodes,
+        edges: result.edges,
+        summary: `Traversed ${result.nodes.length} node(s) and ${result.edges.length} edge(s) from "${options.nodeId}" (depth=${options.maxDepth ?? 2})`
+      };
+    }
+    case "stats": {
+      const stats = await graphStore.getStats();
+      return {
+        action,
+        stats,
+        summary: `Graph: ${stats.nodeCount} nodes, ${stats.edgeCount} edges. Types: ${Object.entries(stats.nodeTypes).map(([t, c]) => `${t}(${c})`).join(", ") || "none"}`
+      };
+    }
+    case "add": {
+      let nodesAdded = 0;
+      let edgesAdded = 0;
+      if (options.nodes && options.nodes.length > 0) {
+        const graphNodes = options.nodes.map((n) => ({
+          id: n.id ?? generateId("node", n.type, n.name),
+          type: n.type,
+          name: n.name,
+          properties: n.properties ?? {},
+          sourceRecordId: n.sourceRecordId,
+          sourcePath: n.sourcePath,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString()
+        }));
+        await graphStore.upsertNodes(graphNodes);
+        nodesAdded = graphNodes.length;
+      }
+      if (options.edges && options.edges.length > 0) {
+        const graphEdges = options.edges.map((e) => ({
+          id: e.id ?? generateId("edge", e.fromId, e.toId, e.type),
+          fromId: e.fromId,
+          toId: e.toId,
+          type: e.type,
+          weight: e.weight,
+          properties: e.properties
+        }));
+        await graphStore.upsertEdges(graphEdges);
+        edgesAdded = graphEdges.length;
+      }
+      return {
+        action,
+        nodesAdded,
+        edgesAdded,
+        summary: `Added ${nodesAdded} node(s) and ${edgesAdded} edge(s) to the graph`
+      };
+    }
+    case "delete": {
+      if (options.nodeId) {
+        await graphStore.deleteNode(options.nodeId);
+        return { action, deleted: 1, summary: `Deleted node "${options.nodeId}" and its edges` };
+      }
+      if (options.sourcePath) {
+        const count = await graphStore.deleteBySourcePath(options.sourcePath);
+        return {
+          action,
+          deleted: count,
+          summary: `Deleted ${count} node(s) from source "${options.sourcePath}"`
+        };
+      }
+      return { action, summary: "Error: nodeId or sourcePath required for delete action" };
+    }
+    case "clear": {
+      const stats = await graphStore.getStats();
+      await graphStore.clear();
+      return {
+        action,
+        deleted: stats.nodeCount,
+        summary: `Cleared graph: removed ${stats.nodeCount} node(s) and ${stats.edgeCount} edge(s)`
+      };
+    }
+    default:
+      return { action, summary: `Unknown action: ${action}` };
+  }
+}
+async function graphAugmentSearch(graphStore, hits, options) {
+  const hops = options?.hops ?? 1;
+  const maxPerHit = options?.maxPerHit ?? 5;
+  const results = [];
+  for (const hit of hits) {
+    try {
+      const linkedNodes = await graphStore.findNodes({ sourcePath: hit.sourcePath });
+      const allNodes = [];
+      const allEdges = [];
+      const seenNodeIds = /* @__PURE__ */ new Set();
+      const seenEdgeIds = /* @__PURE__ */ new Set();
+      for (const node of linkedNodes.slice(0, maxPerHit)) {
+        if (seenNodeIds.has(node.id)) continue;
+        seenNodeIds.add(node.id);
+        allNodes.push(node);
+        if (hops > 0) {
+          const traversal = await graphStore.traverse(node.id, {
+            maxDepth: hops,
+            edgeType: options?.edgeType,
+            limit: maxPerHit
+          });
+          for (const n of traversal.nodes) {
+            if (!seenNodeIds.has(n.id)) {
+              seenNodeIds.add(n.id);
+              allNodes.push(n);
+            }
+          }
+          for (const e of traversal.edges) {
+            if (!seenEdgeIds.has(e.id)) {
+              seenEdgeIds.add(e.id);
+              allEdges.push(e);
+            }
+          }
+        }
+      }
+      results.push({
+        recordId: hit.recordId,
+        score: hit.score,
+        sourcePath: hit.sourcePath,
+        graphContext: { nodes: allNodes, edges: allEdges }
+      });
+    } catch {
+      results.push({
+        recordId: hit.recordId,
+        score: hit.score,
+        sourcePath: hit.sourcePath,
+        graphContext: { nodes: [], edges: [] }
+      });
+    }
+  }
+  return results;
+}
+export {
+  graphAugmentSearch,
+  graphQuery
+};
+//# sourceMappingURL=graph-query.js.map

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

@@ -0,0 +1,14 @@
+export interface HealthCheck {
+    name: string;
+    status: 'pass' | 'warn' | 'fail';
+    message: string;
+}
+export interface HealthResult {
+    path: string;
+    checks: HealthCheck[];
+    score: number;
+    summary: string;
+}
+/** Run project health checks on a directory. */
+export declare function health(rootPath?: string): HealthResult;
+//# sourceMappingURL=health.d.ts.map

package/packages/tools/dist/health.js

@@ -0,0 +1,118 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+function health(rootPath) {
+  const root = resolve(rootPath ?? process.cwd());
+  const checks = [];
+  const pkgPath = join(root, "package.json");
+  if (existsSync(pkgPath)) {
+    checks.push({ name: "package.json", status: "pass", message: "Found" });
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      if (!pkg.name) {
+        checks.push({ name: "package.name", status: "warn", message: "Missing package name" });
+      } else {
+        checks.push({ name: "package.name", status: "pass", message: pkg.name });
+      }
+      const scripts = pkg.scripts ?? {};
+      for (const script of ["build", "test", "lint"]) {
+        if (scripts[script]) {
+          checks.push({ name: `script:${script}`, status: "pass", message: scripts[script] });
+        } else {
+          checks.push({
+            name: `script:${script}`,
+            status: "warn",
+            message: `No "${script}" script defined`
+          });
+        }
+      }
+      if (pkg.type === "module") {
+        checks.push({ name: "esm", status: "pass", message: 'ESM ("type": "module")' });
+      } else if (pkg.type === "commonjs") {
+        checks.push({ name: "esm", status: "pass", message: 'CJS ("type": "commonjs")' });
+      } else {
+        checks.push({ name: "esm", status: "warn", message: 'No "type" field \u2014 defaults to CJS' });
+      }
+      if (pkg.engines?.node) {
+        checks.push({ name: "engines.node", status: "pass", message: pkg.engines.node });
+      } else {
+        checks.push({
+          name: "engines.node",
+          status: "warn",
+          message: "No Node.js engine constraint"
+        });
+      }
+    } catch {
+      checks.push({
+        name: "package.json",
+        status: "fail",
+        message: "Failed to parse package.json"
+      });
+    }
+  } else {
+    checks.push({
+      name: "package.json",
+      status: "fail",
+      message: "Missing \u2014 not a Node.js project"
+    });
+  }
+  const tsconfigPath = join(root, "tsconfig.json");
+  if (existsSync(tsconfigPath)) {
+    checks.push({ name: "tsconfig.json", status: "pass", message: "Found" });
+  } else {
+    checks.push({ name: "tsconfig.json", status: "warn", message: "Missing" });
+  }
+  const gitignorePath = join(root, ".gitignore");
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, "utf-8");
+    const hasNodeModules = content.includes("node_modules");
+    const hasDist = content.includes("dist");
+    if (hasNodeModules && hasDist) {
+      checks.push({
+        name: ".gitignore",
+        status: "pass",
+        message: "Includes node_modules and dist"
+      });
+    } else {
+      checks.push({
+        name: ".gitignore",
+        status: "warn",
+        message: `Missing: ${!hasNodeModules ? "node_modules " : ""}${!hasDist ? "dist" : ""}`.trim()
+      });
+    }
+  } else {
+    checks.push({ name: ".gitignore", status: "warn", message: "Missing" });
+  }
+  const lockFiles = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lock"];
+  const foundLock = lockFiles.find((f) => existsSync(join(root, f)));
+  if (foundLock) {
+    checks.push({ name: "lockfile", status: "pass", message: foundLock });
+  } else {
+    checks.push({ name: "lockfile", status: "warn", message: "No lock file found" });
+  }
+  const readmePath = join(root, "README.md");
+  if (existsSync(readmePath)) {
+    const size = readFileSync(readmePath, "utf-8").length;
+    checks.push({
+      name: "README.md",
+      status: size > 100 ? "pass" : "warn",
+      message: size > 100 ? `Found (${size} chars)` : "Found but very short"
+    });
+  } else {
+    checks.push({ name: "README.md", status: "warn", message: "Missing" });
+  }
+  if (existsSync(join(root, "LICENSE")) || existsSync(join(root, "LICENSE.md"))) {
+    checks.push({ name: "LICENSE", status: "pass", message: "Found" });
+  } else {
+    checks.push({ name: "LICENSE", status: "warn", message: "Missing" });
+  }
+  const total = checks.length;
+  const passed = checks.filter((c) => c.status === "pass").length;
+  const failed = checks.filter((c) => c.status === "fail").length;
+  const score = Math.round(passed / total * 100);
+  const summary = failed > 0 ? `${failed} critical issue(s), ${total - passed - failed} warning(s)` : total - passed > 0 ? `${total - passed} warning(s)` : "All checks passed";
+  return { path: root, checks, score, summary };
+}
+export {
+  health
+};
+//# sourceMappingURL=health.js.map

package/packages/tools/dist/http-request.d.ts

@@ -0,0 +1,23 @@
+/**
+ * kb_http — Make HTTP requests for API testing and debugging.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+export interface HttpRequestOptions {
+    url: string;
+    method?: HttpMethod;
+    headers?: Record<string, string>;
+    body?: string;
+    timeout?: number;
+}
+export interface HttpRequestResult {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+    durationMs: number;
+    contentType: string;
+    sizeBytes: number;
+    truncated: boolean;
+}
+export declare function httpRequest(options: HttpRequestOptions): Promise<HttpRequestResult>;
+//# sourceMappingURL=http-request.d.ts.map

package/packages/tools/dist/http-request.js

@@ -0,0 +1,58 @@
+import { headTailTruncate } from "./truncation.js";
+const MAX_BODY_SIZE = 5e4;
+const DEFAULT_TIMEOUT = 15e3;
+async function httpRequest(options) {
+  const { url, method = "GET", headers = {}, body, timeout = DEFAULT_TIMEOUT } = options;
+  const parsed = new URL(url);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`Unsupported protocol: ${parsed.protocol} \u2014 only http/https allowed`);
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  const start = Date.now();
+  let response;
+  try {
+    response = await fetch(url, {
+      method,
+      headers: { "User-Agent": "kb-http/1.0", ...headers },
+      body: method !== "GET" && method !== "HEAD" ? body : void 0,
+      signal: controller.signal,
+      redirect: "follow"
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+  const durationMs = Date.now() - start;
+  const responseText = await response.text();
+  const contentType = response.headers.get("content-type") ?? "";
+  let formattedBody = responseText;
+  if (contentType.includes("json")) {
+    try {
+      formattedBody = JSON.stringify(JSON.parse(responseText), null, 2);
+    } catch {
+    }
+  }
+  let truncated = false;
+  if (formattedBody.length > MAX_BODY_SIZE) {
+    formattedBody = headTailTruncate(formattedBody, MAX_BODY_SIZE);
+    truncated = true;
+  }
+  const responseHeaders = {};
+  response.headers.forEach((value, key) => {
+    responseHeaders[key] = value;
+  });
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    headers: responseHeaders,
+    body: formattedBody,
+    durationMs,
+    contentType,
+    sizeBytes: responseText.length,
+    truncated
+  };
+}
+export {
+  httpRequest
+};
+//# sourceMappingURL=http-request.js.map

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

@@ -0,0 +1,49 @@
+export { type BatchOperation, type BatchOptions, type BatchResult, batch, } from './batch.js';
+export { type ChangelogEntry, type ChangelogFormat, type ChangelogOptions, type ChangelogResult, changelog, formatChangelog, } from './changelog.js';
+export { type CheckOptions, type CheckResult, check } from './check.js';
+export { type Checkpoint, checkpointLatest, checkpointList, checkpointLoad, checkpointSave, } from './checkpoint.js';
+export { type CodemodChange, type CodemodOptions, type CodemodResult, type CodemodRule, codemod, } from './codemod.js';
+export { type CompactOptions, type CompactResult, compact } from './compact.js';
+export { dataTransform, type TransformOptions, type TransformResult, } from './data-transform.js';
+export { type DeadSymbol, type DeadSymbolOptions, type DeadSymbolResult, findDeadSymbols, } from './dead-symbols.js';
+export { type DelegateOptions, type DelegateResult, delegate, delegateListModels, } from './delegate.js';
+export { type DiffChange, type DiffFile, type DiffHunk, type DiffParseOptions, diffParse, } from './diff-parse.js';
+export { type DigestFieldEntry, type DigestOptions, type DigestResult, type DigestSource, digest, } from './digest.js';
+export { type EncodeOperation, type EncodeOptions, type EncodeResult, encode, } from './encode.js';
+export { type EnvInfoOptions, type EnvInfoResult, envInfo, } from './env-info.js';
+export { type EvalOptions, type EvalResult, evaluate } from './eval.js';
+export { type EvidenceEntry, type EvidenceMapAction, type EvidenceMapResult, type EvidenceMapState, type EvidenceStatus, evidenceMap, type ForgeTier, type GateDecision, type GateResult, type UnknownType, } from './evidence-map.js';
+export { type FileSummaryOptions, type FileSummaryResult, fileSummary, } from './file-summary.js';
+export { type FindOptions, type FindResult, type FindResults, find } from './find.js';
+export { type Example, type FindExamplesOptions, type FindExamplesResult, findExamples, } from './find-examples.js';
+export { type ClassifyTrigger, type ForgeClassifyCeremony, type ForgeClassifyOptions, type ForgeClassifyResult, forgeClassify, type TypedUnknownSeed, } from './forge-classify.js';
+export { type ConstraintRef, type ForgeGroundOptions, type ForgeGroundResult, forgeGround, } from './forge-ground.js';
+export { type GitContextOptions, type GitContextResult, gitContext, } from './git-context.js';
+export { type GraphAugmentedResult, type GraphAugmentOptions, type GraphQueryOptions, type GraphQueryResult, graphAugmentSearch, graphQuery, } from './graph-query.js';
+export { type HealthCheck, type HealthResult, health, } from './health.js';
+export { type HttpMethod, type HttpRequestOptions, type HttpRequestResult, httpRequest, } from './http-request.js';
+export { type LaneDiffEntry, type LaneDiffResult, type LaneMergeResult, type LaneMeta, laneCreate, laneDiff, laneDiscard, laneList, laneMerge, laneStatus, } from './lane.js';
+export { analyzeFile, type FileMetrics, type MeasureOptions, type MeasureResult, measure, } from './measure.js';
+export { type OnboardMode, type OnboardOptions, type OnboardResult, type OnboardStepResult, onboard, } from './onboard.js';
+export { type ParsedError, type ParsedGitStatus, type ParsedOutput, type ParsedTestResult, type ParsedTestSummary, parseBiome, parseGitStatus, parseOutput, parseTsc, parseVitest, } from './parse-output.js';
+export { type ManagedProcess, processList, processLogs, processStart, processStatus, processStop, } from './process-manager.js';
+export { type QueueItem, type QueueState, queueClear, queueCreate, queueDelete, queueDone, queueFail, queueGet, queueList, queueNext, queuePush, } from './queue.js';
+export { type RegexTestOptions, type RegexTestResult, regexTest, } from './regex-test.js';
+export { type RenameChange, type RenameOptions, type RenameResult, rename, } from './rename.js';
+export { type ReplayEntry, type ReplayOptions, replayAppend, replayCapture, replayClear, replayList, replayTrim, } from './replay.js';
+export { type SchemaValidateOptions, type SchemaValidateResult, schemaValidate, type ValidationError, } from './schema-validate.js';
+export { type ScopeMapEntry, type ScopeMapOptions, type ScopeMapResult, scopeMap, } from './scope-map.js';
+export { type Snippet, type SnippetAction, type SnippetOptions, type SnippetResult, snippet, } from './snippet.js';
+export { type StashEntry, stashClear, stashDelete, stashGet, stashList, stashSet, } from './stash.js';
+export { type StratumCard, type StratumCardOptions, type StratumCardResult, stratumCard, } from './stratum-card.js';
+export { type SymbolInfo, type SymbolOptions, symbol } from './symbol.js';
+export { classifyExitCode, type TestRunOptions, type TestRunResult, testRun } from './test-run.js';
+export { cosineSimilarity, estimateTokens, segment, } from './text-utils.js';
+export { type TimeOptions, type TimeResult, timeUtils, } from './time-utils.js';
+export { type TraceNode, type TraceOptions, type TraceResult, trace } from './trace.js';
+export { headTailTruncate, paragraphTruncate } from './truncation.js';
+export { type WatchEvent, type WatchHandle, type WatchOptions, watchList, watchStart, watchStop, } from './watch.js';
+export { type WebFetchMode, type WebFetchOptions, type WebFetchResult, webFetch, } from './web-fetch.js';
+export { parseSearchResults, type WebSearchOptions, type WebSearchResult, type WebSearchResultItem, webSearch, } from './web-search.js';
+export { addToWorkset, deleteWorkset, getWorkset, listWorksets, removeFromWorkset, saveWorkset, type Workset, } from './workset.js';
+//# sourceMappingURL=index.d.ts.map