@vpxa/kb 0.1.1

package/packages/tools/dist/digest.js

@@ -0,0 +1,242 @@
+import { cosineSimilarity, estimateTokens, segment } from "./text-utils.js";
+const DEFAULT_PIN_FIELDS = [
+  "status",
+  "files",
+  "decisions",
+  "blockers",
+  "artifacts",
+  "next"
+];
+const PIN_PATTERNS = {
+  status: /\b(?:status|result)\s*[:=]/i,
+  files: /\b(?:files?|modified|created|deleted)\s*[:=]/i,
+  artifacts: /\b(?:artifacts?)\s*[:=]/i,
+  decisions: /\b(?:decisions?|decided|chose|selected)\s*[:=]/i,
+  blockers: /\b(?:blockers?|blocked|blocking)\s*[:=]/i,
+  next: /\b(?:next\s*(?:steps?|actions?)|todo|follow.up)\s*[:=]/i
+};
+const VALUE_PATTERNS = {
+  status: /(?:^|\b)(?:status|result)\s*[:=]\s*(.+)$/i,
+  files: /(?:^|\b)(?:files?|modified|created|deleted)\s*[:=]\s*(.+)$/i,
+  artifacts: /(?:^|\b)(?:artifacts?)\s*[:=]\s*(.+)$/i,
+  decisions: /(?:^|\b)(?:decisions?|decided|chose|selected)\s*[:=]\s*(.+)$/i,
+  blockers: /(?:^|\b)(?:blockers?|blocked|blocking)\s*[:=]\s*(.+)$/i,
+  next: /(?:^|\b)(?:next\s*(?:steps?|actions?)|todo|follow.up)\s*[:=]\s*(.+)$/i
+};
+const STATUS_MARKERS = /\b(?:APPROVED|NEEDS_REVISION|BLOCKED|SUCCESS|PARTIAL|FAILED|ESCALATE)\b/i;
+const EPSILON = 0.01;
+function normalizePinFields(pinFields) {
+  const requested = pinFields ?? [...DEFAULT_PIN_FIELDS];
+  return [...new Set(requested.map((field) => field.toLowerCase()))];
+}
+function resolveWeight(weight) {
+  if (typeof weight !== "number" || !Number.isFinite(weight) || weight <= 0) {
+    return 1;
+  }
+  return weight;
+}
+function findPinnedFields(text, pinFields) {
+  const matched = /* @__PURE__ */ new Set();
+  for (const field of pinFields) {
+    const pattern = PIN_PATTERNS[field];
+    if (pattern?.test(text)) {
+      matched.add(field);
+    }
+  }
+  if (pinFields.includes("status") && STATUS_MARKERS.test(text)) {
+    matched.add("status");
+  }
+  return [...matched];
+}
+function extractFieldValue(field, text) {
+  const lines = text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+  for (const line of lines) {
+    const pattern = VALUE_PATTERNS[field];
+    const match = pattern?.exec(line);
+    if (match?.[1]) {
+      return match[1].trim();
+    }
+    if (field === "status") {
+      const marker = line.match(STATUS_MARKERS);
+      if (marker) {
+        return marker[0];
+      }
+    }
+  }
+  return text.trim();
+}
+function addFieldEntry(fields, field, sourceId, value) {
+  if (!fields[field]) {
+    fields[field] = [];
+  }
+  fields[field].push({ sourceId, value });
+}
+function prepareSources(sources, strategy, pinFields, fields) {
+  return sources.map((source) => {
+    const segments = segment(source.text, strategy).map((text, index) => {
+      const pinnedFields = findPinnedFields(text, pinFields);
+      for (const field of pinnedFields) {
+        addFieldEntry(fields, field, source.id, extractFieldValue(field, text));
+      }
+      return {
+        index,
+        text,
+        pinnedFields,
+        score: 0
+      };
+    });
+    const pinnedChars = segments.filter((segment2) => segment2.pinnedFields.length > 0).reduce((total, segment2) => total + segment2.text.length, 0);
+    const nonPinnedChars = segments.filter((segment2) => segment2.pinnedFields.length === 0).reduce((total, segment2) => total + segment2.text.length, 0);
+    return {
+      id: source.id,
+      originalText: source.text,
+      weight: resolveWeight(source.weight),
+      segments,
+      pinnedChars,
+      nonPinnedChars
+    };
+  });
+}
+function allocateBudgets(sources, remainingChars) {
+  const budgets = new Map(sources.map((source) => [source.id, 0]));
+  let budgetLeft = Math.max(0, remainingChars);
+  let active = sources.filter((source) => source.nonPinnedChars > 0);
+  while (budgetLeft > EPSILON && active.length > 0) {
+    const totalWeight = active.reduce((sum, source) => sum + source.weight, 0);
+    let allocatedThisRound = 0;
+    const nextActive = [];
+    for (const source of active) {
+      const alreadyAllocated = budgets.get(source.id) ?? 0;
+      const remainingCapacity = source.nonPinnedChars - alreadyAllocated;
+      if (remainingCapacity <= EPSILON) {
+        continue;
+      }
+      const share = budgetLeft * (source.weight / totalWeight);
+      const allocation = Math.min(share, remainingCapacity);
+      budgets.set(source.id, alreadyAllocated + allocation);
+      allocatedThisRound += allocation;
+      if (remainingCapacity - allocation > EPSILON) {
+        nextActive.push(source);
+      }
+    }
+    if (allocatedThisRound <= EPSILON) {
+      break;
+    }
+    budgetLeft -= allocatedThisRound;
+    active = nextActive;
+  }
+  return budgets;
+}
+function formatDigestText(blocks) {
+  return blocks.map((block) => `[${block.id}]
+${block.text}`).join("\n\n");
+}
+function ratio(originalChars, compressedChars) {
+  if (originalChars === 0) {
+    return 0;
+  }
+  return compressedChars / originalChars;
+}
+async function digest(embedder, options) {
+  const { sources, query, maxChars = 4e3, pinFields, segmentation = "paragraph" } = options;
+  const fields = {};
+  const effectivePinFields = normalizePinFields(pinFields);
+  const preparedSources = prepareSources(sources, segmentation, effectivePinFields, fields);
+  const totalOriginalChars = sources.reduce((total, source) => total + source.text.length, 0);
+  if (totalOriginalChars <= maxChars) {
+    const blocks2 = preparedSources.filter((source) => source.originalText.trim().length > 0).map((source) => ({ id: source.id, text: source.originalText }));
+    const sourceStats2 = preparedSources.map((source) => ({
+      id: source.id,
+      originalChars: source.originalText.length,
+      keptChars: source.originalText.length,
+      segmentsKept: source.segments.length,
+      segmentsTotal: source.segments.length
+    }));
+    return {
+      text: formatDigestText(blocks2),
+      fields,
+      sourceStats: sourceStats2,
+      totalOriginalChars,
+      totalCompressedChars: totalOriginalChars,
+      ratio: totalOriginalChars === 0 ? 0 : 1
+    };
+  }
+  const queryVector = await embedder.embedQuery(query);
+  for (const source of preparedSources) {
+    for (const segment2 of source.segments) {
+      if (segment2.pinnedFields.length > 0) {
+        continue;
+      }
+      const vector = await embedder.embed(segment2.text);
+      segment2.score = cosineSimilarity(queryVector, vector);
+    }
+  }
+  const reservedChars = preparedSources.reduce((total, source) => total + source.pinnedChars, 0);
+  const budgets = allocateBudgets(preparedSources, maxChars - reservedChars);
+  const sourceStats = [];
+  const blocks = [];
+  let totalCompressedChars = 0;
+  for (const source of preparedSources) {
+    const budget = budgets.get(source.id) ?? 0;
+    const selectedTexts = /* @__PURE__ */ new Map();
+    let selectedNonPinnedChars = 0;
+    const rankedSegments = source.segments.filter((segment2) => segment2.pinnedFields.length === 0).sort(
+      (left, right) => right.score - left.score || estimateTokens(left.text) - estimateTokens(right.text) || left.index - right.index
+    );
+    let overflowCandidate;
+    for (const segment2 of rankedSegments) {
+      const available = budget - selectedNonPinnedChars;
+      if (available <= EPSILON) {
+        break;
+      }
+      if (segment2.text.length <= available + EPSILON) {
+        selectedTexts.set(segment2.index, segment2.text);
+        selectedNonPinnedChars += segment2.text.length;
+        continue;
+      }
+      if (!overflowCandidate) {
+        overflowCandidate = segment2;
+      }
+    }
+    const leftover = Math.floor(budget - selectedNonPinnedChars);
+    if (overflowCandidate && leftover > 0) {
+      const truncated = overflowCandidate.text.slice(0, leftover).trimEnd();
+      if (truncated.length > 0) {
+        selectedTexts.set(overflowCandidate.index, truncated);
+        selectedNonPinnedChars += truncated.length;
+      }
+    }
+    const keptSegments = source.segments.filter((segment2) => segment2.pinnedFields.length > 0 || selectedTexts.has(segment2.index)).map((segment2) => ({
+      index: segment2.index,
+      text: selectedTexts.get(segment2.index) ?? segment2.text
+    }));
+    const keptChars = keptSegments.reduce((total, segment2) => total + segment2.text.length, 0);
+    sourceStats.push({
+      id: source.id,
+      originalChars: source.originalText.length,
+      keptChars,
+      segmentsKept: keptSegments.length,
+      segmentsTotal: source.segments.length
+    });
+    totalCompressedChars += keptChars;
+    if (keptSegments.length === 0) {
+      continue;
+    }
+    blocks.push({
+      id: source.id,
+      text: keptSegments.map((segment2) => segment2.text).join("\n\n")
+    });
+  }
+  return {
+    text: formatDigestText(blocks),
+    fields,
+    sourceStats,
+    totalOriginalChars,
+    totalCompressedChars,
+    ratio: ratio(totalOriginalChars, totalCompressedChars)
+  };
+}
+export {
+  digest
+};
+//# sourceMappingURL=digest.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * kb_encode — Encoding, decoding, and hashing utilities.
+ */
+export type EncodeOperation = 'base64_encode' | 'base64_decode' | 'url_encode' | 'url_decode' | 'sha256' | 'md5' | 'jwt_decode' | 'hex_encode' | 'hex_decode';
+export interface EncodeOptions {
+    operation: EncodeOperation;
+    input: string;
+}
+export interface EncodeResult {
+    output: string;
+    operation: string;
+}
+export declare function encode(options: EncodeOptions): EncodeResult;
+//# sourceMappingURL=encode.d.ts.map

package/packages/tools/dist/encode.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+function encode(options) {
+  const { operation, input } = options;
+  let output;
+  switch (operation) {
+    case "base64_encode":
+      output = Buffer.from(input).toString("base64");
+      break;
+    case "base64_decode":
+      output = Buffer.from(input, "base64").toString("utf8");
+      break;
+    case "url_encode":
+      output = encodeURIComponent(input);
+      break;
+    case "url_decode":
+      output = decodeURIComponent(input);
+      break;
+    case "sha256":
+      output = createHash("sha256").update(input).digest("hex");
+      break;
+    case "md5":
+      output = createHash("md5").update(input).digest("hex");
+      break;
+    case "jwt_decode": {
+      const parts = input.split(".");
+      if (parts.length !== 3) throw new Error("Invalid JWT: expected 3 dot-separated parts");
+      const header = JSON.parse(Buffer.from(parts[0], "base64url").toString());
+      const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString());
+      output = JSON.stringify({ header, payload }, null, 2);
+      break;
+    }
+    case "hex_encode":
+      output = Buffer.from(input).toString("hex");
+      break;
+    case "hex_decode":
+      output = Buffer.from(input, "hex").toString("utf8");
+      break;
+    default:
+      throw new Error(`Unknown operation: ${operation}`);
+  }
+  return { output, operation };
+}
+export {
+  encode
+};
+//# sourceMappingURL=encode.js.map

package/packages/tools/dist/env-info.d.ts

@@ -0,0 +1,28 @@
+/**
+ * kb_env — System environment and runtime information.
+ */
+export interface EnvInfoOptions {
+    includeEnv?: boolean;
+    filterEnv?: string;
+    showSensitive?: boolean;
+}
+export interface EnvInfoResult {
+    system: {
+        platform: string;
+        arch: string;
+        release: string;
+        hostname: string;
+        type: string;
+        cpus: number;
+        memoryTotalGb: number;
+        memoryFreeGb: number;
+    };
+    runtime: {
+        node: string;
+        v8: string;
+    };
+    cwd: string;
+    env?: Record<string, string>;
+}
+export declare function envInfo(options?: EnvInfoOptions): EnvInfoResult;
+//# sourceMappingURL=env-info.d.ts.map

package/packages/tools/dist/env-info.js

@@ -0,0 +1,58 @@
+import {
+  arch,
+  cpus,
+  freemem,
+  hostname,
+  type as osType,
+  platform,
+  release,
+  totalmem
+} from "node:os";
+const SENSITIVE_PATTERNS = [
+  /key/i,
+  /secret/i,
+  /token/i,
+  /password/i,
+  /passwd/i,
+  /credential/i,
+  /private/i,
+  /certificate/i
+];
+function envInfo(options = {}) {
+  const { includeEnv = false, filterEnv, showSensitive = false } = options;
+  const result = {
+    system: {
+      platform: platform(),
+      arch: arch(),
+      release: release(),
+      hostname: hostname(),
+      type: osType(),
+      cpus: cpus().length,
+      memoryTotalGb: Math.round(totalmem() / 1024 ** 3 * 10) / 10,
+      memoryFreeGb: Math.round(freemem() / 1024 ** 3 * 10) / 10
+    },
+    runtime: {
+      node: process.versions.node,
+      v8: process.versions.v8
+    },
+    cwd: process.cwd()
+  };
+  if (includeEnv) {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (!value) continue;
+      if (filterEnv && !key.toLowerCase().includes(filterEnv.toLowerCase())) continue;
+      if (!showSensitive && SENSITIVE_PATTERNS.some((p) => p.test(key))) {
+        env[key] = "[REDACTED]";
+      } else {
+        env[key] = value;
+      }
+    }
+    result.env = env;
+  }
+  return result;
+}
+export {
+  envInfo
+};
+//# sourceMappingURL=env-info.js.map

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

@@ -0,0 +1,13 @@
+export interface EvalOptions {
+    code: string;
+    lang?: 'js' | 'ts';
+    timeout?: number;
+}
+export interface EvalResult {
+    success: boolean;
+    output: string;
+    error?: string;
+    durationMs: number;
+}
+export declare function evaluate(options: EvalOptions): EvalResult;
+//# sourceMappingURL=eval.d.ts.map

package/packages/tools/dist/eval.js

@@ -0,0 +1,79 @@
+import vm from "node:vm";
+function evaluate(options) {
+  const { code, lang = "js", timeout = 5e3 } = options;
+  const start = Date.now();
+  try {
+    const execCode = lang === "ts" ? stripTypeAnnotations(code) : code;
+    const logs = [];
+    const sandbox = {
+      console: {
+        log: (...args) => logs.push(args.map(String).join(" ")),
+        error: (...args) => logs.push(`[error] ${args.map(String).join(" ")}`),
+        warn: (...args) => logs.push(`[warn] ${args.map(String).join(" ")}`)
+      },
+      setTimeout: void 0,
+      setInterval: void 0,
+      setImmediate: void 0,
+      fetch: void 0,
+      process: void 0,
+      require: void 0,
+      JSON,
+      Math,
+      Date,
+      Array,
+      Object,
+      String,
+      Number,
+      Boolean,
+      Map,
+      Set,
+      RegExp,
+      Error,
+      Promise,
+      parseInt,
+      parseFloat,
+      isNaN,
+      isFinite
+    };
+    const context = vm.createContext(sandbox, {
+      codeGeneration: {
+        strings: false,
+        wasm: false
+      }
+    });
+    const result = vm.runInContext(execCode, context, { timeout });
+    const output = logs.length > 0 ? logs.join("\n") + (result !== void 0 ? `
+\u2192 ${formatValue(result)}` : "") : result !== void 0 ? formatValue(result) : "(no output)";
+    return {
+      success: true,
+      output,
+      durationMs: Date.now() - start
+    };
+  } catch (error) {
+    return {
+      success: false,
+      output: "",
+      error: error.message,
+      durationMs: Date.now() - start
+    };
+  }
+}
+function formatValue(value) {
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value, null, 2);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+function stripTypeAnnotations(code) {
+  return code.replace(/^\s*import\s+type\s+.*?;\s*$/gm, "").replace(/^\s*(?:export\s+)?interface\s+\w+[^{]*\{[\s\S]*?^\s*}\s*$/gm, "").replace(/^\s*(?:export\s+)?type\s+\w+\s*=.*?;\s*$/gm, "").replace(/([,(]\s*[A-Za-z_$][\w$]*)\s*:\s*[^,)=\n]+/g, "$1").replace(/\)\s*:\s*[^={\n]+(?=\s*(?:=>|\{))/g, ")").replace(/\s+as\s+[A-Za-z_$][\w$<>,[\]|&\s.]*/g, "").replace(/<(?:[A-Za-z_$][\w$]*\s*,?\s*)+>(?=\s*\()/g, "");
+}
+export {
+  evaluate
+};
+//# sourceMappingURL=eval.js.map

package/packages/tools/dist/evidence-map.d.ts

@@ -0,0 +1,79 @@
+/**
+ * kb_evidence_map — FORGE Evidence Map CRUD + Gate evaluator.
+ *
+ * Structured storage, validation, and gate evaluation for FORGE Evidence Map entries.
+ * Persisted in .kb-state/evidence-maps.json.
+ */
+export type EvidenceStatus = 'V' | 'A' | 'U';
+export type UnknownType = 'contract' | 'convention' | 'freshness' | 'runtime' | 'data-flow' | 'impact';
+export type GateDecision = 'YIELD' | 'HOLD' | 'HARD_BLOCK' | 'FORCED_DELIVERY';
+export type ForgeTier = 'floor' | 'standard' | 'critical';
+export interface EvidenceEntry {
+    id: number;
+    claim: string;
+    status: EvidenceStatus;
+    receipt: string;
+    criticalPath: boolean;
+    unknownType?: UnknownType;
+}
+export interface EvidenceMapState {
+    taskId: string;
+    tier: ForgeTier;
+    entries: EvidenceEntry[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GateResult {
+    decision: GateDecision;
+    reason: string;
+    unresolvedCritical: EvidenceEntry[];
+    warnings: string[];
+    stats: {
+        total: number;
+        verified: number;
+        assumed: number;
+        unresolved: number;
+    };
+    annotation?: string;
+}
+export type EvidenceMapAction = {
+    action: 'create';
+    taskId: string;
+    tier: ForgeTier;
+} | {
+    action: 'add';
+    taskId: string;
+    claim: string;
+    status: EvidenceStatus;
+    receipt: string;
+    criticalPath?: boolean;
+    unknownType?: UnknownType;
+} | {
+    action: 'update';
+    taskId: string;
+    id: number;
+    status: EvidenceStatus;
+    receipt: string;
+} | {
+    action: 'get';
+    taskId: string;
+} | {
+    action: 'gate';
+    taskId: string;
+    retryCount?: number;
+} | {
+    action: 'list';
+} | {
+    action: 'delete';
+    taskId: string;
+};
+export interface EvidenceMapResult {
+    state?: EvidenceMapState;
+    states?: EvidenceMapState[];
+    entry?: EvidenceEntry;
+    gate?: GateResult;
+    deleted?: boolean;
+    formattedMap?: string;
+}
+export declare function evidenceMap(action: EvidenceMapAction, cwd?: string): EvidenceMapResult;
+//# sourceMappingURL=evidence-map.d.ts.map