@vpxa/kb 0.1.1

package/packages/tools/dist/trace.js

@@ -0,0 +1,114 @@
+async function trace(embedder, store, options) {
+  const { start, direction, maxDepth = 3 } = options;
+  const nodes = [];
+  const visitedTargets = /* @__PURE__ */ new Set();
+  const seenNodes = /* @__PURE__ */ new Set();
+  const startVector = await embedder.embed(start);
+  const startResults = await store.search(startVector, { limit: 10 });
+  if (startResults.length === 0) {
+    return { start, direction, nodes, depth: 0 };
+  }
+  const queue = [{ target: start, depth: 0 }];
+  let maxObservedDepth = 0;
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) break;
+    if (current.depth >= maxDepth) continue;
+    if (visitedTargets.has(current.target)) continue;
+    visitedTargets.add(current.target);
+    const vector = await embedder.embed(current.target);
+    const results = await store.search(vector, { limit: 20 });
+    const escapedTarget = escapeRegExp(current.target);
+    const targetLooksLikeModule = isModuleSpecifier(current.target);
+    for (const result of results) {
+      const lines = result.record.content.split("\n");
+      for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const lineNum = result.record.startLine + index;
+        const path = result.record.sourcePath;
+        if (direction !== "forward") {
+          const importPattern = targetLooksLikeModule ? new RegExp(`from\\s+['"]${escapedTarget}['"]`) : new RegExp(`import\\s+.*\\b${escapedTarget}\\b.*from\\s+`);
+          if (importPattern.test(line)) {
+            addNode(seenNodes, nodes, {
+              path,
+              symbol: current.target,
+              line: lineNum,
+              relationship: "imported-by"
+            });
+            maxObservedDepth = Math.max(maxObservedDepth, current.depth + 1);
+            const fromMatch = line.match(/from\s+['"]([^'"]+)['"]/);
+            if (!targetLooksLikeModule && fromMatch) {
+              queue.push({ target: fromMatch[1], depth: current.depth + 1 });
+            }
+          }
+        }
+        if (direction !== "backward") {
+          if (targetLooksLikeModule) {
+            const moduleImportPattern = new RegExp(`from\\s+['"]${escapedTarget}['"]`);
+            if (moduleImportPattern.test(line)) {
+              addNode(seenNodes, nodes, {
+                path,
+                symbol: current.target,
+                line: lineNum,
+                relationship: "imports"
+              });
+              maxObservedDepth = Math.max(maxObservedDepth, current.depth + 1);
+            }
+          } else {
+            const callPattern = new RegExp(`\\b${escapedTarget}\\s*\\(`);
+            if (callPattern.test(line) && !/^\s*(?:export\s+)?(?:async\s+)?function\s/.test(line)) {
+              addNode(seenNodes, nodes, {
+                path,
+                symbol: current.target,
+                line: lineNum,
+                relationship: "calls"
+              });
+              maxObservedDepth = Math.max(maxObservedDepth, current.depth + 1);
+            }
+          }
+        }
+        const refPattern = targetLooksLikeModule ? new RegExp(`['"]${escapedTarget}['"]`) : new RegExp(`\\b${escapedTarget}\\b`);
+        if (refPattern.test(line) && !/^\s*import\s/.test(line) && !/^\s*(?:export\s+)?(?:async\s+)?function\s/.test(line)) {
+          addNode(seenNodes, nodes, {
+            path,
+            symbol: current.target,
+            line: lineNum,
+            relationship: "references"
+          });
+          maxObservedDepth = Math.max(maxObservedDepth, current.depth + 1);
+        }
+      }
+    }
+  }
+  return {
+    start,
+    direction,
+    nodes: deduplicateNodes(nodes),
+    depth: maxObservedDepth
+  };
+}
+function addNode(seenNodes, nodes, node) {
+  const key = `${node.path}:${node.line}:${node.relationship}`;
+  if (seenNodes.has(key)) return;
+  seenNodes.add(key);
+  nodes.push(node);
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isModuleSpecifier(value) {
+  return /[./\\]/.test(value);
+}
+function deduplicateNodes(nodes) {
+  const seen = /* @__PURE__ */ new Set();
+  return nodes.filter((node) => {
+    const key = `${node.path}:${node.line}:${node.relationship}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+export {
+  trace
+};
+//# sourceMappingURL=trace.js.map

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

@@ -0,0 +1,22 @@
+/**
+ * Smart truncation utilities.
+ *
+ * Head/tail split: preserves both the beginning (context/setup) and
+ * end (errors/results/stack traces) of content. Snaps to line boundaries.
+ */
+/**
+ * Truncate text keeping both head and tail portions.
+ * Critical for process output where errors appear at the end.
+ *
+ * @param text    - Full text to truncate
+ * @param maxLen  - Maximum character length
+ * @param headRatio - Fraction for head portion (default 0.6)
+ * @returns Truncated text with separator showing omitted line/char count
+ */
+export declare function headTailTruncate(text: string, maxLen: number, headRatio?: number): string;
+/**
+ * Truncate at a paragraph boundary near maxLength (head-only).
+ * Best for web content and markdown where structure is at the top.
+ */
+export declare function paragraphTruncate(text: string, maxLen: number): string;
+//# sourceMappingURL=truncation.d.ts.map

package/packages/tools/dist/truncation.js

@@ -0,0 +1,45 @@
+const HEAD_RATIO = 0.6;
+function headTailTruncate(text, maxLen, headRatio = HEAD_RATIO) {
+  if (text.length <= maxLen) return text;
+  const separatorBudget = 120;
+  const contentBudget = Math.max(0, maxLen - separatorBudget);
+  const headBudget = Math.floor(contentBudget * headRatio);
+  const tailBudget = contentBudget - headBudget;
+  const headRegion = text.slice(0, headBudget);
+  const headCut = headRegion.lastIndexOf("\n");
+  const head = headCut > 0 ? headRegion.slice(0, headCut) : headRegion;
+  const tailStart = text.length - tailBudget;
+  const tailRegion = text.slice(tailStart);
+  const tailCut = tailRegion.indexOf("\n");
+  const tail = tailCut >= 0 ? tailRegion.slice(tailCut + 1) : tailRegion;
+  const omittedChars = text.length - head.length - tail.length;
+  let omittedLines = 1;
+  const omittedStart = head.length;
+  const omittedEnd = text.length - tail.length;
+  for (let i = omittedStart; i < omittedEnd; i++) {
+    if (text.charCodeAt(i) === 10) omittedLines++;
+  }
+  return `${head}
+
+[\u2026 ${omittedLines} lines / ${(omittedChars / 1024).toFixed(1)}KB truncated \u2014 showing first ${head.split("\n").length} + last ${tail.split("\n").length} lines]
+
+${tail}`;
+}
+function paragraphTruncate(text, maxLen) {
+  if (text.length <= maxLen) return text;
+  const searchStart = Math.max(0, maxLen - 200);
+  const searchRegion = text.slice(searchStart, maxLen);
+  const lastBreak = searchRegion.lastIndexOf("\n\n");
+  const cutPoint = lastBreak >= 0 ? searchStart + lastBreak : maxLen;
+  const truncated = text.slice(0, cutPoint).trimEnd();
+  const pct = Math.round(cutPoint / text.length * 100);
+  return `${truncated}
+
+---
+*[Truncated at ${cutPoint.toLocaleString()} chars \u2014 ${pct}% of original content]*`;
+}
+export {
+  headTailTruncate,
+  paragraphTruncate
+};
+//# sourceMappingURL=truncation.js.map

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

@@ -0,0 +1,30 @@
+export interface WatchEvent {
+    type: 'change' | 'rename';
+    path: string;
+    timestamp: string;
+}
+export interface WatchOptions {
+    /** Directory to watch */
+    path: string;
+    /** Glob patterns to exclude */
+    exclude?: string[];
+    /** Max events to buffer (default: 100) */
+    maxEvents?: number;
+}
+export interface WatchHandle {
+    id: string;
+    path: string;
+    events: WatchEvent[];
+    status: 'watching' | 'stopped';
+    stop: () => void;
+    getEvents: (since?: string) => WatchEvent[];
+}
+export declare function watchStart(options: WatchOptions): WatchHandle;
+export declare function watchStop(id: string): boolean;
+export declare function watchList(): Array<{
+    id: string;
+    path: string;
+    status: string;
+    eventCount: number;
+}>;
+//# sourceMappingURL=watch.d.ts.map

package/packages/tools/dist/watch.js

@@ -0,0 +1,61 @@
+import { watch } from "node:fs";
+const watchers = /* @__PURE__ */ new Map();
+const DEFAULT_EXCLUDES = ["node_modules", ".git", "dist", ".turbo", ".kb-data", "cdk.out"];
+function watchStart(options) {
+  const { path: watchPath, maxEvents = 100 } = options;
+  const excludes = options.exclude ?? DEFAULT_EXCLUDES;
+  const id = `watch-${Date.now()}`;
+  const events = [];
+  const shouldExclude = (filePath) => excludes.some((pattern) => normalizePath(filePath).includes(normalizePath(pattern)));
+  const watcher = watch(watchPath, { recursive: true }, (eventType, filename) => {
+    if (filename == null) return;
+    const filePath = String(filename);
+    if (!filePath || shouldExclude(filePath)) return;
+    events.push({
+      type: eventType,
+      path: normalizePath(filePath),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    if (events.length > maxEvents) events.shift();
+  });
+  const handle = {
+    id,
+    path: watchPath,
+    events,
+    status: "watching",
+    stop: () => {
+      watcher.close();
+      handle.status = "stopped";
+      watchers.delete(id);
+    },
+    getEvents: (since) => {
+      if (!since) return events;
+      return events.filter((event) => event.timestamp > since);
+    }
+  };
+  watchers.set(id, { watcher, handle });
+  return handle;
+}
+function watchStop(id) {
+  const entry = watchers.get(id);
+  if (!entry) return false;
+  entry.handle.stop();
+  return true;
+}
+function watchList() {
+  return [...watchers.values()].map((entry) => ({
+    id: entry.handle.id,
+    path: entry.handle.path,
+    status: entry.handle.status,
+    eventCount: entry.handle.events.length
+  }));
+}
+function normalizePath(value) {
+  return value.replace(/\\/g, "/");
+}
+export {
+  watchList,
+  watchStart,
+  watchStop
+};
+//# sourceMappingURL=watch.js.map

package/packages/tools/dist/web-fetch.d.ts

@@ -0,0 +1,45 @@
+/**
+ * kb_web_fetch — Fetch a web page and convert to LLM-friendly format.
+ *
+ * Supports multiple output modes: markdown (default), raw HTML,
+ * extracted links, or heading outline. Strips scripts, styles,
+ * and non-content elements for compact, token-efficient output.
+ */
+export type WebFetchMode = 'markdown' | 'raw' | 'links' | 'outline';
+export interface WebFetchOptions {
+    /** URL to fetch */
+    url: string;
+    /** Output mode */
+    mode?: WebFetchMode;
+    /** CSS selector to extract specific element (default: auto-detect main content) */
+    selector?: string;
+    /** Max characters in output — smart truncation at paragraph boundaries */
+    maxLength?: number;
+    /** Include page metadata header (title, description, URL) */
+    includeMetadata?: boolean;
+    /** Append extracted links list at the end */
+    includeLinks?: boolean;
+    /** Include image alt texts inline */
+    includeImages?: boolean;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+export interface WebFetchResult {
+    /** The converted content */
+    content: string;
+    /** Page title */
+    title: string;
+    /** Page description (from meta) */
+    description: string;
+    /** Final URL after redirects */
+    url: string;
+    /** Content length before truncation */
+    originalLength: number;
+    /** Whether content was truncated */
+    truncated: boolean;
+}
+/**
+ * Fetch a web page and convert to an LLM-friendly format.
+ */
+export declare function webFetch(options: WebFetchOptions): Promise<WebFetchResult>;
+//# sourceMappingURL=web-fetch.d.ts.map

package/packages/tools/dist/web-fetch.js

@@ -0,0 +1,249 @@
+import TurndownService from "turndown";
+import { paragraphTruncate } from "./truncation.js";
+const DEFAULT_MAX_LENGTH = 15e3;
+const DEFAULT_TIMEOUT = 15e3;
+const STRIP_ELEMENTS = [
+  "script",
+  "style",
+  "noscript",
+  "iframe",
+  "svg",
+  "nav",
+  "footer",
+  "header",
+  "aside",
+  "form",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  '[role="navigation"]',
+  '[role="banner"]',
+  '[role="contentinfo"]',
+  '[aria-hidden="true"]',
+  ".sidebar",
+  ".nav",
+  ".menu",
+  ".footer",
+  ".header",
+  ".ad",
+  ".advertisement",
+  ".cookie-banner",
+  ".popup",
+  ".modal"
+];
+const MAIN_CONTENT_SELECTORS = [
+  "article",
+  '[role="main"]',
+  "main",
+  ".post-content",
+  ".article-content",
+  ".entry-content",
+  ".content",
+  "#content",
+  ".prose",
+  ".markdown-body",
+  ".documentation",
+  ".doc-content"
+];
+async function webFetch(options) {
+  const {
+    url,
+    mode = "markdown",
+    selector,
+    maxLength = DEFAULT_MAX_LENGTH,
+    includeMetadata = true,
+    includeLinks = false,
+    includeImages = false,
+    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);
+  let response;
+  try {
+    response = await fetch(url, {
+      signal: controller.signal,
+      headers: {
+        "User-Agent": "kb-web-fetch/1.0 (LLM context tool)",
+        Accept: "text/html,application/xhtml+xml,text/plain"
+      },
+      redirect: "follow"
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  const isHtml = /text\/html|application\/xhtml\+xml/i.test(contentType);
+  const responseText = await response.text();
+  const finalUrl = response.url;
+  if (!isHtml) {
+    let content2 = responseText;
+    const title2 = finalUrl.split("/").pop() ?? "";
+    if (includeMetadata) {
+      const meta = buildMetadataHeader(title2, "", finalUrl);
+      content2 = meta + content2;
+    }
+    const originalLength2 = content2.length;
+    const truncated2 = originalLength2 > maxLength;
+    if (truncated2) {
+      content2 = smartTruncate(content2, maxLength);
+    }
+    return { content: content2, title: title2, description: "", url: finalUrl, originalLength: originalLength2, truncated: truncated2 };
+  }
+  const { parseHTML } = await import("linkedom");
+  const { document } = parseHTML(responseText);
+  const title = document.querySelector("title")?.textContent?.trim() ?? document.querySelector('meta[property="og:title"]')?.getAttribute("content")?.trim() ?? "";
+  const description = document.querySelector('meta[name="description"]')?.getAttribute("content")?.trim() ?? document.querySelector('meta[property="og:description"]')?.getAttribute("content")?.trim() ?? "";
+  for (const sel of STRIP_ELEMENTS) {
+    for (const el of document.querySelectorAll(sel)) {
+      el.remove();
+    }
+  }
+  if (!includeImages) {
+    for (const img of document.querySelectorAll("img")) {
+      img.remove();
+    }
+  }
+  let contentEl = null;
+  if (selector) {
+    contentEl = document.querySelector(selector);
+    if (!contentEl) {
+      throw new Error(`Selector "${selector}" matched no elements on the page`);
+    }
+  } else {
+    for (const s of MAIN_CONTENT_SELECTORS) {
+      contentEl = document.querySelector(s);
+      if (contentEl) break;
+    }
+    if (!contentEl) {
+      contentEl = document.querySelector("body");
+    }
+  }
+  if (!contentEl) {
+    return {
+      content: "(empty page \u2014 no content found)",
+      title,
+      description,
+      url: finalUrl,
+      originalLength: 0,
+      truncated: false
+    };
+  }
+  const contentHtml = contentEl.innerHTML;
+  const links = [];
+  if (includeLinks || mode === "links") {
+    for (const a of contentEl.querySelectorAll("a[href]")) {
+      const text = a.textContent?.trim();
+      const href = a.getAttribute("href");
+      if (text && href && !href.startsWith("#") && !href.startsWith("javascript:")) {
+        links.push({ text, href: resolveUrl(href, finalUrl) });
+      }
+    }
+  }
+  let content;
+  switch (mode) {
+    case "raw":
+      content = contentHtml;
+      break;
+    case "links":
+      content = formatLinks(links);
+      break;
+    case "outline":
+      content = extractOutline(contentEl);
+      break;
+    default:
+      content = htmlToMarkdown(contentHtml, includeImages);
+      break;
+  }
+  if (includeMetadata && mode !== "links") {
+    const meta = buildMetadataHeader(title, description, finalUrl);
+    content = meta + content;
+  }
+  if (includeLinks && mode !== "links" && links.length > 0) {
+    content += `
+
+---
+
+## Links
+
+${formatLinks(links)}`;
+  }
+  const originalLength = content.length;
+  const truncated = originalLength > maxLength;
+  if (truncated) {
+    content = smartTruncate(content, maxLength);
+  }
+  return { content, title, description, url: finalUrl, originalLength, truncated };
+}
+function htmlToMarkdown(html, includeImages) {
+  const td = new TurndownService({
+    headingStyle: "atx",
+    codeBlockStyle: "fenced",
+    bulletListMarker: "-"
+  });
+  td.addRule("emptyLinks", {
+    filter: (node) => node.nodeName === "A" && !node.textContent?.trim(),
+    replacement: () => ""
+  });
+  if (!includeImages) {
+    td.addRule("removeImages", {
+      filter: "img",
+      replacement: () => ""
+    });
+  }
+  let md = td.turndown(html);
+  md = md.replace(/\n{3,}/g, "\n\n").trim();
+  return md;
+}
+function extractOutline(element) {
+  const headings = element.querySelectorAll("h1, h2, h3, h4, h5, h6");
+  const lines = [];
+  for (const h of headings) {
+    const level = Number.parseInt(h.tagName.slice(1), 10);
+    const indent = "  ".repeat(level - 1);
+    const text = h.textContent?.trim() ?? "";
+    if (text) {
+      lines.push(`${indent}- ${text}`);
+    }
+  }
+  return lines.length > 0 ? lines.join("\n") : "(no headings found)";
+}
+function formatLinks(links) {
+  if (links.length === 0) return "(no links found)";
+  const seen = /* @__PURE__ */ new Set();
+  const unique = [];
+  for (const link of links) {
+    if (!seen.has(link.href)) {
+      seen.add(link.href);
+      unique.push(link);
+    }
+  }
+  return unique.map((l) => `- [${l.text}](${l.href})`).join("\n");
+}
+function buildMetadataHeader(title, description, url) {
+  const parts = ["---"];
+  if (title) parts.push(`**${title}**`);
+  parts.push(`URL: ${url}`);
+  if (description) parts.push(`> ${description}`);
+  parts.push("---\n\n");
+  return parts.join("\n");
+}
+function resolveUrl(href, base) {
+  try {
+    return new URL(href, base).href;
+  } catch {
+    return href;
+  }
+}
+const smartTruncate = paragraphTruncate;
+export {
+  webFetch
+};
+//# sourceMappingURL=web-fetch.js.map

package/packages/tools/dist/web-search.d.ts

@@ -0,0 +1,23 @@
+/**
+ * kb_web_search — Search the web and return structured results.
+ *
+ * Uses DuckDuckGo HTML search (no API key required).
+ */
+export interface WebSearchOptions {
+    query: string;
+    limit?: number;
+    site?: string;
+}
+export interface WebSearchResultItem {
+    title: string;
+    url: string;
+    snippet: string;
+}
+export interface WebSearchResult {
+    results: WebSearchResultItem[];
+    query: string;
+}
+export declare function webSearch(options: WebSearchOptions): Promise<WebSearchResult>;
+/** Parse search results from DuckDuckGo HTML. Exported for testing. */
+export declare function parseSearchResults(html: string, query: string, limit: number): WebSearchResult;
+//# sourceMappingURL=web-search.d.ts.map

package/packages/tools/dist/web-search.js

@@ -0,0 +1,46 @@
+const DEFAULT_LIMIT = 5;
+async function webSearch(options) {
+  const { query, limit = DEFAULT_LIMIT, site } = options;
+  if (!query.trim()) throw new Error("Search query cannot be empty");
+  const searchQuery = site ? `${query} site:${site}` : query;
+  const response = await fetch("https://html.duckduckgo.com/html/", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      "User-Agent": "kb-web-search/1.0 (LLM developer tool)"
+    },
+    body: `q=${encodeURIComponent(searchQuery)}`
+  });
+  if (!response.ok) {
+    throw new Error(`Search failed: HTTP ${response.status}`);
+  }
+  const html = await response.text();
+  return parseSearchResults(html, searchQuery, limit);
+}
+function parseSearchResults(html, query, limit) {
+  const results = [];
+  const blockRegex = /<a[^>]+class="result__a"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?<a[^>]+class="result__snippet"[^>]*>([\s\S]*?)<\/a>/gi;
+  let match = blockRegex.exec(html);
+  while (match !== null && results.length < limit) {
+    let url = match[1];
+    const title = stripHtml(match[2]).trim();
+    const snippet = stripHtml(match[3]).trim();
+    if (url.includes("uddg=")) {
+      const decoded = url.match(/uddg=([^&]+)/)?.[1];
+      if (decoded) url = decodeURIComponent(decoded);
+    }
+    if (title && url?.startsWith("http")) {
+      results.push({ title, url, snippet });
+    }
+    match = blockRegex.exec(html);
+  }
+  return { results, query };
+}
+function stripHtml(html) {
+  return html.replace(/<[^>]+>/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#x27;/g, "'");
+}
+export {
+  parseSearchResults,
+  webSearch
+};
+//# sourceMappingURL=web-search.js.map

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

@@ -0,0 +1,45 @@
+/**
+ * kb_workset — Named file set management.
+ *
+ * Persistent worksets stored in .kb-state/worksets.json.
+ * Use cases: "remember this set of files I'm working on",
+ * "load my previous context", "share file sets between sessions".
+ */
+export interface Workset {
+    name: string;
+    files: string[];
+    created: string;
+    updated: string;
+    description?: string;
+}
+export interface WorksetStore {
+    worksets: Record<string, Workset>;
+}
+/**
+ * Create or update a workset.
+ */
+export declare function saveWorkset(name: string, files: string[], options?: {
+    description?: string;
+    cwd?: string;
+}): Workset;
+/**
+ * Get a workset by name.
+ */
+export declare function getWorkset(name: string, cwd?: string): Workset | null;
+/**
+ * List all worksets.
+ */
+export declare function listWorksets(cwd?: string): Workset[];
+/**
+ * Delete a workset.
+ */
+export declare function deleteWorkset(name: string, cwd?: string): boolean;
+/**
+ * Add files to an existing workset (creates if not exists).
+ */
+export declare function addToWorkset(name: string, files: string[], cwd?: string): Workset;
+/**
+ * Remove files from a workset.
+ */
+export declare function removeFromWorkset(name: string, files: string[], cwd?: string): Workset | null;
+//# sourceMappingURL=workset.d.ts.map