@context-vault/core 2.8.3

package/src/server/tools/ingest-url.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { captureAndIndex } from "../../capture/index.js";
+import { ok, err, ensureVaultExists } from "../helpers.js";
+import {
+  MAX_KIND_LENGTH,
+  MAX_TAG_LENGTH,
+  MAX_TAGS_COUNT,
+} from "../../constants.js";
+
+const MAX_URL_LENGTH = 2048;
+
+export const name = "ingest_url";
+
+export const description =
+  "Fetch a URL, extract its readable content, and save it as a vault entry. Useful for saving articles, documentation, or web pages to your knowledge vault.";
+
+export const inputSchema = {
+  url: z.string().describe("The URL to fetch and save"),
+  kind: z.string().optional().describe("Entry kind (default: reference)"),
+  tags: z.array(z.string()).optional().describe("Tags for the entry"),
+};
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
+ * @param {import('../types.js').ToolShared} shared
+ */
+export async function handler(
+  { url: targetUrl, kind, tags },
+  ctx,
+  { ensureIndexed },
+) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  const vaultErr = ensureVaultExists(config);
+  if (vaultErr) return vaultErr;
+
+  if (!targetUrl?.trim())
+    return err("Required: url (non-empty string)", "INVALID_INPUT");
+  if (targetUrl.length > MAX_URL_LENGTH)
+    return err(`url must be under ${MAX_URL_LENGTH} chars`, "INVALID_INPUT");
+  if (kind !== undefined && kind !== null) {
+    if (typeof kind !== "string" || kind.length > MAX_KIND_LENGTH) {
+      return err(
+        `kind must be a string, max ${MAX_KIND_LENGTH} chars`,
+        "INVALID_INPUT",
+      );
+    }
+  }
+  if (tags !== undefined && tags !== null) {
+    if (!Array.isArray(tags))
+      return err("tags must be an array of strings", "INVALID_INPUT");
+    if (tags.length > MAX_TAGS_COUNT)
+      return err(`tags: max ${MAX_TAGS_COUNT} tags allowed`, "INVALID_INPUT");
+    for (const tag of tags) {
+      if (typeof tag !== "string" || tag.length > MAX_TAG_LENGTH) {
+        return err(
+          `each tag must be a string, max ${MAX_TAG_LENGTH} chars`,
+          "INVALID_INPUT",
+        );
+      }
+    }
+  }
+
+  await ensureIndexed();
+
+  // Hosted tier limit enforcement
+  if (ctx.checkLimits) {
+    const usage = ctx.checkLimits();
+    if (usage.entryCount >= usage.maxEntries) {
+      return err(
+        `Entry limit reached (${usage.maxEntries}). Upgrade to Pro for unlimited entries.`,
+        "LIMIT_EXCEEDED",
+      );
+    }
+  }
+
+  try {
+    const { ingestUrl } = await import("../../capture/ingest-url.js");
+    const entryData = await ingestUrl(targetUrl, { kind, tags });
+    const entry = await captureAndIndex(ctx, { ...entryData, userId });
+    const relPath = entry.filePath
+      ? entry.filePath.replace(config.vaultDir + "/", "")
+      : entry.filePath;
+    const parts = [
+      `✓ Ingested URL → ${relPath}`,
+      `  id: ${entry.id}`,
+      `  title: ${entry.title || "(untitled)"}`,
+      `  source: ${entry.source || targetUrl}`,
+    ];
+    if (entry.tags?.length) parts.push(`  tags: ${entry.tags.join(", ")}`);
+    parts.push(`  body: ${entry.body?.length || 0} chars`);
+    parts.push("", "_Use this id to update or delete later._");
+    return ok(parts.join("\n"));
+  } catch (e) {
+    return err(`Failed to ingest URL: ${e.message}`, "INGEST_FAILED");
+  }
+}

package/src/server/tools/list-context.js

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import { normalizeKind } from "../../core/files.js";
+import { ok } from "../helpers.js";
+
+export const name = "list_context";
+
+export const description =
+  "Browse vault entries without a search query. Returns id, title, kind, category, tags, created_at. Use get_context with a query for semantic search. Use this to browse by tags or find recent entries.";
+
+export const inputSchema = {
+  kind: z
+    .string()
+    .optional()
+    .describe("Filter by kind (e.g. 'insight', 'decision', 'pattern')"),
+  category: z
+    .enum(["knowledge", "entity", "event"])
+    .optional()
+    .describe("Filter by category"),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("Filter by tags (entries must match at least one)"),
+  since: z
+    .string()
+    .optional()
+    .describe("ISO date, return entries created after this"),
+  until: z
+    .string()
+    .optional()
+    .describe("ISO date, return entries created before this"),
+  limit: z
+    .number()
+    .optional()
+    .describe("Max results to return (default 20, max 100)"),
+  offset: z.number().optional().describe("Skip first N results for pagination"),
+};
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
+ * @param {import('../types.js').ToolShared} shared
+ */
+export async function handler(
+  { kind, category, tags, since, until, limit, offset },
+  ctx,
+  { ensureIndexed, reindexFailed },
+) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  await ensureIndexed();
+
+  const clauses = [];
+  const params = [];
+
+  if (userId !== undefined) {
+    clauses.push("user_id = ?");
+    params.push(userId);
+  }
+  if (kind) {
+    clauses.push("kind = ?");
+    params.push(normalizeKind(kind));
+  }
+  if (category) {
+    clauses.push("category = ?");
+    params.push(category);
+  }
+  if (since) {
+    clauses.push("created_at >= ?");
+    params.push(since);
+  }
+  if (until) {
+    clauses.push("created_at <= ?");
+    params.push(until);
+  }
+  clauses.push("(expires_at IS NULL OR expires_at > datetime('now'))");
+
+  const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+  const effectiveLimit = Math.min(limit || 20, 100);
+  const effectiveOffset = offset || 0;
+  // When tag-filtering, over-fetch to compensate for post-filter reduction
+  const fetchLimit = tags?.length ? effectiveLimit * 10 : effectiveLimit;
+
+  const countParams = [...params];
+  const total = ctx.db
+    .prepare(`SELECT COUNT(*) as c FROM vault ${where}`)
+    .get(...countParams).c;
+
+  params.push(fetchLimit, effectiveOffset);
+  const rows = ctx.db
+    .prepare(
+      `SELECT id, title, kind, category, tags, created_at, SUBSTR(body, 1, 120) as preview FROM vault ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+    )
+    .all(...params);
+
+  // Post-filter by tags if provided, then apply requested limit
+  const filtered = tags?.length
+    ? rows
+        .filter((r) => {
+          const entryTags = r.tags ? JSON.parse(r.tags) : [];
+          return tags.some((t) => entryTags.includes(t));
+        })
+        .slice(0, effectiveLimit)
+    : rows;
+
+  if (!filtered.length)
+    return ok("No entries found matching the given filters.");
+
+  const lines = [];
+  if (reindexFailed)
+    lines.push(
+      `> **Warning:** Auto-reindex failed. Results may be stale. Run \`context-vault reindex\` to fix.\n`,
+    );
+  lines.push(`## Vault Entries (${filtered.length} shown, ${total} total)\n`);
+  for (const r of filtered) {
+    const entryTags = r.tags ? JSON.parse(r.tags) : [];
+    const tagStr = entryTags.length ? entryTags.join(", ") : "none";
+    lines.push(
+      `- **${r.title || "(untitled)"}** [${r.kind}/${r.category}] — ${tagStr} — ${r.created_at} — \`${r.id}\``,
+    );
+    if (r.preview)
+      lines.push(
+        `  ${r.preview.replace(/\n+/g, " ").trim()}${r.preview.length >= 120 ? "…" : ""}`,
+      );
+  }
+
+  if (effectiveOffset + effectiveLimit < total) {
+    lines.push(
+      `\n_Page ${Math.floor(effectiveOffset / effectiveLimit) + 1}. Use offset: ${effectiveOffset + effectiveLimit} for next page._`,
+    );
+  }
+
+  return ok(lines.join("\n"));
+}

package/src/server/tools/save-context.js

@@ -0,0 +1,297 @@
+import { z } from "zod";
+import { captureAndIndex, updateEntryFile } from "../../capture/index.js";
+import { indexEntry } from "../../index/index.js";
+import { categoryFor } from "../../core/categories.js";
+import { normalizeKind } from "../../core/files.js";
+import { ok, err, ensureVaultExists, ensureValidKind } from "../helpers.js";
+import {
+  MAX_BODY_LENGTH,
+  MAX_TITLE_LENGTH,
+  MAX_KIND_LENGTH,
+  MAX_TAG_LENGTH,
+  MAX_TAGS_COUNT,
+  MAX_META_LENGTH,
+  MAX_SOURCE_LENGTH,
+  MAX_IDENTITY_KEY_LENGTH,
+} from "../../constants.js";
+
+/**
+ * Validate input fields for save_context. Returns an error response or null.
+ */
+function validateSaveInput({
+  kind,
+  title,
+  body,
+  tags,
+  meta,
+  source,
+  identity_key,
+}) {
+  if (kind !== undefined && kind !== null) {
+    if (typeof kind !== "string" || kind.length > MAX_KIND_LENGTH) {
+      return err(
+        `kind must be a string, max ${MAX_KIND_LENGTH} chars`,
+        "INVALID_INPUT",
+      );
+    }
+  }
+  if (body !== undefined && body !== null) {
+    if (typeof body !== "string" || body.length > MAX_BODY_LENGTH) {
+      return err(
+        `body must be a string, max ${MAX_BODY_LENGTH / 1024}KB`,
+        "INVALID_INPUT",
+      );
+    }
+  }
+  if (title !== undefined && title !== null) {
+    if (typeof title !== "string" || title.length > MAX_TITLE_LENGTH) {
+      return err(
+        `title must be a string, max ${MAX_TITLE_LENGTH} chars`,
+        "INVALID_INPUT",
+      );
+    }
+  }
+  if (tags !== undefined && tags !== null) {
+    if (!Array.isArray(tags))
+      return err("tags must be an array of strings", "INVALID_INPUT");
+    if (tags.length > MAX_TAGS_COUNT)
+      return err(`tags: max ${MAX_TAGS_COUNT} tags allowed`, "INVALID_INPUT");
+    for (const tag of tags) {
+      if (typeof tag !== "string" || tag.length > MAX_TAG_LENGTH) {
+        return err(
+          `each tag must be a string, max ${MAX_TAG_LENGTH} chars`,
+          "INVALID_INPUT",
+        );
+      }
+    }
+  }
+  if (meta !== undefined && meta !== null) {
+    const metaStr = JSON.stringify(meta);
+    if (metaStr.length > MAX_META_LENGTH) {
+      return err(
+        `meta must be under ${MAX_META_LENGTH / 1024}KB when serialized`,
+        "INVALID_INPUT",
+      );
+    }
+  }
+  if (source !== undefined && source !== null) {
+    if (typeof source !== "string" || source.length > MAX_SOURCE_LENGTH) {
+      return err(
+        `source must be a string, max ${MAX_SOURCE_LENGTH} chars`,
+        "INVALID_INPUT",
+      );
+    }
+  }
+  if (identity_key !== undefined && identity_key !== null) {
+    if (
+      typeof identity_key !== "string" ||
+      identity_key.length > MAX_IDENTITY_KEY_LENGTH
+    ) {
+      return err(
+        `identity_key must be a string, max ${MAX_IDENTITY_KEY_LENGTH} chars`,
+        "INVALID_INPUT",
+      );
+    }
+  }
+  return null;
+}
+
+export const name = "save_context";
+
+export const description =
+  "Save knowledge to your vault. Creates a .md file and indexes it for search. Use for any kind of context: insights, decisions, patterns, references, or any custom kind. To update an existing entry, pass its `id` — omitted fields are preserved.";
+
+export const inputSchema = {
+  id: z
+    .string()
+    .optional()
+    .describe(
+      "Entry ULID to update. When provided, updates the existing entry instead of creating new. Omitted fields are preserved.",
+    ),
+  kind: z
+    .string()
+    .optional()
+    .describe(
+      "Entry kind — determines folder (e.g. 'insight', 'decision', 'pattern', 'reference', or any custom kind). Required for new entries.",
+    ),
+  title: z.string().optional().describe("Entry title (optional for insights)"),
+  body: z
+    .string()
+    .optional()
+    .describe("Main content. Required for new entries."),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("Tags for categorization and search"),
+  meta: z
+    .any()
+    .optional()
+    .describe(
+      "Additional structured metadata (JSON object, e.g. { language: 'js', status: 'accepted' })",
+    ),
+  folder: z
+    .string()
+    .optional()
+    .describe("Subfolder within the kind directory (e.g. 'react/hooks')"),
+  source: z.string().optional().describe("Where this knowledge came from"),
+  identity_key: z
+    .string()
+    .optional()
+    .describe(
+      "Required for entity kinds (contact, project, tool, source). The unique identifier for this entity.",
+    ),
+  expires_at: z.string().optional().describe("ISO date for TTL expiry"),
+};
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
+ * @param {import('../types.js').ToolShared} shared
+ */
+export async function handler(
+  {
+    id,
+    kind,
+    title,
+    body,
+    tags,
+    meta,
+    folder,
+    source,
+    identity_key,
+    expires_at,
+  },
+  ctx,
+  { ensureIndexed },
+) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  const vaultErr = ensureVaultExists(config);
+  if (vaultErr) return vaultErr;
+
+  const inputErr = validateSaveInput({
+    kind,
+    title,
+    body,
+    tags,
+    meta,
+    source,
+    identity_key,
+  });
+  if (inputErr) return inputErr;
+
+  // ── Update mode ──
+  if (id) {
+    await ensureIndexed();
+
+    const existing = ctx.stmts.getEntryById.get(id);
+    if (!existing) return err(`Entry not found: ${id}`, "NOT_FOUND");
+
+    // Ownership check: don't leak existence across users
+    if (userId !== undefined && existing.user_id !== userId) {
+      return err(`Entry not found: ${id}`, "NOT_FOUND");
+    }
+
+    if (kind && normalizeKind(kind) !== existing.kind) {
+      return err(
+        `Cannot change kind (current: "${existing.kind}"). Delete and re-create instead.`,
+        "INVALID_UPDATE",
+      );
+    }
+    if (identity_key && identity_key !== existing.identity_key) {
+      return err(
+        `Cannot change identity_key (current: "${existing.identity_key}"). Delete and re-create instead.`,
+        "INVALID_UPDATE",
+      );
+    }
+
+    // Decrypt existing entry before merge if encrypted
+    if (ctx.decrypt && existing.body_encrypted) {
+      const decrypted = await ctx.decrypt(existing);
+      existing.body = decrypted.body;
+      if (decrypted.title) existing.title = decrypted.title;
+      if (decrypted.meta) existing.meta = JSON.stringify(decrypted.meta);
+    }
+
+    const entry = updateEntryFile(ctx, existing, {
+      title,
+      body,
+      tags,
+      meta,
+      source,
+      expires_at,
+    });
+    await indexEntry(ctx, entry);
+    const relPath = entry.filePath
+      ? entry.filePath.replace(config.vaultDir + "/", "")
+      : entry.filePath;
+    const parts = [`✓ Updated ${entry.kind} → ${relPath}`, `  id: ${entry.id}`];
+    if (entry.title) parts.push(`  title: ${entry.title}`);
+    const entryTags = entry.tags || [];
+    if (entryTags.length) parts.push(`  tags: ${entryTags.join(", ")}`);
+    parts.push("", "_Search with get_context to verify changes._");
+    return ok(parts.join("\n"));
+  }
+
+  // ── Create mode ──
+  if (!kind) return err("Required: kind (for new entries)", "INVALID_INPUT");
+  const kindErr = ensureValidKind(kind);
+  if (kindErr) return kindErr;
+  if (!body?.trim())
+    return err("Required: body (for new entries)", "INVALID_INPUT");
+
+  // Normalize kind to canonical singular form (e.g. "insights" → "insight")
+  const normalizedKind = normalizeKind(kind);
+
+  if (categoryFor(normalizedKind) === "entity" && !identity_key) {
+    return err(
+      `Entity kind "${normalizedKind}" requires identity_key`,
+      "MISSING_IDENTITY_KEY",
+    );
+  }
+
+  // Hosted tier limit enforcement (skipped in local mode — no checkLimits on ctx)
+  if (ctx.checkLimits) {
+    const usage = ctx.checkLimits();
+    if (usage.entryCount >= usage.maxEntries) {
+      return err(
+        `Entry limit reached (${usage.maxEntries}). Upgrade to Pro for unlimited entries.`,
+        "LIMIT_EXCEEDED",
+      );
+    }
+    if (usage.storageMb >= usage.maxStorageMb) {
+      return err(
+        `Storage limit reached (${usage.maxStorageMb} MB). Upgrade to Pro for more storage.`,
+        "LIMIT_EXCEEDED",
+      );
+    }
+  }
+
+  await ensureIndexed();
+
+  const mergedMeta = { ...(meta || {}) };
+  if (folder) mergedMeta.folder = folder;
+  const finalMeta = Object.keys(mergedMeta).length ? mergedMeta : undefined;
+
+  const entry = await captureAndIndex(ctx, {
+    kind: normalizedKind,
+    title,
+    body,
+    meta: finalMeta,
+    tags,
+    source,
+    folder,
+    identity_key,
+    expires_at,
+    userId,
+  });
+  const relPath = entry.filePath
+    ? entry.filePath.replace(config.vaultDir + "/", "")
+    : entry.filePath;
+  const parts = [`✓ Saved ${normalizedKind} → ${relPath}`, `  id: ${entry.id}`];
+  if (title) parts.push(`  title: ${title}`);
+  if (tags?.length) parts.push(`  tags: ${tags.join(", ")}`);
+  parts.push("", "_Use this id to update or delete later._");
+  return ok(parts.join("\n"));
+}

package/src/server/tools/submit-feedback.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { captureAndIndex } from "../../capture/index.js";
+import { ok, ensureVaultExists } from "../helpers.js";
+
+export const name = "submit_feedback";
+
+export const description =
+  "Report a bug, request a feature, or suggest an improvement. Feedback is stored in the vault and triaged by the development pipeline.";
+
+export const inputSchema = {
+  type: z.enum(["bug", "feature", "improvement"]).describe("Type of feedback"),
+  title: z.string().describe("Short summary of the feedback"),
+  body: z.string().describe("Detailed description"),
+  severity: z
+    .enum(["low", "medium", "high"])
+    .optional()
+    .describe("Severity level (default: medium)"),
+};
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
+ * @param {import('../types.js').ToolShared} shared
+ */
+export async function handler(
+  { type, title, body, severity },
+  ctx,
+  { ensureIndexed },
+) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  const vaultErr = ensureVaultExists(config);
+  if (vaultErr) return vaultErr;
+
+  await ensureIndexed();
+
+  const effectiveSeverity = severity || "medium";
+  const entry = await captureAndIndex(ctx, {
+    kind: "feedback",
+    title,
+    body,
+    tags: [type, effectiveSeverity],
+    source: "submit_feedback",
+    meta: { feedback_type: type, severity: effectiveSeverity, status: "new" },
+    userId,
+  });
+
+  const relPath = entry.filePath
+    ? entry.filePath.replace(config.vaultDir + "/", "")
+    : entry.filePath;
+  return ok(
+    `Feedback submitted: ${type} [${effectiveSeverity}] → ${relPath}\n  id: ${entry.id}\n  title: ${title}`,
+  );
+}

package/src/server/tools.js

@@ -0,0 +1,111 @@
+import { reindex } from "../index/index.js";
+import { err } from "./helpers.js";
+
+import * as getContext from "./tools/get-context.js";
+import * as saveContext from "./tools/save-context.js";
+import * as listContext from "./tools/list-context.js";
+import * as deleteContext from "./tools/delete-context.js";
+import * as submitFeedback from "./tools/submit-feedback.js";
+import * as ingestUrl from "./tools/ingest-url.js";
+import * as contextStatus from "./tools/context-status.js";
+
+const toolModules = [
+  getContext,
+  saveContext,
+  listContext,
+  deleteContext,
+  submitFeedback,
+  ingestUrl,
+  contextStatus,
+];
+
+const TOOL_TIMEOUT_MS = 60_000;
+
+export function registerTools(server, ctx) {
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  function tracked(handler) {
+    return async (...args) => {
+      if (ctx.activeOps) ctx.activeOps.count++;
+      let timer;
+      try {
+        return await Promise.race([
+          Promise.resolve(handler(...args)),
+          new Promise((_, reject) => {
+            timer = setTimeout(
+              () => reject(new Error("TOOL_TIMEOUT")),
+              TOOL_TIMEOUT_MS,
+            );
+          }),
+        ]);
+      } catch (e) {
+        if (e.message === "TOOL_TIMEOUT") {
+          return err(
+            "Tool timed out after 60s. Try a simpler query or run `context-vault reindex` first.",
+            "TIMEOUT",
+          );
+        }
+        throw e;
+      } finally {
+        clearTimeout(timer);
+        if (ctx.activeOps) ctx.activeOps.count--;
+      }
+    };
+  }
+
+  // In hosted mode, skip reindex — DB is always in sync via writeEntry→indexEntry
+  let reindexDone = userId !== undefined ? true : false;
+  let reindexPromise = null;
+  let reindexAttempts = 0;
+  let reindexFailed = false;
+  const MAX_REINDEX_ATTEMPTS = 2;
+
+  async function ensureIndexed() {
+    if (reindexDone) return;
+    if (reindexPromise) return reindexPromise;
+    // Assign promise synchronously to prevent concurrent calls from both entering reindex()
+    const promise = reindex(ctx, { fullSync: true })
+      .then((stats) => {
+        reindexDone = true;
+        const total = stats.added + stats.updated + stats.removed;
+        if (total > 0) {
+          console.error(
+            `[context-vault] Auto-reindex: +${stats.added} ~${stats.updated} -${stats.removed} (${stats.unchanged} unchanged)`,
+          );
+        }
+      })
+      .catch((e) => {
+        reindexAttempts++;
+        console.error(
+          `[context-vault] Auto-reindex failed (attempt ${reindexAttempts}/${MAX_REINDEX_ATTEMPTS}): ${e.message}`,
+        );
+        if (reindexAttempts >= MAX_REINDEX_ATTEMPTS) {
+          console.error(
+            `[context-vault] Giving up on auto-reindex. Run \`context-vault reindex\` manually to diagnose.`,
+          );
+          reindexDone = true;
+          reindexFailed = true;
+        } else {
+          reindexPromise = null; // Allow retry on next tool call
+        }
+      });
+    reindexPromise = promise;
+    return reindexPromise;
+  }
+
+  const shared = {
+    ensureIndexed,
+    get reindexFailed() {
+      return reindexFailed;
+    },
+  };
+
+  for (const mod of toolModules) {
+    server.tool(
+      mod.name,
+      mod.description,
+      mod.inputSchema,
+      tracked((args) => mod.handler(args, ctx, shared)),
+    );
+  }
+}