@context-vault/core 2.17.0 → 2.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-vault/core",
-  "version": "2.17.0",
+  "version": "2.17.1",
   "type": "module",
   "description": "Shared core: capture, index, retrieve, tools, and utilities for context-vault",
   "main": "src/index.js",
@@ -23,7 +23,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=24"
+    "node": ">=20"
   },
   "author": "Felix Hellstrom",
   "repository": {
@@ -36,7 +36,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.78.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "sqlite-vec": "^0.1.0"
   },

package/src/capture/file-ops.js

@@ -38,6 +38,7 @@ export function writeEntryFile(
     identity_key,
     expires_at,
     supersedes,
+    related_to,
   },
 ) {
   // P5: folder is now a top-level param; also accept from meta for backward compat
@@ -64,6 +65,7 @@ export function writeEntryFile(
   if (identity_key) fmFields.identity_key = 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 = created;

package/src/capture/index.js

@@ -27,6 +27,7 @@ export function writeEntry(
     identity_key,
     expires_at,
     supersedes,
+    related_to,
     source_files,
     tier,
     userId,
@@ -88,6 +89,7 @@ export function writeEntry(
     identity_key,
     expires_at,
     supersedes,
+    related_to,
   });
 
   return {
@@ -105,6 +107,7 @@ export function writeEntry(
     identity_key,
     expires_at,
     supersedes,
+    related_to: related_to || null,
     source_files: source_files || null,
     tier: tier || null,
     userId: userId || null,
@@ -126,6 +129,9 @@ export function updateEntryFile(ctx, existing, updates) {
 
   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;
@@ -138,6 +144,8 @@ export function updateEntryFile(ctx, existing, updates) {
     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
@@ -162,6 +170,7 @@ export function updateEntryFile(ctx, existing, updates) {
   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;
@@ -189,6 +198,7 @@ export function updateEntryFile(ctx, existing, updates) {
     identity_key: existing.identity_key,
     expires_at,
     supersedes,
+    related_to: related_to || null,
     source_files: source_files || null,
     userId: existing.user_id || null,
   };
@@ -217,6 +227,10 @@ export async function captureAndIndex(ctx, data) {
         }
       }
     }
+    // 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

package/src/core/categories.js

@@ -23,6 +23,7 @@ const KIND_CATEGORY = {
   source: "entity",
   bucket: "entity",
   // Event — append-only, decaying
+  event: "event",
   conversation: "event",
   message: "event",
   session: "event",

package/src/core/files.js

@@ -37,42 +37,19 @@ export function slugify(text, maxLen = 60) {
   return slug;
 }
 
-const PLURAL_MAP = {
-  insight: "insights",
-  decision: "decisions",
-  pattern: "patterns",
-  status: "statuses",
-  analysis: "analyses",
-  contact: "contacts",
-  project: "projects",
-  tool: "tools",
-  source: "sources",
-  conversation: "conversations",
-  message: "messages",
-  session: "sessions",
-  log: "logs",
-  feedback: "feedbacks",
-};
-
-const SINGULAR_MAP = Object.fromEntries(
-  Object.entries(PLURAL_MAP).map(([k, v]) => [v, k]),
-);
-
+/** Map kind name to its directory name. Kind names are used as-is (no pluralization). */
 export function kindToDir(kind) {
-  if (PLURAL_MAP[kind]) return PLURAL_MAP[kind];
-  return kind.endsWith("s") ? kind : kind + "s";
+  return kind;
 }
 
+/** Map directory name back to kind name. Directory names equal kind names (identity). */
 export function dirToKind(dirName) {
-  if (SINGULAR_MAP[dirName]) return SINGULAR_MAP[dirName];
-  return dirName.replace(/s$/, "");
+  return dirName;
 }
 
-/** Normalize a kind input (singular or plural) to its canonical singular form. */
+/** Normalize a kind input to its canonical form. Kind names are returned as-is. */
 export function normalizeKind(input) {
-  if (PLURAL_MAP[input]) return input; // Already a known singular kind
-  if (SINGULAR_MAP[input]) return SINGULAR_MAP[input]; // Known plural → singular
-  return input; // Unknown — use as-is (don't strip 's')
+  return input;
 }
 
 /** Returns relative path from vault root → kind dir: "knowledge/insights", "events/sessions", etc. */

package/src/core/frontmatter.js

@@ -69,6 +69,7 @@ const RESERVED_FM_KEYS = new Set([
   "identity_key",
   "expires_at",
   "supersedes",
+  "related_to",
 ]);
 
 export function extractCustomMeta(fmMeta) {

package/src/core/linking.js

@@ -0,0 +1,161 @@
+/**
+ * linking.js — Pure graph traversal for related_to links.
+ *
+ * All functions accept a db handle and return data — no side effects.
+ * The calling layer (get-context handler) is responsible for I/O wiring.
+ */
+
+/**
+ * Parse a `related_to` JSON string from the DB into an array of ID strings.
+ * Returns an empty array on any parse failure or null input.
+ *
+ * @param {string|null|undefined} raw
+ * @returns {string[]}
+ */
+export function parseRelatedTo(raw) {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((id) => typeof id === "string" && id.trim());
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Fetch vault entries by their IDs, scoped to a user.
+ * Returns only entries that exist and are not expired or superseded.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string[]} ids
+ * @param {string|null|undefined} userId
+ * @returns {object[]} Matching DB rows
+ */
+export function resolveLinks(db, ids, userId) {
+  if (!ids.length) return [];
+  const unique = [...new Set(ids)];
+  const placeholders = unique.map(() => "?").join(",");
+  // When userId is defined (hosted mode), scope to that user.
+  // When userId is undefined (local mode), no user scoping — all entries accessible.
+  const userClause =
+    userId !== undefined && userId !== null ? "AND user_id = ?" : "";
+  const params =
+    userId !== undefined && userId !== null ? [...unique, userId] : unique;
+  try {
+    return db
+      .prepare(
+        `SELECT * FROM vault
+         WHERE id IN (${placeholders})
+           ${userClause}
+           AND (expires_at IS NULL OR expires_at > datetime('now'))
+           AND superseded_by IS NULL`,
+      )
+      .all(...params);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Find all entries that declare `entryId` in their `related_to` field
+ * (i.e. entries that point *to* this entry — backlinks).
+ * Scoped to the same user. Excludes expired and superseded entries.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string} entryId
+ * @param {string|null|undefined} userId
+ * @returns {object[]} Entries with a backlink to entryId
+ */
+export function resolveBacklinks(db, entryId, userId) {
+  if (!entryId) return [];
+  // When userId is defined (hosted mode), scope to that user.
+  // When userId is undefined (local mode), no user scoping — all entries accessible.
+  const userClause =
+    userId !== undefined && userId !== null ? "AND user_id = ?" : "";
+  const likePattern = `%"${entryId}"%`;
+  const params =
+    userId !== undefined && userId !== null
+      ? [likePattern, userId]
+      : [likePattern];
+  try {
+    return db
+      .prepare(
+        `SELECT * FROM vault
+         WHERE related_to LIKE ?
+           ${userClause}
+           AND (expires_at IS NULL OR expires_at > datetime('now'))
+           AND superseded_by IS NULL`,
+      )
+      .all(...params);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * For a set of primary entry IDs, collect all forward links (entries pointed
+ * to by `related_to`) and backlinks (entries that point back to any primary).
+ *
+ * Returns a Map of id → entry row for all linked entries, excluding entries
+ * already present in `primaryIds`.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {object[]} primaryEntries - Full entry rows (must have id + related_to fields)
+ * @param {string|null|undefined} userId
+ * @returns {{ forward: object[], backward: object[] }}
+ */
+export function collectLinkedEntries(db, primaryEntries, userId) {
+  const primaryIds = new Set(primaryEntries.map((e) => e.id));
+
+  // Forward: resolve all IDs from related_to fields
+  const forwardIds = [];
+  for (const entry of primaryEntries) {
+    const ids = parseRelatedTo(entry.related_to);
+    for (const id of ids) {
+      if (!primaryIds.has(id)) forwardIds.push(id);
+    }
+  }
+  const forwardEntries = resolveLinks(db, forwardIds, userId).filter(
+    (e) => !primaryIds.has(e.id),
+  );
+
+  // Backward: find all entries that link to any primary entry
+  const backwardSeen = new Set();
+  const backwardEntries = [];
+  const forwardIds2 = new Set(forwardEntries.map((e) => e.id));
+  for (const entry of primaryEntries) {
+    const backlinks = resolveBacklinks(db, entry.id, userId);
+    for (const bl of backlinks) {
+      if (!primaryIds.has(bl.id) && !backwardSeen.has(bl.id)) {
+        backwardSeen.add(bl.id);
+        backwardEntries.push(bl);
+      }
+    }
+  }
+
+  return { forward: forwardEntries, backward: backwardEntries };
+}
+
+/**
+ * Validate a `related_to` value from user input.
+ * Must be an array of non-empty strings (ULID-like IDs).
+ * Returns an error message string if invalid, or null if valid.
+ *
+ * @param {unknown} relatedTo
+ * @returns {string|null}
+ */
+export function validateRelatedTo(relatedTo) {
+  if (relatedTo === undefined || relatedTo === null) return null;
+  if (!Array.isArray(relatedTo))
+    return "related_to must be an array of entry IDs";
+  for (const id of relatedTo) {
+    if (typeof id !== "string" || !id.trim()) {
+      return "each related_to entry must be a non-empty string ID";
+    }
+    if (id.length > 32) {
+      return `related_to ID too long (max 32 chars): "${id.slice(0, 32)}..."`;
+    }
+  }
+  return null;
+}

package/src/core/migrate-dirs.js

@@ -0,0 +1,196 @@
+/**
+ * migrate-dirs.js — Rename plural vault directories to singular
+ *
+ * After context-vault >= 2.18.0, kindToDir() returns singular names.
+ * Existing vaults still have plural dirs (e.g. knowledge/decisions/).
+ * This module plans and executes the rename/merge migration.
+ *
+ * Architecture: pure planning function + I/O execution function.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  mkdirSync,
+  renameSync,
+  copyFileSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { join, basename } from "node:path";
+
+/**
+ * Complete plural→singular mapping for vault directory names.
+ * Covers the old PLURAL_MAP from files.js plus extended kinds seen in the wild.
+ *
+ * @type {Record<string, string>}
+ */
+export const PLURAL_TO_SINGULAR = {
+  // From old PLURAL_MAP in files.js
+  insights: "insight",
+  decisions: "decision",
+  patterns: "pattern",
+  statuses: "status",
+  analyses: "analysis",
+  contacts: "contact",
+  projects: "project",
+  tools: "tool",
+  sources: "source",
+  conversations: "conversation",
+  messages: "message",
+  sessions: "session",
+  logs: "log",
+  feedbacks: "feedback",
+  // Extended kinds from categories.js + observed in vaults
+  notes: "note",
+  prompts: "prompt",
+  documents: "document",
+  references: "reference",
+  tasks: "task",
+  buckets: "bucket",
+  architectures: "architecture",
+  briefs: "brief",
+  companies: "company",
+  discoveries: "discovery",
+  events: "event",
+  ideas: "idea",
+  issues: "issue",
+  agents: "agent",
+  "session-summaries": "session-summary",
+  "session-reviews": "session-review",
+  "user-prompts": "user-prompt",
+};
+
+/**
+ * Category directory names that are scanned for plural kind subdirectories.
+ */
+const CATEGORY_DIRS = ["knowledge", "entities", "events"];
+
+/**
+ * Count .md files recursively in a directory.
+ *
+ * @param {string} dir
+ * @returns {number}
+ */
+function countMdFiles(dir) {
+  let count = 0;
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        count += countMdFiles(join(dir, entry.name));
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        count++;
+      }
+    }
+  } catch {
+    // ignore unreadable dirs
+  }
+  return count;
+}
+
+/**
+ * Plan migration operations: walk the vault and detect plural dirs that need renaming.
+ * Pure I/O read-only — does not modify any files.
+ *
+ * @param {string} vaultDir - Absolute path to vault root
+ * @returns {MigrationOp[]} Array of planned operations
+ *
+ * @typedef {{ action: 'rename'|'merge', pluralDir: string, singularDir: string, pluralName: string, singularName: string, fileCount: number }} MigrationOp
+ */
+export function planMigration(vaultDir) {
+  const ops = [];
+
+  for (const catName of CATEGORY_DIRS) {
+    const catDir = join(vaultDir, catName);
+    if (!existsSync(catDir) || !statSync(catDir).isDirectory()) continue;
+
+    let entries;
+    try {
+      entries = readdirSync(catDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const dirName = entry.name;
+      const singular = PLURAL_TO_SINGULAR[dirName];
+
+      // Not a known plural — skip (might already be singular or unknown kind)
+      if (!singular) continue;
+
+      const pluralDir = join(catDir, dirName);
+      const singularDir = join(catDir, singular);
+
+      // Guard: plural and singular are the same (shouldn't happen but be safe)
+      if (pluralDir === singularDir) continue;
+
+      const fileCount = countMdFiles(pluralDir);
+      const singularExists = existsSync(singularDir);
+
+      ops.push({
+        action: singularExists ? "merge" : "rename",
+        pluralDir,
+        singularDir,
+        pluralName: dirName,
+        singularName: singular,
+        fileCount,
+      });
+    }
+  }
+
+  return ops;
+}
+
+/**
+ * Copy all files and subdirectories from src into dst (non-overwriting).
+ * Mirrors `cp -rn src/* dst/`.
+ *
+ * @param {string} src
+ * @param {string} dst
+ */
+function mergeDir(src, dst) {
+  mkdirSync(dst, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name);
+    const dstPath = join(dst, entry.name);
+    if (entry.isDirectory()) {
+      mergeDir(srcPath, dstPath);
+    } else if (entry.isFile()) {
+      if (!existsSync(dstPath)) {
+        copyFileSync(srcPath, dstPath);
+      }
+    }
+  }
+}
+
+/**
+ * Execute migration operations. Renames or merges plural dirs into singular dirs.
+ * Safe to call multiple times — already-renamed dirs produce no-op ops from planMigration.
+ *
+ * @param {MigrationOp[]} ops - Operations from planMigration()
+ * @returns {{ renamed: number, merged: number, errors: string[] }}
+ */
+export function executeMigration(ops) {
+  let renamed = 0;
+  let merged = 0;
+  const errors = [];
+
+  for (const op of ops) {
+    try {
+      if (op.action === "rename") {
+        renameSync(op.pluralDir, op.singularDir);
+        renamed++;
+      } else {
+        // merge: copy files from plural into singular, then remove plural
+        mergeDir(op.pluralDir, op.singularDir);
+        rmSync(op.pluralDir, { recursive: true, force: true });
+        merged++;
+      }
+    } catch (e) {
+      errors.push(`${op.pluralName} → ${op.singularName}: ${e.message}`);
+    }
+  }
+
+  return { renamed, merged, errors };
+}

package/src/core/temporal.js

@@ -0,0 +1,146 @@
+/**
+ * Temporal shortcut resolver.
+ *
+ * Converts natural-language time expressions to ISO date strings.
+ * Fully pure — accepts an explicit `now` Date for deterministic testing.
+ *
+ * Supported shortcuts (case-insensitive, spaces or underscores):
+ *   today          → start of today (00:00:00 local midnight in UTC)
+ *   yesterday      → { since: start of yesterday, until: end of yesterday }
+ *   this_week      → start of current ISO week (Monday 00:00)
+ *   last_N_days    → N days ago (e.g. last_3_days, last 7 days)
+ *   last_N_weeks   → N weeks ago
+ *   last_N_months  → N calendar months ago (approximate: N × 30 days)
+ *
+ * Anything that doesn't match a shortcut is returned unchanged so that ISO
+ * date strings pass straight through without modification.
+ */
+
+const SHORTCUT_RE = /^last[_ ](\d+)[_ ](day|days|week|weeks|month|months)$/i;
+
+/**
+ * Start of today in UTC (i.e. the midnight boundary at which the local date begins,
+ * expressed as an ISO string). We operate in UTC throughout so tests are portable.
+ *
+ * @param {Date} now
+ * @returns {Date}
+ */
+function startOfToday(now) {
+  const d = new Date(now);
+  d.setUTCHours(0, 0, 0, 0);
+  return d;
+}
+
+/**
+ * Resolve a single temporal expression to one or two ISO date strings.
+ *
+ * @param {"since"|"until"} role  - Which parameter we are resolving.
+ * @param {string} value          - Raw parameter value from the caller.
+ * @param {Date} [now]            - Override for "now" (defaults to `new Date()`).
+ * @returns {string}              - Resolved ISO date string (or original value if unrecognised).
+ */
+export function resolveTemporalShortcut(role, value, now = new Date()) {
+  if (!value || typeof value !== "string") return value;
+
+  const trimmed = value.trim().toLowerCase().replace(/\s+/g, "_");
+
+  if (trimmed === "today") {
+    const start = startOfToday(now);
+    if (role === "until") {
+      // "until today" means up to end-of-today
+      const end = new Date(start);
+      end.setUTCDate(end.getUTCDate() + 1);
+      return end.toISOString();
+    }
+    return start.toISOString();
+  }
+
+  if (trimmed === "yesterday") {
+    const todayStart = startOfToday(now);
+    const yesterdayStart = new Date(todayStart);
+    yesterdayStart.setUTCDate(yesterdayStart.getUTCDate() - 1);
+    if (role === "since") return yesterdayStart.toISOString();
+    // role === "until": end of yesterday = start of today
+    return todayStart.toISOString();
+  }
+
+  if (trimmed === "this_week") {
+    // Monday 00:00 UTC of the current week
+    const todayStart = startOfToday(now);
+    const dayOfWeek = todayStart.getUTCDay(); // 0=Sun, 1=Mon, ..., 6=Sat
+    const daysFromMonday = (dayOfWeek + 6) % 7; // 0 on Monday
+    const monday = new Date(todayStart);
+    monday.setUTCDate(monday.getUTCDate() - daysFromMonday);
+    if (role === "since") return monday.toISOString();
+    // "until this_week" means up to now (end of today)
+    const endOfToday = new Date(todayStart);
+    endOfToday.setUTCDate(endOfToday.getUTCDate() + 1);
+    return endOfToday.toISOString();
+  }
+
+  if (trimmed === "this_month") {
+    const d = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+    if (role === "since") return d.toISOString();
+    const endOfMonth = new Date(
+      Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1),
+    );
+    return endOfMonth.toISOString();
+  }
+
+  const m = SHORTCUT_RE.exec(trimmed);
+  if (m) {
+    const n = parseInt(m[1], 10);
+    const unit = m[2].replace(/s$/, ""); // normalise plural → singular
+    let ms;
+    if (unit === "day") {
+      ms = n * 86400000;
+    } else if (unit === "week") {
+      ms = n * 7 * 86400000;
+    } else {
+      // month → approximate as 30 days
+      ms = n * 30 * 86400000;
+    }
+    const target = new Date(now.getTime() - ms);
+    target.setUTCHours(0, 0, 0, 0);
+    return target.toISOString();
+  }
+
+  // Unrecognised — pass through unchanged (ISO dates, empty strings, etc.)
+  return value;
+}
+
+/**
+ * Resolve both `since` and `until` parameters, handling the special case where
+ * "yesterday" sets both bounds automatically when only `since` is specified.
+ *
+ * Returns `{ since, until }` with resolved ISO strings (or originals).
+ *
+ * @param {{ since?: string, until?: string }} params
+ * @param {Date} [now]
+ * @returns {{ since: string|undefined, until: string|undefined }}
+ */
+export function resolveTemporalParams(params, now = new Date()) {
+  let { since, until } = params;
+
+  // Special case: "yesterday" on `since` without an explicit `until`
+  // auto-fills `until` to the end of yesterday.
+  if (
+    since?.trim().toLowerCase() === "yesterday" &&
+    (until === undefined || until === null)
+  ) {
+    since = resolveTemporalShortcut("since", since, now);
+    until = resolveTemporalShortcut("until", "yesterday", now);
+    return { since, until };
+  }
+
+  return {
+    since:
+      since !== undefined
+        ? resolveTemporalShortcut("since", since, now)
+        : since,
+    until:
+      until !== undefined
+        ? resolveTemporalShortcut("until", until, now)
+        : until,
+  };
+}