@context-vault/core 2.17.1 → 3.0.0

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

@@ -1,244 +0,0 @@
-import { z } from "zod";
-import { readFileSync, existsSync } from "node:fs";
-import { execSync } from "node:child_process";
-import { join, basename } from "node:path";
-import { captureAndIndex } from "../../capture/index.js";
-import { ok, err, ensureVaultExists } from "../helpers.js";
-
-export const name = "ingest_project";
-
-export const description =
-  "Scan a local project directory and register it as a project entity in the vault. Extracts metadata from package.json, git history, and README. Also creates a bucket entity for project-scoped tagging.";
-
-export const inputSchema = {
-  path: z.string().describe("Absolute path to the project directory to ingest"),
-  tags: z
-    .array(z.string())
-    .optional()
-    .describe("Additional tags to apply (bucket tags are auto-generated)"),
-  pillar: z
-    .string()
-    .optional()
-    .describe("Parent pillar/domain name — creates a bucket:pillar tag"),
-};
-
-function safeRead(filePath) {
-  try {
-    return readFileSync(filePath, "utf-8");
-  } catch {
-    return null;
-  }
-}
-
-function safeExec(cmd, cwd) {
-  try {
-    return execSync(cmd, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
-  } catch {
-    return null;
-  }
-}
-
-function detectTechStack(projectPath, pkgJson) {
-  const stack = [];
-
-  if (existsSync(join(projectPath, "pyproject.toml")) || existsSync(join(projectPath, "setup.py"))) {
-    stack.push("python");
-  }
-  if (existsSync(join(projectPath, "Cargo.toml"))) {
-    stack.push("rust");
-  }
-  if (existsSync(join(projectPath, "go.mod"))) {
-    stack.push("go");
-  }
-  if (pkgJson) {
-    stack.push("javascript");
-    const allDeps = {
-      ...(pkgJson.dependencies || {}),
-      ...(pkgJson.devDependencies || {}),
-    };
-    if (allDeps.typescript || existsSync(join(projectPath, "tsconfig.json"))) {
-      stack.push("typescript");
-    }
-    if (allDeps.react || allDeps["react-dom"]) stack.push("react");
-    if (allDeps.next || allDeps["next"]) stack.push("nextjs");
-    if (allDeps.vue) stack.push("vue");
-    if (allDeps.svelte) stack.push("svelte");
-    if (allDeps.express) stack.push("express");
-    if (allDeps.fastify) stack.push("fastify");
-    if (allDeps.hono) stack.push("hono");
-    if (allDeps.vite) stack.push("vite");
-    if (allDeps.electron) stack.push("electron");
-    if (allDeps.tauri || allDeps["@tauri-apps/api"]) stack.push("tauri");
-  }
-
-  return [...new Set(stack)];
-}
-
-function extractReadmeDescription(projectPath) {
-  const raw = safeRead(join(projectPath, "README.md")) || safeRead(join(projectPath, "readme.md"));
-  if (!raw) return null;
-  for (const line of raw.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    return trimmed.slice(0, 200);
-  }
-  return null;
-}
-
-function buildProjectBody({ projectName, description, techStack, repoUrl, lastCommit, projectPath, hasClaudeMd }) {
-  const lines = [];
-  lines.push(`## ${projectName}`);
-  if (description) lines.push("", description);
-  lines.push("", "### Metadata");
-  lines.push(`- **Path**: \`${projectPath}\``);
-  if (repoUrl) lines.push(`- **Repo**: ${repoUrl}`);
-  if (techStack.length) lines.push(`- **Stack**: ${techStack.join(", ")}`);
-  if (lastCommit) lines.push(`- **Last commit**: ${lastCommit}`);
-  lines.push(`- **CLAUDE.md**: ${hasClaudeMd ? "yes" : "no"}`);
-  return lines.join("\n");
-}
-
-/**
- * @param {object} args
- * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
- * @param {import('../types.js').ToolShared} shared
- */
-export async function handler({ path: projectPath, tags, pillar }, ctx, { ensureIndexed }) {
-  const { config } = ctx;
-  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
-
-  const vaultErr = ensureVaultExists(config);
-  if (vaultErr) return vaultErr;
-
-  if (!projectPath?.trim()) {
-    return err("Required: path (absolute path to project directory)", "INVALID_INPUT");
-  }
-  if (!existsSync(projectPath)) {
-    return err(`Directory not found: ${projectPath}`, "INVALID_INPUT");
-  }
-
-  await ensureIndexed();
-
-  // Read package.json if present
-  let pkgJson = null;
-  const pkgPath = join(projectPath, "package.json");
-  if (existsSync(pkgPath)) {
-    try {
-      pkgJson = JSON.parse(readFileSync(pkgPath, "utf-8"));
-    } catch {
-      pkgJson = null;
-    }
-  }
-
-  // Derive project name
-  let projectName = basename(projectPath);
-  if (pkgJson?.name) {
-    projectName = pkgJson.name.replace(/^@[^/]+\//, "");
-  }
-
-  // Slug-safe identity_key
-  const identityKey = projectName.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-
-  // Description: package.json > README
-  const description =
-    pkgJson?.description || extractReadmeDescription(projectPath) || null;
-
-  // Tech stack detection
-  const techStack = detectTechStack(projectPath, pkgJson);
-
-  // Git metadata
-  const isGitRepo = existsSync(join(projectPath, ".git"));
-  const repoUrl = isGitRepo
-    ? safeExec("git remote get-url origin", projectPath)
-    : null;
-  const lastCommit = isGitRepo
-    ? safeExec("git log -1 --format=%ci", projectPath)
-    : null;
-
-  // CLAUDE.md presence
-  const hasClaudeMd = existsSync(join(projectPath, "CLAUDE.md"));
-
-  // Build tags
-  const bucketTag = `bucket:${identityKey}`;
-  const autoTags = [bucketTag];
-  if (pillar) autoTags.push(`bucket:${pillar}`);
-  const allTags = [...new Set([...autoTags, ...(tags || [])])];
-
-  // Build body
-  const body = buildProjectBody({
-    projectName,
-    description,
-    techStack,
-    repoUrl,
-    lastCommit,
-    projectPath,
-    hasClaudeMd,
-  });
-
-  // Build meta
-  const meta = {
-    path: projectPath,
-    ...(repoUrl ? { repo_url: repoUrl } : {}),
-    ...(techStack.length ? { tech_stack: techStack } : {}),
-    has_claude_md: hasClaudeMd,
-  };
-
-  // Save project entity
-  const projectEntry = await captureAndIndex(ctx, {
-    kind: "project",
-    title: projectName,
-    body,
-    tags: allTags,
-    identity_key: identityKey,
-    meta,
-    userId,
-  });
-
-  // Save bucket entity if it doesn't already exist
-  const bucketUserClause = userId !== undefined ? "AND user_id = ?" : "";
-  const bucketParams = userId !== undefined ? [bucketTag, userId] : [bucketTag];
-  const bucketExists = ctx.db
-    .prepare(
-      `SELECT 1 FROM vault WHERE kind = 'bucket' AND identity_key = ? ${bucketUserClause} LIMIT 1`,
-    )
-    .get(...bucketParams);
-
-  let bucketEntry = null;
-  if (!bucketExists) {
-    bucketEntry = await captureAndIndex(ctx, {
-      kind: "bucket",
-      title: projectName,
-      body: `Bucket for project: ${projectName}`,
-      tags: allTags,
-      identity_key: bucketTag,
-      meta: { project_path: projectPath },
-      userId,
-    });
-  }
-
-  const relPath = projectEntry.filePath
-    ? projectEntry.filePath.replace(config.vaultDir + "/", "")
-    : projectEntry.filePath;
-
-  const parts = [
-    `✓ Ingested project → ${relPath}`,
-    `  id: ${projectEntry.id}`,
-    `  title: ${projectEntry.title}`,
-    `  tags: ${allTags.join(", ")}`,
-    ...(techStack.length ? [`  stack: ${techStack.join(", ")}`] : []),
-    ...(repoUrl ? [`  repo: ${repoUrl}`] : []),
-  ];
-
-  if (bucketEntry) {
-    const bucketRelPath = bucketEntry.filePath
-      ? bucketEntry.filePath.replace(config.vaultDir + "/", "")
-      : bucketEntry.filePath;
-    parts.push(``, `✓ Created bucket → ${bucketRelPath}`);
-    parts.push(`  id: ${bucketEntry.id}`);
-  } else {
-    parts.push(``, `  (bucket '${bucketTag}' already exists — skipped)`);
-  }
-
-  parts.push("", "_Use get_context with bucket tag to retrieve project-scoped entries._");
-  return ok(parts.join("\n"));
-}

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

@@ -1,88 +0,0 @@
-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();
-
-  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-buckets.js

@@ -1,116 +0,0 @@
-import { z } from "zod";
-import { ok } from "../helpers.js";
-
-export const name = "list_buckets";
-
-export const description =
-  "List all registered bucket entities in the vault. Buckets are named scopes used to group entries via 'bucket:' prefixed tags. Returns each bucket's name, description, parent, and optional entry count.";
-
-export const inputSchema = {
-  include_counts: z
-    .boolean()
-    .optional()
-    .describe(
-      "Include count of entries tagged with each bucket (default true). Set false to skip the count queries for faster response.",
-    ),
-};
-
-/**
- * @param {object} args
- * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
- * @param {import('../types.js').ToolShared} shared
- */
-export async function handler(
-  { include_counts = true },
-  ctx,
-  { ensureIndexed, reindexFailed },
-) {
-  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
-
-  await ensureIndexed();
-
-  const userClause = userId !== undefined ? "AND user_id = ?" : "";
-  const userParams = userId !== undefined ? [userId] : [];
-
-  const buckets = ctx.db
-    .prepare(
-      `SELECT id, title, identity_key, body, tags, meta, created_at, updated_at
-       FROM vault
-       WHERE kind = 'bucket'
-         AND (expires_at IS NULL OR expires_at > datetime('now'))
-         AND superseded_by IS NULL
-         ${userClause}
-       ORDER BY title ASC`,
-    )
-    .all(...userParams);
-
-  if (!buckets.length) {
-    return ok(
-      "No buckets registered.\n\nCreate one with `save_context(kind: \"bucket\", identity_key: \"bucket:myproject\", title: \"My Project\", body: \"...\")` to register a bucket.",
-    );
-  }
-
-  const lines = [];
-  if (reindexFailed) {
-    lines.push(
-      `> **Warning:** Auto-reindex failed. Results may be stale. Run \`context-vault reindex\` to fix.\n`,
-    );
-  }
-  lines.push(`## Registered Buckets (${buckets.length})\n`);
-
-  for (const b of buckets) {
-    let meta = {};
-    if (b.meta) {
-      try {
-        meta = typeof b.meta === "string" ? JSON.parse(b.meta) : b.meta;
-      } catch {
-        meta = {};
-      }
-    }
-
-    const bucketTags = b.tags ? JSON.parse(b.tags) : [];
-    const name = b.identity_key
-      ? b.identity_key.replace(/^bucket:/, "")
-      : b.title || b.id;
-    const parent = meta.parent || null;
-
-    let entryCount = null;
-    if (include_counts && b.identity_key) {
-      const countUserClause =
-        userId !== undefined ? "AND user_id = ?" : "";
-      const countParams = userId !== undefined ? [userId] : [];
-      const row = ctx.db
-        .prepare(
-          `SELECT COUNT(*) as c FROM vault
-           WHERE tags LIKE ?
-             AND kind != 'bucket'
-             AND (expires_at IS NULL OR expires_at > datetime('now'))
-             AND superseded_by IS NULL
-             ${countUserClause}`,
-        )
-        .get(`%"${b.identity_key}"%`, ...countParams);
-      entryCount = row ? row.c : 0;
-    }
-
-    const titleDisplay = b.title || name;
-    const headerParts = [`**${titleDisplay}**`];
-    if (b.identity_key) headerParts.push(`\`${b.identity_key}\``);
-    if (parent) headerParts.push(`parent: ${parent}`);
-    if (entryCount !== null) headerParts.push(`${entryCount} entries`);
-    lines.push(`- ${headerParts.join(" — ")}`);
-
-    if (b.body) {
-      const preview = b.body.replace(/\n+/g, " ").trim().slice(0, 120);
-      lines.push(`  ${preview}${b.body.length > 120 ? "…" : ""}`);
-    }
-    if (bucketTags.length) {
-      lines.push(`  tags: ${bucketTags.join(", ")}`);
-    }
-  }
-
-  lines.push(
-    "\n_Register a new bucket with `save_context(kind: \"bucket\", identity_key: \"bucket:<name>\", title: \"...\", body: \"...\")`_",
-  );
-
-  return ok(lines.join("\n"));
-}

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

@@ -1,163 +0,0 @@
-import { z } from "zod";
-import { normalizeKind } from "../../core/files.js";
-import { categoryFor } from "../../core/categories.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, updated_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 kindFilter = kind ? normalizeKind(kind) : null;
-  const effectiveCategory =
-    category || (kindFilter ? categoryFor(kindFilter) : null);
-  let effectiveSince = since || null;
-  let autoWindowed = false;
-  if (effectiveCategory === "event" && !since && !until) {
-    const decayMs = (config.eventDecayDays || 30) * 86400000;
-    effectiveSince = new Date(Date.now() - decayMs).toISOString();
-    autoWindowed = true;
-  }
-
-  const clauses = [];
-  const params = [];
-
-  if (userId !== undefined) {
-    clauses.push("user_id = ?");
-    params.push(userId);
-  }
-  if (kindFilter) {
-    clauses.push("kind = ?");
-    params.push(kindFilter);
-  }
-  if (category) {
-    clauses.push("category = ?");
-    params.push(category);
-  }
-  if (effectiveSince) {
-    clauses.push("created_at >= ?");
-    params.push(effectiveSince);
-  }
-  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, updated_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) {
-    if (autoWindowed) {
-      const days = config.eventDecayDays || 30;
-      return ok(
-        `No entries found matching the given filters in events (last ${days} days).\nTry with \`since: "YYYY-MM-DD"\` to search older events.`,
-      );
-    }
-    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`);
-  if (autoWindowed) {
-    const days = config.eventDecayDays || 30;
-    lines.push(
-      `> ℹ Event search limited to last ${days} days. Use \`since\` parameter for older results.\n`,
-    );
-  }
-  for (const r of filtered) {
-    const entryTags = r.tags ? JSON.parse(r.tags) : [];
-    const tagStr = entryTags.length ? entryTags.join(", ") : "none";
-    const dateStr =
-      r.updated_at && r.updated_at !== r.created_at
-        ? `${r.created_at} (updated ${r.updated_at})`
-        : r.created_at;
-    lines.push(
-      `- **${r.title || "(untitled)"}** [${r.kind}/${r.category}] — ${tagStr} — ${dateStr} — \`${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"));
-}