context-vault 3.1.6 → 3.1.8

package/src/tools/{session-start.js → session-start.ts}

@@ -1,45 +1,44 @@
-import { z } from "zod";
-import { execSync } from "node:child_process";
-import { ok, err, ensureVaultExists } from "../helpers.js";
+import { z } from 'zod';
+import { execSync } from 'node:child_process';
+import { ok, err, ensureVaultExists } from '../helpers.js';
+import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
 
 const DEFAULT_MAX_TOKENS = 4000;
 const RECENT_DAYS = 7;
 const MAX_BODY_PER_ENTRY = 400;
-const PRIORITY_KINDS = ["decision", "insight", "pattern"];
-const SESSION_SUMMARY_KIND = "session";
+const PRIORITY_KINDS = ['decision', 'insight', 'pattern'];
+const SESSION_SUMMARY_KIND = 'session';
 
-export const name = "session_start";
+export const name = 'session_start';
 
 export const description =
-  "Auto-assemble a context brief for the current project on session start. Pulls recent entries, last session summary, and active decisions/blockers into a token-budgeted capsule formatted for agent consumption.";
+  'Auto-assemble a context brief for the current project on session start. Pulls recent entries, last session summary, and active decisions/blockers into a token-budgeted capsule formatted for agent consumption.';
 
 export const inputSchema = {
   project: z
     .string()
     .optional()
     .describe(
-      "Project name or tag to scope the brief. Auto-detected from cwd/git remote if not provided.",
+      'Project name or tag to scope the brief. Auto-detected from cwd/git remote if not provided.'
     ),
   max_tokens: z
     .number()
     .optional()
-    .describe(
-      "Token budget for the capsule (rough estimate: 1 token ~ 4 chars). Default: 4000.",
-    ),
+    .describe('Token budget for the capsule (rough estimate: 1 token ~ 4 chars). Default: 4000.'),
   buckets: z
     .array(z.string())
     .optional()
     .describe(
-      "Bucket names to scope the session brief. Each name expands to a 'bucket:<name>' tag filter. When provided, the brief only includes entries from these buckets.",
+      "Bucket names to scope the session brief. Each name expands to a 'bucket:<name>' tag filter. When provided, the brief only includes entries from these buckets."
     ),
 };
 
 function detectProject() {
   try {
-    const remote = execSync("git remote get-url origin 2>/dev/null", {
-      encoding: "utf-8",
+    const remote = execSync('git remote get-url origin 2>/dev/null', {
+      encoding: 'utf-8',
       timeout: 3000,
-      stdio: ["pipe", "pipe", "pipe"],
+      stdio: ['pipe', 'pipe', 'pipe'],
     }).trim();
     if (remote) {
       const match = remote.match(/\/([^/]+?)(?:\.git)?$/);
@@ -56,32 +55,32 @@ function detectProject() {
   return null;
 }
 
-function truncateBody(body, maxLen = MAX_BODY_PER_ENTRY) {
-  if (!body) return "(no body)";
+function truncateBody(body: string | null | undefined, maxLen = MAX_BODY_PER_ENTRY): string {
+  if (!body) return '(no body)';
   if (body.length <= maxLen) return body;
-  return body.slice(0, maxLen) + "...";
+  return body.slice(0, maxLen) + '...';
 }
 
-function estimateTokens(text) {
-  return Math.ceil((text || "").length / 4);
+function estimateTokens(text: string | null | undefined): number {
+  return Math.ceil((text || '').length / 4);
 }
 
-function formatEntry(entry) {
+function formatEntry(entry: any): string {
   const tags = entry.tags ? JSON.parse(entry.tags) : [];
-  const tagStr = tags.length ? tags.join(", ") : "none";
-  const date = entry.updated_at || entry.created_at || "unknown";
+  const tagStr = tags.length ? tags.join(', ') : 'none';
+  const date = entry.updated_at || entry.created_at || 'unknown';
   return [
-    `- **${entry.title || "(untitled)"}** [${entry.kind}]`,
+    `- **${entry.title || '(untitled)'}** [${entry.kind}]`,
     `  tags: ${tagStr} | ${date} | id: \`${entry.id}\``,
-    `  ${truncateBody(entry.body).replace(/\n+/g, " ").trim()}`,
-  ].join("\n");
+    `  ${truncateBody(entry.body).replace(/\n+/g, ' ').trim()}`,
+  ].join('\n');
 }
 
 export async function handler(
-  { project, max_tokens, buckets },
-  ctx,
-  { ensureIndexed },
-) {
+  { project, max_tokens, buckets }: Record<string, any>,
+  ctx: LocalCtx,
+  { ensureIndexed }: SharedCtx
+): Promise<ToolResult> {
   const { config } = ctx;
 
   const vaultErr = ensureVaultExists(config);
@@ -92,36 +91,26 @@ export async function handler(
   const effectiveProject = project?.trim() || detectProject();
   const tokenBudget = max_tokens || DEFAULT_MAX_TOKENS;
 
-  const bucketTags = buckets?.length ? buckets.map((b) => `bucket:${b}`) : [];
-  const effectiveTags = bucketTags.length
-    ? bucketTags
-    : effectiveProject
-      ? [effectiveProject]
-      : [];
+  const bucketTags = buckets?.length ? buckets.map((b: string) => `bucket:${b}`) : [];
+  const effectiveTags = bucketTags.length ? bucketTags : effectiveProject ? [effectiveProject] : [];
 
   const sinceDate = new Date(Date.now() - RECENT_DAYS * 86400000).toISOString();
 
   const sections = [];
   let tokensUsed = 0;
 
+  sections.push(`# Session Brief${effectiveProject ? ` — ${effectiveProject}` : ''}`);
+  const bucketsLabel = buckets?.length ? ` | buckets: ${buckets.join(', ')}` : '';
   sections.push(
-    `# Session Brief${effectiveProject ? ` — ${effectiveProject}` : ""}`,
-  );
-  const bucketsLabel = buckets?.length
-    ? ` | buckets: ${buckets.join(", ")}`
-    : "";
-  sections.push(
-    `_Generated ${new Date().toISOString().slice(0, 10)} | budget: ${tokenBudget} tokens${bucketsLabel}_\n`,
+    `_Generated ${new Date().toISOString().slice(0, 10)} | budget: ${tokenBudget} tokens${bucketsLabel}_\n`
   );
-  tokensUsed += estimateTokens(sections.join("\n"));
+  tokensUsed += estimateTokens(sections.join('\n'));
 
   const lastSession = queryLastSession(ctx, effectiveTags);
   if (lastSession) {
-    const sessionBlock = [
-      "## Last Session Summary",
-      truncateBody(lastSession.body, 600),
-      "",
-    ].join("\n");
+    const sessionBlock = ['## Last Session Summary', truncateBody(lastSession.body, 600), ''].join(
+      '\n'
+    );
     const sessionTokens = estimateTokens(sessionBlock);
     if (tokensUsed + sessionTokens <= tokenBudget) {
       sections.push(sessionBlock);
@@ -134,10 +123,10 @@ export async function handler(
     PRIORITY_KINDS,
     sinceDate,
 
-    effectiveTags,
+    effectiveTags
   );
   if (decisions.length > 0) {
-    const header = "## Active Decisions, Insights & Patterns\n";
+    const header = '## Active Decisions, Insights & Patterns\n';
     const headerTokens = estimateTokens(header);
     if (tokensUsed + headerTokens <= tokenBudget) {
       const entryLines = [];
@@ -150,15 +139,15 @@ export async function handler(
         tokensUsed += lineTokens;
       }
       if (entryLines.length > 0) {
-        sections.push(header + entryLines.join("\n") + "\n");
+        sections.push(header + entryLines.join('\n') + '\n');
       }
     }
   }
 
   const recent = queryRecent(ctx, sinceDate, effectiveTags);
-  const seenIds = new Set(decisions.map((d) => d.id));
+  const seenIds = new Set(decisions.map((d: any) => d.id));
   if (lastSession) seenIds.add(lastSession.id);
-  const deduped = recent.filter((r) => !seenIds.has(r.id));
+  const deduped = recent.filter((r: any) => !seenIds.has(r.id));
 
   if (deduped.length > 0) {
     const header = `## Recent Entries (last ${RECENT_DAYS} days)\n`;
@@ -174,7 +163,7 @@ export async function handler(
         tokensUsed += lineTokens;
       }
       if (entryLines.length > 0) {
-        sections.push(header + entryLines.join("\n") + "\n");
+        sections.push(header + entryLines.join('\n') + '\n');
       }
     }
   }
@@ -182,17 +171,16 @@ export async function handler(
   const totalEntries =
     (lastSession ? 1 : 0) +
     decisions.length +
-    deduped.filter((d) => {
-      const line = formatEntry(d);
+    deduped.filter((_d: any) => {
       return true;
     }).length;
 
-  sections.push("---");
+  sections.push('---');
   sections.push(
-    `_${tokensUsed} / ${tokenBudget} tokens used | project: ${effectiveProject || "unscoped"}_`,
+    `_${tokensUsed} / ${tokenBudget} tokens used | project: ${effectiveProject || 'unscoped'}_`
   );
 
-  const result = ok(sections.join("\n"));
+  const result: ToolResult = ok(sections.join('\n'));
   result._meta = {
     project: effectiveProject || null,
     buckets: buckets || null,
@@ -207,76 +195,81 @@ export async function handler(
   return result;
 }
 
-function queryLastSession(ctx, effectiveTags) {
+function queryLastSession(ctx: LocalCtx, effectiveTags: string[]): any {
   const clauses = [`kind = '${SESSION_SUMMARY_KIND}'`];
-  const params = [];
+  const params: any[] = [];
 
   if (false) {
   }
   clauses.push("(expires_at IS NULL OR expires_at > datetime('now'))");
-  clauses.push("superseded_by IS NULL");
+  clauses.push('superseded_by IS NULL');
 
-  const where = `WHERE ${clauses.join(" AND ")}`;
+  const where = `WHERE ${clauses.join(' AND ')}`;
   const rows = ctx.db
     .prepare(`SELECT * FROM vault ${where} ORDER BY created_at DESC LIMIT 5`)
     .all(...params);
 
   if (effectiveTags.length) {
-    const match = rows.find((r) => {
+    const match = rows.find((r: any) => {
       const tags = r.tags ? JSON.parse(r.tags) : [];
-      return effectiveTags.some((t) => tags.includes(t));
+      return effectiveTags.some((t: string) => tags.includes(t));
     });
     if (match) return match;
   }
   return rows[0] || null;
 }
 
-function queryByKinds(ctx, kinds, since, effectiveTags) {
-  const kindPlaceholders = kinds.map(() => "?").join(",");
+function queryByKinds(
+  ctx: LocalCtx,
+  kinds: string[],
+  since: string,
+  effectiveTags: string[]
+): any[] {
+  const kindPlaceholders = kinds.map(() => '?').join(',');
   const clauses = [`kind IN (${kindPlaceholders})`];
   const params = [...kinds];
 
-  clauses.push("created_at >= ?");
+  clauses.push('created_at >= ?');
   params.push(since);
 
   if (false) {
   }
   clauses.push("(expires_at IS NULL OR expires_at > datetime('now'))");
-  clauses.push("superseded_by IS NULL");
+  clauses.push('superseded_by IS NULL');
 
-  const where = `WHERE ${clauses.join(" AND ")}`;
+  const where = `WHERE ${clauses.join(' AND ')}`;
   const rows = ctx.db
     .prepare(`SELECT * FROM vault ${where} ORDER BY created_at DESC LIMIT 50`)
     .all(...params);
 
   if (effectiveTags.length) {
-    const tagged = rows.filter((r) => {
+    const tagged = rows.filter((r: any) => {
       const tags = r.tags ? JSON.parse(r.tags) : [];
-      return effectiveTags.some((t) => tags.includes(t));
+      return effectiveTags.some((t: string) => tags.includes(t));
     });
     if (tagged.length > 0) return tagged;
   }
   return rows;
 }
 
-function queryRecent(ctx, since, effectiveTags) {
-  const clauses = ["created_at >= ?"];
+function queryRecent(ctx: LocalCtx, since: string, effectiveTags: string[]): any[] {
+  const clauses = ['created_at >= ?'];
   const params = [since];
 
   if (false) {
   }
   clauses.push("(expires_at IS NULL OR expires_at > datetime('now'))");
-  clauses.push("superseded_by IS NULL");
+  clauses.push('superseded_by IS NULL');
 
-  const where = `WHERE ${clauses.join(" AND ")}`;
+  const where = `WHERE ${clauses.join(' AND ')}`;
   const rows = ctx.db
     .prepare(`SELECT * FROM vault ${where} ORDER BY created_at DESC LIMIT 50`)
     .all(...params);
 
   if (effectiveTags.length) {
-    const tagged = rows.filter((r) => {
+    const tagged = rows.filter((r: any) => {
       const tags = r.tags ? JSON.parse(r.tags) : [];
-      return effectiveTags.some((t) => tags.includes(t));
+      return effectiveTags.some((t: string) => tags.includes(t));
     });
     if (tagged.length > 0) return tagged;
   }

package/src/types.ts

@@ -0,0 +1,29 @@
+import type { BaseCtx, VaultConfig } from '@context-vault/core/types';
+
+export interface LocalCtx extends BaseCtx {
+  activeOps: { count: number };
+  toolStats: {
+    ok: number;
+    errors: number;
+    lastError: { tool: string; code: string; timestamp: number } | null;
+  };
+}
+
+export interface SharedCtx {
+  ensureIndexed: (opts?: { blocking?: boolean }) => Promise<void>;
+  reindexFailed?: boolean;
+}
+
+export interface ToolResult {
+  content: Array<{ type: string; text: string }>;
+  isError?: boolean;
+  code?: string;
+  _meta?: Record<string, unknown>;
+}
+
+export interface ToolModule {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: (args: Record<string, unknown>, ctx: LocalCtx, shared: SharedCtx) => Promise<ToolResult>;
+}

package/src/helpers.js

@@ -1,57 +0,0 @@
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(
-  readFileSync(join(__dirname, "..", "package.json"), "utf-8"),
-);
-
-export function ok(text) {
-  return { content: [{ type: "text", text }] };
-}
-
-export function err(text, code = "UNKNOWN", meta = {}) {
-  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, code, hint) {
-  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) {
-  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) {
-  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/register-tools.js

@@ -1,175 +0,0 @@
-import { reindex } from "@context-vault/core/index";
-import { captureAndIndex } from "@context-vault/core/capture";
-import { err } from "./helpers.js";
-import { sendTelemetryEvent } from "./telemetry.js";
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(
-  readFileSync(join(__dirname, "..", "package.json"), "utf-8"),
-);
-
-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 ingestUrl from "./tools/ingest-url.js";
-import * as contextStatus from "./tools/context-status.js";
-import * as clearContext from "./tools/clear-context.js";
-import * as createSnapshot from "./tools/create-snapshot.js";
-import * as sessionStart from "./tools/session-start.js";
-import * as listBuckets from "./tools/list-buckets.js";
-import * as ingestProject from "./tools/ingest-project.js";
-
-const toolModules = [
-  getContext,
-  saveContext,
-  listContext,
-  deleteContext,
-  ingestUrl,
-  ingestProject,
-  contextStatus,
-  clearContext,
-  createSnapshot,
-  sessionStart,
-  listBuckets,
-];
-
-const TOOL_TIMEOUT_MS = 60_000;
-
-export function registerTools(server, ctx) {
-  function tracked(handler, toolName) {
-    return async (...args) => {
-      if (ctx.activeOps) ctx.activeOps.count++;
-      let timer;
-      let handlerPromise;
-      try {
-        handlerPromise = Promise.resolve(handler(...args));
-        const result = await Promise.race([
-          handlerPromise,
-          new Promise((_, reject) => {
-            timer = setTimeout(
-              () => reject(new Error("TOOL_TIMEOUT")),
-              TOOL_TIMEOUT_MS,
-            );
-          }),
-        ]);
-        if (ctx.toolStats) ctx.toolStats.ok++;
-        return result;
-      } catch (e) {
-        if (e.message === "TOOL_TIMEOUT") {
-          handlerPromise?.catch(() => {});
-          if (ctx.toolStats) {
-            ctx.toolStats.errors++;
-            ctx.toolStats.lastError = {
-              tool: toolName,
-              code: "TIMEOUT",
-              timestamp: Date.now(),
-            };
-          }
-          sendTelemetryEvent(ctx.config, {
-            event: "tool_error",
-            code: "TIMEOUT",
-            tool: toolName,
-            cv_version: pkg.version,
-          });
-          return err(
-            "Tool timed out after 60s. Try a simpler query or run `context-vault reindex` first.",
-            "TIMEOUT",
-          );
-        }
-        if (ctx.toolStats) {
-          ctx.toolStats.errors++;
-          ctx.toolStats.lastError = {
-            tool: toolName,
-            code: "UNKNOWN",
-            timestamp: Date.now(),
-          };
-        }
-        sendTelemetryEvent(ctx.config, {
-          event: "tool_error",
-          code: "UNKNOWN",
-          tool: toolName,
-          cv_version: pkg.version,
-        });
-        try {
-          await captureAndIndex(ctx, {
-            kind: "feedback",
-            title: `Unhandled error in ${toolName ?? "tool"} call`,
-            body: `${e.message}\n\n${e.stack ?? ""}`,
-            tags: ["bug", "auto-captured"],
-            source: "auto-capture",
-            meta: {
-              tool: toolName,
-              error_type: e.constructor?.name,
-              cv_version: pkg.version,
-              auto: true,
-            },
-          });
-        } catch {}
-        return err(e.message, "INTERNAL_ERROR");
-      } finally {
-        clearTimeout(timer);
-        if (ctx.activeOps) ctx.activeOps.count--;
-      }
-    };
-  }
-
-  let reindexDone = 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;
-    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;
-        }
-      });
-    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), mod.name),
-    );
-  }
-
-  ensureIndexed().catch(() => {});
-}

package/src/telemetry.js

@@ -1,80 +0,0 @@
-import { existsSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import {
-  API_URL,
-  MARKETING_URL,
-  GITHUB_ISSUES_URL,
-} from "@context-vault/core/constants";
-
-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;
-}
-
-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(() => {});
-}
-
-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");
-  }
-}
-
-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");
-  }
-}