eve-knowledge 0.1.0

package/dist/cli.js

@@ -0,0 +1,1090 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/indexer.ts
+import { performance } from "perf_hooks";
+
+// src/hash.ts
+import { createHash } from "crypto";
+function sha256(input) {
+  return createHash("sha256").update(input).digest("hex");
+}
+function shortHash(input, length = 16) {
+  return sha256(input).slice(0, length);
+}
+
+// src/chunk.ts
+function chunkDocument(document, config, indexedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+  const chunks = [];
+  for (const section of document.sections) {
+    const parts = splitText(section.text, config.chunking.maxCharacters, config.chunking.overlapCharacters);
+    parts.forEach((text, partIndex) => {
+      const contentHash = shortHash(text, 32);
+      const ordinal = chunks.length;
+      chunks.push({
+        id: createChunkId(document.source.path, section.headingPath, section.ordinal, partIndex, contentHash),
+        source: document.source,
+        text,
+        headingPath: section.headingPath,
+        ordinal,
+        contentHash,
+        tokenCount: estimateTokenCount(text),
+        charCount: text.length,
+        indexedAt
+      });
+    });
+  }
+  return chunks;
+}
+function createChunkId(sourcePath, headingPath, sectionOrdinal, partOrdinal, contentHash) {
+  return `chk_${shortHash(
+    [sourcePath, headingPath.join(" > "), sectionOrdinal, partOrdinal, contentHash].join("\n"),
+    24
+  )}`;
+}
+function splitText(text, maxCharacters, overlapCharacters) {
+  const normalized = text.trim();
+  if (!normalized) return [];
+  if (normalized.length <= maxCharacters) return [normalized];
+  const parts = [];
+  let start = 0;
+  while (start < normalized.length) {
+    const hardEnd = Math.min(start + maxCharacters, normalized.length);
+    const end = chooseBreak(normalized, start, hardEnd);
+    const part = normalized.slice(start, end).trim();
+    if (part) parts.push(part);
+    if (end >= normalized.length) break;
+    start = Math.max(end - overlapCharacters, start + 1);
+  }
+  return parts;
+}
+function chooseBreak(text, start, hardEnd) {
+  if (hardEnd >= text.length) return text.length;
+  const window = text.slice(start, hardEnd);
+  const paragraphBreak = window.lastIndexOf("\n\n");
+  if (paragraphBreak > Math.floor(window.length * 0.5)) {
+    return start + paragraphBreak;
+  }
+  const sentenceBreak = Math.max(window.lastIndexOf(". "), window.lastIndexOf("? "), window.lastIndexOf("! "));
+  if (sentenceBreak > Math.floor(window.length * 0.5)) {
+    return start + sentenceBreak + 1;
+  }
+  const wordBreak = window.lastIndexOf(" ");
+  if (wordBreak > Math.floor(window.length * 0.5)) {
+    return start + wordBreak;
+  }
+  return hardEnd;
+}
+function estimateTokenCount(text) {
+  return Math.ceil(text.length / 4);
+}
+
+// src/config.ts
+import path from "path";
+var defaultIncludePatterns = ["**/*.{md,mdx,txt,json,yaml,yml}"];
+var defaultIgnorePatterns = [
+  ".git/**",
+  "node_modules/**",
+  "dist/**",
+  "build/**",
+  ".next/**",
+  ".nuxt/**",
+  ".output/**",
+  ".vercel/**",
+  ".turbo/**",
+  ".cache/**",
+  ".eve-knowledge/**",
+  "**/.env",
+  "**/.env.*",
+  "**/*.pem",
+  "**/*.key",
+  "**/*secret*",
+  "**/*credential*"
+];
+var defaultMaxFileBytes = 256 * 1024;
+var defaultChunking = {
+  maxCharacters: 1600,
+  overlapCharacters: 160
+};
+function resolveKnowledgeConfig(config = {}, cwd = process.cwd()) {
+  const rootDir = path.resolve(cwd, config.rootDir ?? ".");
+  const agentDir = path.resolve(rootDir, config.agentDir ?? "agent");
+  const knowledgeDir = path.resolve(rootDir, config.knowledgeDir ?? "agent/knowledge");
+  const storeDir = path.resolve(rootDir, config.storeDir ?? ".eve-knowledge");
+  const chunking = {
+    ...defaultChunking,
+    ...config.chunking
+  };
+  if (chunking.maxCharacters <= 0) {
+    throw new Error("chunking.maxCharacters must be greater than 0");
+  }
+  if (chunking.overlapCharacters < 0) {
+    throw new Error("chunking.overlapCharacters must be zero or greater");
+  }
+  if (chunking.overlapCharacters >= chunking.maxCharacters) {
+    throw new Error("chunking.overlapCharacters must be smaller than chunking.maxCharacters");
+  }
+  return {
+    rootDir,
+    agentDir,
+    knowledgeDir,
+    storeDir,
+    include: config.include ?? defaultIncludePatterns,
+    ignore: [...defaultIgnorePatterns, ...config.ignore ?? []],
+    maxFileBytes: config.maxFileBytes ?? defaultMaxFileBytes,
+    chunking,
+    redaction: {
+      mode: config.redaction?.mode ?? "warn"
+    },
+    memory: config.memory ?? { enabled: false }
+  };
+}
+
+// src/loader.ts
+import fs2 from "fs/promises";
+import path4 from "path";
+
+// src/fs-utils.ts
+import fs from "fs/promises";
+import path2 from "path";
+function toRepoPath(filePath) {
+  return filePath.split(path2.sep).join("/");
+}
+function isMissingFileError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/loader.ts
+import { parse as parseYaml2 } from "yaml";
+
+// src/frontmatter.ts
+import { parse as parseYaml } from "yaml";
+var frontmatterPattern = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+function parseFrontmatter(content) {
+  const match = frontmatterPattern.exec(content);
+  if (!match) {
+    return { body: content, metadata: {} };
+  }
+  const yamlText = match[1] ?? "";
+  const parsed = parseYaml(yamlText);
+  return {
+    body: content.slice(match[0].length),
+    metadata: normalizeMetadata(parsed)
+  };
+}
+function normalizeMetadata(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  const metadata = {};
+  for (const [key, rawValue] of Object.entries(value)) {
+    const normalized = normalizeMetadataValue(rawValue);
+    if (normalized !== void 0) {
+      metadata[key] = normalized;
+    }
+  }
+  return metadata;
+}
+function normalizeMetadataValue(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    const normalized = value.filter(isMetadataPrimitive);
+    return normalized.length > 0 ? normalized : void 0;
+  }
+  return void 0;
+}
+function isMetadataPrimitive(value) {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+
+// src/format.ts
+import path3 from "path";
+function detectKnowledgeFormat(filePath) {
+  const ext = path3.extname(filePath).toLowerCase();
+  if (ext === ".md") return "markdown";
+  if (ext === ".mdx") return "mdx";
+  if (ext === ".txt") return "text";
+  if (ext === ".json") return "json";
+  if (ext === ".yaml" || ext === ".yml") return "yaml";
+  return void 0;
+}
+
+// src/redaction.ts
+var KnowledgeRedactionError = class extends Error {
+  constructor(level, path10, findings) {
+    super(`Possible secret detected (${findings.map((finding) => finding.label).join(", ")}).`);
+    this.level = level;
+    this.path = path10;
+    this.findings = findings;
+    this.name = "KnowledgeRedactionError";
+  }
+  level;
+  path;
+  findings;
+};
+var secretPatterns = [
+  { label: "openai_api_key", pattern: /\bsk-[A-Za-z0-9_-]{20,}\b/g },
+  { label: "anthropic_api_key", pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+  { label: "github_token", pattern: /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g },
+  { label: "private_key", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+  {
+    label: "env_secret_assignment",
+    pattern: /\b[A-Z0-9_]*(?:SECRET|TOKEN|API_KEY|PASSWORD)[A-Z0-9_]*\s*=\s*["']?[^"'\s]{8,}/g
+  }
+];
+function detectSecrets(content) {
+  const findings = [];
+  for (const { label, pattern } of secretPatterns) {
+    pattern.lastIndex = 0;
+    for (const match of content.matchAll(pattern)) {
+      findings.push({
+        label,
+        index: match.index ?? 0,
+        preview: maskSecret(match[0] ?? "")
+      });
+    }
+  }
+  return findings;
+}
+function maskSecret(value) {
+  if (value.length <= 8) return "[redacted]";
+  return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}
+
+// src/sections.ts
+var markdownHeadingPattern = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+function splitMarkdownSections(content) {
+  const sections = [];
+  const headingStack = [];
+  let currentLines = [];
+  let currentHeadingPath = [];
+  let ordinal = 0;
+  for (const line of content.split(/\r?\n/)) {
+    const heading = markdownHeadingPattern.exec(line);
+    if (heading) {
+      pushSection();
+      const level = heading[1]?.length ?? 1;
+      const title = normalizeHeadingTitle(heading[2] ?? "");
+      while (headingStack.length > 0 && headingStack[headingStack.length - 1].level >= level) {
+        headingStack.pop();
+      }
+      headingStack.push({ level, title });
+      currentHeadingPath = headingStack.map((entry) => entry.title);
+      currentLines = [];
+      continue;
+    }
+    currentLines.push(line);
+  }
+  pushSection();
+  if (sections.length === 0) {
+    return [{ text: "", headingPath: [], ordinal: 0 }];
+  }
+  return sections;
+  function pushSection() {
+    const text = currentLines.join("\n").trim();
+    if (!text) {
+      currentLines = [];
+      return;
+    }
+    sections.push({
+      text,
+      headingPath: currentHeadingPath,
+      ordinal
+    });
+    ordinal += 1;
+    currentLines = [];
+  }
+}
+function sectionFromText(content) {
+  return [
+    {
+      text: content.trim(),
+      headingPath: [],
+      ordinal: 0
+    }
+  ];
+}
+function normalizeHeadingTitle(title) {
+  return title.replace(/\s+/g, " ").trim();
+}
+
+// src/loader.ts
+async function loadKnowledgeDocument(filePath, config) {
+  const format = detectKnowledgeFormat(filePath);
+  if (!format) return void 0;
+  const stat = await fs2.stat(filePath);
+  const content = await fs2.readFile(filePath, "utf8");
+  const relativePath = toRepoPath(path4.relative(config.rootDir, filePath));
+  const secrets = detectSecrets(content);
+  if (secrets.length > 0 && config.redaction.mode !== "off") {
+    throw new KnowledgeRedactionError(
+      config.redaction.mode === "fail" ? "error" : "warning",
+      relativePath,
+      secrets
+    );
+  }
+  const contentHash = sha256(content);
+  const modifiedTime = stat.mtime.toISOString();
+  let metadata = {};
+  let body = content;
+  if (format === "markdown" || format === "mdx") {
+    const parsed = parseFrontmatter(content);
+    metadata = parsed.metadata;
+    body = parsed.body;
+  } else if (format === "json") {
+    const parsed = JSON.parse(content);
+    metadata = normalizeMetadata(parsed);
+    body = JSON.stringify(parsed, null, 2);
+  } else if (format === "yaml") {
+    const parsed = parseYaml2(content);
+    metadata = normalizeMetadata(parsed);
+    body = parsed === null || parsed === void 0 ? "" : JSON.stringify(parsed, null, 2);
+  }
+  return {
+    source: {
+      path: relativePath,
+      format,
+      contentHash,
+      modifiedTime,
+      sizeBytes: stat.size,
+      metadata
+    },
+    sections: format === "markdown" || format === "mdx" ? splitMarkdownSections(body) : sectionFromText(body)
+  };
+}
+
+// src/scan.ts
+import fs3 from "fs/promises";
+import path5 from "path";
+import fg from "fast-glob";
+import ignore from "ignore";
+async function scanKnowledgeFiles(config) {
+  const builtInIg = ignore().add(config.ignore);
+  const userIg = ignore().add(await readEveKnowledgeIgnore(config));
+  const rootRealPath = await fs3.realpath(config.rootDir);
+  const knowledgeRealPath = await fs3.realpath(config.knowledgeDir);
+  const entries = await fg(config.include, {
+    cwd: config.knowledgeDir,
+    absolute: true,
+    onlyFiles: true,
+    dot: true,
+    followSymbolicLinks: false,
+    unique: true
+  });
+  const files = [];
+  const skipped = [];
+  const warnings = [];
+  const errors = [];
+  for (const filePath of entries.sort()) {
+    const relativeToRoot = toRepoPath(path5.relative(config.rootDir, filePath));
+    const relativeToKnowledge = toRepoPath(path5.relative(config.knowledgeDir, filePath));
+    const lstat = await fs3.lstat(filePath);
+    if (lstat.isSymbolicLink()) {
+      skipped.push(issue("warning", relativeToRoot, "symlink_skipped", "Symlinks are not indexed."));
+      continue;
+    }
+    const realPath = await fs3.realpath(filePath);
+    if (!isInside(realPath, knowledgeRealPath) || !isInside(realPath, rootRealPath)) {
+      skipped.push(issue("warning", relativeToRoot, "path_escape", "File resolves outside the knowledge tree."));
+      continue;
+    }
+    if (builtInIg.ignores(relativeToRoot) || builtInIg.ignores(relativeToKnowledge) || userIg.ignores(relativeToRoot) || userIg.ignores(relativeToKnowledge)) {
+      skipped.push(issue("info", relativeToRoot, "ignored", "File matched .eveknowledgeignore rules."));
+      continue;
+    }
+    const stat = await fs3.stat(filePath);
+    if (stat.size > config.maxFileBytes) {
+      skipped.push(
+        issue(
+          "warning",
+          relativeToRoot,
+          "max_file_size",
+          `File is ${stat.size} bytes, above the ${config.maxFileBytes} byte limit.`
+        )
+      );
+      continue;
+    }
+    files.push(filePath);
+  }
+  return { files, skipped, warnings, errors };
+}
+async function readEveKnowledgeIgnore(config) {
+  const candidates = [
+    path5.join(config.rootDir, ".eveknowledgeignore"),
+    path5.join(config.knowledgeDir, ".eveknowledgeignore")
+  ];
+  const patterns = [];
+  for (const filePath of candidates) {
+    try {
+      const content = await fs3.readFile(filePath, "utf8");
+      patterns.push(
+        ...content.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"))
+      );
+    } catch (error) {
+      if (!isMissingFileError(error)) {
+        throw error;
+      }
+    }
+  }
+  return patterns;
+}
+function issue(level, filePath, code, message) {
+  return { level, path: filePath, code, message };
+}
+function isInside(candidate, directory) {
+  const relative = path5.relative(directory, candidate);
+  return relative === "" || !relative.startsWith("..") && !path5.isAbsolute(relative);
+}
+
+// src/store/local.ts
+import fs4 from "fs/promises";
+import path6 from "path";
+
+// src/store/helpers.ts
+function replaceChunksBySource(existing, incoming) {
+  const incomingSourcePaths = new Set(incoming.map((chunk) => chunk.source.path));
+  const incomingIds = new Set(incoming.map((chunk) => chunk.id));
+  return [
+    ...existing.filter(
+      (chunk) => !incomingSourcePaths.has(chunk.source.path) && !incomingIds.has(chunk.id)
+    ),
+    ...incoming
+  ].sort((a, b) => a.id.localeCompare(b.id));
+}
+function removeChunksBySource(chunks, sourcePath) {
+  return chunks.filter((chunk) => chunk.source.path !== sourcePath);
+}
+function citationForChunk(chunk) {
+  return {
+    path: chunk.source.path,
+    chunkId: chunk.id,
+    indexedAt: chunk.indexedAt,
+    ...chunk.headingPath.length > 0 ? { heading: chunk.headingPath.join(" > ") } : {}
+  };
+}
+function countSources(chunks) {
+  return listSourcePaths(chunks).length;
+}
+function listSourcePaths(chunks) {
+  return [...new Set(chunks.map((chunk) => chunk.source.path))].sort();
+}
+function matchesMetadataFilters(chunk, filters) {
+  if (!filters) return true;
+  for (const [key, expected] of Object.entries(filters)) {
+    const actual = chunk.source.metadata[key];
+    if (actual === void 0) return false;
+    const expectedValues = Array.isArray(expected) ? expected : [expected];
+    const actualValues = Array.isArray(actual) ? actual : [actual];
+    if (!expectedValues.some((value) => actualValues.includes(value))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// src/store/local.ts
+var LocalKnowledgeStore = class {
+  name = "local-json";
+  durability = "local";
+  filePath;
+  data;
+  constructor(options) {
+    this.filePath = path6.join(options.storeDir, "index.json");
+  }
+  async upsertChunks(chunks) {
+    const data = await this.read();
+    data.chunks = replaceChunksBySource(data.chunks, chunks);
+    await this.write(data);
+  }
+  async deleteBySource(sourcePath) {
+    const data = await this.read();
+    data.chunks = removeChunksBySource(data.chunks, sourcePath);
+    await this.write(data);
+  }
+  async search(input) {
+    const data = await this.read();
+    const queryTokens = tokenize(input.query);
+    if (queryTokens.length === 0) return [];
+    return data.chunks.filter((chunk) => matchesMetadataFilters(chunk, input.filters)).map((chunk) => ({
+      chunk,
+      score: scoreChunk(chunk, queryTokens),
+      citation: citationForChunk(chunk)
+    })).filter((hit) => hit.score > 0).sort((a, b) => b.score - a.score || a.chunk.source.path.localeCompare(b.chunk.source.path)).slice(0, input.topK);
+  }
+  async stats() {
+    const data = await this.read();
+    return {
+      chunks: data.chunks.length,
+      sources: countSources(data.chunks),
+      storePath: this.filePath,
+      durability: this.durability
+    };
+  }
+  async listChunks() {
+    const data = await this.read();
+    return [...data.chunks];
+  }
+  async listSources() {
+    const data = await this.read();
+    return listSourcePaths(data.chunks);
+  }
+  async read() {
+    if (this.data) return this.data;
+    try {
+      const content = await fs4.readFile(this.filePath, "utf8");
+      this.data = JSON.parse(content);
+    } catch (error) {
+      if (!isMissingFileError(error)) throw error;
+      this.data = { version: 1, chunks: [] };
+    }
+    return this.data;
+  }
+  async write(data) {
+    await fs4.mkdir(path6.dirname(this.filePath), { recursive: true });
+    const tempPath = `${this.filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+    await fs4.writeFile(tempPath, `${JSON.stringify(data, null, 2)}
+`);
+    await fs4.rename(tempPath, this.filePath);
+    this.data = data;
+  }
+};
+function createLocalKnowledgeStore(options) {
+  return new LocalKnowledgeStore(options);
+}
+function scoreChunk(chunk, queryTokens) {
+  const haystack = tokenize(
+    [
+      chunk.text,
+      chunk.headingPath.join(" "),
+      chunk.source.path,
+      Object.values(chunk.source.metadata).flat().join(" ")
+    ].join(" ")
+  );
+  const haystackCounts = /* @__PURE__ */ new Map();
+  for (const token of haystack) {
+    haystackCounts.set(token, (haystackCounts.get(token) ?? 0) + 1);
+  }
+  let score = 0;
+  for (const token of queryTokens) {
+    score += haystackCounts.get(token) ?? 0;
+  }
+  if (queryTokens.some((token) => chunk.source.path.toLowerCase().includes(token))) {
+    score += 0.25;
+  }
+  return score / queryTokens.length;
+}
+function tokenize(input) {
+  return input.toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length > 1);
+}
+
+// src/indexer.ts
+async function indexKnowledge(options = {}) {
+  const startedAt = performance.now();
+  const config = resolveKnowledgeConfig(options.config, options.cwd);
+  const store = options.store ?? createLocalKnowledgeStore({ storeDir: config.storeDir });
+  const scan = await scanKnowledgeFiles(config);
+  const warnings = [...scan.warnings];
+  const errors = [...scan.errors];
+  if (errors.length > 0) {
+    return {
+      filesScanned: scan.files.length + scan.skipped.length + scan.errors.length,
+      filesIndexed: 0,
+      filesSkipped: scan.skipped.length,
+      chunksCreated: 0,
+      chunksReused: 0,
+      sourcesChanged: 0,
+      sourcesDeleted: 0,
+      warnings,
+      errors,
+      elapsedMs: Math.round(performance.now() - startedAt),
+      store: await store.stats()
+    };
+  }
+  const existingChunks = "listChunks" in store && store.listChunks ? await store.listChunks() : [];
+  const existingBySource = groupChunksBySource(existingChunks);
+  const seenSources = /* @__PURE__ */ new Set();
+  let chunksCreated = 0;
+  let chunksReused = 0;
+  let sourcesChanged = 0;
+  let sourcesDeleted = 0;
+  let filesIndexed = 0;
+  const chunksToUpsert = [];
+  const sourcesToDelete = [];
+  for (const filePath of scan.files) {
+    try {
+      const document = await loadKnowledgeDocument(filePath, config);
+      if (!document) continue;
+      const chunks = chunkDocument(document, config, options.now?.toISOString());
+      const existingForSource = existingBySource.get(document.source.path) ?? [];
+      const reconciled = reconcileChunks(chunks, existingForSource);
+      chunksReused += reconciled.reused;
+      chunksCreated += reconciled.created;
+      if (!options.dryRun) {
+        if (chunks.length === 0) {
+          sourcesToDelete.push(document.source.path);
+        } else if (!reconciled.unchanged) {
+          chunksToUpsert.push(...reconciled.chunks);
+        }
+      }
+      if (!reconciled.unchanged) {
+        sourcesChanged += 1;
+      }
+      seenSources.add(document.source.path);
+      filesIndexed += 1;
+    } catch (error) {
+      if (error instanceof KnowledgeRedactionError) {
+        const issue2 = {
+          level: error.level,
+          path: error.path,
+          code: "possible_secret",
+          message: error.message
+        };
+        if (error.level === "error") errors.push(issue2);
+        else warnings.push(issue2);
+        continue;
+      }
+      errors.push({
+        level: "error",
+        path: filePath,
+        code: "load_failed",
+        message: error instanceof Error ? error.message : "Failed to load knowledge file."
+      });
+    }
+  }
+  if ("listSources" in store && store.listSources) {
+    const previousSources = await store.listSources();
+    for (const sourcePath of previousSources.filter((sourcePath2) => !seenSources.has(sourcePath2))) {
+      sourcesDeleted += 1;
+      if (!options.dryRun) {
+        sourcesToDelete.push(sourcePath);
+      }
+    }
+  }
+  if (!options.dryRun) {
+    if (chunksToUpsert.length > 0) {
+      await store.upsertChunks(chunksToUpsert);
+    }
+    for (const sourcePath of sourcesToDelete) {
+      await store.deleteBySource(sourcePath);
+    }
+  }
+  return {
+    filesScanned: scan.files.length + scan.skipped.length,
+    filesIndexed,
+    filesSkipped: scan.skipped.length + warnings.length,
+    chunksCreated,
+    chunksReused,
+    sourcesChanged,
+    sourcesDeleted,
+    warnings,
+    errors,
+    elapsedMs: Math.round(performance.now() - startedAt),
+    store: await store.stats()
+  };
+}
+function reconcileChunks(chunks, existingChunks) {
+  const existingById = new Map(existingChunks.map((chunk) => [chunk.id, chunk]));
+  let reused = 0;
+  let created = 0;
+  const reconciled = chunks.map((chunk) => {
+    const existing = existingById.get(chunk.id);
+    if (existing?.contentHash === chunk.contentHash) {
+      reused += 1;
+      return mergeReusedChunk(chunk, existing);
+    }
+    created += 1;
+    return chunk;
+  });
+  return {
+    chunks: reconciled,
+    reused,
+    created,
+    unchanged: isSameChunkSet(reconciled, existingChunks)
+  };
+}
+function mergeReusedChunk(chunk, existing) {
+  return {
+    ...chunk,
+    source: sameSourceExceptModifiedTime(chunk, existing) ? existing.source : chunk.source,
+    indexedAt: existing.indexedAt
+  };
+}
+function sameSourceExceptModifiedTime(next, existing) {
+  const { modifiedTime: _nextModifiedTime, ...nextSource } = next.source;
+  const { modifiedTime: _existingModifiedTime, ...existingSource } = existing.source;
+  return JSON.stringify(nextSource) === JSON.stringify(existingSource);
+}
+function isSameChunkSet(nextChunks, existingChunks) {
+  if (nextChunks.length !== existingChunks.length) return false;
+  const existingById = new Map(existingChunks.map((chunk) => [chunk.id, chunk]));
+  return nextChunks.every((chunk) => {
+    const existing = existingById.get(chunk.id);
+    return existing !== void 0 && JSON.stringify(existing) === JSON.stringify(chunk);
+  });
+}
+function groupChunksBySource(chunks) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const chunk of chunks) {
+    const group = grouped.get(chunk.source.path) ?? [];
+    group.push(chunk);
+    grouped.set(chunk.source.path, group);
+  }
+  return grouped;
+}
+
+// src/check.ts
+async function checkKnowledge(options = {}) {
+  const store = options.store;
+  const summary = await indexKnowledge({
+    ...options.cwd ? { cwd: options.cwd } : {},
+    config: {
+      ...options.config,
+      redaction: {
+        ...options.config?.redaction,
+        mode: "fail"
+      }
+    },
+    ...store ? { store } : {},
+    dryRun: true
+  });
+  const issues = [...summary.errors];
+  if (summary.sourcesChanged > 0 || summary.sourcesDeleted > 0) {
+    issues.push({
+      level: "error",
+      code: "stale_index",
+      message: `${summary.sourcesChanged} sources changed and ${summary.sourcesDeleted} sources were deleted. Run eve-knowledge index before shipping.`
+    });
+  }
+  if (options.production) {
+    const durability = options.store?.durability ?? summary.store.durability;
+    if (durability !== "durable") {
+      issues.push({
+        level: "error",
+        code: "non_durable_store",
+        message: "Production checks require a durable KnowledgeStore. Local filesystem storage is not durable in serverless deployments."
+      });
+    }
+  }
+  return {
+    ok: issues.length === 0,
+    summary,
+    issues
+  };
+}
+
+// src/config-loader.ts
+import fs5 from "fs/promises";
+import path7 from "path";
+import { pathToFileURL } from "url";
+var safeConfigFileNames = ["eve-knowledge.config.json"];
+var trustedConfigFileNames = ["eve-knowledge.config.ts", "eve-knowledge.config.mjs", "eve-knowledge.config.js"];
+async function loadKnowledgeConfig(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const safeConfigPath = await findConfigPath(cwd, safeConfigFileNames);
+  if (safeConfigPath) {
+    return JSON.parse(await fs5.readFile(safeConfigPath, "utf8"));
+  }
+  const configPath = await findConfigPath(cwd, trustedConfigFileNames);
+  if (!configPath) return {};
+  if (!options.trustedConfig) {
+    throw new Error(
+      `Refusing to execute ${path7.basename(configPath)}. Use --trusted-config for trusted local config, or use eve-knowledge.config.json for CI.`
+    );
+  }
+  const loaded = await import(pathToFileURL(configPath).href);
+  return loaded.default ?? {};
+}
+async function findConfigPath(cwd, fileNames) {
+  for (const fileName of fileNames) {
+    const filePath = path7.join(cwd, fileName);
+    try {
+      await fs5.access(filePath);
+      return filePath;
+    } catch {
+    }
+  }
+  return void 0;
+}
+
+// src/search.ts
+async function searchKnowledge(input, options = {}) {
+  const config = resolveKnowledgeConfig(options.config, options.cwd);
+  const store = options.store ?? createLocalKnowledgeStore({ storeDir: config.storeDir });
+  const topK = Math.min(Math.max(input.topK ?? options.maxResults ?? 5, 1), 20);
+  const results = await store.search({
+    query: input.query,
+    topK,
+    ...input.filters ? { filters: input.filters } : {}
+  });
+  if (results.length === 0) {
+    return {
+      status: "no_results",
+      query: input.query,
+      message: "No relevant knowledge results were found. Do not fabricate an answer; ask for source material or say you do not know."
+    };
+  }
+  return {
+    status: "results",
+    query: input.query,
+    results
+  };
+}
+
+// src/scaffold.ts
+import fs7 from "fs/promises";
+import path9 from "path";
+
+// src/project.ts
+import fs6 from "fs/promises";
+import path8 from "path";
+async function detectEveProject(cwd) {
+  const signals = [];
+  const agentDir = path8.join(cwd, "agent");
+  if (await pathExists(agentDir)) {
+    signals.push("agent/");
+  }
+  for (const filePath of ["agent/agent.ts", "agent/instructions.md", "agent/tools"]) {
+    if (await pathExists(path8.join(cwd, filePath))) {
+      signals.push(filePath);
+    }
+  }
+  if (await packageHasEveDependency(path8.join(cwd, "package.json"))) {
+    signals.push("package.json:eve");
+  }
+  return {
+    isEveProject: signals.some((signal) => signal !== "agent/"),
+    signals
+  };
+}
+async function packageHasEveDependency(filePath) {
+  try {
+    const pkg = JSON.parse(await fs6.readFile(filePath, "utf8"));
+    return Boolean(pkg.dependencies?.eve ?? pkg.devDependencies?.eve);
+  } catch {
+    return false;
+  }
+}
+
+// src/scaffold.ts
+async function scaffoldEveKnowledge(options) {
+  const detection = await detectEveProject(options.cwd);
+  if (!detection.isEveProject && !options.allowNonEve) {
+    throw new Error(
+      "No Eve project detected. Run this inside an Eve app or pass --allow-non-eve to scaffold anyway."
+    );
+  }
+  const files = scaffoldFiles();
+  const written = [];
+  const skipped = [];
+  for (const file of files) {
+    const absolutePath = path9.join(options.cwd, file.path);
+    const exists = await pathExists(absolutePath);
+    if (exists && !options.force) {
+      skipped.push(file.path);
+      continue;
+    }
+    if (!options.dryRun) {
+      await fs7.mkdir(path9.dirname(absolutePath), { recursive: true });
+      await fs7.writeFile(absolutePath, file.content);
+    }
+    written.push(file.path);
+  }
+  return { files, written, skipped };
+}
+function scaffoldFiles() {
+  return [
+    {
+      path: "agent/knowledge/README.md",
+      content: knowledgeReadme()
+    },
+    {
+      path: "agent/knowledge/.eveknowledgeignore",
+      content: `${defaultIgnorePatterns.join("\n")}
+`
+    },
+    {
+      path: "agent/tools/search_knowledge.ts",
+      content: searchKnowledgeTool()
+    },
+    {
+      path: "agent/skills/answer-with-citations.md",
+      content: citationSkill()
+    },
+    {
+      path: "eve-knowledge.config.json",
+      content: configFile()
+    }
+  ];
+}
+function knowledgeReadme() {
+  return `# Agent Knowledge
+
+Place reference docs for this Eve agent here. This folder is indexed by eve-knowledge; Eve core does not currently load agent/knowledge as a native slot.
+
+Recommended folders:
+
+- product/
+- runbooks/
+- decisions/
+- policies/
+
+Do not store credentials, private customer data, or regulated records here unless your team has consent, retention, deletion, and access-control rules in place.
+`;
+}
+function searchKnowledgeTool() {
+  return `import { defineTool } from "eve/tools";
+import { parseSearchKnowledgeInput, searchKnowledge, toModelOutput } from "eve-knowledge";
+
+const inputSchema = {
+  type: "object",
+  properties: {
+    query: {
+      type: "string",
+      minLength: 1,
+      description: "The natural-language knowledge search query.",
+    },
+    topK: {
+      type: "integer",
+      minimum: 1,
+      maximum: 10,
+      description: "Maximum number of cited chunks to return.",
+    },
+    filters: {
+      type: "object",
+      additionalProperties: true,
+      description: "Optional metadata filters such as audience, tenant, or product.",
+    },
+  },
+  required: ["query"],
+  additionalProperties: false,
+} as const;
+
+export default defineTool({
+  description: "Search the agent knowledge base and return cited results.",
+  inputSchema,
+  async execute(input) {
+    return searchKnowledge(parseSearchKnowledgeInput(input));
+  },
+  toModelOutput(output) {
+    return toModelOutput(output);
+  },
+});
+`;
+}
+function citationSkill() {
+  return `---
+description: Answer using retrieved eve-knowledge citations.
+---
+
+# Answer With Citations
+
+When answering from knowledge search results:
+
+- Use only the retrieved evidence.
+- Cite repo-relative source paths and headings when available.
+- If the evidence is missing or weak, say you do not know.
+- Do not expose secrets, raw private data, or unrelated chunks.
+`;
+}
+function configFile() {
+  return `{
+  "knowledgeDir": "agent/knowledge",
+  "storeDir": ".eve-knowledge",
+  "redaction": {
+    "mode": "warn"
+  }
+}
+`;
+}
+
+// src/index.ts
+var version = "0.1.0";
+
+// src/cli.ts
+function createCli() {
+  const program = new Command();
+  program.name("eve-knowledge").description("Add a cited agent/knowledge folder to Eve agents.").version(version);
+  program.command("init").description("Create the agent/knowledge convention, Eve tool, citation skill, and config.").option("--dry-run", "Print planned files without writing them.").option("--force", "Overwrite existing generated files.").option("--allow-non-eve", "Scaffold even if no Eve project is detected.").action(async (options) => {
+    const result = await scaffoldEveKnowledge({
+      cwd: process.cwd(),
+      ...options.dryRun ? { dryRun: true } : {},
+      ...options.force ? { force: true } : {},
+      ...options.allowNonEve ? { allowNonEve: true } : {}
+    });
+    printList(options.dryRun ? "Would write" : "Written", result.written);
+    printList("Skipped existing files", result.skipped);
+    if (result.skipped.length > 0 && !options.force) {
+      console.log("Use --force to overwrite skipped files.");
+    }
+  });
+  program.command("index").description("Index files from agent/knowledge into the configured local store.").option("--trusted-config", "Allow executable eve-knowledge.config.ts/js/mjs. Use only with trusted code.").action(async (options) => {
+    const config = await loadKnowledgeConfig({ trustedConfig: Boolean(options.trustedConfig) });
+    const summary = await indexKnowledge({ config });
+    console.log(JSON.stringify(summary, null, 2));
+    if (summary.errors.length > 0) {
+      process.exitCode = 1;
+    }
+  });
+  program.command("search").description("Search the local knowledge store.").argument("<query>", "Knowledge search query.").option("--top-k <number>", "Maximum number of results.", parseInteger).option("--trusted-config", "Allow executable eve-knowledge.config.ts/js/mjs. Use only with trusted code.").action(async (query, options) => {
+    const config = await loadKnowledgeConfig({ trustedConfig: Boolean(options.trustedConfig) });
+    const response = await searchKnowledge(
+      {
+        query,
+        ...options.topK !== void 0 ? { topK: options.topK } : {}
+      },
+      { config }
+    );
+    console.log(JSON.stringify(response, null, 2));
+  });
+  program.command("check").description("Validate that knowledge can be indexed safely for CI.").option("--production", "Fail if the configured store is not durable.").option("--trusted-config", "Allow executable eve-knowledge.config.ts/js/mjs. Use only with trusted code.").action(async (options) => {
+    const loadedConfig = await loadKnowledgeConfig({ trustedConfig: Boolean(options.trustedConfig) });
+    const result = await checkKnowledge({
+      config: {
+        ...loadedConfig
+      },
+      ...options.production ? { production: true } : {}
+    });
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
+  });
+  return program;
+}
+async function runCli(argv = process.argv) {
+  await createCli().parseAsync(argv);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await runCli();
+}
+function printList(label, values) {
+  if (values.length === 0) return;
+  console.log(`${label}:`);
+  for (const value of values) {
+    console.log(`  - ${value}`);
+  }
+}
+function parseInteger(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed)) {
+    throw new Error(`Expected an integer, received ${value}`);
+  }
+  return parsed;
+}
+export {
+  createCli,
+  runCli
+};
+//# sourceMappingURL=cli.js.map