context-vault 3.1.6 → 3.1.8

package/scripts/postinstall.js

@@ -9,15 +9,15 @@
  * 2. Ensures data directory exists.
  */
 
-import { execSync } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const PKG_ROOT = join(__dirname, "..");
-const NODE_MODULES = join(PKG_ROOT, "node_modules");
+const PKG_ROOT = join(__dirname, '..');
+const NODE_MODULES = join(PKG_ROOT, 'node_modules');
 
 async function main() {
   // ── 1. Install @huggingface/transformers (optional) ───────────────────
@@ -26,33 +26,26 @@ async function main() {
   // context-vault only uses text embeddings, not image processing.
   // Check the package's own node_modules (not general import resolution,
   // which may find it in the workspace during `npm install -g ./tarball`).
-  const transformersDir = join(NODE_MODULES, "@huggingface", "transformers");
+  const transformersDir = join(NODE_MODULES, '@huggingface', 'transformers');
   if (!existsSync(transformersDir)) {
-    console.log(
-      "[context-vault] Installing embedding support (@huggingface/transformers)...",
-    );
+    console.log('[context-vault] Installing embedding support (@huggingface/transformers)...');
     try {
-      execSync(
-        "npm install --no-save --ignore-scripts @huggingface/transformers@^3.0.0",
-        {
-          stdio: "inherit",
-          timeout: 120000,
-          cwd: PKG_ROOT,
-        },
-      );
-      console.log("[context-vault] Embedding support installed.");
+      execSync('npm install --no-save --ignore-scripts @huggingface/transformers@^3.0.0', {
+        stdio: 'inherit',
+        timeout: 120000,
+        cwd: PKG_ROOT,
+      });
+      console.log('[context-vault] Embedding support installed.');
     } catch {
+      console.error('[context-vault] Warning: could not install @huggingface/transformers.');
       console.error(
-        "[context-vault] Warning: could not install @huggingface/transformers.",
-      );
-      console.error(
-        "[context-vault] Semantic search will be unavailable; full-text search still works.",
+        '[context-vault] Semantic search will be unavailable; full-text search still works.'
       );
     }
   }
 
   // ── 2. Ensure data dir exists ────────────────────────────────────────
-  const DATA_DIR = join(homedir(), ".context-mcp");
+  const DATA_DIR = join(homedir(), '.context-mcp');
   mkdirSync(DATA_DIR, { recursive: true });
 }
 

package/scripts/prepack.js

@@ -1,33 +1,27 @@
 #!/usr/bin/env node
 
-import {
-  cpSync,
-  rmSync,
-  mkdirSync,
-  readFileSync,
-  writeFileSync,
-} from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { cpSync, rmSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const LOCAL_ROOT = join(__dirname, "..");
-const NODE_MODULES = join(LOCAL_ROOT, "node_modules");
-const CORE_SRC = join(LOCAL_ROOT, "..", "core");
-const CORE_DEST = join(NODE_MODULES, "@context-vault", "core");
+const LOCAL_ROOT = join(__dirname, '..');
+const NODE_MODULES = join(LOCAL_ROOT, 'node_modules');
+const CORE_SRC = join(LOCAL_ROOT, '..', 'core');
+const CORE_DEST = join(NODE_MODULES, '@context-vault', 'core');
 
 // Clean node_modules to prevent workspace deps from leaking into the tarball.
 // Only @context-vault/core should be bundled.
 rmSync(NODE_MODULES, { recursive: true, force: true });
 
 // Ensure target directory exists
-mkdirSync(join(NODE_MODULES, "@context-vault"), { recursive: true });
+mkdirSync(join(NODE_MODULES, '@context-vault'), { recursive: true });
 
 // Copy core package (dereference symlinks)
 cpSync(CORE_SRC, CORE_DEST, { recursive: true, dereference: true });
 
 // Remove nested node_modules from the copy
-rmSync(join(CORE_DEST, "node_modules"), { recursive: true, force: true });
+rmSync(join(CORE_DEST, 'node_modules'), { recursive: true, force: true });
 
 // Strip all dependencies from the bundled core's package.json.
 // Core's deps (sqlite-vec, MCP SDK) are hoisted to
@@ -35,9 +29,9 @@ rmSync(join(CORE_DEST, "node_modules"), { recursive: true, force: true });
 // dynamically imported and installed via postinstall.  Leaving them
 // in the bundled core causes duplicate resolution that breaks native
 // module install scripts in global npm contexts.
-const corePkgPath = join(CORE_DEST, "package.json");
-const corePkg = JSON.parse(readFileSync(corePkgPath, "utf8"));
+const corePkgPath = join(CORE_DEST, 'package.json');
+const corePkg = JSON.parse(readFileSync(corePkgPath, 'utf8'));
 delete corePkg.dependencies;
-writeFileSync(corePkgPath, JSON.stringify(corePkg, null, 2) + "\n");
+writeFileSync(corePkgPath, JSON.stringify(corePkg, null, 2) + '\n');
 
-console.log("[prepack] Bundled @context-vault/core into node_modules");
+console.log('[prepack] Bundled @context-vault/core into node_modules');

package/src/archive.ts

@@ -0,0 +1,244 @@
+import { existsSync, mkdirSync, renameSync, readFileSync } from 'node:fs';
+import { join, dirname, relative } from 'node:path';
+import { categoryDirFor, categoryFor, defaultTierFor } from '@context-vault/core/categories';
+import { parseFrontmatter, parseEntryFromMarkdown } from '@context-vault/core/frontmatter';
+import { DEFAULT_LIFECYCLE } from '@context-vault/core/constants';
+import { walkDir } from '@context-vault/core/files';
+import { indexEntry } from '@context-vault/core/index';
+import type { LocalCtx } from './types.js';
+import type { VaultConfig } from '@context-vault/core/types';
+
+const VALID_TIERS = new Set(['ephemeral', 'working', 'durable']);
+const VALID_CATEGORIES = new Set(['knowledge', 'entity', 'event']);
+
+function resolveLifecycle(config: VaultConfig): Record<string, { archiveAfterDays?: number }> {
+  return config?.lifecycle ?? structuredClone(DEFAULT_LIFECYCLE);
+}
+
+function archiveDir(vaultDir: string): string {
+  return join(vaultDir, '_archive');
+}
+
+export function findArchiveCandidates(ctx: LocalCtx): unknown[] {
+  const lifecycle = resolveLifecycle(ctx.config);
+  const now = new Date();
+  const candidates: unknown[] = [];
+  const seen = new Set<string>();
+
+  for (const [key, rules] of Object.entries(lifecycle)) {
+    if (!rules?.archiveAfterDays) continue;
+    const cutoff = new Date(now.getTime() - rules.archiveAfterDays * 86400000).toISOString();
+
+    const isTier = VALID_TIERS.has(key);
+    const isCategory = VALID_CATEGORIES.has(key);
+    if (!isTier && !isCategory) continue;
+
+    const column = isTier ? 'tier' : 'category';
+    const rows = ctx.db
+      .prepare(
+        `SELECT id, kind, category, title, tier, file_path, created_at, updated_at
+         FROM vault
+         WHERE ${column} = ? AND COALESCE(updated_at, created_at) <= ?
+         ORDER BY COALESCE(updated_at, created_at) ASC`
+      )
+      .all(key, cutoff) as Array<{ id: string; file_path: string | null; [key: string]: unknown }>;
+
+    for (const row of rows) {
+      if (seen.has(row.id)) continue;
+      seen.add(row.id);
+      candidates.push({
+        ...row,
+        reason: `${column}=${key}, archiveAfterDays=${rules.archiveAfterDays}`,
+      });
+    }
+  }
+
+  return candidates;
+}
+
+function removeFromIndex(ctx: LocalCtx, id: string): void {
+  const rowidRow = ctx.stmts.getRowid.get(id) as { rowid?: number } | undefined;
+  if (rowidRow?.rowid) {
+    try {
+      ctx.deleteVec(Number(rowidRow.rowid));
+    } catch {}
+  }
+  ctx.stmts.deleteEntry.run(id);
+}
+
+export async function archiveEntries(
+  ctx: LocalCtx
+): Promise<{ archived: unknown[]; count: number }> {
+  const candidates = findArchiveCandidates(ctx) as Array<{
+    id: string;
+    file_path: string | null;
+    [key: string]: unknown;
+  }>;
+  if (candidates.length === 0) return { archived: candidates, count: 0 };
+
+  const vaultDir = ctx.config.vaultDir;
+  const archRoot = archiveDir(vaultDir);
+  let count = 0;
+
+  for (const entry of candidates) {
+    const filePath = entry.file_path;
+    if (!filePath) {
+      removeFromIndex(ctx, entry.id);
+      count++;
+      continue;
+    }
+
+    const rel = relative(vaultDir, filePath);
+    if (rel.startsWith('..') || rel.startsWith('_archive')) continue;
+
+    const destPath = join(archRoot, rel);
+    const destDir = dirname(destPath);
+
+    try {
+      mkdirSync(destDir, { recursive: true });
+      renameSync(filePath, destPath);
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code === 'ENOENT' && !existsSync(filePath)) {
+        // File already gone — just remove from index
+      } else {
+        throw e;
+      }
+    }
+
+    removeFromIndex(ctx, entry.id);
+    count++;
+  }
+
+  return { archived: candidates, count };
+}
+
+export async function restoreEntry(
+  ctx: LocalCtx,
+  entryId: string
+): Promise<{ restored: boolean; reason?: string; filePath?: string; kind?: string; id?: string }> {
+  const vaultDir = ctx.config.vaultDir;
+  const archRoot = archiveDir(vaultDir);
+
+  if (!existsSync(archRoot)) {
+    return { restored: false, reason: 'no _archive directory' };
+  }
+
+  const mdFiles = walkDir(archRoot);
+  let targetFile: string | null = null;
+
+  for (const { filePath } of mdFiles) {
+    try {
+      const raw = readFileSync(filePath, 'utf-8');
+      const { meta } = parseFrontmatter(raw);
+      if (meta.id === entryId) {
+        targetFile = filePath;
+        break;
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  if (!targetFile) {
+    return { restored: false, reason: `entry ${entryId} not found in _archive` };
+  }
+
+  const rel = relative(archRoot, targetFile);
+  const destPath = join(vaultDir, rel);
+  const destDir = dirname(destPath);
+
+  if (existsSync(destPath)) {
+    return { restored: false, reason: `destination already exists: ${destPath}` };
+  }
+
+  mkdirSync(destDir, { recursive: true });
+  renameSync(targetFile, destPath);
+
+  const raw = readFileSync(destPath, 'utf-8');
+  const { meta, body: rawBody } = parseFrontmatter(raw);
+
+  const relFromVault = relative(vaultDir, destPath);
+  const kindDir = relFromVault.split('/').filter(Boolean);
+  let kind =
+    (meta.kind as string | undefined) ||
+    (kindDir.length >= 2 ? kindDir[kindDir.length - 2] : kindDir[0]) ||
+    'note';
+
+  const parsed = parseEntryFromMarkdown(kind, rawBody, meta);
+  const category = categoryFor(kind);
+
+  await indexEntry(ctx, {
+    id: (meta.id as string | undefined) || entryId,
+    kind,
+    category,
+    title: parsed.title,
+    body: parsed.body,
+    meta: parsed.meta ?? undefined,
+    tags: Array.isArray(meta.tags) ? (meta.tags as string[]) : null,
+    source: (meta.source as string | undefined) || 'archive-restore',
+    filePath: destPath,
+    createdAt: (meta.created as string | undefined) || new Date().toISOString(),
+    identity_key: (meta.identity_key as string | undefined) || null,
+    expires_at: (meta.expires_at as string | undefined) || null,
+    tier: (meta.tier as string | undefined) || defaultTierFor(kind),
+    source_files: null,
+  });
+
+  return {
+    restored: true,
+    filePath: destPath,
+    kind,
+    id: (meta.id as string | undefined) || entryId,
+  };
+}
+
+export function countArchivedEntries(vaultDir: string): number {
+  const archRoot = archiveDir(vaultDir);
+  if (!existsSync(archRoot)) return 0;
+  try {
+    return walkDir(archRoot).length;
+  } catch {
+    return 0;
+  }
+}
+
+export function listArchivedEntries(vaultDir: string): Array<{
+  id: string | null;
+  kind: string;
+  title: string;
+  tags: unknown[];
+  created: string | null;
+  filePath: string;
+}> {
+  const archRoot = archiveDir(vaultDir);
+  if (!existsSync(archRoot)) return [];
+
+  const entries: Array<{
+    id: string | null;
+    kind: string;
+    title: string;
+    tags: unknown[];
+    created: string | null;
+    filePath: string;
+  }> = [];
+  try {
+    const mdFiles = walkDir(archRoot);
+    for (const { filePath, relDir } of mdFiles) {
+      try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const { meta, body } = parseFrontmatter(raw);
+        entries.push({
+          id: (meta.id as string | null) || null,
+          kind: relDir?.split('/').pop() || 'unknown',
+          title: (meta.title as string | undefined) || body.slice(0, 80),
+          tags: Array.isArray(meta.tags) ? meta.tags : [],
+          created: (meta.created as string | null) || null,
+          filePath,
+        });
+      } catch {
+        continue;
+      }
+    }
+  } catch {}
+  return entries;
+}

package/src/consolidation.ts

@@ -0,0 +1,78 @@
+import type { DatabaseSync } from 'node:sqlite';
+
+export function findHotTags(
+  db: DatabaseSync,
+  opts: { tagThreshold?: number; maxSnapshotAgeDays?: number } = {}
+): Array<{ tag: string; entryCount: number; lastSnapshotAge: number | null }> {
+  const tagThreshold = opts.tagThreshold ?? 10;
+  const maxSnapshotAgeDays = opts.maxSnapshotAgeDays ?? 7;
+  const cutoff = new Date(Date.now() - maxSnapshotAgeDays * 86400000).toISOString();
+
+  const rows = db
+    .prepare(
+      `SELECT tags FROM vault
+       WHERE kind != 'brief'
+         AND superseded_by IS NULL
+         AND (expires_at IS NULL OR expires_at > datetime('now'))`
+    )
+    .all();
+
+  const tagCounts = new Map<string, number>();
+  for (const row of rows as Array<{ tags: string | null }>) {
+    if (!row.tags) continue;
+    try {
+      const tags = JSON.parse(row.tags);
+      for (const tag of tags) {
+        tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  const results = [];
+  for (const [tag, count] of tagCounts) {
+    if (count < tagThreshold) continue;
+
+    const recentBrief = db
+      .prepare(
+        `SELECT created_at FROM vault
+         WHERE kind = 'brief'
+           AND tags LIKE ?
+         ORDER BY created_at DESC LIMIT 1`
+      )
+      .get(`%"${tag}"%`);
+
+    let lastSnapshotAge: number | null = null;
+    if (recentBrief) {
+      const brief = recentBrief as { created_at: string };
+      lastSnapshotAge = Math.round((Date.now() - new Date(brief.created_at).getTime()) / 86400000);
+      if (brief.created_at >= cutoff) continue;
+    }
+
+    results.push({ tag, entryCount: count, lastSnapshotAge });
+  }
+
+  return results.sort((a, b) => b.entryCount - a.entryCount);
+}
+
+export function findColdEntries(
+  db: DatabaseSync,
+  opts: { maxAgeDays?: number; maxHitCount?: number } = {}
+): string[] {
+  const maxAgeDays = opts.maxAgeDays ?? 90;
+  const maxHitCount = opts.maxHitCount ?? 0;
+  const cutoff = new Date(Date.now() - maxAgeDays * 86400000).toISOString();
+
+  const rows = db
+    .prepare(
+      `SELECT id FROM vault
+       WHERE created_at < ?
+         AND superseded_by IS NULL
+         AND COALESCE(hit_count, 0) <= ?
+         AND (expires_at IS NULL OR expires_at > datetime('now'))`
+    )
+    .all(cutoff, maxHitCount);
+
+  return (rows as Array<{ id: string }>).map((r) => r.id);
+}

package/src/{error-log.js → error-log.ts}

@@ -5,34 +5,34 @@ import {
   readFileSync,
   statSync,
   writeFileSync,
-} from "node:fs";
-import { join } from "node:path";
+} from 'node:fs';
+import { join } from 'node:path';
 
 const MAX_LOG_SIZE = 1024 * 1024;
 
-export function errorLogPath(dataDir) {
-  return join(dataDir, "error.log");
+export function errorLogPath(dataDir: string): string {
+  return join(dataDir, 'error.log');
 }
 
-export function appendErrorLog(dataDir, entry) {
+export function appendErrorLog(dataDir: string, entry: Record<string, unknown>): void {
   try {
     mkdirSync(dataDir, { recursive: true });
     const logPath = errorLogPath(dataDir);
     if (existsSync(logPath) && statSync(logPath).size >= MAX_LOG_SIZE) {
-      writeFileSync(logPath, "");
+      writeFileSync(logPath, '');
     }
-    appendFileSync(logPath, JSON.stringify(entry) + "\n");
+    appendFileSync(logPath, JSON.stringify(entry) + '\n');
   } catch {
     // intentionally swallowed
   }
 }
 
-export function errorLogCount(dataDir) {
+export function errorLogCount(dataDir: string): number {
   try {
     const logPath = errorLogPath(dataDir);
     if (!existsSync(logPath)) return 0;
-    return readFileSync(logPath, "utf-8")
-      .split("\n")
+    return readFileSync(logPath, 'utf-8')
+      .split('\n')
       .filter((l) => l.trim()).length;
   } catch {
     return 0;

package/src/helpers.ts

@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { VaultConfig } from '@context-vault/core/types';
+import type { ToolResult } from './types.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+
+export function ok(text: string): ToolResult {
+  return { content: [{ type: 'text', text }] };
+}
+
+export function err(
+  text: string,
+  code = 'UNKNOWN',
+  meta: Record<string, unknown> = {}
+): ToolResult {
+  return {
+    content: [{ type: 'text', text }],
+    isError: true,
+    code,
+    _meta: {
+      cv_version: pkg.version,
+      node_version: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      ...meta,
+    },
+  };
+}
+
+export function errWithHint(text: string, code: string, hint?: string): ToolResult {
+  const prompt = hint
+    ? `\n\n**Debug with AI:** Paste this into Claude Code or your AI assistant:\n> "${hint}"`
+    : '';
+  return err(text + prompt, code);
+}
+
+export function ensureVaultExists(config: VaultConfig): ToolResult | null {
+  if (!config.vaultDirExists) {
+    return errWithHint(
+      `Vault directory not found: ${config.vaultDir}. Run context-status for diagnostics.`,
+      'VAULT_NOT_FOUND',
+      "My context-vault can't find the vault directory. Run `context-vault doctor` and help me fix it."
+    );
+  }
+  return null;
+}
+
+export function ensureValidKind(kind: string): ToolResult | null {
+  if (!/^[a-z][a-z0-9_-]*$/.test(kind)) {
+    return err(
+      "Required: kind (lowercase alphanumeric, e.g. 'insight', 'reference')",
+      'INVALID_KIND'
+    );
+  }
+  return null;
+}
+
+export { pkg };

package/src/{linking.js → linking.ts}

@@ -1,25 +1,27 @@
-export function parseRelatedTo(raw) {
+import type { DatabaseSync } from 'node:sqlite';
+
+export function parseRelatedTo(raw: unknown): string[] {
   if (!raw) return [];
   try {
-    const parsed = JSON.parse(raw);
+    const parsed = JSON.parse(raw as string);
     if (!Array.isArray(parsed)) return [];
-    return parsed.filter((id) => typeof id === "string" && id.trim());
+    return parsed.filter((id) => typeof id === 'string' && id.trim());
   } catch {
     return [];
   }
 }
 
-export function resolveLinks(db, ids) {
+export function resolveLinks(db: DatabaseSync, ids: string[]): any[] {
   if (!ids.length) return [];
   const unique = [...new Set(ids)];
-  const placeholders = unique.map(() => "?").join(",");
+  const placeholders = unique.map(() => '?').join(',');
   try {
     return db
       .prepare(
         `SELECT * FROM vault
          WHERE id IN (${placeholders})
            AND (expires_at IS NULL OR expires_at > datetime('now'))
-           AND superseded_by IS NULL`,
+           AND superseded_by IS NULL`
       )
       .all(...unique);
   } catch {
@@ -27,7 +29,7 @@ export function resolveLinks(db, ids) {
   }
 }
 
-export function resolveBacklinks(db, entryId) {
+export function resolveBacklinks(db: DatabaseSync, entryId: string): any[] {
   if (!entryId) return [];
   const likePattern = `%"${entryId}"%`;
   try {
@@ -36,7 +38,7 @@ export function resolveBacklinks(db, entryId) {
         `SELECT * FROM vault
          WHERE related_to LIKE ?
            AND (expires_at IS NULL OR expires_at > datetime('now'))
-           AND superseded_by IS NULL`,
+           AND superseded_by IS NULL`
       )
       .all(likePattern);
   } catch {
@@ -44,22 +46,23 @@ export function resolveBacklinks(db, entryId) {
   }
 }
 
-export function collectLinkedEntries(db, primaryEntries) {
+export function collectLinkedEntries(
+  db: DatabaseSync,
+  primaryEntries: Array<{ id: string; related_to?: string | null }>
+): { forward: any[]; backward: any[] } {
   const primaryIds = new Set(primaryEntries.map((e) => e.id));
 
-  const forwardIds = [];
+  const forwardIds: string[] = [];
   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).filter(
-    (e) => !primaryIds.has(e.id),
-  );
+  const forwardEntries = resolveLinks(db, forwardIds).filter((e) => !primaryIds.has(e.id));
 
-  const backwardSeen = new Set();
-  const backwardEntries = [];
+  const backwardSeen = new Set<string>();
+  const backwardEntries: any[] = [];
   for (const entry of primaryEntries) {
     const backlinks = resolveBacklinks(db, entry.id);
     for (const bl of backlinks) {
@@ -73,13 +76,12 @@ export function collectLinkedEntries(db, primaryEntries) {
   return { forward: forwardEntries, backward: backwardEntries };
 }
 
-export function validateRelatedTo(relatedTo) {
+export function validateRelatedTo(relatedTo: unknown): string | null {
   if (relatedTo === undefined || relatedTo === null) return null;
-  if (!Array.isArray(relatedTo))
-    return "related_to must be an array of entry IDs";
+  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 (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)}..."`;