@context-vault/core 2.17.1 → 3.0.0

package/src/core/migrate-dirs.js

@@ -1,196 +0,0 @@
-/**
- * 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/status.js

@@ -1,350 +0,0 @@
-/**
- * status.js — Vault status/diagnostics data gathering
- */
-
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { walkDir } from "./files.js";
-import { isEmbedAvailable } from "../index/embed.js";
-import { KIND_STALENESS_DAYS } from "./categories.js";
-
-/**
- * Gather raw vault status data for formatting by consumers.
- *
- * @param {import('../server/types.js').BaseCtx} ctx
- * @param {{ userId?: string }} opts — optional userId for per-user stats
- * @returns {{ fileCount, subdirs, kindCounts, dbSize, stalePaths, resolvedFrom, embeddingStatus, errors }}
- */
-export function gatherVaultStatus(ctx, opts = {}) {
-  const { db, config } = ctx;
-  const { userId } = opts;
-  const errors = [];
-
-  // Build user filter clause for DB queries
-  const hasUser = userId !== undefined;
-  const userWhere = hasUser ? "WHERE user_id = ?" : "";
-  const userAnd = hasUser ? "AND user_id = ?" : "";
-  const userParams = hasUser ? [userId] : [];
-
-  // Count files in vault subdirs (auto-discover)
-  let fileCount = 0;
-  const subdirs = [];
-  try {
-    if (existsSync(config.vaultDir)) {
-      for (const d of readdirSync(config.vaultDir, { withFileTypes: true })) {
-        if (d.isDirectory()) {
-          const dir = join(config.vaultDir, d.name);
-          const count = walkDir(dir).length;
-          fileCount += count;
-          if (count > 0) subdirs.push({ name: d.name, count });
-        }
-      }
-    }
-  } catch (e) {
-    errors.push(`File scan failed: ${e.message}`);
-  }
-
-  // Count DB rows by kind
-  let kindCounts = [];
-  try {
-    kindCounts = db
-      .prepare(
-        `SELECT kind, COUNT(*) as c FROM vault ${userWhere} GROUP BY kind`,
-      )
-      .all(...userParams);
-  } catch (e) {
-    errors.push(`Kind count query failed: ${e.message}`);
-  }
-
-  // Count DB rows by category
-  let categoryCounts = [];
-  try {
-    categoryCounts = db
-      .prepare(
-        `SELECT category, COUNT(*) as c FROM vault ${userWhere} GROUP BY category`,
-      )
-      .all(...userParams);
-  } catch (e) {
-    errors.push(`Category count query failed: ${e.message}`);
-  }
-
-  // DB file size
-  let dbSize = "n/a";
-  let dbSizeBytes = 0;
-  try {
-    if (existsSync(config.dbPath)) {
-      dbSizeBytes = statSync(config.dbPath).size;
-      dbSize =
-        dbSizeBytes > 1024 * 1024
-          ? `${(dbSizeBytes / 1024 / 1024).toFixed(1)}MB`
-          : `${(dbSizeBytes / 1024).toFixed(1)}KB`;
-    }
-  } catch (e) {
-    errors.push(`DB size check failed: ${e.message}`);
-  }
-
-  // Check for stale paths (count all mismatches, not just a sample)
-  let stalePaths = false;
-  let staleCount = 0;
-  try {
-    const result = db
-      .prepare(
-        `SELECT COUNT(*) as c FROM vault WHERE file_path NOT LIKE ? || '%' ${userAnd}`,
-      )
-      .get(config.vaultDir, ...userParams);
-    staleCount = result.c;
-    stalePaths = staleCount > 0;
-  } catch (e) {
-    errors.push(`Stale path check failed: ${e.message}`);
-  }
-
-  // Count expired entries pending pruning
-  let expiredCount = 0;
-  try {
-    expiredCount = db
-      .prepare(
-        `SELECT COUNT(*) as c FROM vault WHERE expires_at IS NOT NULL AND expires_at <= datetime('now') ${userAnd}`,
-      )
-      .get(...userParams).c;
-  } catch (e) {
-    errors.push(`Expired count failed: ${e.message}`);
-  }
-
-  // Count event-category entries
-  let eventCount = 0;
-  try {
-    eventCount = db
-      .prepare(
-        `SELECT COUNT(*) as c FROM vault WHERE category = 'event' ${userAnd}`,
-      )
-      .get(...userParams).c;
-  } catch (e) {
-    errors.push(`Event count failed: ${e.message}`);
-  }
-
-  // Count event entries without expires_at
-  let eventsWithoutTtlCount = 0;
-  try {
-    eventsWithoutTtlCount = db
-      .prepare(
-        `SELECT COUNT(*) as c FROM vault WHERE category = 'event' AND expires_at IS NULL ${userAnd}`,
-      )
-      .get(...userParams).c;
-  } catch (e) {
-    errors.push(`Events without TTL count failed: ${e.message}`);
-  }
-
-  // Embedding/vector status
-  let embeddingStatus = null;
-  try {
-    const total = db
-      .prepare(`SELECT COUNT(*) as c FROM vault ${userWhere}`)
-      .get(...userParams).c;
-    const indexed = db
-      .prepare(
-        `SELECT COUNT(*) as c FROM vault WHERE rowid IN (SELECT rowid FROM vault_vec) ${userAnd}`,
-      )
-      .get(...userParams).c;
-    embeddingStatus = { indexed, total, missing: total - indexed };
-  } catch (e) {
-    errors.push(`Embedding status check failed: ${e.message}`);
-  }
-
-  // Embedding model availability
-  const embedModelAvailable = isEmbedAvailable();
-
-  // Count auto-captured feedback entries (written by tracked() on unhandled errors)
-  let autoCapturedFeedbackCount = 0;
-  try {
-    autoCapturedFeedbackCount = db
-      .prepare(
-        `SELECT COUNT(*) as c FROM vault WHERE kind = 'feedback' AND tags LIKE '%"auto-captured"%' ${userAnd}`,
-      )
-      .get(...userParams).c;
-  } catch (e) {
-    errors.push(`Auto-captured feedback count failed: ${e.message}`);
-  }
-
-  // Stale knowledge entries — kinds with a threshold, not updated within N days
-  let staleKnowledge = [];
-  try {
-    const stalenessKinds = Object.entries(KIND_STALENESS_DAYS);
-    if (stalenessKinds.length > 0) {
-      const kindClauses = stalenessKinds
-        .map(
-          ([kind, days]) =>
-            `(kind = '${kind}' AND COALESCE(updated_at, created_at) <= datetime('now', '-${days} days'))`,
-        )
-        .join(" OR ");
-      staleKnowledge = db
-        .prepare(
-          `SELECT kind, title, COALESCE(updated_at, created_at) as last_updated FROM vault WHERE category = 'knowledge' AND (${kindClauses}) AND (expires_at IS NULL OR expires_at > datetime('now')) ${userAnd} ORDER BY last_updated ASC LIMIT 10`,
-        )
-        .all(...userParams);
-    }
-  } catch (e) {
-    errors.push(`Stale knowledge check failed: ${e.message}`);
-  }
-
-  return {
-    fileCount,
-    subdirs,
-    kindCounts,
-    categoryCounts,
-    dbSize,
-    dbSizeBytes,
-    stalePaths,
-    staleCount,
-    expiredCount,
-    eventCount,
-    eventsWithoutTtlCount,
-    embeddingStatus,
-    embedModelAvailable,
-    autoCapturedFeedbackCount,
-    staleKnowledge,
-    resolvedFrom: config.resolvedFrom,
-    errors,
-  };
-}
-
-/**
- * Compute growth warnings based on vault status and configured thresholds.
- *
- * @param {object} status — result of gatherVaultStatus()
- * @param {object} thresholds — from config.thresholds
- * @returns {{ warnings: Array, hasCritical: boolean, hasWarnings: boolean, actions: string[], kindBreakdown: Array }}
- */
-export function computeGrowthWarnings(status, thresholds) {
-  if (!thresholds)
-    return {
-      warnings: [],
-      hasCritical: false,
-      hasWarnings: false,
-      actions: [],
-      kindBreakdown: [],
-    };
-
-  const t = thresholds;
-  const warnings = [];
-  const actions = [];
-
-  const total = status.embeddingStatus?.total ?? 0;
-  const {
-    eventCount = 0,
-    eventsWithoutTtlCount = 0,
-    expiredCount = 0,
-    dbSizeBytes = 0,
-  } = status;
-
-  let totalExceeded = false;
-
-  if (t.totalEntries?.critical != null && total >= t.totalEntries.critical) {
-    totalExceeded = true;
-    warnings.push({
-      level: "critical",
-      message: `Total entries: ${total.toLocaleString()} (exceeds critical limit of ${t.totalEntries.critical.toLocaleString()})`,
-    });
-  } else if (t.totalEntries?.warn != null && total >= t.totalEntries.warn) {
-    totalExceeded = true;
-    warnings.push({
-      level: "warn",
-      message: `Total entries: ${total.toLocaleString()} (exceeds recommended ${t.totalEntries.warn.toLocaleString()})`,
-    });
-  }
-
-  if (
-    t.eventEntries?.critical != null &&
-    eventCount >= t.eventEntries.critical
-  ) {
-    warnings.push({
-      level: "critical",
-      message: `Event entries: ${eventCount.toLocaleString()} (exceeds critical limit of ${t.eventEntries.critical.toLocaleString()})`,
-    });
-  } else if (
-    t.eventEntries?.warn != null &&
-    eventCount >= t.eventEntries.warn
-  ) {
-    const ttlNote =
-      eventsWithoutTtlCount > 0
-        ? ` (${eventsWithoutTtlCount.toLocaleString()} without TTL)`
-        : "";
-    warnings.push({
-      level: "warn",
-      message: `Event entries: ${eventCount.toLocaleString()}${ttlNote} (exceeds recommended ${t.eventEntries.warn.toLocaleString()})`,
-    });
-  }
-
-  if (
-    t.vaultSizeBytes?.critical != null &&
-    dbSizeBytes >= t.vaultSizeBytes.critical
-  ) {
-    warnings.push({
-      level: "critical",
-      message: `Database size: ${(dbSizeBytes / 1024 / 1024).toFixed(1)}MB (exceeds critical limit of ${(t.vaultSizeBytes.critical / 1024 / 1024).toFixed(0)}MB)`,
-    });
-  } else if (
-    t.vaultSizeBytes?.warn != null &&
-    dbSizeBytes >= t.vaultSizeBytes.warn
-  ) {
-    warnings.push({
-      level: "warn",
-      message: `Database size: ${(dbSizeBytes / 1024 / 1024).toFixed(1)}MB (exceeds recommended ${(t.vaultSizeBytes.warn / 1024 / 1024).toFixed(0)}MB)`,
-    });
-  }
-
-  if (
-    t.eventsWithoutTtl?.warn != null &&
-    eventsWithoutTtlCount >= t.eventsWithoutTtl.warn
-  ) {
-    warnings.push({
-      level: "warn",
-      message: `Event entries without expires_at: ${eventsWithoutTtlCount.toLocaleString()} (exceeds recommended ${t.eventsWithoutTtl.warn.toLocaleString()})`,
-    });
-  }
-
-  const hasCritical = warnings.some((w) => w.level === "critical");
-
-  if (expiredCount > 0) {
-    actions.push(
-      `Run \`context-vault prune\` to remove ${expiredCount} expired event entr${expiredCount === 1 ? "y" : "ies"}`,
-    );
-  }
-  const eventThresholdExceeded =
-    eventCount >= (t.eventEntries?.warn ?? Infinity);
-  const ttlThresholdExceeded =
-    eventsWithoutTtlCount >= (t.eventsWithoutTtl?.warn ?? Infinity);
-  if (
-    eventsWithoutTtlCount > 0 &&
-    (eventThresholdExceeded || ttlThresholdExceeded)
-  ) {
-    actions.push(
-      "Add `expires_at` to event/session entries to enable automatic cleanup",
-    );
-  }
-  if (total >= (t.totalEntries?.warn ?? Infinity)) {
-    actions.push("Consider archiving events older than 90 days");
-  }
-
-  const kindBreakdown = totalExceeded
-    ? buildKindBreakdown(status.kindCounts, total)
-    : [];
-
-  return {
-    warnings,
-    hasCritical,
-    hasWarnings: warnings.length > 0,
-    actions,
-    kindBreakdown,
-  };
-}
-
-function buildKindBreakdown(kindCounts, total) {
-  if (!kindCounts?.length || total === 0) return [];
-  return [...kindCounts]
-    .sort((a, b) => b.c - a.c)
-    .map(({ kind, c }) => ({
-      kind,
-      count: c,
-      pct: Math.round((c / total) * 100),
-    }));
-}

package/src/core/telemetry.js

@@ -1,90 +0,0 @@
-import { existsSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { API_URL, MARKETING_URL, GITHUB_ISSUES_URL } from "../constants.js";
-
-const TELEMETRY_ENDPOINT = `${API_URL}/telemetry`;
-const NOTICE_MARKER = ".telemetry-notice-shown";
-const FEEDBACK_PROMPT_MARKER = ".feedback-prompt-shown";
-
-export function isTelemetryEnabled(config) {
-  const envVal = process.env.CONTEXT_VAULT_TELEMETRY;
-  if (envVal !== undefined) return envVal === "1" || envVal === "true";
-  return config?.telemetry === true;
-}
-
-/**
- * Fire-and-forget telemetry event. Never throws, never blocks.
- * Payload contains only: event, code, tool, cv_version, node_version, platform, arch, ts.
- * No message text, stack traces, vault content, file paths, or user identifiers.
- */
-export function sendTelemetryEvent(config, payload) {
-  if (!isTelemetryEnabled(config)) return;
-
-  const event = {
-    event: payload.event,
-    code: payload.code || null,
-    tool: payload.tool || null,
-    cv_version: payload.cv_version,
-    node_version: process.version,
-    platform: process.platform,
-    arch: process.arch,
-    ts: new Date().toISOString(),
-  };
-
-  fetch(TELEMETRY_ENDPOINT, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(event),
-    signal: AbortSignal.timeout(5000),
-  }).catch(() => {});
-}
-
-/**
- * Print the one-time telemetry notice to stderr.
- * Uses a marker file in dataDir to ensure it's only shown once.
- */
-export function maybeShowTelemetryNotice(dataDir) {
-  try {
-    const markerPath = join(dataDir, NOTICE_MARKER);
-    if (existsSync(markerPath)) return;
-    writeFileSync(markerPath, new Date().toISOString() + "\n");
-  } catch {
-    return;
-  }
-
-  const lines = [
-    "[context-vault] Telemetry: disabled by default.",
-    "[context-vault] To help improve context-vault, you can opt in to anonymous error reporting.",
-    "[context-vault] Reports contain only: event type, error code, tool name, version, node version, platform, arch, timestamp.",
-    "[context-vault] No vault content, file paths, or personal data is ever sent.",
-    '[context-vault] Opt in: set "telemetry": true in ~/.context-mcp/config.json or set CONTEXT_VAULT_TELEMETRY=1.',
-    `[context-vault] Full payload schema: ${MARKETING_URL}/telemetry`,
-  ];
-  for (const line of lines) {
-    process.stderr.write(line + "\n");
-  }
-}
-
-/**
- * Print a one-time feedback prompt after the user's first successful save.
- * Uses a marker file in dataDir to ensure it's only shown once.
- * Never throws, never blocks.
- */
-export function maybeShowFeedbackPrompt(dataDir) {
-  try {
-    const markerPath = join(dataDir, FEEDBACK_PROMPT_MARKER);
-    if (existsSync(markerPath)) return;
-    writeFileSync(markerPath, new Date().toISOString() + "\n");
-  } catch {
-    return;
-  }
-
-  const lines = [
-    "[context-vault] First entry saved — nice work!",
-    "[context-vault] Got feedback, a bug, or a feature request?",
-    `[context-vault] Open an issue: ${GITHUB_ISSUES_URL}`,
-  ];
-  for (const line of lines) {
-    process.stderr.write(line + "\n");
-  }
-}