context-vault 2.17.1 → 3.0.2

package/node_modules/@context-vault/core/src/capture/index.js

@@ -1,250 +0,0 @@
-/**
- * Capture Layer — Public API
- *
- * Writes knowledge entries to vault as .md files and indexes them.
- * captureAndIndex() is the write-through entry point (capture + index + rollback on failure).
- */
-
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { ulid, slugify, kindToPath } from "../core/files.js";
-import { categoryFor } from "../core/categories.js";
-import { parseFrontmatter, formatFrontmatter } from "../core/frontmatter.js";
-import { formatBody } from "./formatters.js";
-import { writeEntryFile } from "./file-ops.js";
-import { indexEntry } from "../index/index.js";
-
-export function writeEntry(
-  ctx,
-  {
-    kind,
-    title,
-    body,
-    meta,
-    tags,
-    source,
-    folder,
-    identity_key,
-    expires_at,
-    supersedes,
-    related_to,
-    source_files,
-    tier,
-    userId,
-  },
-) {
-  if (!kind || typeof kind !== "string") {
-    throw new Error("writeEntry: kind is required (non-empty string)");
-  }
-  if (!body || typeof body !== "string" || !body.trim()) {
-    throw new Error("writeEntry: body is required (non-empty string)");
-  }
-  if (tags != null && !Array.isArray(tags)) {
-    throw new Error("writeEntry: tags must be an array if provided");
-  }
-  if (meta != null && typeof meta !== "object") {
-    throw new Error("writeEntry: meta must be an object if provided");
-  }
-
-  const category = categoryFor(kind);
-
-  // Entity upsert: check for existing file at deterministic path
-  let id;
-  let createdAt;
-  let updatedAt;
-  if (category === "entity" && identity_key) {
-    const identitySlug = slugify(identity_key);
-    const dir = resolve(ctx.config.vaultDir, kindToPath(kind));
-    const existingPath = resolve(dir, `${identitySlug}.md`);
-
-    if (existsSync(existingPath)) {
-      // Preserve original ID and created timestamp from existing file
-      const raw = readFileSync(existingPath, "utf-8");
-      const { meta: fmMeta } = parseFrontmatter(raw);
-      id = fmMeta.id || ulid();
-      createdAt = fmMeta.created || new Date().toISOString();
-      updatedAt = new Date().toISOString();
-    } else {
-      id = ulid();
-      createdAt = new Date().toISOString();
-      updatedAt = createdAt;
-    }
-  } else {
-    id = ulid();
-    createdAt = new Date().toISOString();
-    updatedAt = createdAt;
-  }
-
-  const filePath = writeEntryFile(ctx.config.vaultDir, kind, {
-    id,
-    title,
-    body,
-    meta,
-    tags,
-    source,
-    createdAt,
-    updatedAt,
-    folder,
-    category,
-    identity_key,
-    expires_at,
-    supersedes,
-    related_to,
-  });
-
-  return {
-    id,
-    filePath,
-    kind,
-    category,
-    title,
-    body,
-    meta,
-    tags,
-    source,
-    createdAt,
-    updatedAt,
-    identity_key,
-    expires_at,
-    supersedes,
-    related_to: related_to || null,
-    source_files: source_files || null,
-    tier: tier || null,
-    userId: userId || null,
-  };
-}
-
-/**
- * Update an existing entry's file on disk (merge provided fields with existing).
- * Does NOT re-index — caller must call indexEntry after.
- *
- * @param {{ config, stmts }} ctx
- * @param {object} existing — Row from vault table (from getEntryById)
- * @param {{ title?, body?, tags?, meta?, source?, expires_at? }} updates
- * @returns {object} Entry object suitable for indexEntry
- */
-export function updateEntryFile(ctx, existing, updates) {
-  const raw = readFileSync(existing.file_path, "utf-8");
-  const { meta: fmMeta } = parseFrontmatter(raw);
-
-  const existingMeta = existing.meta ? JSON.parse(existing.meta) : {};
-  const existingTags = existing.tags ? JSON.parse(existing.tags) : [];
-  const existingRelatedTo = existing.related_to
-    ? JSON.parse(existing.related_to)
-    : fmMeta.related_to || null;
-
-  const title = updates.title !== undefined ? updates.title : existing.title;
-  const body = updates.body !== undefined ? updates.body : existing.body;
-  const tags = updates.tags !== undefined ? updates.tags : existingTags;
-  const source =
-    updates.source !== undefined ? updates.source : existing.source;
-  const expires_at =
-    updates.expires_at !== undefined ? updates.expires_at : existing.expires_at;
-  const supersedes =
-    updates.supersedes !== undefined
-      ? updates.supersedes
-      : fmMeta.supersedes || null;
-  const related_to =
-    updates.related_to !== undefined ? updates.related_to : existingRelatedTo;
-  const source_files =
-    updates.source_files !== undefined
-      ? updates.source_files
-      : existing.source_files
-        ? JSON.parse(existing.source_files)
-        : null;
-
-  let mergedMeta;
-  if (updates.meta !== undefined) {
-    mergedMeta = { ...existingMeta, ...(updates.meta || {}) };
-  } else {
-    mergedMeta = { ...existingMeta };
-  }
-
-  // Build frontmatter
-  const now = new Date().toISOString();
-  const fmFields = { id: existing.id };
-  for (const [k, v] of Object.entries(mergedMeta)) {
-    if (k === "folder") continue;
-    if (v !== null && v !== undefined) fmFields[k] = v;
-  }
-  if (existing.identity_key) fmFields.identity_key = existing.identity_key;
-  if (expires_at) fmFields.expires_at = expires_at;
-  if (supersedes?.length) fmFields.supersedes = supersedes;
-  if (related_to?.length) fmFields.related_to = related_to;
-  fmFields.tags = tags;
-  fmFields.source = source || "claude-code";
-  fmFields.created = fmMeta.created || existing.created_at;
-  if (now !== fmFields.created) fmFields.updated = now;
-
-  const mdBody = formatBody(existing.kind, { title, body, meta: mergedMeta });
-  const md = formatFrontmatter(fmFields) + mdBody;
-
-  writeFileSync(existing.file_path, md);
-
-  const finalMeta = Object.keys(mergedMeta).length ? mergedMeta : undefined;
-
-  return {
-    id: existing.id,
-    filePath: existing.file_path,
-    kind: existing.kind,
-    category: existing.category,
-    title,
-    body,
-    meta: finalMeta,
-    tags,
-    source,
-    createdAt: fmMeta.created || existing.created_at,
-    updatedAt: now,
-    identity_key: existing.identity_key,
-    expires_at,
-    supersedes,
-    related_to: related_to || null,
-    source_files: source_files || null,
-    userId: existing.user_id || null,
-  };
-}
-
-export async function captureAndIndex(ctx, data) {
-  // For entity upserts, preserve previous file content for safe rollback
-  let previousContent = null;
-  if (categoryFor(data.kind) === "entity" && data.identity_key) {
-    const identitySlug = slugify(data.identity_key);
-    const dir = resolve(ctx.config.vaultDir, kindToPath(data.kind));
-    const existingPath = resolve(dir, `${identitySlug}.md`);
-    if (existsSync(existingPath)) {
-      previousContent = readFileSync(existingPath, "utf-8");
-    }
-  }
-
-  const entry = writeEntry(ctx, data);
-  try {
-    await indexEntry(ctx, entry);
-    // Apply supersedes: mark referenced entries as superseded by this entry
-    if (entry.supersedes?.length && ctx.stmts.updateSupersededBy) {
-      for (const supersededId of entry.supersedes) {
-        if (typeof supersededId === "string" && supersededId.trim()) {
-          ctx.stmts.updateSupersededBy.run(entry.id, supersededId.trim());
-        }
-      }
-    }
-    // Store related_to links in DB
-    if (entry.related_to?.length && ctx.stmts.updateRelatedTo) {
-      ctx.stmts.updateRelatedTo.run(JSON.stringify(entry.related_to), entry.id);
-    }
-    return entry;
-  } catch (err) {
-    // Rollback: restore previous content for entity upserts, delete for new entries
-    if (previousContent) {
-      try {
-        writeFileSync(entry.filePath, previousContent);
-      } catch {}
-    } else {
-      try {
-        unlinkSync(entry.filePath);
-      } catch {}
-    }
-    throw new Error(
-      `Capture succeeded but indexing failed — file rolled back. ${err.message}`,
-    );
-  }
-}

package/node_modules/@context-vault/core/src/capture/ingest-url.js

@@ -1,252 +0,0 @@
-export function htmlToMarkdown(html) {
-  let md = html;
-
-  // Remove scripts, styles, nav, header, footer, aside
-  md = md.replace(/<script[\s\S]*?<\/script>/gi, "");
-  md = md.replace(/<style[\s\S]*?<\/style>/gi, "");
-  md = md.replace(/<nav[\s\S]*?<\/nav>/gi, "");
-  md = md.replace(/<header[\s\S]*?<\/header>/gi, "");
-  md = md.replace(/<footer[\s\S]*?<\/footer>/gi, "");
-  md = md.replace(/<aside[\s\S]*?<\/aside>/gi, "");
-
-  // Convert headings
-  md = md.replace(
-    /<h1[^>]*>([\s\S]*?)<\/h1>/gi,
-    (_, c) => `\n# ${stripTags(c).trim()}\n`,
-  );
-  md = md.replace(
-    /<h2[^>]*>([\s\S]*?)<\/h2>/gi,
-    (_, c) => `\n## ${stripTags(c).trim()}\n`,
-  );
-  md = md.replace(
-    /<h3[^>]*>([\s\S]*?)<\/h3>/gi,
-    (_, c) => `\n### ${stripTags(c).trim()}\n`,
-  );
-  md = md.replace(
-    /<h4[^>]*>([\s\S]*?)<\/h4>/gi,
-    (_, c) => `\n#### ${stripTags(c).trim()}\n`,
-  );
-  md = md.replace(
-    /<h5[^>]*>([\s\S]*?)<\/h5>/gi,
-    (_, c) => `\n##### ${stripTags(c).trim()}\n`,
-  );
-  md = md.replace(
-    /<h6[^>]*>([\s\S]*?)<\/h6>/gi,
-    (_, c) => `\n###### ${stripTags(c).trim()}\n`,
-  );
-
-  // Convert links
-  md = md.replace(
-    /<a[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi,
-    (_, href, text) => {
-      const cleanText = stripTags(text).trim();
-      return cleanText ? `[${cleanText}](${href})` : "";
-    },
-  );
-
-  // Convert code blocks
-  md = md.replace(
-    /<pre[^>]*><code[^>]*>([\s\S]*?)<\/code><\/pre>/gi,
-    (_, c) => `\n\`\`\`\n${decodeEntities(c).trim()}\n\`\`\`\n`,
-  );
-  md = md.replace(
-    /<pre[^>]*>([\s\S]*?)<\/pre>/gi,
-    (_, c) => `\n\`\`\`\n${decodeEntities(stripTags(c)).trim()}\n\`\`\`\n`,
-  );
-
-  // Convert inline code
-  md = md.replace(
-    /<code[^>]*>([\s\S]*?)<\/code>/gi,
-    (_, c) => `\`${decodeEntities(c).trim()}\``,
-  );
-
-  // Convert strong/em
-  md = md.replace(
-    /<(strong|b)[^>]*>([\s\S]*?)<\/\1>/gi,
-    (_, __, c) => `**${stripTags(c).trim()}**`,
-  );
-  md = md.replace(
-    /<(em|i)[^>]*>([\s\S]*?)<\/\1>/gi,
-    (_, __, c) => `*${stripTags(c).trim()}*`,
-  );
-
-  // Convert list items
-  md = md.replace(
-    /<li[^>]*>([\s\S]*?)<\/li>/gi,
-    (_, c) => `- ${stripTags(c).trim()}\n`,
-  );
-
-  // Convert paragraphs and line breaks
-  md = md.replace(/<br\s*\/?>/gi, "\n");
-  md = md.replace(
-    /<p[^>]*>([\s\S]*?)<\/p>/gi,
-    (_, c) => `\n${stripTags(c).trim()}\n`,
-  );
-  md = md.replace(/<blockquote[^>]*>([\s\S]*?)<\/blockquote>/gi, (_, c) => {
-    return (
-      "\n" +
-      stripTags(c)
-        .trim()
-        .split("\n")
-        .map((l) => `> ${l}`)
-        .join("\n") +
-      "\n"
-    );
-  });
-
-  // Remove remaining HTML tags
-  md = stripTags(md);
-
-  // Decode HTML entities
-  md = decodeEntities(md);
-
-  // Clean up whitespace
-  md = md.replace(/\n{3,}/g, "\n\n").trim();
-
-  return md;
-}
-
-function stripTags(html) {
-  return html.replace(/<[^>]+>/g, "");
-}
-
-function decodeEntities(text) {
-  return text
-    .replace(/&amp;/g, "&")
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&nbsp;/g, " ")
-    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n, 10)))
-    .replace(/&#x([0-9a-f]+);/gi, (_, n) =>
-      String.fromCharCode(parseInt(n, 16)),
-    );
-}
-
-/**
- * Extract the main readable content from an HTML page.
- * Prefers <article> or <main>, falls back to <body>.
- *
- * @param {string} html
- * @param {string} url
- * @returns {{ title: string, body: string }}
- */
-export function extractHtmlContent(html, url) {
-  // Extract <title>
-  const titleMatch = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
-  const title = titleMatch
-    ? stripTags(decodeEntities(titleMatch[1])).trim()
-    : "";
-
-  // Try to extract main content area
-  let contentHtml = "";
-
-  const articleMatch = html.match(/<article[^>]*>([\s\S]*?)<\/article>/i);
-  const mainMatch = html.match(/<main[^>]*>([\s\S]*?)<\/main>/i);
-
-  if (articleMatch) {
-    contentHtml = articleMatch[1];
-  } else if (mainMatch) {
-    contentHtml = mainMatch[1];
-  } else {
-    // Fall back to <body>
-    const bodyMatch = html.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
-    contentHtml = bodyMatch ? bodyMatch[1] : html;
-  }
-
-  const body = htmlToMarkdown(contentHtml);
-
-  return { title, body };
-}
-
-/**
- * Fetch a URL, extract readable content, and return an EntryData object.
- *
- * @param {string} url
- * @param {{ kind?: string, tags?: string[], source?: string, maxBodyLength?: number, timeoutMs?: number }} [opts]
- * @returns {Promise<{ kind: string, title: string, body: string, tags: string[], meta: object, source: string }>}
- */
-export async function ingestUrl(url, opts = {}) {
-  const {
-    kind = "reference",
-    tags = [],
-    source,
-    maxBodyLength = 50000,
-    timeoutMs = 15000,
-  } = opts;
-
-  let domain;
-  try {
-    domain = new URL(url).hostname;
-  } catch {
-    throw new Error(`Invalid URL: ${url}`);
-  }
-
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-
-  let response;
-  try {
-    response = await fetch(url, {
-      signal: controller.signal,
-      headers: {
-        "User-Agent":
-          "ContextVault/1.0 (+https://github.com/fellanH/context-vault)",
-        Accept: "text/html,application/xhtml+xml,text/plain,*/*",
-      },
-    });
-  } catch (err) {
-    if (err.name === "AbortError") {
-      throw new Error(`Request timed out after ${timeoutMs}ms`);
-    }
-    throw new Error(`Fetch failed: ${err.message}`);
-  } finally {
-    clearTimeout(timeout);
-  }
-
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-  }
-
-  const contentType = response.headers.get("content-type") || "";
-  const html = await response.text();
-
-  let title, body;
-
-  if (
-    contentType.includes("text/html") ||
-    contentType.includes("application/xhtml")
-  ) {
-    const extracted = extractHtmlContent(html, url);
-    title = extracted.title;
-    body = extracted.body;
-  } else {
-    // Plain text or other — use as-is
-    title = domain;
-    body = html;
-  }
-
-  // Truncate if too long
-  if (body.length > maxBodyLength) {
-    body = body.slice(0, maxBodyLength) + "\n\n[Content truncated]";
-  }
-
-  if (!body.trim()) {
-    throw new Error("No readable content extracted from URL");
-  }
-
-  return {
-    kind,
-    title: title || domain,
-    body,
-    tags: [...tags, "web-import"],
-    meta: {
-      url,
-      domain,
-      fetched_at: new Date().toISOString(),
-      content_type: contentType.split(";")[0].trim() || "text/html",
-    },
-    source: source || domain,
-  };
-}

package/node_modules/@context-vault/core/src/consolidation/index.js

@@ -1,112 +0,0 @@
-/**
- * Consolidation utilities — identifies tags and entries that warrant maintenance.
- *
- * These are pure DB queries with no LLM calls. The caller decides what to do
- * with the results (e.g. run create_snapshot, archive entries, report to user).
- */
-
-/**
- * Identifies tags that have accumulated enough entries to warrant consolidation.
- *
- * A tag is "hot" when it has >= tagThreshold non-superseded entries AND no
- * brief/snapshot was saved for it within the last maxSnapshotAgeDays days.
- *
- * @param {import('node:sqlite').DatabaseSync} db
- * @param {{ tagThreshold?: number, maxSnapshotAgeDays?: number }} [opts]
- * @returns {{ tag: string, entryCount: number, lastSnapshotAge: number | null }[]}
- */
-export function findHotTags(
-  db,
-  { tagThreshold = 10, maxSnapshotAgeDays = 7 } = {},
-) {
-  const rows = db
-    .prepare(
-      `SELECT id, tags, kind FROM vault
-       WHERE superseded_by IS NULL
-         AND tags IS NOT NULL
-         AND tags != '[]'`,
-    )
-    .all();
-
-  const tagCounts = new Map();
-
-  for (const row of rows) {
-    let tags;
-    try {
-      tags = JSON.parse(row.tags);
-    } catch {
-      continue;
-    }
-    if (!Array.isArray(tags)) continue;
-
-    for (const tag of tags) {
-      if (typeof tag !== "string" || !tag) continue;
-      tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
-    }
-  }
-
-  const hotTags = [];
-
-  for (const [tag, count] of tagCounts) {
-    if (count < tagThreshold) continue;
-
-    const snapshotRow = db
-      .prepare(
-        `SELECT created_at FROM vault
-         WHERE kind = 'brief'
-           AND tags LIKE ?
-           AND created_at > datetime('now', '-' || ? || ' days')
-         ORDER BY created_at DESC
-         LIMIT 1`,
-      )
-      .get(`%"${tag}"%`, String(maxSnapshotAgeDays));
-
-    if (snapshotRow) continue;
-
-    const lastSnapshotAny = db
-      .prepare(
-        `SELECT created_at FROM vault
-         WHERE kind = 'brief'
-           AND tags LIKE ?
-         ORDER BY created_at DESC
-         LIMIT 1`,
-      )
-      .get(`%"${tag}"%`);
-
-    let lastSnapshotAge = null;
-    if (lastSnapshotAny) {
-      const ms = Date.now() - new Date(lastSnapshotAny.created_at).getTime();
-      lastSnapshotAge = Math.floor(ms / (1000 * 60 * 60 * 24));
-    }
-
-    hotTags.push({ tag, entryCount: count, lastSnapshotAge });
-  }
-
-  hotTags.sort((a, b) => b.entryCount - a.entryCount);
-
-  return hotTags;
-}
-
-/**
- * Identifies cold entries (old, never or rarely accessed) that can be archived.
- *
- * Returns IDs of entries that are old enough, have low hit counts, are not
- * superseded, and are not in permanent kinds (decision, architecture, brief).
- *
- * @param {import('node:sqlite').DatabaseSync} db
- * @param {{ maxAgeDays?: number, maxHitCount?: number }} [opts]
- * @returns {string[]} Entry IDs eligible for archiving
- */
-export function findColdEntries(db, { maxAgeDays = 90, maxHitCount = 0 } = {}) {
-  const rows = db
-    .prepare(
-      `SELECT id FROM vault
-       WHERE hit_count <= ?
-         AND created_at < datetime('now', '-' || ? || ' days')
-         AND superseded_by IS NULL
-         AND kind NOT IN ('decision', 'architecture', 'brief')`,
-    )
-    .all(maxHitCount, String(maxAgeDays));
-
-  return rows.map((r) => r.id);
-}

package/node_modules/@context-vault/core/src/core/categories.js

@@ -1,73 +0,0 @@
-/**
- * categories.js — Static kind→category mapping
- *
- * Three categories with distinct write semantics:
- *   knowledge — append-only, enduring (default)
- *   entity    — upsert by identity_key, enduring
- *   event     — append-only, decaying relevance
- */
-
-const KIND_CATEGORY = {
-  // Knowledge — append-only, enduring
-  insight: "knowledge",
-  decision: "knowledge",
-  pattern: "knowledge",
-  prompt: "knowledge",
-  note: "knowledge",
-  document: "knowledge",
-  reference: "knowledge",
-  // Entity — upsert, enduring
-  contact: "entity",
-  project: "entity",
-  tool: "entity",
-  source: "entity",
-  bucket: "entity",
-  // Event — append-only, decaying
-  event: "event",
-  conversation: "event",
-  message: "event",
-  session: "event",
-  task: "event",
-  log: "event",
-  feedback: "event",
-};
-
-/** Map category name → directory name on disk */
-const CATEGORY_DIR_NAMES = {
-  knowledge: "knowledge",
-  entity: "entities",
-  event: "events",
-};
-
-/** Set of valid category directory names (for reindex discovery) */
-export const CATEGORY_DIRS = new Set(Object.values(CATEGORY_DIR_NAMES));
-
-/**
- * Staleness thresholds (in days) per knowledge kind.
- * Kinds not listed here are considered enduring (no staleness threshold).
- * Based on updated_at; falls back to created_at if updated_at is null.
- */
-export const KIND_STALENESS_DAYS = {
-  pattern: 180,
-  decision: 365,
-  reference: 90,
-};
-
-const DURABLE_KINDS = new Set(["decision", "architecture", "pattern"]);
-const EPHEMERAL_KINDS = new Set(["session", "observation"]);
-
-export function categoryFor(kind) {
-  return KIND_CATEGORY[kind] || "knowledge";
-}
-
-export function defaultTierFor(kind) {
-  if (DURABLE_KINDS.has(kind)) return "durable";
-  if (EPHEMERAL_KINDS.has(kind)) return "ephemeral";
-  return "working";
-}
-
-/** Returns the category directory name for a given kind (e.g. "insight" → "knowledge") */
-export function categoryDirFor(kind) {
-  const cat = categoryFor(kind);
-  return CATEGORY_DIR_NAMES[cat] || "knowledge";
-}