context-mcp-server 1.0.1

package/src/tools/fileTools.js

@@ -0,0 +1,185 @@
+import { readdirSync, statSync, readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, openSync, writeSync, fsyncSync, closeSync, renameSync } from 'node:fs';
+import { join as pathJoin, resolve as pathResolve, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { saveAutoContext } from '../hooks/autoContext.js';
+import { guardPath } from '../guard.js';
+
+// Atomic write: write to .tmp → fsync → rename
+// Guarantees the target is never left in a partial state if process dies mid-write
+function atomicWrite(filePath, data) {
+  const tmp = filePath + '.patch-' + randomUUID();
+  try {
+    const fd = openSync(tmp, 'w');
+    writeSync(fd, data, 0, 'utf8');
+    fsyncSync(fd);
+    closeSync(fd);
+    renameSync(tmp, filePath);
+  } catch (err) {
+    try { rmSync(tmp, { force: true }); } catch {}
+    throw err;
+  }
+}
+
+export const definitions = [
+  {
+    name: 'create_dir',
+    description: 'Create a directory (and any missing parent directories). Safe to call if already exists.',
+    inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+    outputSchema: { type: 'object', properties: { path: { type: 'string' }, existed: { type: 'boolean' }, message: { type: 'string' } } },
+  },
+  {
+    name: 'list_dir',
+    description: 'List the contents of a local directory.',
+    inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+    outputSchema: { type: 'object', properties: { directory: { type: 'string' }, items: { type: 'array' } } },
+  },
+  {
+    name: 'read_file',
+    description: 'Read the text contents of a local file.',
+    inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+    outputSchema: { type: 'object', properties: { file: { type: 'string' }, content: { type: 'string' } } },
+  },
+  {
+    name: 'write_file',
+    description: 'Create a new file or overwrite an existing file.',
+    inputSchema: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] },
+    outputSchema: { type: 'object', properties: { file: { type: 'string' }, message: { type: 'string' } } },
+  },
+  {
+    name: 'patch_file',
+    description:
+      `Apply targeted string replacement(s) to a file.\n` +
+      `Single edit: pass old_str + new_str.\n` +
+      `Multi edit:  pass edits:[{old_str, new_str, description?}] — atomic.\n` +
+      `Use dry_run:true to validate without writing.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path:    { type: 'string' },
+        old_str: { type: 'string' },
+        new_str: { type: 'string' },
+        edits:   { type: 'array', items: { type: 'object' } },
+        dry_run: { type: 'boolean' },
+        backup:  { type: 'boolean' },
+      },
+      required: ['path'],
+    },
+    outputSchema: { type: 'object' },
+  },
+  {
+    name: 'delete_file',
+    description: 'Delete a local file. Pass recursive:true to delete a directory and its contents.',
+    inputSchema: { type: 'object', properties: { path: { type: 'string' }, recursive: { type: 'boolean', description: 'Required to delete a directory. Defaults to false.' } }, required: ['path'] },
+    outputSchema: { type: 'object', properties: { path: { type: 'string' }, message: { type: 'string' } } },
+  },
+];
+
+export async function handle(name, args, state) {
+  switch (name) {
+    case 'create_dir': {
+      const dirPath = guardPath(args.path, state.projectRootPath);
+      const existed = existsSync(dirPath);
+      mkdirSync(dirPath, { recursive: true });
+      return { path: dirPath, existed, message: existed ? `Already exists: ${dirPath}` : `Created: ${dirPath}` };
+    }
+
+    case 'list_dir': {
+      const dirPath = guardPath(args.path || '.', state.projectRootPath);
+      const items = readdirSync(dirPath).map(name => {
+        const full = pathJoin(dirPath, name);
+        try { const s = statSync(full); return { name, type: s.isDirectory() ? 'dir' : 'file', size: s.size }; }
+        catch { return { name, type: 'unknown' }; }
+      }).sort((a, b) => a.type === b.type ? a.name.localeCompare(b.name) : a.type === 'dir' ? -1 : 1);
+      return { directory: dirPath, items };
+    }
+
+    case 'read_file': {
+      const filePath = guardPath(args.path, state.projectRootPath);
+      return { file: filePath, content: readFileSync(filePath, 'utf8') };
+    }
+
+    case 'write_file': {
+      const filePath = guardPath(args.path, state.projectRootPath);
+      mkdirSync(dirname(filePath), { recursive: true });
+      atomicWrite(filePath, args.content);
+      saveAutoContext({
+        title:   `wrote ${filePath.split(/[\\/]/).pop()}`,
+        content: `write_file: created/overwrote ${filePath}`,
+        type:    'code',
+        files:   [{ path: filePath, action: 'modified' }],
+        tags:    ['file-write'],
+        state,
+      });
+      return { file: filePath, message: `Successfully wrote: ${filePath}` };
+    }
+
+    case 'patch_file': {
+      const filePath = guardPath(args.path, state.projectRootPath);
+      if (!args.old_str && !args.edits?.length) throw new Error('old_str or edits[] required');
+
+      const raw     = readFileSync(filePath, 'utf8');
+      const hasCRLF = raw.includes('\r\n');
+      const original = hasCRLF ? raw.replace(/\r\n/g, '\n') : raw;
+
+      const editList = args.edits?.length
+        ? args.edits.map((e, i) => ({ old_str: e.old_str.replace(/\r\n/g, '\n'), new_str: (e.new_str ?? '').replace(/\r\n/g, '\n'), description: e.description || `edit ${i + 1}` }))
+        : [{ old_str: args.old_str.replace(/\r\n/g, '\n'), new_str: (args.new_str ?? '').replace(/\r\n/g, '\n'), description: 'edit 1' }];
+
+      const resolved = editList.map((edit, i) => {
+        const occ = original.split(edit.old_str).length - 1;
+        if (occ === 0) throw new Error(`patch_file edit ${i + 1}: old_str not found in ${filePath}`);
+        if (occ > 1)  throw new Error(`patch_file edit ${i + 1}: old_str matches ${occ} times — must match exactly once`);
+        const pos = original.indexOf(edit.old_str);
+        return { ...edit, pos, end: pos + edit.old_str.length, index: i + 1 };
+      });
+
+      const sorted = [...resolved].sort((a, b) => a.pos - b.pos);
+      for (let i = 0; i < sorted.length - 1; i++) {
+        if (sorted[i].end > sorted[i + 1].pos) throw new Error(`patch_file: edit ${sorted[i].index} and ${sorted[i + 1].index} overlap`);
+      }
+
+      if (args.dry_run) {
+        return { dry_run: true, file: filePath, edits: sorted.map(e => ({ index: e.index, description: e.description, match: true, position: e.pos })), message: `Dry run: all ${sorted.length} edit(s) matched.` };
+      }
+
+      if (args.backup) atomicWrite(filePath + '.bak', raw);
+
+      let patched = original;
+      for (const edit of [...sorted].reverse()) {
+        patched = patched.slice(0, edit.pos) + edit.new_str + patched.slice(edit.end);
+      }
+      if (hasCRLF) patched = patched.replace(/\n/g, '\r\n');
+      atomicWrite(filePath, patched);
+
+      const totalRemoved = sorted.reduce((s, e) => s + e.old_str.split('\n').length, 0);
+      const totalAdded   = sorted.reduce((s, e) => s + e.new_str.split('\n').length, 0);
+      saveAutoContext({
+        title:   `patched ${filePath.split(/[\\/]/).pop()}${sorted.length > 1 ? ` (${sorted.length} edits)` : ''}`,
+        content: `patch_file: ${sorted.length} edit(s) in ${filePath}\n` +
+                 sorted.map(e => `  ${e.description}: -${e.old_str.split('\n').length} +${e.new_str.split('\n').length} lines`).join('\n'),
+        type:    'code',
+        files:   [{ path: filePath, action: 'modified' }],
+        tags:    ['file-patch'],
+        state,
+      });
+      return { success: true, file: filePath, edits_applied: sorted.length,
+        edits: sorted.map(e => ({ index: e.index, description: e.description, lines_removed: e.old_str.split('\n').length, lines_added: e.new_str.split('\n').length })),
+        total_lines_removed: totalRemoved, total_lines_added: totalAdded,
+        message: `Patched ${filePath.split(/[\\/]/).pop()}: ${sorted.length} edit(s), -${totalRemoved} +${totalAdded} lines.`,
+      };
+    }
+
+    case 'delete_file': {
+      const filePath = guardPath(args.path, state.projectRootPath);
+      const isDir = existsSync(filePath) && statSync(filePath).isDirectory();
+      if (isDir && !args.recursive) {
+        throw new Error(`"${filePath}" is a directory. Pass recursive:true to delete it and its contents.`);
+      }
+      rmSync(filePath, { recursive: !!args.recursive });
+      return { path: filePath, message: `Deleted: ${filePath}` };
+    }
+
+    default:
+      throw new Error(`Unknown file tool: ${name}`);
+  }
+}

package/src/tools/gitTools.js

@@ -0,0 +1,259 @@
+import { execFileSync } from 'node:child_process';
+import { resolve as pathResolve } from 'node:path';
+import { saveAutoContext } from '../hooks/autoContext.js';
+import { guardPath } from '../guard.js';
+
+const MAX_DIFF_LENGTH = 10000;
+
+function runGit(argArr, cwd) {
+  const dir = cwd || process.cwd();
+  try {
+    return execFileSync('git', argArr, { cwd: dir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch (err) {
+    const msg = ((err.stderr || '') + (err.stdout || '') || err.message || '').trim();
+    throw new Error(`git ${argArr[0]} failed: ${msg}`);
+  }
+}
+
+function resolveCwd(args, state) {
+  const raw = args.cwd ? pathResolve(args.cwd) : process.cwd();
+  // If a project root is configured, validate cwd is within it
+  if (state.projectRootPath) return guardPath(raw, state.projectRootPath);
+  return raw;
+}
+
+export const definitions = [
+  {
+    name: 'git_status',
+    description: 'Show working tree status — current branch, staged, unstaged, and untracked files.',
+    inputSchema: { type: 'object', properties: { cwd: { type: 'string' } } },
+    outputSchema: { type: 'object', properties: { branch: { type: 'string' }, clean: { type: 'boolean' }, staged: { type: 'array' }, unstaged: { type: 'array' }, untracked: { type: 'array' } } },
+  },
+  {
+    name: 'git_diff',
+    description: 'Show file changes. Use staged:true for cached diff. Optionally scope to a path.',
+    inputSchema: { type: 'object', properties: { staged: { type: 'boolean' }, path: { type: 'string' }, cwd: { type: 'string' } } },
+    outputSchema: { type: 'object', properties: { diff: { type: 'string' }, staged: { type: 'boolean' } } },
+  },
+  {
+    name: 'git_log',
+    description: 'Show recent commit history — hash, author, date, message.',
+    inputSchema: { type: 'object', properties: { limit: { type: 'number' }, path: { type: 'string' }, cwd: { type: 'string' } } },
+    outputSchema: { type: 'object', properties: { commits: { type: 'array' }, count: { type: 'number' } } },
+  },
+  {
+    name: 'git_add',
+    description: 'Stage files for commit. Pass paths:["."] to stage everything.',
+    inputSchema: { type: 'object', properties: { paths: { type: 'array', items: { type: 'string' } }, cwd: { type: 'string' } }, required: ['paths'] },
+    outputSchema: { type: 'object', properties: { success: { type: 'boolean' }, staged: { type: 'array' }, message: { type: 'string' } } },
+  },
+  {
+    name: 'git_commit',
+    description: 'Commit staged changes. Set all:true to auto-stage tracked modified files first. Auto-saves context entry.',
+    inputSchema: { type: 'object', properties: { message: { type: 'string' }, all: { type: 'boolean' }, cwd: { type: 'string' } }, required: ['message'] },
+    outputSchema: { type: 'object', properties: { success: { type: 'boolean' }, hash: { type: 'string' }, branch: { type: 'string' }, message: { type: 'string' }, files: { type: 'array' } } },
+  },
+  {
+    name: 'git_push',
+    description: 'Push current branch to remote.',
+    inputSchema: { type: 'object', properties: { remote: { type: 'string' }, branch: { type: 'string' }, cwd: { type: 'string' } } },
+    outputSchema: { type: 'object', properties: { success: { type: 'boolean' }, remote: { type: 'string' }, branch: { type: 'string' }, output: { type: 'string' } } },
+  },
+  {
+    name: 'git_pull',
+    description: 'Pull from remote and merge into current branch.',
+    inputSchema: { type: 'object', properties: { remote: { type: 'string' }, branch: { type: 'string' }, cwd: { type: 'string' } } },
+    outputSchema: { type: 'object', properties: { success: { type: 'boolean' }, remote: { type: 'string' }, output: { type: 'string' } } },
+  },
+  {
+    name: 'git_branch',
+    description: 'List, create, or checkout branches.',
+    inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['list', 'create', 'checkout'] }, name: { type: 'string' }, cwd: { type: 'string' } } },
+  },
+  {
+    name: 'git_stash',
+    description: 'Stash or restore work-in-progress changes.',
+    inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['save', 'pop', 'list', 'drop'] }, message: { type: 'string' }, ref: { type: 'string' }, cwd: { type: 'string' } } },
+  },
+  {
+    name: 'git_reset',
+    description: 'Unstage files or reset HEAD. Use mode:file + path to restore a single file.',
+    inputSchema: { type: 'object', properties: { mode: { type: 'string', enum: ['soft', 'mixed', 'hard', 'file'] }, path: { type: 'string' }, ref: { type: 'string' }, cwd: { type: 'string' } } },
+  },
+  {
+    name: 'git_show',
+    description: 'Show full diff and metadata for a specific commit.',
+    inputSchema: { type: 'object', properties: { ref: { type: 'string' }, cwd: { type: 'string' } } },
+  },
+];
+
+export async function handle(name, args, state) {
+  switch (name) {
+    case 'git_status': {
+      const cwd      = resolveCwd(args, state);
+      const porcelain = runGit(['status', '--porcelain'], cwd);
+      const branch   = runGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+      const lines    = porcelain ? porcelain.split('\n').filter(Boolean) : [];
+      return {
+        branch,
+        clean:     lines.length === 0,
+        staged:    lines.filter(l => l[0] !== ' ' && l[0] !== '?').map(l => l.slice(3)),
+        unstaged:  lines.filter(l => l[1] === 'M' || l[1] === 'D').map(l => l.slice(3)),
+        untracked: lines.filter(l => l.startsWith('??')).map(l => l.slice(3)),
+      };
+    }
+
+    case 'git_diff': {
+      const cwd  = resolveCwd(args, state);
+      const argv = ['diff'];
+      if (args.staged) argv.push('--cached');
+      if (args.path) { argv.push('--'); argv.push(guardPath(args.path, state.projectRootPath || cwd)); }
+      let diff = runGit(argv, cwd);
+      if (diff.length > MAX_DIFF_LENGTH) diff = diff.slice(0, MAX_DIFF_LENGTH) + '\n…(truncated)';
+      return { diff: diff || '(no changes)', staged: !!args.staged };
+    }
+
+    case 'git_log': {
+      const cwd   = resolveCwd(args, state);
+      const limit = Math.min(Math.max(1, parseInt(args.limit) || 10), 200);
+      const argv  = ['log', '--pretty=format:%H\t%an\t%ad\t%s', '--date=short', `-n${limit}`];
+      if (args.path) { argv.push('--'); argv.push(guardPath(args.path, state.projectRootPath || cwd)); }
+      const raw   = runGit(argv, cwd);
+      const commits = raw
+        ? raw.split('\n').filter(Boolean).map(line => {
+            const [hash, author, date, ...msg] = line.split('\t');
+            return { hash: hash.slice(0, 8), author, date, message: msg.join('\t') };
+          })
+        : [];
+      return { commits, count: commits.length };
+    }
+
+    case 'git_add': {
+      const cwd   = resolveCwd(args, state);
+      const paths = Array.isArray(args.paths) ? args.paths : [args.paths || '.'];
+      const resolvedPaths = paths.map(p => state.projectRootPath ? guardPath(p, state.projectRootPath) : pathResolve(p));
+      runGit(['add', '--', ...resolvedPaths], cwd);
+      const status = runGit(['status', '--porcelain'], cwd);
+      const staged = status
+        ? status.split('\n').filter(l => l[0] !== ' ' && l[0] !== '?' && l.trim()).map(l => l.slice(3))
+        : [];
+      return { success: true, staged, message: `Staged: ${paths.join(', ')}` };
+    }
+
+    case 'git_commit': {
+      if (!args.message) throw new Error('message is required for git_commit');
+      const cwd = resolveCwd(args, state);
+
+      const nameStatus = runGit(['diff', '--cached', '--name-status'], cwd);
+      const stagedFiles = nameStatus
+        ? nameStatus.split('\n').filter(Boolean).map(l => {
+            const [s, ...parts] = l.split('\t');
+            return { path: parts.join('\t'), action: s === 'A' ? 'created' : s === 'D' ? 'deleted' : 'modified' };
+          })
+        : [];
+
+      if (args.all) runGit(['add', '-u'], cwd);
+
+      runGit(['commit', '-m', args.message], cwd);
+
+      const hash   = runGit(['rev-parse', '--short', 'HEAD'], cwd);
+      const branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+
+      saveAutoContext({
+        title:   `git commit: ${args.message.slice(0, 57)}${args.message.length > 57 ? '...' : ''}`,
+        content: `hash: ${hash} | branch: ${branch}\nmessage: ${args.message}\nfiles: ${stagedFiles.map(f => f.path).join(', ')}`,
+        type:    'decision',
+        files:   stagedFiles,
+        tags:    ['git', 'commit', branch],
+        state,
+      });
+
+      return { success: true, hash, branch, message: args.message, files: stagedFiles };
+    }
+
+    case 'git_push': {
+      const cwd    = resolveCwd(args, state);
+      const remote = args.remote || 'origin';
+      const branch = args.branch || runGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+      const output = runGit(['push', remote, branch], cwd);
+      return { success: true, remote, branch, output: output || 'Pushed successfully.' };
+    }
+
+    case 'git_pull': {
+      const cwd    = resolveCwd(args, state);
+      const remote = args.remote || 'origin';
+      const argv   = ['pull', remote];
+      if (args.branch) argv.push(args.branch);
+      const output = runGit(argv, cwd);
+      return { success: true, remote, output: output || 'Already up to date.' };
+    }
+
+    case 'git_branch': {
+      const cwd    = resolveCwd(args, state);
+      const action = args.action || 'list';
+      if (action === 'list') {
+        const raw      = runGit(['branch', '-a'], cwd);
+        const branches = raw ? raw.split('\n').map(b => b.trim()).filter(Boolean) : [];
+        const current  = branches.find(b => b.startsWith('* '))?.slice(2) || '';
+        return { branches: branches.map(b => b.replace(/^\* /, '')), current };
+      } else if (action === 'create') {
+        if (!args.name) throw new Error('name is required for branch create');
+        runGit(['checkout', '-b', args.name], cwd);
+        return { success: true, branch: args.name, message: `Created and switched to "${args.name}"` };
+      } else if (action === 'checkout') {
+        if (!args.name) throw new Error('name is required for branch checkout');
+        runGit(['checkout', args.name], cwd);
+        return { success: true, branch: args.name, message: `Switched to "${args.name}"` };
+      }
+      throw new Error(`Unknown branch action: ${action}. Use: list, create, checkout`);
+    }
+
+    case 'git_stash': {
+      const cwd    = resolveCwd(args, state);
+      const action = args.action || 'save';
+      if (action === 'save') {
+        const argv = ['stash', 'push'];
+        if (args.message) { argv.push('-m'); argv.push(args.message); }
+        runGit(argv, cwd);
+        return { success: true, message: `Stashed changes${args.message ? `: ${args.message}` : '.'}` };
+      } else if (action === 'pop') {
+        const out = runGit(['stash', 'pop'], cwd);
+        return { success: true, output: out };
+      } else if (action === 'list') {
+        const raw = runGit(['stash', 'list'], cwd);
+        return { stashes: raw ? raw.split('\n').filter(Boolean) : [] };
+      } else if (action === 'drop') {
+        const ref = args.ref || 'stash@{0}';
+        runGit(['stash', 'drop', ref], cwd);
+        return { success: true, message: `Dropped ${ref}` };
+      }
+      throw new Error(`Unknown stash action: ${action}. Use: save, pop, list, drop`);
+    }
+
+    case 'git_reset': {
+      const cwd  = resolveCwd(args, state);
+      const mode = args.mode || 'mixed';
+      if (mode === 'file') {
+        if (!args.path) throw new Error('path is required for file mode reset');
+        const filePath = state.projectRootPath ? guardPath(args.path, state.projectRootPath) : pathResolve(args.path);
+        runGit(['checkout', '--', filePath], cwd);
+        return { success: true, message: `Restored "${args.path}" to last committed state.` };
+      }
+      const ref = args.ref || 'HEAD';
+      runGit(['reset', `--${mode}`, ref], cwd);
+      return { success: true, mode, ref, message: `Reset --${mode} to ${ref}` };
+    }
+
+    case 'git_show': {
+      const cwd = resolveCwd(args, state);
+      const ref = args.ref || 'HEAD';
+      const info = runGit(['show', '--stat', '--format=%H%n%an%n%ad%n%s', ref], cwd);
+      let diff = runGit(['show', ref], cwd);
+      if (diff.length > MAX_DIFF_LENGTH) diff = diff.slice(0, MAX_DIFF_LENGTH) + '\n…(truncated)';
+      return { ref, info, diff };
+    }
+
+    default:
+      throw new Error(`Unknown git tool: ${name}`);
+  }
+}

package/src/tools/search.js

@@ -0,0 +1,55 @@
+import { search as unifiedSearch } from '../search.js';
+
+export const definition = {
+  name: 'search',
+  description:
+    `Search across all saved context. Three modes:\n` +
+    `• "semantic" (default) — TF-IDF similarity. Best for natural language queries.\n` +
+    `• "keyword" — Exact keyword matching. Best for specific terms.\n` +
+    `• "related" — Find entries similar to a given entry ID.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query:   { type: 'string' },
+      mode:    { type: 'string', enum: ['keyword', 'semantic', 'related'] },
+      project: { type: 'string' },
+      limit:   { type: 'number' },
+      id:      { type: 'string', description: '[related mode] entry ID' },
+    },
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      matches: { type: 'array' },
+      count:   { type: 'number' },
+      mode:    { type: 'string' },
+      message: { type: 'string' },
+      source:  { type: 'string' },
+      related: { type: 'array' },
+    },
+  },
+};
+
+export async function handle(args, _state) {
+  const mode  = args.mode || 'semantic';
+  const limit = args.limit || (mode === 'related' ? 5 : 10);
+
+  if (mode === 'related') {
+    const { target, results } = unifiedSearch({ mode, id: args.id, limit });
+    return { source: target.title, related: results, count: results.length, mode };
+  }
+
+  const raw = unifiedSearch({ mode, query: args.query, project: args.project, limit });
+  const matches = raw.map(e => ({
+    id: e.id, project: e.project, title: e.title || '',
+    tags: e.tags, createdAt: e.createdAt,
+    similarity: e.similarity,
+    preview: (e.content || '').slice(0, 200),
+  }));
+  return {
+    matches, count: matches.length, mode,
+    message: matches.length
+      ? `${matches.length} ${mode} result(s) for "${args.query}".`
+      : `No results for "${args.query}".`,
+  };
+}

package/src/vector.js

@@ -0,0 +1,153 @@
+/**
+ * vector.js — TF-IDF cosine similarity search (cached)
+ *
+ * Optimizations:
+ *   1. IDF cache — reuses computed IDF when the corpus hasn't changed
+ *   2. Pre-computed corpus strings — avoids re-concatenating on every search
+ *   3. Early exit — skips entries with zero query term overlap
+ *   4. Sparse dot product — only iterates non-zero dimensions
+ */
+
+import { getGeneration } from './db.js';
+
+// ── Text utilities ────────────────────────────────────────────────────────────
+
+const STOP_WORDS = new Set([
+  'a','an','the','and','or','but','in','on','at','to','for','of','with',
+  'by','from','is','it','its','as','be','was','are','were','this','that',
+  'i','we','you','he','she','they','have','has','had','do','did','will',
+  'would','could','should','not','no','so','if','then','than','just','my',
+]);
+
+function stemLight(w) {
+  return w
+    .replace(/ication$/, 'ic').replace(/ations?$/, 'ate').replace(/ments?$/, '')
+    .replace(/ings?$/, '').replace(/tion$/, 't').replace(/ness$/, '')
+    .replace(/ity$/, '').replace(/ies$/, 'y').replace(/s$/, '');
+}
+
+function tokenize(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s_-]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 2 && !STOP_WORDS.has(w))
+    .map(stemLight);
+}
+
+function termFreq(tokens) {
+  const tf = {};
+  for (const t of tokens) tf[t] = (tf[t] || 0) + 1;
+  // FIX: avoid Math.max(...array) spread which can hit the JS argument limit
+  // on very large texts. Use a reduce loop instead.
+  let max = 1;
+  for (const v of Object.values(tf)) if (v > max) max = v;
+  for (const t in tf) tf[t] /= max;
+  return tf;
+}
+
+// ── IDF cache ─────────────────────────────────────────────────────────────────
+
+let _idfCache = null;
+let _idfGeneration = -1;
+let _idfCorpusLen = -1;
+
+function buildIDF(docs) {
+  const df = {};
+  for (const doc of docs) {
+    const seen = new Set(tokenize(doc));
+    for (const t of seen) df[t] = (df[t] || 0) + 1;
+  }
+  const N = docs.length || 1;
+  const idf = {};
+  for (const t in df) idf[t] = Math.log((N + 1) / (df[t] + 1)) + 1;
+  return idf;
+}
+
+function getCachedIDF(corpus) {
+  const gen = getGeneration();
+  // Cache hit: same generation (no mutations) and same corpus size
+  if (_idfCache && _idfGeneration === gen && _idfCorpusLen === corpus.length) {
+    return _idfCache;
+  }
+  _idfCache = buildIDF(corpus);
+  _idfGeneration = gen;
+  _idfCorpusLen = corpus.length;
+  return _idfCache;
+}
+
+// ── TF-IDF vector ─────────────────────────────────────────────────────────────
+
+function tfidfVector(text, idf) {
+  const tokens = tokenize(text);
+  const tf = termFreq(tokens);
+  const vec = {};
+  for (const t in tf) vec[t] = tf[t] * (idf[t] || Math.log(2));
+  return vec;
+}
+
+// ── Cosine similarity (sparse) ────────────────────────────────────────────────
+
+function cosine(a, b) {
+  let dot = 0, magA = 0, magB = 0;
+  for (const t in a) {
+    magA += a[t] ** 2;
+    if (t in b) dot += a[t] * b[t];
+  }
+  for (const t in b) magB += b[t] ** 2;
+  if (!magA || !magB) return 0;
+  return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+}
+
+// ── Quick overlap check (skip zero-similarity entries early) ──────────────────
+
+function hasOverlap(queryTokens, text) {
+  const tokens = new Set(tokenize(text));
+  return queryTokens.some(t => tokens.has(t));
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Rank entries by semantic similarity to query.
+ * Returns compact results by default (preview, not full content).
+ */
+export function vectorSearch(query, entries, limit = 10) {
+  if (!entries.length) return [];
+
+  const queryTokens = tokenize(query);
+  if (!queryTokens.length) return [];
+
+  // Build corpus strings (once per call)
+  const corpus = entries.map(e => {
+    const tags = Array.isArray(e.tags) ? e.tags : [];
+    return `${e.title || ''} ${e.content || ''} ${tags.join(' ')}`;
+  });
+
+  // Use cached IDF when corpus hasn't changed
+  const idf = getCachedIDF(corpus);
+  const queryVec = tfidfVector(query, idf);
+
+  const scored = [];
+  for (let i = 0; i < entries.length; i++) {
+    // Early exit: skip entries with zero token overlap
+    if (!hasOverlap(queryTokens, corpus[i])) continue;
+
+    const sim = cosine(queryVec, tfidfVector(corpus[i], idf));
+    if (sim > 0) {
+      scored.push({ ...entries[i], similarity: Math.round(sim * 100) / 100 });
+    }
+  }
+
+  scored.sort((a, b) => b.similarity - a.similarity);
+  return scored.slice(0, limit);
+}
+
+/**
+ * Find entries similar to a given entry.
+ */
+export function findRelated(targetEntry, allEntries, limit = 5) {
+  const others = allEntries.filter(e => e.id !== targetEntry.id);
+  const query = `${targetEntry.title || ''} ${targetEntry.content || ''}`;
+  return vectorSearch(query, others, limit);
+}