@dotdotgod/context 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/context",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Local-first MCP execution, indexing, and retrieval runtime for dotdotgod adapters.",
   "type": "module",
   "license": "Elastic-2.0",
@@ -28,7 +28,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
     "zod": "^3.25.76",
-    "@dotdotgod/cli": "0.3.1"
+    "@dotdotgod/cli": "0.3.3"
   },
   "engines": {
     "node": ">=22.5.0"

package/src/hooks.mjs

@@ -1,15 +1,39 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, parse, resolve } from 'node:path';
 
 function inputText() { return readFileSync(0, 'utf8'); }
 function parseInput() { const text = inputText().trim(); return text ? JSON.parse(text) : {}; }
-function projectRoot(input) { return resolve(input.cwd || input.project_dir || process.env.CLAUDE_PROJECT_DIR || process.cwd()); }
 function sessionId(input) { return String(input.session_id || input.sessionId || 'default').replace(/[^a-zA-Z0-9._-]/g, '_'); }
-function statePath(input) { return join(projectRoot(input), '.dotdotgod', 'context', 'runtime', `${sessionId(input)}.json`); }
-function readState(input) { try { return JSON.parse(readFileSync(statePath(input), 'utf8')); } catch { return { loadRequired: false, pending: {} }; } }
-function writeState(input, state) {
-  const path = statePath(input); mkdirSync(dirname(path), { recursive: true });
+function runtimeStatePath(root, id) { return join(root, '.dotdotgod', 'context', 'runtime', `${id}.json`); }
+function declaredProjectRoot(input) {
+  const value = input.project_dir || process.env.CLAUDE_PROJECT_DIR;
+  return typeof value === 'string' && value.trim() ? resolve(value) : null;
+}
+function findExistingStateRoot(cwd, id) {
+  let current = resolve(cwd);
+  const filesystemRoot = parse(current).root;
+  while (true) {
+    if (existsSync(runtimeStatePath(current, id))) return current;
+    if (current === filesystemRoot) return null;
+    current = dirname(current);
+  }
+}
+function resolveHookContext(input, event) {
+  const id = sessionId(input);
+  const declared = declaredProjectRoot(input);
+  if (declared) return { root: declared, path: runtimeStatePath(declared, id) };
+  if (typeof input.cwd !== 'string' || !input.cwd.trim()) return null;
+  const existing = findExistingStateRoot(input.cwd, id);
+  if (existing) return { root: existing, path: runtimeStatePath(existing, id) };
+  if (event !== 'sessionstart') return null;
+  const root = resolve(input.cwd);
+  return { root, path: runtimeStatePath(root, id) };
+}
+function readState(path) { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return { loadRequired: false, pending: {} }; } }
+function writeState(path, state) {
+  if (!path) return;
+  mkdirSync(dirname(path), { recursive: true });
   const temp = `${path}.${process.pid}.tmp`; writeFileSync(temp, `${JSON.stringify(state, null, 2)}\n`); renameSync(temp, path);
 }
 function fileHash(path) { try { return createHash('sha256').update(readFileSync(path)).digest('hex'); } catch { return 'missing'; } }
@@ -23,21 +47,23 @@ function isImpactGate(name, input) {
   if (!/^(Bash|Shell|local_shell|shell|shell_command|exec_command)$/i.test(name)) return false;
   return /(^|\s)(test|build|lint|verify|commit|push|publish|deploy)(\s|:|$)|\b(git\s+(commit|push)|npm\s+(test|publish)|pnpm\s+[^\n]*(test|build|lint|verify|publish))\b/i.test(commandFrom(input));
 }
-function changedPath(input) {
+function changedPath(input, root) {
   const value = toolInput(input);
   const path = value.file_path || value.path;
-  return typeof path === 'string' ? resolve(projectRoot(input), path) : null;
+  return root && typeof path === 'string' ? resolve(root, path) : null;
 }
 
 export function runHook(event) {
   const input = parseInput();
   const name = toolName(input);
-  const state = readState(input);
+  const context = resolveHookContext(input, event);
+  const state = readState(context?.path);
   state.pending ||= {};
 
   if (event === 'sessionstart') {
+    if (!context) return {};
     state.loadRequired = true;
-    writeState(input, state);
+    writeState(context.path, state);
     return { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: 'Dotdotgod project memory has not been loaded for this session. Before substantive shell or write work, call dotdotgod_project_load once with a concise task-specific focus.' } };
   }
 
@@ -50,18 +76,19 @@ export function runHook(event) {
   }
 
   if (event === 'posttooluse') {
+    if (!context) return {};
     if (mcpTool(name, 'dotdotgod_project_load')) state.loadRequired = false;
     else if (mcpTool(name, 'dotdotgod_project_impact')) {
       const checked = toolInput(input).paths;
       if (Array.isArray(checked)) for (const path of checked) {
-        const absolute = resolve(projectRoot(input), path);
+        const absolute = resolve(context.root, path);
         if (state.pending[absolute] === fileHash(absolute)) delete state.pending[absolute];
       }
     } else if (/^(Edit|Write|apply_patch)$/i.test(name)) {
-      const path = changedPath(input);
+      const path = changedPath(input, context.root);
       if (path) state.pending[path] = fileHash(path);
     }
-    writeState(input, state);
+    writeState(context.path, state);
     return {};
   }
 

package/src/index.d.ts

@@ -32,7 +32,7 @@ export class ContextStore {
 export function healContextDatabase(root?: string): { ok: true; backupPath: string; fromVersion: number; toVersion: number; rebuilt: true };
 export function validateSessionId(value: unknown): string;
 export function resolveSessionId(value?: unknown): string;
-export class IngestionJobRunner { sessionId?: string; constructor(store: ContextStore, options?: { sessionId?: string; renderer?: BrowserRenderer; root?: string }); enqueue(kind: 'index' | 'fetch', input: Record<string, unknown>): IngestionJob; status(id: string): IngestionJob | null; cancel(id: string): { changed: number; job: IngestionJob | null }; pump(): Promise<void> }
+export class IngestionJobRunner { sessionId?: string; constructor(store: ContextStore, options?: { sessionId?: string; renderer?: BrowserRenderer; root?: string }); enqueue(kind: 'index' | 'fetch', input: Record<string, unknown>): IngestionJob; status(id: string): IngestionJob | null; cancel(id: string): { changed: number; job: IngestionJob | null }; close(): Promise<void>; pump(): Promise<void> }
 export interface BrowserRendererResult { body?: Buffer; text?: string; url?: string; contentType?: string; status?: number }
 export type BrowserRenderer = (input: Readonly<{ url: string; signal: AbortSignal; timeoutMs: number; maxBytes: number }>) => Promise<BrowserRendererResult>;
 export const INGESTION_JOB_LIMITS: Readonly<{ maxPendingJobs: number; concurrency: 1 }>;

package/src/index.mjs

@@ -11,5 +11,5 @@ export { normalizeHtml } from './html-normalize.mjs';
 export { runDoctor } from './doctor.mjs';
 export { createProvenanceMetadata, readProvenanceMetadata, sha256Content } from './provenance.mjs';
 export { normalizeSearchTerms, reciprocalRankFusion, rerankCandidates } from './rank.mjs';
-export { projectImpact, projectInitialize, projectLoad } from './project.mjs';
+export { projectEmbeddingInstall, projectEmbeddingStatus, projectImpact, projectInitialize, projectLoad } from './project.mjs';
 export { startServer } from './server.mjs';

package/src/jobs.mjs

@@ -10,11 +10,14 @@ export class IngestionJobRunner {
     this.renderer = renderer;
     this.running = false;
     this.scheduled = false;
+    this.closed = false;
+    this.pumpPromise = undefined;
     this.controllers = new Map();
     this.schedule();
   }
 
   enqueue(kind, input) {
+    if (this.closed) throw new Error('Ingestion job runner is closed.');
     if (!['index', 'fetch'].includes(kind)) throw new Error('Unsupported ingestion job kind.');
     const job = this.store.createJob({ kind, input, sessionId: this.sessionId ?? null });
     this.schedule();
@@ -29,16 +32,33 @@ export class IngestionJobRunner {
   }
 
   schedule() {
-    if (this.scheduled || this.running) return;
+    if (this.closed || this.scheduled || this.running) return;
     this.scheduled = true;
-    queueMicrotask(() => { this.scheduled = false; void this.pump(); });
+    queueMicrotask(() => {
+      this.scheduled = false;
+      if (this.closed) return;
+      const pending = this.pump();
+      this.pumpPromise = pending;
+      const clearPending = () => {
+        if (this.pumpPromise === pending) this.pumpPromise = undefined;
+      };
+      void pending.then(clearPending, clearPending);
+    });
+  }
+
+  async close() {
+    this.closed = true;
+    for (const controller of this.controllers.values()) controller.abort();
+    if (this.scheduled) await Promise.resolve();
+    await this.pumpPromise;
   }
 
   async pump() {
-    if (this.running) return;
+    if (this.closed || this.running) return;
     this.running = true;
     try {
       for (;;) {
+        if (this.closed) break;
         const job = this.store.claimNextJob();
         if (!job) break;
         const controller = new AbortController();
@@ -53,7 +73,7 @@ export class IngestionJobRunner {
           const current = this.store.getJob(job.id);
           if (current?.state === 'running') this.store.finishJob(job.id, controller.signal.aborted ? 'cancelled' : 'failed', error instanceof Error ? error.message : String(error));
         } finally { this.controllers.delete(job.id); }
-        await new Promise((resolve) => setImmediate(resolve));
+        if (!this.closed) await new Promise((resolve) => setImmediate(resolve));
       }
     } finally { this.running = false; }
   }

package/src/project.mjs

@@ -40,10 +40,39 @@ async function cliJson(args, cwd) {
 
 export async function projectLoad(input) {
   const root = resolve(input.root || process.cwd());
-  const tree = markdownTree(root, input.maxDepth ?? (input.focus ? 3 : 5));
+  const focus = input.focus?.trim() ?? '';
+  const tree = markdownTree(root, input.maxDepth ?? (focus ? 3 : 5));
   let query = null;
-  if (input.focus?.trim()) query = await cliJson(['query', root, input.focus.trim(), '--limit', String(Math.min(input.limit ?? 30, 30)), '--json'], root);
-  return { ok: true, root, focus: input.focus?.trim() ?? '', documentationTree: tree, query };
+  let queryUnavailable;
+  if (focus) {
+    try {
+      query = await cliJson(['query', root, focus, '--limit', String(Math.min(input.limit ?? 30, 30)), '--json'], root);
+    } catch (error) {
+      const missingRuntime = String(error?.message ?? error).includes('Optional local embedding runtime is not installed');
+      queryUnavailable = missingRuntime ? {
+        code: 'EMBEDDING_RUNTIME_MISSING',
+        message: 'Local semantic search requires an optional embedding runtime; continue with the documentation map or ask the user before installation.',
+        recovery: { kind: 'embedding-runtime-install', requiresConfirmation: true, statusTool: 'dotdotgod_embedding_status', installTool: 'dotdotgod_embedding_install', cliCommand: 'dotdotgod embedding install --confirm' },
+      } : {
+        code: 'QUERY_UNAVAILABLE',
+        message: 'Semantic project query is unavailable; continue with the documentation map and targeted reads.',
+      };
+    }
+  }
+  return { ok: true, root, focus, documentationTree: tree, query, ...(queryUnavailable ? { queryUnavailable } : {}) };
+}
+
+export async function projectEmbeddingStatus(input = {}) {
+  const root = resolve(input.root || process.cwd());
+  const result = await cliJson(['embedding', 'status', root, '--json'], root);
+  return { ...result, ...(result.location ? { location: '~/.dotdotgod/runtime/embedding' } : {}) };
+}
+
+export async function projectEmbeddingInstall(input = {}) {
+  if (input.confirm !== true) throw new Error('confirm: true is required after explicit user approval.');
+  const root = resolve(input.root || process.cwd());
+  const result = await cliJson(['embedding', 'install', root, '--confirm', '--json'], root);
+  return { ...result, ...(result.location ? { location: '~/.dotdotgod/runtime/embedding' } : {}) };
 }
 
 export async function projectImpact(input) {

package/src/server.mjs

@@ -5,7 +5,7 @@ import { ContextStore, contextDbPath, healContextDatabase } from './store.mjs';
 import { executeBatch, executeCommand, executeFile } from './execute.mjs';
 import { fetchAndIndex, indexFile } from './content.mjs';
 import { runDoctor } from './doctor.mjs';
-import { projectImpact, projectInitialize, projectLoad } from './project.mjs';
+import { projectEmbeddingInstall, projectEmbeddingStatus, projectImpact, projectInitialize, projectLoad } from './project.mjs';
 import { resolveWithinRoot } from './paths.mjs';
 import { IngestionJobRunner } from './jobs.mjs';
 import { resolveSessionId, validateSessionId } from './session.mjs';
@@ -93,7 +93,7 @@ register('session_resume', 'Use an explicit opaque session ID for subsequent con
 register('ingestion_job_start', 'Queue one durable bounded background index or strict-fetch ingestion job.', phase3Shape('ingestion_job_start'), (input) => ({ ok: true, job: getJobs().enqueue(input.kind, input.input) }));
 register('ingestion_job_status', 'Return bounded status for one background ingestion job.', phase3Shape('ingestion_job_status'), (input) => ({ ok: true, job: getJobs().status(input.id) }), { readOnlyHint: true });
 register('ingestion_job_cancel', 'Cancel one queued or running background ingestion job.', phase3Shape('ingestion_job_cancel'), (input) => ({ ok: true, ...getJobs().cancel(input.id) }), { destructiveHint: true });
-register('context_heal', 'Explicitly back up and migrate only a recognized recoverable context database.', phase3Shape('context_heal'), () => { contextStore?.close(); contextStore = undefined; jobRunner = undefined; return healContextDatabase(root); }, { destructiveHint: true });
+register('context_heal', 'Explicitly back up and migrate only a recognized recoverable context database.', phase3Shape('context_heal'), async () => { await jobRunner?.close(); jobRunner = undefined; contextStore?.close(); contextStore = undefined; return healContextDatabase(root); }, { destructiveHint: true });
 register('stats', 'Report local context store counts and location.', {}, () => ({ ok: true, sessionId, ...getStore().stats() }), { readOnlyHint: true });
 register('doctor', 'Run local read-only Node.js, SQLite FTS5, storage, schema, and fetch-policy checks without network or repair actions.', {}, () => ({ sessionId, ...runDoctor({ root, dbPath: contextDbPath(root) }) }), { readOnlyHint: true });
 register('purge', 'Permanently delete one explicit context scope, session, or source.', {
@@ -102,6 +102,8 @@ register('purge', 'Permanently delete one explicit context scope, session, or so
 register('dotdotgod_project_load', 'Load a bounded documentation map and optional semantic project query.', {
   root: z.string().optional(), focus: z.string().max(500).optional(), limit: z.number().int().min(1).max(30).optional(), maxDepth: z.number().int().min(1).max(5).optional(),
 }, (input) => projectLoad(projectInput(input)), { readOnlyHint: true });
+register('dotdotgod_embedding_status', 'Inspect the optional persistent embedding runtime without installing or contacting a registry.', { root: z.string().optional() }, (input) => projectEmbeddingStatus(projectInput(input)), { readOnlyHint: true });
+register('dotdotgod_embedding_install', 'After explicit user approval, install the fixed optional embedding runtime persistently. Uses network and dependency install scripts.', { root: z.string().optional(), confirm: z.literal(true) }, (input) => projectEmbeddingInstall(projectInput(input)), { destructiveHint: true, openWorldHint: true });
 register('dotdotgod_project_impact', 'Run bounded graph impact for up to 20 changed paths.', {
   root: z.string().optional(), paths: z.array(z.string()).min(1).max(20),
 }, (input) => projectImpact(projectInput(input)), { readOnlyHint: true });