substrata-cli 0.1.0

package/dist/chunk-5V44C5UO.js

@@ -0,0 +1,1589 @@
+// ../core/dist/index.js
+import path from "path";
+import { randomBytes } from "crypto";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { readFile } from "fs/promises";
+import path2 from "path";
+import { parse as parseYaml2, stringify as stringifyYaml2 } from "yaml";
+import { mkdir, readdir, readFile as readFile2, writeFile } from "fs/promises";
+import path3 from "path";
+import { readdir as readdir2, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import path4 from "path";
+import { readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
+import { parse as parseYaml3, stringify as stringifyYaml3 } from "yaml";
+import { mkdir as mkdir2, writeFile as writeFile4 } from "fs/promises";
+import path5 from "path";
+import { readFileSync, writeFileSync } from "fs";
+import path6 from "path";
+import { lstatSync } from "fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import path7 from "path";
+import { chmodSync, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
+import path8 from "path";
+var SubstrataError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SubstrataError";
+  }
+};
+var ConfigError = class extends SubstrataError {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+var ParseError = class extends SubstrataError {
+  filePath;
+  constructor(message, filePath) {
+    super(filePath ? `${message} (${filePath})` : message);
+    this.name = "ParseError";
+    this.filePath = filePath;
+  }
+};
+var SecretDetectedError = class extends SubstrataError {
+  findings;
+  constructor(findings) {
+    const detail = findings.map((f) => `${f.name} at line ${f.line}`).join(", ");
+    super(`Refusing to write: ${findings.length} potential secret(s) detected: ${detail}`);
+    this.name = "SecretDetectedError";
+    this.findings = findings;
+  }
+};
+var NotFoundError = class extends SubstrataError {
+  constructor(message) {
+    super(message);
+    this.name = "NotFoundError";
+  }
+};
+var SUBSTRATA_DIRNAME = ".substrata";
+function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+function substrataDir(cwd) {
+  return path.join(cwd, SUBSTRATA_DIRNAME);
+}
+function configPath(cwd) {
+  return path.join(substrataDir(cwd), "config.yml");
+}
+function footprintsDir(cwd) {
+  return path.join(substrataDir(cwd), "footprints");
+}
+function memoryDir(cwd) {
+  return path.join(substrataDir(cwd), "memory");
+}
+function templatesDir(cwd) {
+  return path.join(substrataDir(cwd), "templates");
+}
+function indexPath(cwd) {
+  return path.join(substrataDir(cwd), "index", "footprint.sqlite");
+}
+function relativeToCwd(cwd, absolutePath) {
+  return toPosix(path.relative(cwd, absolutePath));
+}
+var SUFFIX_ALPHABET = "abcdefghjkmnpqrstvwxyz0123456789";
+var SUFFIX_LENGTH = 6;
+function slugify(title) {
+  const slug = title.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "untitled";
+}
+function randomSuffix(length = SUFFIX_LENGTH) {
+  const bytes = randomBytes(length);
+  let out = "";
+  for (let i = 0; i < length; i++) {
+    out += SUFFIX_ALPHABET[bytes[i] % SUFFIX_ALPHABET.length];
+  }
+  return out;
+}
+function generateFootprintId(date, slug, suffix) {
+  const yyyy = String(date.getUTCFullYear()).padStart(4, "0");
+  const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(date.getUTCDate()).padStart(2, "0");
+  const underscored = slug.replace(/-/g, "_");
+  const sfx = suffix ?? randomSuffix();
+  return `fp_${yyyy}${mm}${dd}_${underscored}_${sfx}`;
+}
+function buildFootprintFilename(date, slug, suffix) {
+  const yyyy = String(date.getUTCFullYear()).padStart(4, "0");
+  const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(date.getUTCDate()).padStart(2, "0");
+  return `${yyyy}/${mm}/${yyyy}-${mm}-${dd}-${slug}-${suffix}.md`;
+}
+var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+function parseFrontmatter(raw) {
+  const match = FRONTMATTER_RE.exec(raw);
+  if (!match) {
+    return { frontmatter: {}, body: raw };
+  }
+  const parsed = parseYaml(match[1]);
+  const frontmatter = parsed && typeof parsed === "object" ? parsed : {};
+  return { frontmatter, body: match[2] ?? "" };
+}
+function serializeFrontmatter(frontmatter, body) {
+  const yaml = stringifyYaml(frontmatter, { lineWidth: 0 }).trimEnd();
+  const trimmedBody = body.replace(/^\r?\n+/, "");
+  return `---
+${yaml}
+---
+
+${trimmedBody.length > 0 ? `${trimmedBody.replace(/\s+$/, "")}
+` : ""}`;
+}
+function extractTitle(body) {
+  const match = /^#\s+(.+?)\s*$/m.exec(body);
+  return match ? match[1].trim() : "";
+}
+function renderListSection(heading, items) {
+  if (!items || items.length === 0) return null;
+  const lines = items.map((item) => `- ${item}`);
+  return `## ${heading}
+
+${lines.join("\n")}`;
+}
+function renderProseSection(heading, text) {
+  if (!text || text.trim().length === 0) return null;
+  return `## ${heading}
+
+${text.trim()}`;
+}
+function renderRejectedOptions(options) {
+  if (!options || options.length === 0) return null;
+  const blocks = options.map((o) => `### ${o.option}
+
+${o.reason.trim()}`);
+  return `## Rejected options
+
+${blocks.join("\n\n")}`;
+}
+function renderCommands(commands) {
+  if (!commands || commands.length === 0) return null;
+  return `## Commands run
+
+\`\`\`bash
+${commands.join("\n")}
+\`\`\``;
+}
+function renderFootprintBody(title, sections) {
+  const parts = [
+    `# ${title}`,
+    renderProseSection("Purpose", sections.purpose),
+    renderListSection("Decisions", sections.decisions),
+    renderRejectedOptions(sections.rejectedOptions),
+    renderProseSection("Implementation notes", sections.implementationNotes),
+    renderCommands(sections.commandsRun),
+    renderListSection("Memory learned", sections.memoryLearned),
+    renderProseSection("Future agent guidance", sections.futureAgentGuidance)
+  ];
+  return `${parts.filter((p) => p !== null).join("\n\n")}
+`;
+}
+function splitSections(body) {
+  const lines = body.split(/\r?\n/);
+  const sections = [];
+  let current = null;
+  let inFence = false;
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) {
+      inFence = !inFence;
+      if (current) current.content += `${line}
+`;
+      continue;
+    }
+    const headingMatch = !inFence ? /^##\s+(.+?)\s*$/.exec(line) : null;
+    if (headingMatch) {
+      if (current) sections.push(current);
+      current = { heading: headingMatch[1].trim(), content: "" };
+      continue;
+    }
+    if (current) current.content += `${line}
+`;
+  }
+  if (current) sections.push(current);
+  return sections;
+}
+function parseListItems(content) {
+  return content.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.startsWith("- ")).map((l) => l.slice(2).trim()).filter((l) => l.length > 0);
+}
+function parseProse(content) {
+  return content.trim();
+}
+function parseCommands(content) {
+  const fenceMatch = /```(?:bash|sh)?\r?\n([\s\S]*?)```/.exec(content);
+  const inner = fenceMatch ? fenceMatch[1] : content;
+  return inner.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
+}
+function parseRejectedOptions(content) {
+  const options = [];
+  const parts = content.split(/^###\s+/m);
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const newlineIdx = trimmed.indexOf("\n");
+    if (newlineIdx === -1) {
+      options.push({ option: trimmed, reason: "" });
+      continue;
+    }
+    const option = trimmed.slice(0, newlineIdx).trim();
+    const reason = trimmed.slice(newlineIdx + 1).trim();
+    options.push({ option, reason });
+  }
+  return options;
+}
+function parseFootprintBody(body) {
+  const sections = {};
+  for (const raw of splitSections(body)) {
+    const key = raw.heading.toLowerCase();
+    switch (key) {
+      case "purpose":
+        sections.purpose = parseProse(raw.content);
+        break;
+      case "decisions":
+        sections.decisions = parseListItems(raw.content);
+        break;
+      case "rejected options":
+        sections.rejectedOptions = parseRejectedOptions(raw.content);
+        break;
+      case "implementation notes":
+        sections.implementationNotes = parseProse(raw.content);
+        break;
+      case "commands run":
+        sections.commandsRun = parseCommands(raw.content);
+        break;
+      case "memory learned":
+        sections.memoryLearned = parseListItems(raw.content);
+        break;
+      case "future agent guidance":
+        sections.futureAgentGuidance = parseProse(raw.content);
+        break;
+      default:
+        break;
+    }
+  }
+  return sections;
+}
+var defaultConfig = {
+  schema_version: 1,
+  project: {
+    name: "substrata-demo"
+  },
+  storage: {
+    footprints_dir: ".substrata/footprints",
+    memory_dir: ".substrata/memory",
+    index_path: ".substrata/index/footprint.sqlite"
+  },
+  search: {
+    default_limit: 8,
+    max_context_tokens: 1600
+  },
+  security: {
+    redact: true,
+    scan_content: true,
+    entropy_scan: false,
+    entropy_min_length: 32,
+    block_on_secret: true,
+    redaction_keys: [
+      "token",
+      "apiKey",
+      "api_key",
+      "authorization",
+      "password",
+      "secret",
+      "cookie",
+      "privateKey",
+      "accessToken",
+      "refreshToken"
+    ]
+  },
+  agent: {
+    default_actor: "unknown-agent",
+    require_footprint_after_non_trivial_work: true
+  }
+};
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepMerge(base, override) {
+  if (!isObject(base) || !isObject(override)) {
+    return override === void 0 ? base : override;
+  }
+  const result = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (value === void 0) continue;
+    const baseValue = base[key];
+    if (isObject(baseValue) && isObject(value)) {
+      result[key] = deepMerge(baseValue, value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+async function loadConfig(cwd) {
+  const file = configPath(cwd);
+  let raw;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch {
+    throw new ConfigError(`Config not found at ${file}. Run \`substrata init\`.`);
+  }
+  let parsed;
+  try {
+    parsed = parseYaml2(raw);
+  } catch (err) {
+    throw new ConfigError(`Failed to parse ${file}: ${err.message}`);
+  }
+  if (!isObject(parsed)) {
+    throw new ConfigError(`Config at ${file} must be a YAML mapping.`);
+  }
+  if (parsed.schema_version !== 1) {
+    throw new ConfigError(
+      `Unsupported config schema_version: ${String(parsed.schema_version)} (expected 1).`
+    );
+  }
+  const base = {
+    ...defaultConfig,
+    project: { name: path2.basename(cwd) }
+  };
+  return deepMerge(base, parsed);
+}
+function renderConfig(projectName) {
+  const config = {
+    ...defaultConfig,
+    project: { name: projectName }
+  };
+  return stringifyYaml2(config, { lineWidth: 0 });
+}
+var DEFAULT_REDACTION_KEYS2 = [
+  "token",
+  "apiKey",
+  "api_key",
+  "authorization",
+  "password",
+  "secret",
+  "cookie",
+  "set-cookie",
+  "privateKey",
+  "accessToken",
+  "refreshToken"
+];
+var REDACTED = "[REDACTED]";
+function normalizeKey(key) {
+  return key.toLowerCase().replace(/[-_]/g, "");
+}
+function redactDeep(value, options = {}) {
+  const keys = options.keys ?? DEFAULT_REDACTION_KEYS2;
+  const replacement = options.replacement ?? REDACTED;
+  const normalizedKeys = new Set(keys.map(normalizeKey));
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      return node.map(walk);
+    }
+    if (node && typeof node === "object") {
+      const out = {};
+      for (const [k, v] of Object.entries(node)) {
+        if (normalizedKeys.has(normalizeKey(k))) {
+          out[k] = replacement;
+        } else {
+          out[k] = walk(v);
+        }
+      }
+      return out;
+    }
+    return node;
+  };
+  return walk(value);
+}
+var SECRET_PATTERNS = [
+  { name: "aws_access_key_id", re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { name: "github_pat", re: /\bghp_[A-Za-z0-9]{36}\b/ },
+  { name: "github_fine_grained", re: /\bgithub_pat_[A-Za-z0-9_]{60,}\b/ },
+  { name: "gitlab_pat", re: /\bglpat-[A-Za-z0-9_-]{20}\b/ },
+  { name: "slack_token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+  { name: "google_api_key", re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+  { name: "openai_key", re: /\bsk-[A-Za-z0-9]{20,}\b/ },
+  { name: "anthropic_key", re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/ },
+  {
+    name: "jwt",
+    re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/
+  },
+  {
+    name: "private_key_block",
+    re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/
+  },
+  { name: "bearer_header", re: /\bBearer\s+[A-Za-z0-9._-]{20,}\b/ },
+  { name: "url_basic_auth", re: /\b[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:[^/\s:@]+@/i }
+];
+function scanForSecrets(text) {
+  const findings = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const { name, re } of SECRET_PATTERNS) {
+      if (re.test(line)) {
+        findings.push({ name, line: i + 1 });
+      }
+    }
+  }
+  return findings;
+}
+var REQUIRED_KEYS = [
+  "schema_version",
+  "id",
+  "created_at",
+  "actor",
+  "work_type",
+  "status"
+];
+var VALID_WORK_TYPES = /* @__PURE__ */ new Set([
+  "implementation",
+  "implementation_decision",
+  "bug_fix",
+  "refactor",
+  "investigation",
+  "architecture_decision",
+  "test_update",
+  "documentation"
+]);
+var VALID_STATUSES = /* @__PURE__ */ new Set([
+  "draft",
+  "completed",
+  "superseded",
+  "deprecated"
+]);
+function validateFrontmatter(fm, filePath) {
+  for (const key of REQUIRED_KEYS) {
+    if (fm[key] === void 0 || fm[key] === null) {
+      throw new ParseError(`Footprint missing required frontmatter field "${key}"`, filePath);
+    }
+  }
+  if (fm.schema_version !== 1) {
+    throw new ParseError(
+      `Footprint has unsupported schema_version: ${String(fm.schema_version)} (expected 1)`,
+      filePath
+    );
+  }
+  if (typeof fm.id !== "string" || fm.id.length === 0) {
+    throw new ParseError('Footprint "id" must be a non-empty string', filePath);
+  }
+  if (typeof fm.actor !== "string" || fm.actor.length === 0) {
+    throw new ParseError('Footprint "actor" must be a non-empty string', filePath);
+  }
+  if (typeof fm.created_at !== "string" || fm.created_at.length === 0) {
+    throw new ParseError('Footprint "created_at" must be a non-empty string', filePath);
+  }
+  if (typeof fm.work_type !== "string" || !VALID_WORK_TYPES.has(fm.work_type)) {
+    throw new ParseError(`Footprint has invalid work_type: ${String(fm.work_type)}`, filePath);
+  }
+  if (typeof fm.status !== "string" || !VALID_STATUSES.has(fm.status)) {
+    throw new ParseError(`Footprint has invalid status: ${String(fm.status)}`, filePath);
+  }
+  return fm;
+}
+function parseFootprint(raw, filePath) {
+  const { frontmatter, body } = parseFrontmatter(raw);
+  const fm = validateFrontmatter(frontmatter, filePath);
+  const title = extractTitle(body);
+  const sections = parseFootprintBody(body);
+  return { frontmatter: fm, title, body, sections, filePath, raw };
+}
+async function parseFootprintFile(filePath) {
+  let raw;
+  try {
+    raw = await readFile2(filePath, "utf8");
+  } catch {
+    throw new ParseError("Footprint file could not be read", filePath);
+  }
+  return parseFootprint(raw, filePath);
+}
+function mergeSupersedes(related, supersedes) {
+  if (!related && (!supersedes || supersedes.length === 0)) return void 0;
+  const merged = { ...related ?? {} };
+  if (supersedes && supersedes.length > 0) {
+    const existing = merged.supersedes ?? [];
+    merged.supersedes = Array.from(/* @__PURE__ */ new Set([...existing, ...supersedes]));
+  }
+  return merged;
+}
+function cleanFrontmatter(fm) {
+  const out = {
+    schema_version: fm.schema_version,
+    id: fm.id,
+    created_at: fm.created_at
+  };
+  if (fm.updated_at) out.updated_at = fm.updated_at;
+  out.actor = fm.actor;
+  if (fm.requester) out.requester = fm.requester;
+  if (fm.agent_model) out.agent_model = fm.agent_model;
+  out.work_type = fm.work_type;
+  out.status = fm.status;
+  if (fm.repo && (fm.repo.name || fm.repo.branch)) out.repo = fm.repo;
+  if (fm.related && Object.keys(fm.related).length > 0) out.related = fm.related;
+  if (fm.files_touched && fm.files_touched.length > 0) out.files_touched = fm.files_touched;
+  if (fm.tags && fm.tags.length > 0) out.tags = fm.tags;
+  return out;
+}
+function validateFilesTouched(files) {
+  if (!files || files.length === 0) return void 0;
+  return files.map((entry) => {
+    const f = entry.trim().replace(/\\/g, "/");
+    if (f === "") {
+      throw new ParseError("files_touched entries must be non-empty repo-relative paths");
+    }
+    if (f.startsWith("/") || /^[A-Za-z]:\//.test(f)) {
+      throw new ParseError(`files_touched must be repo-relative, got absolute path: ${f}`);
+    }
+    if (f.split("/").includes("..")) {
+      throw new ParseError(`files_touched must not contain '..' segments: ${f}`);
+    }
+    return f;
+  });
+}
+function validateRelatedUrls(related) {
+  for (const u of related?.urls ?? []) {
+    let parsed;
+    try {
+      parsed = new URL(u);
+    } catch {
+      throw new ParseError(`related.urls entry is not a valid URL: ${u}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new ParseError(`related.urls only allows http(s) URLs, got: ${u}`);
+    }
+  }
+}
+async function writeFootprint(input) {
+  const { cwd } = input;
+  const config = await loadConfig(cwd);
+  const createdAt = input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const date = new Date(createdAt);
+  const slug = slugify(input.title);
+  const suffix = randomSuffix();
+  const id = generateFootprintId(date, slug, suffix);
+  const relPath = buildFootprintFilename(date, slug, suffix);
+  const absPath = path3.join(footprintsDir(cwd), ...relPath.split("/"));
+  const workType = input.workType ?? "implementation";
+  const status = input.status ?? "completed";
+  const filesTouched = validateFilesTouched(input.filesTouched);
+  const related = mergeSupersedes(input.related, input.supersedes);
+  validateRelatedUrls(related);
+  const frontmatter = {
+    schema_version: 1,
+    id,
+    created_at: createdAt,
+    actor: input.actor,
+    requester: input.requester,
+    agent_model: input.agentModel,
+    work_type: workType,
+    status,
+    repo: input.repo ? redactDeep(input.repo, { keys: config.security.redaction_keys }) : void 0,
+    related: related ? redactDeep(related, { keys: config.security.redaction_keys }) : void 0,
+    files_touched: filesTouched,
+    tags: input.tags
+  };
+  const body = renderFootprintBody(input.title, {
+    purpose: input.purpose,
+    decisions: input.decisions,
+    rejectedOptions: input.rejectedOptions,
+    implementationNotes: input.implementationNotes,
+    commandsRun: input.commandsRun,
+    memoryLearned: input.memoryLearned,
+    futureAgentGuidance: input.futureAgentGuidance
+  });
+  if (config.security.scan_content) {
+    const findings = scanForSecrets(body);
+    if (findings.length > 0 && config.security.block_on_secret && !input.allowSecret) {
+      throw new SecretDetectedError(findings);
+    }
+  }
+  const raw = serializeFrontmatter(cleanFrontmatter(frontmatter), body);
+  await mkdir(path3.dirname(absPath), { recursive: true });
+  await writeFile(absPath, raw, "utf8");
+  return parseFootprint(raw, absPath);
+}
+async function walkMarkdown(dir) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const full = path3.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walkMarkdown(full));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+async function listFootprints(cwd) {
+  const dir = footprintsDir(cwd);
+  const files = await walkMarkdown(dir);
+  const footprints = await Promise.all(files.map((f) => parseFootprintFile(f)));
+  footprints.sort((a, b) => {
+    const at = a.frontmatter.created_at;
+    const bt = b.frontmatter.created_at;
+    return at < bt ? 1 : at > bt ? -1 : 0;
+  });
+  return footprints;
+}
+async function findFootprintById(cwd, id) {
+  const files = await walkMarkdown(footprintsDir(cwd));
+  for (const file of files) {
+    const fp = await parseFootprintFile(file);
+    if (fp.frontmatter.id === id) return fp;
+  }
+  return null;
+}
+var ENTRIES_START = "<!-- substrata:entries:start -->";
+var ENTRIES_END = "<!-- substrata:entries:end -->";
+function entryOpen(id) {
+  return `<!-- substrata:entry id=${id} -->`;
+}
+var ENTRY_CLOSE = "<!-- /substrata:entry -->";
+function validateMemoryFrontmatter(fm, filePath) {
+  if (fm.schema_version !== 1) {
+    throw new ParseError(
+      `Memory file has unsupported schema_version: ${String(fm.schema_version)} (expected 1)`,
+      filePath
+    );
+  }
+  if (typeof fm.id !== "string" || fm.id.length === 0) {
+    throw new ParseError('Memory "id" must be a non-empty string', filePath);
+  }
+  return fm;
+}
+function parseMemory(raw, filePath) {
+  const { frontmatter, body } = parseFrontmatter(raw);
+  const fm = validateMemoryFrontmatter(frontmatter, filePath);
+  return { frontmatter: fm, title: extractTitle(body), body, filePath, raw };
+}
+async function parseMemoryFile(filePath) {
+  let raw;
+  try {
+    raw = await readFile3(filePath, "utf8");
+  } catch {
+    throw new ParseError("Memory file could not be read", filePath);
+  }
+  return parseMemory(raw, filePath);
+}
+async function walkMarkdown2(dir) {
+  let entries;
+  try {
+    entries = await readdir2(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const full = path4.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walkMarkdown2(full));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+async function listMemoryDocuments(cwd) {
+  const files = await walkMarkdown2(memoryDir(cwd));
+  files.sort();
+  return Promise.all(files.map((f) => parseMemoryFile(f)));
+}
+function existingEntryIds(content) {
+  const ids = /* @__PURE__ */ new Set();
+  const re = /<!--\s*substrata:entry\s+id=([^\s]+)\s*-->/g;
+  let match;
+  while ((match = re.exec(content)) !== null) {
+    ids.add(match[1]);
+  }
+  return ids;
+}
+function renderEntry(entry) {
+  return [entryOpen(entry.sourceId), ...entry.lines, ENTRY_CLOSE].join("\n");
+}
+async function appendMemoryEntries(filePath, entries) {
+  const original = await readFile3(filePath, "utf8");
+  const existing = existingEntryIds(original);
+  const toAdd = entries.filter((e) => !existing.has(e.sourceId));
+  if (toAdd.length === 0) return false;
+  const rendered = toAdd.map(renderEntry).join("\n");
+  let next;
+  const endIdx = original.indexOf(ENTRIES_END);
+  if (endIdx !== -1) {
+    const before = original.slice(0, endIdx);
+    const after = original.slice(endIdx);
+    const sep = before.endsWith("\n") ? "" : "\n";
+    next = `${before}${sep}${rendered}
+${after}`;
+  } else {
+    const base = original.endsWith("\n") ? original : `${original}
+`;
+    next = `${base}
+${ENTRIES_START}
+${rendered}
+${ENTRIES_END}
+`;
+  }
+  await writeFile2(filePath, next, "utf8");
+  return true;
+}
+var FRONTMATTER_RE2 = /^(---\r?\n)([\s\S]*?)(\r?\n---\r?\n?)([\s\S]*)$/;
+function addUnique(list, value) {
+  const arr = list ? [...list] : [];
+  if (!arr.includes(value)) arr.push(value);
+  return arr;
+}
+async function editFrontmatter(filePath, mutate) {
+  const raw = await readFile4(filePath, "utf8");
+  const match = FRONTMATTER_RE2.exec(raw);
+  if (!match) {
+    throw new NotFoundError(`Footprint at ${filePath} has no parseable frontmatter`);
+  }
+  const [, open, yamlText, close, body] = match;
+  const parsed = parseYaml3(yamlText);
+  mutate(parsed);
+  const newYaml = stringifyYaml3(parsed, { lineWidth: 0 }).replace(/\n$/, "");
+  const next = `${open}${newYaml}${close}${body}`;
+  await writeFile3(filePath, next, "utf8");
+}
+async function supersedeFootprint(cwd, oldId, newId) {
+  const oldFp = await findFootprintById(cwd, oldId);
+  if (!oldFp) throw new NotFoundError(`Footprint not found: ${oldId}`);
+  const newFp = await findFootprintById(cwd, newId);
+  if (!newFp) throw new NotFoundError(`Footprint not found: ${newId}`);
+  await editFrontmatter(oldFp.filePath, (fm) => {
+    fm.status = "superseded";
+    const related = fm.related ?? {};
+    related.superseded_by = addUnique(related.superseded_by, newId);
+    fm.related = related;
+  });
+  await editFrontmatter(newFp.filePath, (fm) => {
+    const related = fm.related ?? {};
+    related.supersedes = addUnique(related.supersedes, oldId);
+    fm.related = related;
+  });
+}
+var README_CONTENTS = `# Substrata
+
+This directory holds shared agent memory for this repository.
+
+- \`footprints/\` \u2014 committed source-of-truth records of agent-assisted work.
+- \`memory/\` \u2014 curated, durable repo knowledge agents should read often.
+- \`templates/\` \u2014 templates used when creating footprints and memory files.
+- \`config.yml\` \u2014 Substrata configuration (see the docs).
+- \`index/\` and \`cache/\` \u2014 generated, gitignored; safe to delete and rebuild.
+
+Footprints and memory files are committed. Do not store secrets, credentials,
+private keys, tokens, or sensitive user data here.
+`;
+var FOOTPRINT_TEMPLATE = `---
+schema_version: 1
+id: fp_YYYYMMDD_slug_suffix
+created_at: 2026-01-01T00:00:00Z
+actor: unknown-agent
+work_type: implementation
+status: completed
+---
+
+# Title
+
+## Purpose
+
+Why this work was done.
+
+## Decisions
+
+- Decision one.
+
+## Rejected options
+
+### Option name
+
+Why it was rejected.
+
+## Implementation notes
+
+What was changed.
+
+## Commands run
+
+\`\`\`bash
+pnpm test
+\`\`\`
+
+## Memory learned
+
+- Something durable about this repo.
+
+## Future agent guidance
+
+What a future agent should check before changing this area.
+`;
+var MEMORY_TEMPLATE = `---
+schema_version: 1
+id: mem_example
+type: repo_conventions
+tags:
+  - conventions
+---
+
+# Memory title
+
+## Section
+
+- Durable note one.
+
+<!-- substrata:entries:start -->
+<!-- substrata:entries:end -->
+`;
+async function exists(p) {
+  const { stat: stat3 } = await import("fs/promises");
+  try {
+    await stat3(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function initProject(cwd, options = {}) {
+  const projectName = options.projectName ?? path5.basename(path5.resolve(cwd));
+  const dirs = [
+    substrataDir(cwd),
+    footprintsDir(cwd),
+    memoryDir(cwd),
+    templatesDir(cwd)
+  ];
+  const files = [
+    { absPath: configPath(cwd), contents: renderConfig(projectName) },
+    { absPath: path5.join(substrataDir(cwd), "README.md"), contents: README_CONTENTS },
+    { absPath: path5.join(templatesDir(cwd), "footprint.md"), contents: FOOTPRINT_TEMPLATE },
+    { absPath: path5.join(templatesDir(cwd), "memory.md"), contents: MEMORY_TEMPLATE }
+  ];
+  const changes = [];
+  for (const dir of dirs) {
+    await mkdir2(dir, { recursive: true });
+  }
+  for (const file of files) {
+    if (await exists(file.absPath)) {
+      changes.push({
+        path: file.absPath,
+        action: "skip",
+        description: "already exists"
+      });
+      continue;
+    }
+    await writeFile4(file.absPath, file.contents, "utf8");
+    changes.push({
+      path: file.absPath,
+      action: "create",
+      description: "created",
+      contents: file.contents
+    });
+  }
+  return changes;
+}
+function isSymlink(filePath) {
+  try {
+    return lstatSync(filePath).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+var GITIGNORE_LINES = [".substrata/index/", ".substrata/cache/", ".substrata/tmp/"];
+function readIfExists(filePath) {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function ensureGitignore(cwd, dry = false) {
+  const filePath = path6.join(cwd, ".gitignore");
+  if (isSymlink(filePath)) {
+    return { path: filePath, action: "skip", description: "refused: .gitignore is a symlink" };
+  }
+  const existing = readIfExists(filePath);
+  const present = existing ?? "";
+  const presentLines = new Set(present.split(/\r?\n/).map((l) => l.trim()));
+  const missing = GITIGNORE_LINES.filter((line) => !presentLines.has(line));
+  if (missing.length === 0) {
+    return {
+      path: filePath,
+      action: "skip",
+      description: existing === null ? "no gitignore needed" : "gitignore already covers Substrata"
+    };
+  }
+  const header = "# Substrata generated files";
+  const block = presentLines.has(header) ? missing.join("\n") : `${header}
+${missing.join("\n")}`;
+  let next;
+  if (existing === null) {
+    next = `${block}
+`;
+  } else {
+    const sep = existing.endsWith("\n") ? "" : "\n";
+    next = `${existing}${sep}${block}
+`;
+  }
+  if (!dry) writeFileSync(filePath, next, "utf8");
+  return {
+    path: filePath,
+    action: existing === null ? "create" : "update",
+    description: `add ${missing.length} gitignore line(s)`,
+    contents: next
+  };
+}
+var BEGIN = "# >>> substrata >>>";
+var END = "# <<< substrata <<<";
+function readIfExists2(filePath) {
+  try {
+    return readFileSync2(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function renderBlock(vars) {
+  const lines = [BEGIN, "# Substrata agent attribution (managed; safe to edit values)"];
+  if (vars.actor) lines.push(`export SUBSTRATA_ACTOR="${vars.actor}"`);
+  if (vars.model) lines.push(`export SUBSTRATA_MODEL="${vars.model}"`);
+  if (vars.requester) lines.push(`export SUBSTRATA_REQUESTER="${vars.requester}"`);
+  lines.push(END);
+  return lines.join("\n");
+}
+function writeShellEnv(rcPath, vars, dry = false) {
+  const block = renderBlock(vars);
+  const existing = readIfExists2(rcPath);
+  const markerRe = new RegExp(`${escapeRegExp(BEGIN)}[\\s\\S]*?${escapeRegExp(END)}`, "m");
+  let next;
+  let action;
+  if (existing === null) {
+    next = `${block}
+`;
+    action = "create";
+  } else if (markerRe.test(existing)) {
+    const replaced = existing.replace(markerRe, block);
+    if (replaced === existing) {
+      return { path: rcPath, action: "skip", description: "env block already current" };
+    }
+    next = replaced;
+    action = "update";
+  } else {
+    const sep = existing.endsWith("\n") ? "" : "\n";
+    next = `${existing}${sep}
+${block}
+`;
+    action = "update";
+  }
+  if (!dry) writeFileSync2(rcPath, next, "utf8");
+  return {
+    path: rcPath,
+    action,
+    description: "write Substrata env block",
+    contents: next
+  };
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var BEGIN2 = "<!-- substrata:start -->";
+var END2 = "<!-- substrata:end -->";
+var AGENTS_MD_SECTION = `${BEGIN2}
+## Substrata Rules
+
+This repository uses Substrata for shared agent memory.
+
+Set these once per agent session so footprints are attributed correctly:
+- \`SUBSTRATA_ACTOR\`     (e.g. "claude-code")
+- \`SUBSTRATA_MODEL\`     (e.g. "claude-opus-4")
+- \`SUBSTRATA_REQUESTER\` (falls back to git user.email)
+
+Before making non-trivial changes:
+
+1. Run \`substrata context "<task description>"\`.
+2. Search for relevant files using \`substrata search\` or the MCP tool \`substrata_context\`.
+3. Respect prior architectural decisions unless the user explicitly asks to override them.
+
+After making non-trivial changes:
+
+1. Add a footprint with \`substrata add\` or MCP tool \`substrata_add\`.
+2. Include: purpose, requester, actor, files changed, decisions made, rejected
+   alternatives, implementation notes, commands run, memory learned, future agent guidance.
+3. If the work changes durable repo conventions, update \`.substrata/memory/\`.
+4. If the work reverses a prior decision, use \`substrata supersede\`.
+
+Do not store secrets, credentials, private keys, tokens, or sensitive user data in Substrata files.
+${END2}`;
+function readIfExists3(filePath) {
+  try {
+    return readFileSync3(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function escapeRegExp2(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function upsertAgentsMd(cwd, dry = false) {
+  const filePath = path7.join(cwd, "AGENTS.md");
+  if (isSymlink(filePath)) {
+    return { path: filePath, action: "skip", description: "refused: AGENTS.md is a symlink" };
+  }
+  const existing = readIfExists3(filePath);
+  const markerRe = new RegExp(`${escapeRegExp2(BEGIN2)}[\\s\\S]*?${escapeRegExp2(END2)}`, "m");
+  let next;
+  let action;
+  if (existing === null) {
+    next = `${AGENTS_MD_SECTION}
+`;
+    action = "create";
+  } else if (markerRe.test(existing)) {
+    const replaced = existing.replace(markerRe, AGENTS_MD_SECTION);
+    if (replaced === existing) {
+      return { path: filePath, action: "skip", description: "AGENTS.md section already current" };
+    }
+    next = replaced;
+    action = "update";
+  } else {
+    const sep = existing.endsWith("\n") ? "" : "\n";
+    next = `${existing}${sep}
+${AGENTS_MD_SECTION}
+`;
+    action = "update";
+  }
+  if (!dry) writeFileSync3(filePath, next, "utf8");
+  return {
+    path: filePath,
+    action,
+    description: "write Substrata AGENTS.md section",
+    contents: next
+  };
+}
+var GUARD_BEGIN = "# >>> substrata pre-commit >>>";
+var GUARD_END = "# <<< substrata pre-commit <<<";
+var GUARDED_BLOCK = `${GUARD_BEGIN}
+# Substrata secret scan over staged .substrata files (second line of defense).
+npx --no-install substrata internal-scan-staged || exit 1
+${GUARD_END}`;
+var FULL_HOOK = `#!/bin/sh
+${GUARDED_BLOCK}
+`;
+function readIfExists4(filePath) {
+  try {
+    return readFileSync4(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function installSecretHook(cwd, dry = false) {
+  const filePath = path8.join(cwd, ".git", "hooks", "pre-commit");
+  if (isSymlink(filePath)) {
+    return { path: filePath, action: "skip", description: "refused: pre-commit hook is a symlink" };
+  }
+  const existing = readIfExists4(filePath);
+  let next;
+  let action;
+  if (existing === null) {
+    next = FULL_HOOK;
+    action = "create";
+  } else if (existing.includes(GUARD_BEGIN)) {
+    return { path: filePath, action: "skip", description: "pre-commit hook already installed" };
+  } else {
+    const sep = existing.endsWith("\n") ? "" : "\n";
+    next = `${existing}${sep}
+${GUARDED_BLOCK}
+`;
+    action = "update";
+  }
+  if (!dry) {
+    writeFileSync4(filePath, next, "utf8");
+    chmodSync(filePath, 493);
+  }
+  return {
+    path: filePath,
+    action,
+    description: "install Substrata pre-commit secret hook",
+    contents: next
+  };
+}
+
+// ../search/dist/index.js
+import { stat } from "fs/promises";
+import { existsSync, mkdirSync } from "fs";
+import path9 from "path";
+import Database from "better-sqlite3";
+import { readdir as readdir3, stat as stat2 } from "fs/promises";
+import path22 from "path";
+import path32 from "path";
+var SCHEMA_VERSION = 1;
+var CREATE_DOCUMENTS = `
+CREATE TABLE IF NOT EXISTS documents (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  title TEXT NOT NULL,
+  file_path TEXT NOT NULL,
+  status TEXT,
+  created_at TEXT,
+  updated_at TEXT,
+  tags_json TEXT NOT NULL,
+  files_json TEXT NOT NULL,
+  raw_text TEXT NOT NULL,
+  work_type TEXT
+);
+`;
+var CREATE_DOCUMENTS_FTS = `
+CREATE VIRTUAL TABLE IF NOT EXISTS documents_fts USING fts5(
+  id UNINDEXED,
+  title,
+  tags,
+  files,
+  content,
+  tokenize = 'porter unicode61'
+);
+`;
+var CREATE_INDEX_META = `
+CREATE TABLE IF NOT EXISTS index_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+function applySchema(db) {
+  db.exec(CREATE_DOCUMENTS);
+  db.exec(CREATE_DOCUMENTS_FTS);
+  db.exec(CREATE_INDEX_META);
+}
+function dropSchema(db) {
+  db.exec("DROP TABLE IF EXISTS documents;");
+  db.exec("DROP TABLE IF EXISTS documents_fts;");
+  db.exec("DROP TABLE IF EXISTS index_meta;");
+}
+function openIndexDb(cwd, options = {}) {
+  const dbPath = indexPath(cwd);
+  if (!options.readonly) {
+    mkdirSync(path9.dirname(dbPath), { recursive: true });
+  }
+  const db = new Database(dbPath, { readonly: options.readonly ?? false });
+  if (!options.readonly) {
+    db.pragma("journal_mode = DELETE");
+    applySchema(db);
+  }
+  return db;
+}
+function indexDbExists(cwd) {
+  return existsSync(indexPath(cwd));
+}
+function closeDb(db) {
+  try {
+    db.close();
+  } catch {
+  }
+}
+function joinNonEmpty(parts) {
+  return parts.map((p) => (p ?? "").trim()).filter((p) => p.length > 0).join("\n\n");
+}
+function footprintToRow(cwd, fp) {
+  const fm = fp.frontmatter;
+  const s = fp.sections;
+  const rejected = (s.rejectedOptions ?? []).map((r) => `${r.option}: ${r.reason}`).join("\n");
+  const content = joinNonEmpty([
+    fp.title,
+    s.purpose,
+    (s.decisions ?? []).join("\n"),
+    rejected,
+    s.implementationNotes,
+    (s.memoryLearned ?? []).join("\n"),
+    s.futureAgentGuidance,
+    (fm.tags ?? []).join(" "),
+    (fm.files_touched ?? []).join(" ")
+  ]);
+  return {
+    id: fm.id,
+    type: "footprint",
+    title: fp.title,
+    filePath: relativeToCwd(cwd, fp.filePath),
+    status: fm.status,
+    createdAt: fm.created_at,
+    updatedAt: fm.updated_at ?? null,
+    tags: fm.tags ?? [],
+    files: fm.files_touched ?? [],
+    content,
+    workType: fm.work_type
+  };
+}
+function memoryToRow(cwd, doc) {
+  const fm = doc.frontmatter;
+  const tags = Array.isArray(fm.tags) ? fm.tags : [];
+  const content = joinNonEmpty([doc.title, doc.body, tags.join(" ")]);
+  return {
+    id: fm.id,
+    type: "memory",
+    title: doc.title,
+    filePath: relativeToCwd(cwd, doc.filePath),
+    status: null,
+    createdAt: null,
+    updatedAt: typeof fm.updated_at === "string" ? fm.updated_at : null,
+    tags,
+    files: [],
+    content,
+    workType: null
+  };
+}
+async function maxMtimeMs(filePaths) {
+  let max = 0;
+  for (const filePath of filePaths) {
+    try {
+      const st = await stat(filePath);
+      if (st.mtimeMs > max) max = st.mtimeMs;
+    } catch {
+    }
+  }
+  return max;
+}
+function writeRows(db, rows) {
+  const insertDoc = db.prepare(
+    `INSERT INTO documents
+       (id, type, title, file_path, status, created_at, updated_at, tags_json, files_json, raw_text, work_type)
+     VALUES
+       (@id, @type, @title, @filePath, @status, @createdAt, @updatedAt, @tagsJson, @filesJson, @content, @workType)`
+  );
+  const insertFts = db.prepare(
+    `INSERT INTO documents_fts (id, title, tags, files, content)
+     VALUES (@id, @title, @tags, @files, @content)`
+  );
+  for (const row of rows) {
+    insertDoc.run({
+      id: row.id,
+      type: row.type,
+      title: row.title,
+      filePath: row.filePath,
+      status: row.status,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+      tagsJson: JSON.stringify(row.tags),
+      filesJson: JSON.stringify(row.files),
+      content: row.content,
+      workType: row.workType
+    });
+    insertFts.run({
+      id: row.id,
+      title: row.title,
+      tags: row.tags.join(" "),
+      files: row.files.join(" "),
+      content: row.content
+    });
+  }
+}
+function writeMeta(db, meta) {
+  const upsert = db.prepare(
+    `INSERT INTO index_meta (key, value) VALUES (@key, @value)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+  );
+  upsert.run({ key: "schema_version", value: String(SCHEMA_VERSION) });
+  upsert.run({ key: "built_at", value: (/* @__PURE__ */ new Date()).toISOString() });
+  upsert.run({ key: "source_max_mtime", value: String(meta.sourceMaxMtime) });
+  upsert.run({ key: "source_file_count", value: String(meta.sourceFileCount) });
+}
+async function buildIndex(cwd, _options = {}) {
+  const [footprints, memory] = await Promise.all([listFootprints(cwd), listMemoryDocuments(cwd)]);
+  const rows = [
+    ...footprints.map((fp) => footprintToRow(cwd, fp)),
+    ...memory.map((doc) => memoryToRow(cwd, doc))
+  ];
+  const sourceFiles = [
+    ...footprints.map((fp) => fp.filePath),
+    ...memory.map((doc) => doc.filePath)
+  ];
+  const sourceMaxMtime = await maxMtimeMs(sourceFiles);
+  const db = openIndexDb(cwd);
+  try {
+    const rebuild = db.transaction(() => {
+      dropSchema(db);
+      applySchema(db);
+      writeRows(db, rows);
+      writeMeta(db, { sourceMaxMtime, sourceFileCount: sourceFiles.length });
+    });
+    rebuild();
+  } finally {
+    closeDb(db);
+  }
+}
+async function walkStats(dir) {
+  let entries;
+  try {
+    entries = await readdir3(dir, { withFileTypes: true });
+  } catch {
+    return { maxMtime: 0, count: 0 };
+  }
+  let maxMtime = 0;
+  let count = 0;
+  for (const entry of entries) {
+    const full = path22.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const sub = await walkStats(full);
+      if (sub.maxMtime > maxMtime) maxMtime = sub.maxMtime;
+      count += sub.count;
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      count += 1;
+      try {
+        const st = await stat2(full);
+        if (st.mtimeMs > maxMtime) maxMtime = st.mtimeMs;
+      } catch {
+      }
+    }
+  }
+  return { maxMtime, count };
+}
+function readMeta(cwd) {
+  const db = openIndexDb(cwd, { readonly: true });
+  try {
+    const rows = db.prepare("SELECT key, value FROM index_meta").all();
+    return new Map(rows.map((r) => [r.key, r.value]));
+  } finally {
+    closeDb(db);
+  }
+}
+async function getIndexStatus(cwd) {
+  if (!indexDbExists(cwd)) {
+    return { state: "missing" };
+  }
+  let meta;
+  try {
+    meta = readMeta(cwd);
+  } catch {
+    return { state: "missing" };
+  }
+  const recordedSchema = Number(meta.get("schema_version"));
+  if (!Number.isFinite(recordedSchema) || recordedSchema !== SCHEMA_VERSION) {
+    return { state: "stale", reason: "schema" };
+  }
+  const [fp, mem] = await Promise.all([walkStats(footprintsDir(cwd)), walkStats(memoryDir(cwd))]);
+  const sourceCount = fp.count + mem.count;
+  const sourceMaxMtime = Math.max(fp.maxMtime, mem.maxMtime);
+  const recordedCount = Number(meta.get("source_file_count"));
+  if (!Number.isFinite(recordedCount) || recordedCount !== sourceCount) {
+    return { state: "stale", reason: "count" };
+  }
+  const recordedMtime = Number(meta.get("source_max_mtime"));
+  if (!Number.isFinite(recordedMtime) || sourceMaxMtime > recordedMtime + 1) {
+    return { state: "stale", reason: "mtime" };
+  }
+  return { state: "fresh" };
+}
+var RECENCY_DECAY_DAYS = 180;
+var MS_PER_DAY = 24 * 60 * 60 * 1e3;
+var RECENCY_BOOST_WEIGHT = 0.15;
+var FILES_OVERLAP_BOOST = 1.5;
+var STATUS_PENALTIES = {
+  draft: 0.5,
+  completed: 1,
+  superseded: 0.15,
+  deprecated: 0.1
+};
+function normalizeBm25(bm25) {
+  return -bm25;
+}
+function recencyDecay(timestamp, now = Date.now()) {
+  if (!timestamp) return 0;
+  const t = Date.parse(timestamp);
+  if (Number.isNaN(t)) return 0;
+  const ageDays = (now - t) / MS_PER_DAY;
+  if (ageDays <= 0) return 1;
+  if (ageDays >= RECENCY_DECAY_DAYS) return 0;
+  return 1 - ageDays / RECENCY_DECAY_DAYS;
+}
+function recencyBoost(timestamp, workType, now = Date.now()) {
+  let contribution = RECENCY_BOOST_WEIGHT * recencyDecay(timestamp, now);
+  if (workType === "architecture_decision") {
+    contribution /= 2;
+  }
+  return 1 + contribution;
+}
+function filesOverlap(docFiles, queryFiles) {
+  if (queryFiles.length === 0 || docFiles.length === 0) return false;
+  const want = new Set(queryFiles.map((f) => f.toLowerCase()));
+  return docFiles.some((f) => want.has(f.toLowerCase()));
+}
+function statusPenalty(status) {
+  if (!status) return 1;
+  return STATUS_PENALTIES[status] ?? 1;
+}
+function score(input, now = Date.now()) {
+  let s = normalizeBm25(input.bm25);
+  if (filesOverlap(input.docFiles, input.queryFiles)) {
+    s *= FILES_OVERLAP_BOOST;
+  }
+  const recencyTimestamp = input.updatedAt ?? input.createdAt ?? void 0;
+  s *= recencyBoost(recencyTimestamp, input.workType ?? null, now);
+  s *= statusPenalty(input.status ?? null);
+  return s;
+}
+var DEFAULT_LIMIT = 8;
+var FILE_HIT_BM25 = -10;
+function parseJsonArray(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+function buildMatchQuery(query) {
+  const tokens = query.split(/[^A-Za-z0-9_]+/u).map((t) => t.trim()).filter((t) => t.length > 0);
+  if (tokens.length === 0) return null;
+  return tokens.map((t) => `"${t.replace(/"/g, '""')}"`).join(" OR ");
+}
+function rowToResult(row, queryFiles) {
+  const tags = parseJsonArray(row.tags_json);
+  const files = parseJsonArray(row.files_json);
+  const status = row.status ?? "completed";
+  const ranked = score(
+    {
+      bm25: row.bm25,
+      status: row.status,
+      workType: row.work_type,
+      updatedAt: row.updated_at,
+      createdAt: row.created_at,
+      docFiles: files,
+      queryFiles
+    },
+    Date.now()
+  );
+  return {
+    id: row.id,
+    title: row.title,
+    filePath: row.file_path,
+    score: ranked,
+    snippet: row.snippet,
+    tags,
+    createdAt: row.created_at ?? void 0,
+    filesTouched: files,
+    status
+  };
+}
+function executeMatch(db, match, queryFiles, options) {
+  const where = [];
+  const params = { match };
+  if (options.excludeSuperseded) {
+    where.push("(d.status IS NULL OR d.status NOT IN ('superseded', 'deprecated'))");
+  }
+  if (options.tags && options.tags.length > 0) {
+    const clauses = options.tags.map((tag, i) => {
+      params[`tag${i}`] = tag;
+      return `EXISTS (SELECT 1 FROM json_each(d.tags_json) WHERE json_each.value = @tag${i})`;
+    });
+    where.push(`(${clauses.join(" OR ")})`);
+  }
+  if (options.files && options.files.length > 0) {
+    const clauses = options.files.map((file, i) => {
+      params[`file${i}`] = toPosix(file);
+      return `EXISTS (SELECT 1 FROM json_each(d.files_json) WHERE json_each.value = @file${i})`;
+    });
+    where.push(`(${clauses.join(" OR ")})`);
+  }
+  const whereSql = where.length > 0 ? ` AND ${where.join(" AND ")}` : "";
+  const sql = `
+    SELECT
+      d.id, d.type, d.title, d.file_path, d.status,
+      d.created_at, d.updated_at, d.tags_json, d.files_json, d.work_type,
+      bm25(documents_fts) AS bm25,
+      snippet(documents_fts, 4, '[', ']', ' \u2026 ', 12) AS snippet
+    FROM documents_fts
+    JOIN documents d ON d.id = documents_fts.id
+    WHERE documents_fts MATCH @match${whereSql}
+  `;
+  const rows = db.prepare(sql).all(params);
+  const results = rows.map((row) => rowToResult(row, queryFiles));
+  results.sort((a, b) => b.score - a.score);
+  return results.slice(0, options.limit);
+}
+async function search(query, options) {
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  const match = buildMatchQuery(query);
+  if (!match) return [];
+  const queryFiles = (options.files ?? []).map((f) => toPosix(f));
+  const db = openIndexDb(options.cwd, { readonly: true });
+  try {
+    return executeMatch(db, match, queryFiles, {
+      excludeSuperseded: options.excludeSuperseded,
+      files: options.files,
+      tags: options.tags,
+      limit
+    });
+  } finally {
+    closeDb(db);
+  }
+}
+async function getRelatedToFile(filePath, options) {
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  const posixPath = toPosix(filePath);
+  const stem = path32.basename(posixPath).replace(/\.[^.]+$/, "");
+  const db = openIndexDb(options.cwd, { readonly: true });
+  try {
+    const fileRows = db.prepare(
+      `SELECT
+           d.id, d.type, d.title, d.file_path, d.status,
+           d.created_at, d.updated_at, d.tags_json, d.files_json, d.work_type
+         FROM documents d
+         WHERE EXISTS (
+           SELECT 1 FROM json_each(d.files_json) WHERE json_each.value = @path
+         )`
+    ).all({ path: posixPath });
+    const byId = /* @__PURE__ */ new Map();
+    for (const row of fileRows) {
+      const joined = { ...row, bm25: FILE_HIT_BM25, snippet: "" };
+      const result = rowToResult(joined, [posixPath]);
+      byId.set(result.id, result);
+    }
+    const match = buildMatchQuery(stem);
+    if (match) {
+      const ftsResults = executeMatch(db, match, [posixPath], {
+        excludeSuperseded: options.excludeSuperseded,
+        tags: options.tags,
+        limit: limit * 4
+      });
+      for (const r of ftsResults) {
+        if (!byId.has(r.id)) byId.set(r.id, r);
+      }
+    }
+    let merged = Array.from(byId.values());
+    if (options.excludeSuperseded) {
+      merged = merged.filter((r) => r.status !== "superseded" && r.status !== "deprecated");
+    }
+    merged.sort((a, b) => b.score - a.score);
+    return merged.slice(0, limit);
+  } finally {
+    closeDb(db);
+  }
+}
+
+export {
+  SecretDetectedError,
+  NotFoundError,
+  substrataDir,
+  configPath,
+  memoryDir,
+  relativeToCwd,
+  loadConfig,
+  renderConfig,
+  scanForSecrets,
+  writeFootprint,
+  listFootprints,
+  findFootprintById,
+  listMemoryDocuments,
+  existingEntryIds,
+  appendMemoryEntries,
+  supersedeFootprint,
+  initProject,
+  GITIGNORE_LINES,
+  ensureGitignore,
+  writeShellEnv,
+  upsertAgentsMd,
+  installSecretHook,
+  buildIndex,
+  getIndexStatus,
+  search,
+  getRelatedToFile
+};
+//# sourceMappingURL=chunk-5V44C5UO.js.map