@dotdotgod/context 0.2.23

package/LICENSE

@@ -0,0 +1,3 @@
+Elastic License 2.0
+
+See https://www.elastic.co/licensing/elastic-license

package/README.md

@@ -0,0 +1,18 @@
+# @dotdotgod/context
+
+Local-first execution and retrieval runtime for dotdotgod adapters.
+
+The package exposes a stdio MCP server and shared core modules. Claude Code and Codex load the server through their adapter packages. Pi uses the shared modules through native extension tools rather than starting the MCP server.
+
+## Tools
+
+- `execute`, `batch_execute`, `execute_file`
+- `index`, `search`, `fetch_and_index`
+- `stats`, `doctor`, `purge`
+- `dotdotgod_project_load`, `dotdotgod_project_impact`, `dotdotgod_project_initialize`
+
+Large command output is captured in temporary files and indexed into a project-local SQLite FTS5 store under `.dotdotgod/context/`. The raw output is not returned before output policy filtering.
+
+```bash
+dotdotgod-context
+```

package/bin/server.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startServer } from '../src/server.mjs';
+
+startServer().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dotdotgod/context",
+  "version": "0.2.23",
+  "description": "Local-first MCP execution, indexing, and retrieval runtime for dotdotgod adapters.",
+  "type": "module",
+  "license": "Elastic-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "dotdotgod-context": "./bin/server.mjs"
+  },
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs"
+    },
+    "./server": "./src/server.mjs",
+    "./hooks": "./src/hooks.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "zod": "^3.25.76",
+    "@dotdotgod/cli": "0.2.23"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotdotgod/dotdotgod-kit.git",
+    "directory": "packages/context"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "verify": "node --check bin/server.mjs && node --check src/server.mjs && pnpm run test",
+    "pack:dry-run": "pnpm pack --dry-run --json"
+  }
+}

package/src/chunks.mjs

@@ -0,0 +1,38 @@
+const DEFAULT_CHARS = 4000;
+const DEFAULT_OVERLAP = 400;
+
+export function normalizeText(value) {
+  return String(value ?? '').replace(/\0/g, '\uFFFD').replace(/\r\n?/g, '\n');
+}
+
+export function chunkText(value, options = {}) {
+  const text = normalizeText(value);
+  const maxChars = Math.max(512, options.maxChars ?? DEFAULT_CHARS);
+  const overlap = Math.min(Math.max(0, options.overlap ?? DEFAULT_OVERLAP), Math.floor(maxChars / 3));
+  if (!text) return [];
+  const chunks = [];
+  let start = 0;
+  while (start < text.length) {
+    let end = Math.min(text.length, start + maxChars);
+    if (end < text.length) {
+      const boundary = Math.max(text.lastIndexOf('\n\n', end), text.lastIndexOf('\n', end));
+      if (boundary > start + Math.floor(maxChars / 2)) end = boundary + 1;
+    }
+    chunks.push({ text: text.slice(start, end), start, end });
+    if (end >= text.length) break;
+    start = Math.max(start + 1, end - overlap);
+  }
+  return chunks;
+}
+
+export function excerpt(text, query, maxChars = 1200) {
+  const normalized = normalizeText(text);
+  if (normalized.length <= maxChars) return normalized;
+  const terms = String(query ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+  const lower = normalized.toLowerCase();
+  const positions = terms.map((term) => lower.indexOf(term)).filter((index) => index >= 0);
+  const center = positions.length ? Math.min(...positions) : 0;
+  const start = Math.max(0, center - Math.floor(maxChars / 3));
+  const end = Math.min(normalized.length, start + maxChars);
+  return `${start > 0 ? '…' : ''}${normalized.slice(start, end)}${end < normalized.length ? '…' : ''}`;
+}

package/src/content.mjs

@@ -0,0 +1,42 @@
+import { readFileSync, statSync } from 'node:fs';
+import { resolveExistingWithinRoot } from './paths.mjs';
+
+const MAX_FILE_BYTES = 25 * 1024 * 1024;
+const MAX_FETCH_BYTES = 10 * 1024 * 1024;
+
+export function indexFile(store, input, sessionId) {
+  const path = resolveExistingWithinRoot(input.root || process.cwd(), input.path);
+  const stat = statSync(path);
+  if (!stat.isFile()) throw new Error('Only regular files are supported in the first release.');
+  if (stat.size > (input.maxBytes ?? MAX_FILE_BYTES)) throw new Error(`File exceeds maximum size: ${stat.size} bytes`);
+  return store.index({
+    scope: input.scope ?? 'session',
+    sessionId,
+    label: input.source ?? path,
+    kind: 'file',
+    text: readFileSync(path, 'utf8'),
+    metadata: { path, size: stat.size },
+    ttlMs: input.ttlMs ?? null,
+  });
+}
+
+export async function fetchAndIndex(store, input, sessionId) {
+  const url = new URL(input.url);
+  if (!['http:', 'https:'].includes(url.protocol)) throw new Error('Only http and https URLs are supported.');
+  const response = await fetch(url, { signal: AbortSignal.timeout(Math.min(input.timeoutMs ?? 30_000, 120_000)) });
+  if (!response.ok) throw new Error(`Fetch failed: HTTP ${response.status}`);
+  const length = Number(response.headers.get('content-length') || 0);
+  if (length > (input.maxBytes ?? MAX_FETCH_BYTES)) throw new Error(`Response exceeds maximum size: ${length} bytes`);
+  const text = await response.text();
+  if (Buffer.byteLength(text) > (input.maxBytes ?? MAX_FETCH_BYTES)) throw new Error('Response exceeds maximum size after download.');
+  const contentType = response.headers.get('content-type') || 'text/plain';
+  return store.index({
+    scope: input.scope ?? 'project',
+    sessionId,
+    label: input.source ?? url.href,
+    kind: 'url',
+    text,
+    metadata: { url: url.href, contentType, status: response.status },
+    ttlMs: input.ttlMs ?? 24 * 60 * 60 * 1000,
+  });
+}

package/src/execute.mjs

@@ -0,0 +1,155 @@
+import { createWriteStream, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { resolveWithinRoot } from './paths.mjs';
+
+const DIRECT_LIMIT = 12_000;
+const HARD_LIMIT = 10 * 1024 * 1024;
+
+function readBounded(path, limit = DIRECT_LIMIT) {
+  const value = readFileSync(path);
+  if (value.length <= limit) return { text: value.toString('utf8'), truncated: false, bytes: value.length };
+  const head = value.subarray(0, Math.floor(limit * 0.7));
+  const tail = value.subarray(value.length - Math.floor(limit * 0.3));
+  return { text: `${head.toString('utf8')}\n… ${value.length - head.length - tail.length} byte(s) omitted …\n${tail.toString('utf8')}`, truncated: true, bytes: value.length };
+}
+
+function commandSpec(input) {
+  if (input.executable) return { command: input.executable, args: input.args ?? [], shell: false };
+  if (!input.command) throw new Error('command or executable is required');
+  return { command: input.command, args: [], shell: input.shell ?? true };
+}
+
+function killProcess(child) {
+  if (!child.pid) return;
+  try { if (process.platform !== 'win32') process.kill(-child.pid, 'SIGTERM'); else child.kill('SIGTERM'); } catch {}
+  setTimeout(() => {
+    try { if (process.platform !== 'win32') process.kill(-child.pid, 'SIGKILL'); else child.kill('SIGKILL'); } catch {}
+  }, 500).unref();
+}
+
+export async function executeCommand(input, options = {}) {
+  const spec = commandSpec(input);
+  const cwd = resolveWithinRoot(options.root || process.cwd(), input.cwd || '.');
+  const timeoutMs = Math.min(Math.max(1, input.timeoutMs ?? 120_000), 30 * 60_000);
+  const dir = mkdtempSync(join(tmpdir(), 'dotdotgod-context-'));
+  const stdoutPath = join(dir, 'stdout.log');
+  const stderrPath = join(dir, 'stderr.log');
+  const stdout = createWriteStream(stdoutPath);
+  const stderr = createWriteStream(stderrPath);
+  const startedAt = Date.now();
+  let timedOut = false;
+  let aborted = false;
+
+  try {
+    const result = await new Promise((resolvePromise, reject) => {
+      const child = spawn(spec.command, spec.args, {
+        cwd,
+        shell: spec.shell,
+        detached: process.platform !== 'win32',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: options.env ?? process.env,
+      });
+      child.stdout.pipe(stdout);
+      child.stderr.pipe(stderr);
+      const timer = setTimeout(() => { timedOut = true; killProcess(child); }, timeoutMs);
+      const onAbort = () => { aborted = true; killProcess(child); };
+      options.signal?.addEventListener('abort', onAbort, { once: true });
+      child.once('error', (error) => { clearTimeout(timer); reject(error); });
+      child.once('close', (code, signal) => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', onAbort);
+        stdout.end(() => stderr.end(() => resolvePromise({ code, signal })));
+      });
+    });
+
+    const stdoutResult = readBounded(stdoutPath, input.outputLimit ?? DIRECT_LIMIT);
+    const stderrResult = readBounded(stderrPath, input.outputLimit ?? DIRECT_LIMIT);
+    const totalBytes = stdoutResult.bytes + stderrResult.bytes;
+    const metadata = {
+      command: input.command ?? [input.executable, ...(input.args ?? [])].join(' '),
+      cwd,
+      code: result.code,
+      signal: result.signal,
+      timedOut,
+      aborted,
+      durationMs: Date.now() - startedAt,
+      stdoutBytes: stdoutResult.bytes,
+      stderrBytes: stderrResult.bytes,
+    };
+    const mode = input.outputMode ?? 'auto';
+    const shouldIndex = mode === 'indexed' || (mode === 'auto' && totalBytes > (input.directLimit ?? DIRECT_LIMIT));
+    let indexed;
+    if (shouldIndex && options.store) {
+      const stdoutText = statSync(stdoutPath).size <= HARD_LIMIT ? readFileSync(stdoutPath, 'utf8') : stdoutResult.text;
+      const stderrText = statSync(stderrPath).size <= HARD_LIMIT ? readFileSync(stderrPath, 'utf8') : stderrResult.text;
+      indexed = options.store.index({
+        scope: input.scope ?? 'session',
+        sessionId: options.sessionId,
+        label: input.label ?? metadata.command,
+        kind: 'command',
+        text: `# stdout\n${stdoutText}\n\n# stderr\n${stderrText}`,
+        metadata,
+        ttlMs: input.ttlMs ?? 24 * 60 * 60 * 1000,
+      });
+    }
+    return {
+      ok: result.code === 0 && !timedOut && !aborted,
+      ...metadata,
+      ...(mode === 'discard' ? {} : shouldIndex ? { indexed } : { stdout: stdoutResult.text, stderr: stderrResult.text, truncated: stdoutResult.truncated || stderrResult.truncated }),
+    };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export async function executeFile(input, options = {}) {
+  const path = resolveWithinRoot(options.root || process.cwd(), input.path);
+  const dir = mkdtempSync(join(tmpdir(), 'dotdotgod-context-file-'));
+  try {
+    let executable;
+    let args;
+    if (input.language === 'python') {
+      const wrapper = join(dir, 'run.py');
+      writeFileSync(wrapper, `from pathlib import Path\nFILE_CONTENT = Path(${JSON.stringify(path)}).read_text(encoding='utf-8', errors='replace')\n${input.code}\n`);
+      executable = process.env.PYTHON || 'python3';
+      args = [wrapper];
+    } else if (input.language === 'shell') {
+      const wrapper = join(dir, 'run.sh');
+      writeFileSync(wrapper, `FILE_PATH=${JSON.stringify(path)}\nexport FILE_PATH\n${input.code}\n`);
+      executable = process.env.SHELL || '/bin/sh';
+      args = [wrapper];
+    } else {
+      const wrapper = join(dir, 'run.mjs');
+      writeFileSync(wrapper, `import { readFileSync } from 'node:fs';\nconst FILE_CONTENT = readFileSync(${JSON.stringify(path)}, 'utf8');\n${input.code}\n`);
+      executable = process.execPath;
+      args = [wrapper];
+    }
+    return await executeCommand({ ...input, executable, args, command: undefined, shell: false, cwd: input.cwd ?? options.root }, options);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export async function executeBatch(input, options = {}) {
+  const commands = input.commands ?? [];
+  if (commands.length === 0) throw new Error('commands must contain at least one command');
+  if (commands.length > 100) throw new Error('commands is limited to 100 entries');
+  const concurrency = Math.min(8, Math.max(1, input.concurrency ?? 1));
+  const results = new Array(commands.length);
+  let cursor = 0;
+  async function worker() {
+    while (true) {
+      const index = cursor++;
+      if (index >= commands.length) return;
+      try {
+        results[index] = await executeCommand({ ...commands[index], cwd: commands[index].cwd ?? input.cwd, timeoutMs: commands[index].timeoutMs ?? input.timeoutMs }, options);
+      } catch (error) {
+        results[index] = { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, commands.length) }, () => worker()));
+  return { ok: results.every((result) => result.ok), concurrency, results };
+}

package/src/hooks.mjs

@@ -0,0 +1,74 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join, 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 });
+  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'; } }
+function toolName(input) { return String(input.tool_name || input.toolName || ''); }
+function toolInput(input) { return input.tool_input || input.toolInput || {}; }
+function mcpTool(name, suffix) { return name === suffix || name.endsWith(`__${suffix}`) || name.endsWith(`_${suffix}`); }
+function deny(reason) { return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } }; }
+function commandFrom(input) { const value = toolInput(input); return String(value.command || value.cmd || ''); }
+function isSubstantive(name) { return /^(Bash|Shell|local_shell|shell|shell_command|exec_command|Edit|Write|apply_patch)$/i.test(name); }
+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) {
+  const value = toolInput(input);
+  const path = value.file_path || value.path;
+  return typeof path === 'string' ? resolve(projectRoot(input), path) : null;
+}
+
+export function runHook(event) {
+  const input = parseInput();
+  const name = toolName(input);
+  const state = readState(input);
+  state.pending ||= {};
+
+  if (event === 'sessionstart') {
+    state.loadRequired = true;
+    writeState(input, 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.' } };
+  }
+
+  if (event === 'pretooluse') {
+    if (mcpTool(name, 'dotdotgod_project_load') || mcpTool(name, 'dotdotgod_project_impact')) return {};
+    if (state.loadRequired && isSubstantive(name)) return deny('Project memory is required first. Call dotdotgod_project_load with the current project root and a concise task-specific focus, then retry this tool.');
+    const pendingPaths = Object.keys(state.pending);
+    if (pendingPaths.length && isImpactGate(name, input)) return deny(`Graph impact is pending. Call dotdotgod_project_impact with paths=${JSON.stringify(pendingPaths)} and then retry this tool.`);
+    return {};
+  }
+
+  if (event === 'posttooluse') {
+    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);
+        if (state.pending[absolute] === fileHash(absolute)) delete state.pending[absolute];
+      }
+    } else if (/^(Edit|Write|apply_patch)$/i.test(name)) {
+      const path = changedPath(input);
+      if (path) state.pending[path] = fileHash(path);
+    }
+    writeState(input, state);
+    return {};
+  }
+
+  return {};
+}
+
+export function hookMain(event) {
+  try { process.stdout.write(`${JSON.stringify(runHook(event))}\n`); }
+  catch (error) { process.stderr.write(`dotdotgod hook error: ${error instanceof Error ? error.message : String(error)}\n`); process.stdout.write('{}\n'); }
+}

package/src/index.d.ts

@@ -0,0 +1,19 @@
+export class ContextStore {
+  constructor(root?: string);
+  root: string;
+  path: string;
+  close(): void;
+  index(input: Record<string, unknown>): Record<string, unknown>;
+  search(input: Record<string, unknown>): unknown[];
+  stats(): Record<string, unknown>;
+  purge(input: Record<string, unknown>): Record<string, unknown>;
+}
+export function executeCommand(input: Record<string, any>, options?: Record<string, any>): Promise<Record<string, any>>;
+export function executeBatch(input: Record<string, any>, options?: Record<string, any>): Promise<Record<string, any>>;
+export function executeFile(input: Record<string, any>, options?: Record<string, any>): Promise<Record<string, any>>;
+export function indexFile(store: ContextStore, input: Record<string, any>, sessionId?: string): Record<string, any>;
+export function fetchAndIndex(store: ContextStore, input: Record<string, any>, sessionId?: string): Promise<Record<string, any>>;
+export function projectLoad(input: Record<string, any>): Promise<Record<string, any>>;
+export function projectImpact(input: Record<string, any>): Promise<Record<string, any>>;
+export function projectInitialize(input: Record<string, any>): Promise<Record<string, any>>;
+export function startServer(): Promise<void>;

package/src/index.mjs

@@ -0,0 +1,6 @@
+export { chunkText, excerpt, normalizeText } from './chunks.mjs';
+export { ContextStore, contextDbPath } from './store.mjs';
+export { executeBatch, executeCommand, executeFile } from './execute.mjs';
+export { fetchAndIndex, indexFile } from './content.mjs';
+export { projectImpact, projectInitialize, projectLoad } from './project.mjs';
+export { startServer } from './server.mjs';

package/src/paths.mjs

@@ -0,0 +1,23 @@
+import { realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve } from 'node:path';
+
+function assertWithinRoot(base, target, candidate) {
+  const rel = relative(base, target);
+  if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(rel)) {
+    throw new Error(`Path escapes project root: ${candidate}`);
+  }
+}
+
+export function resolveWithinRoot(root, candidate = '.') {
+  const base = resolve(root || process.cwd());
+  const target = resolve(base, candidate);
+  assertWithinRoot(base, target, candidate);
+  return target;
+}
+
+export function resolveExistingWithinRoot(root, candidate = '.') {
+  const base = realpathSync(resolve(root || process.cwd()));
+  const target = realpathSync(resolveWithinRoot(base, candidate));
+  assertWithinRoot(base, target, candidate);
+  return target;
+}

package/src/project.mjs

@@ -0,0 +1,70 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { relative, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+
+const require = createRequire(import.meta.url);
+const cli = require.resolve('@dotdotgod/cli/bin/dotdotgod.mjs');
+
+function markdownTree(root, maxDepth = 5) {
+  const docs = resolve(root, 'docs');
+  if (!existsSync(docs)) return [];
+  const output = [];
+  function walk(dir, depth) {
+    if (depth > maxDepth) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = resolve(dir, entry.name);
+      if (entry.isDirectory()) { output.push(`${'  '.repeat(depth - 1)}- ${relative(root, path)}/`); walk(path, depth + 1); }
+      else if (entry.isFile() && entry.name.endsWith('.md')) output.push(`${'  '.repeat(depth - 1)}- ${relative(root, path)}`);
+    }
+  }
+  walk(docs, 1);
+  return output;
+}
+
+async function cliJson(args, cwd) {
+  return await new Promise((resolvePromise, reject) => {
+    const child = spawn(process.execPath, [cli, ...args], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.once('error', reject);
+    child.once('close', (code) => {
+      const out = Buffer.concat(stdout).toString('utf8');
+      if (code !== 0) return reject(new Error(Buffer.concat(stderr).toString('utf8') || out || `dotdotgod exited ${code}`));
+      try { resolvePromise(JSON.parse(out)); } catch { reject(new Error(`Expected JSON from dotdotgod: ${out.slice(0, 500)}`)); }
+    });
+  });
+}
+
+export async function projectLoad(input) {
+  const root = resolve(input.root || process.cwd());
+  const tree = markdownTree(root, input.maxDepth ?? (input.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 };
+}
+
+export async function projectImpact(input) {
+  const root = resolve(input.root || process.cwd());
+  const paths = [...new Set(input.paths ?? [])];
+  if (paths.length === 0) throw new Error('paths must contain at least one changed path');
+  if (paths.length > 20) throw new Error('paths is limited to 20 entries per call');
+  const args = ['graph', 'impact', root];
+  for (const path of paths) args.push('--changed', path);
+  args.push('--json');
+  return await cliJson(args, root);
+}
+
+export async function projectInitialize(input) {
+  const root = resolve(input.root || process.cwd());
+  const dryRun = input.dryRun !== false;
+  if (!dryRun && input.confirmWrite !== true) throw new Error('confirmWrite: true is required when dryRun is false');
+  const args = ['init', root, '--json'];
+  if (dryRun) args.push('--dry-run');
+  if (input.projectName) args.push('--project-name', input.projectName);
+  if (input.template) args.push('--template', input.template);
+  if (input.dotdotSetting) args.push('--dotdot-setting');
+  return await cliJson(args, root);
+}

package/src/server.mjs

@@ -0,0 +1,73 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { ContextStore } from './store.mjs';
+import { executeBatch, executeCommand, executeFile } from './execute.mjs';
+import { fetchAndIndex, indexFile } from './content.mjs';
+import { projectImpact, projectInitialize, projectLoad } from './project.mjs';
+import { resolveWithinRoot } from './paths.mjs';
+
+const root = process.env.DOTDOTGOD_PROJECT_ROOT || process.cwd();
+const sessionId = process.env.DOTDOTGOD_SESSION_ID || crypto.randomUUID();
+const store = new ContextStore(root);
+const server = new McpServer({ name: 'dotdotgod-context', version: '0.2.23' });
+
+const scopeSchema = z.enum(['transient', 'session', 'project']).optional();
+const outputModeSchema = z.enum(['auto', 'direct', 'indexed', 'discard']).optional();
+const commandSchema = {
+  label: z.string().optional(), command: z.string().optional(), executable: z.string().optional(), args: z.array(z.string()).optional(),
+  shell: z.boolean().optional(), cwd: z.string().optional(), timeoutMs: z.number().int().positive().optional(), outputLimit: z.number().int().positive().optional(),
+  directLimit: z.number().int().positive().optional(), outputMode: outputModeSchema, scope: scopeSchema, ttlMs: z.number().int().nonnegative().optional(),
+};
+
+function success(value) {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }], structuredContent: value };
+}
+function failure(error) {
+  const value = { ok: false, error: error instanceof Error ? error.message : String(error) };
+  return { isError: true, content: [{ type: 'text', text: JSON.stringify(value, null, 2) }], structuredContent: value };
+}
+function projectInput(input) {
+  return { ...input, root: resolveWithinRoot(root, input.root || '.') };
+}
+function register(name, description, inputSchema, handler, annotations) {
+  server.registerTool(name, { description, inputSchema, annotations }, async (input, extra) => {
+    try { return success(await handler(input, extra)); } catch (error) { return failure(error); }
+  });
+}
+
+register('execute', 'Run one local command while keeping large stdout/stderr outside model context.', commandSchema,
+  (input, extra) => executeCommand(input, { root, store, sessionId, signal: extra.signal }), { openWorldHint: true, destructiveHint: true });
+register('batch_execute', 'Run labeled local commands sequentially or with bounded concurrency and index large outputs.', {
+  commands: z.array(z.object(commandSchema)).min(1).max(100), concurrency: z.number().int().min(1).max(8).optional(), cwd: z.string().optional(), timeoutMs: z.number().int().positive().optional(),
+}, (input, extra) => executeBatch(input, { root, store, sessionId, signal: extra.signal }), { openWorldHint: true, destructiveHint: true });
+register('execute_file', 'Process a local file in an isolated child process; only bounded stdout/stderr is returned.', {
+  path: z.string(), language: z.enum(['javascript', 'python', 'shell']).default('javascript'), code: z.string(), ...commandSchema,
+}, (input, extra) => executeFile(input, { root, store, sessionId, signal: extra.signal }), { openWorldHint: false, destructiveHint: true });
+register('index', 'Index a local text file into the project-local FTS5 store without returning its raw bytes.', {
+  path: z.string(), root: z.string().optional(), source: z.string().optional(), scope: scopeSchema, ttlMs: z.number().int().nonnegative().optional(), maxBytes: z.number().int().positive().optional(),
+}, (input) => ({ ok: true, ...indexFile(store, { ...input, root }, sessionId) }), { readOnlyHint: true });
+register('search', 'Search indexed command, file, and fetched content and return bounded excerpts.', {
+  query: z.string().min(1), scope: scopeSchema, source: z.string().optional(), limit: z.number().int().min(1).max(50).optional(), sessionOnly: z.boolean().optional(),
+}, (input) => ({ ok: true, results: store.search({ ...input, sessionId: input.sessionOnly ? sessionId : undefined }) }), { readOnlyHint: true });
+register('fetch_and_index', 'Fetch an HTTP(S) URL locally, index bounded text, and return metadata only.', {
+  url: z.string().url(), source: z.string().optional(), scope: scopeSchema, ttlMs: z.number().int().nonnegative().optional(), timeoutMs: z.number().int().positive().optional(), maxBytes: z.number().int().positive().optional(),
+}, (input) => fetchAndIndex(store, input, sessionId).then((value) => ({ ok: true, ...value })), { openWorldHint: true, readOnlyHint: true });
+register('stats', 'Report local context store counts and location.', {}, () => ({ ok: true, sessionId, ...store.stats() }), { readOnlyHint: true });
+register('doctor', 'Check local Node.js, SQLite FTS5, project storage, and MCP runtime readiness.', {}, () => ({ ok: true, node: process.version, platform: process.platform, root, sessionId, store: store.stats() }), { readOnlyHint: true });
+register('purge', 'Permanently delete one explicit context scope, session, or source.', {
+  confirm: z.literal(true), scope: scopeSchema, sessionId: z.string().optional(), sourceId: z.string().optional(),
+}, (input) => ({ ok: true, ...store.purge(input) }), { destructiveHint: true });
+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_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 });
+register('dotdotgod_project_initialize', 'Initialize project memory; dry-run is default and writes require explicit confirmation.', {
+  root: z.string().optional(), dryRun: z.boolean().optional(), confirmWrite: z.boolean().optional(), projectName: z.string().optional(), template: z.string().optional(), dotdotSetting: z.boolean().optional(),
+}, (input) => projectInitialize(projectInput(input)), { destructiveHint: true });
+
+export async function startServer() {
+  await server.connect(new StdioServerTransport());
+}

package/src/store.mjs

@@ -0,0 +1,133 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { chunkText, excerpt } from './chunks.mjs';
+
+function ftsQuery(value) {
+  const terms = String(value ?? '').match(/[\p{L}\p{N}_./:@-]+/gu) ?? [];
+  if (terms.length === 0) throw new Error('Search query must contain at least one searchable term.');
+  return terms.slice(0, 20).map((term) => `"${term.replaceAll('"', '""')}"`).join(' OR ');
+}
+
+function safeRoot(root) {
+  return resolve(root || process.cwd());
+}
+
+export function contextDbPath(root) {
+  return join(safeRoot(root), '.dotdotgod', 'context', 'context.sqlite');
+}
+
+export class ContextStore {
+  constructor(root = process.cwd()) {
+    this.root = safeRoot(root);
+    this.path = contextDbPath(this.root);
+    mkdirSync(dirname(this.path), { recursive: true });
+    this.db = new DatabaseSync(this.path);
+    this.db.exec(`
+      PRAGMA journal_mode=WAL;
+      CREATE TABLE IF NOT EXISTS sources (
+        id TEXT PRIMARY KEY,
+        scope TEXT NOT NULL,
+        session_id TEXT,
+        label TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        metadata TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        expires_at INTEGER
+      );
+      CREATE VIRTUAL TABLE IF NOT EXISTS chunks USING fts5(
+        source_id UNINDEXED,
+        scope UNINDEXED,
+        session_id UNINDEXED,
+        ordinal UNINDEXED,
+        body,
+        tokenize='porter unicode61'
+      );
+    `);
+  }
+
+  close() { this.db.close(); }
+
+  index({ id = crypto.randomUUID(), scope = 'session', sessionId = null, label, kind = 'text', text, metadata = {}, ttlMs = null }) {
+    const createdAt = Date.now();
+    const expiresAt = ttlMs == null ? null : createdAt + Math.max(0, ttlMs);
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      this.db.prepare('INSERT OR REPLACE INTO sources(id, scope, session_id, label, kind, metadata, created_at, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)')
+        .run(id, scope, sessionId, label || id, kind, JSON.stringify(metadata), createdAt, expiresAt);
+      this.db.prepare('DELETE FROM chunks WHERE source_id = ?').run(id);
+      const insert = this.db.prepare('INSERT INTO chunks(source_id, scope, session_id, ordinal, body) VALUES (?, ?, ?, ?, ?)');
+      const chunks = chunkText(text);
+      chunks.forEach((chunk, ordinal) => insert.run(id, scope, sessionId, ordinal, chunk.text));
+      this.db.exec('COMMIT');
+      return { id, chunks: chunks.length, bytes: Buffer.byteLength(String(text ?? '')), scope, expiresAt };
+    } catch (error) {
+      this.db.exec('ROLLBACK');
+      throw error;
+    }
+  }
+
+  expire() {
+    const ids = this.db.prepare('SELECT id FROM sources WHERE expires_at IS NOT NULL AND expires_at <= ?').all(Date.now()).map((row) => row.id);
+    const removeChunks = this.db.prepare('DELETE FROM chunks WHERE source_id = ?');
+    const removeSource = this.db.prepare('DELETE FROM sources WHERE id = ?');
+    for (const id of ids) { removeChunks.run(id); removeSource.run(id); }
+    return ids.length;
+  }
+
+  search({ query, scope, sessionId, source, limit = 5 }) {
+    this.expire();
+    const clauses = ['chunks MATCH ?'];
+    const params = [ftsQuery(query)];
+    if (scope) { clauses.push('c.scope = ?'); params.push(scope); }
+    if (sessionId) { clauses.push('c.session_id = ?'); params.push(sessionId); }
+    if (source) { clauses.push('(s.id = ? OR s.label LIKE ?)'); params.push(source, `%${source}%`); }
+    params.push(Math.min(50, Math.max(1, limit)));
+    const rows = this.db.prepare(`
+      SELECT c.source_id, c.ordinal, c.body, s.label, s.kind, s.scope, s.metadata, bm25(chunks) AS rank
+      FROM chunks c JOIN sources s ON s.id = c.source_id
+      WHERE ${clauses.join(' AND ')}
+      ORDER BY rank LIMIT ?
+    `).all(...params);
+    return rows.map((row) => ({
+      sourceId: row.source_id,
+      label: row.label,
+      kind: row.kind,
+      scope: row.scope,
+      ordinal: Number(row.ordinal),
+      rank: row.rank,
+      text: excerpt(row.body, query),
+      metadata: JSON.parse(row.metadata),
+    }));
+  }
+
+  stats() {
+    this.expire();
+    const sources = this.db.prepare('SELECT count(*) AS count FROM sources').get().count;
+    const chunks = this.db.prepare('SELECT count(*) AS count FROM chunks').get().count;
+    const byScope = this.db.prepare('SELECT scope, count(*) AS count FROM sources GROUP BY scope ORDER BY scope').all();
+    return { path: this.path, sources, chunks, byScope };
+  }
+
+  purge({ scope, sessionId, sourceId }) {
+    const selectors = [scope != null, sessionId != null, sourceId != null].filter(Boolean).length;
+    if (selectors !== 1) throw new Error('Choose exactly one purge selector: scope, sessionId, or sourceId.');
+    let ids;
+    if (scope) ids = this.db.prepare('SELECT id FROM sources WHERE scope = ?').all(scope).map((row) => row.id);
+    else if (sessionId) ids = this.db.prepare('SELECT id FROM sources WHERE session_id = ?').all(sessionId).map((row) => row.id);
+    else ids = [sourceId];
+    const removeChunks = this.db.prepare('DELETE FROM chunks WHERE source_id = ?');
+    const removeSource = this.db.prepare('DELETE FROM sources WHERE id = ?');
+    let removed = 0;
+    for (const id of ids) {
+      removeChunks.run(id);
+      removed += Number(removeSource.run(id).changes ?? 0);
+    }
+    return { removed };
+  }
+
+  destroy() {
+    this.close();
+    rmSync(dirname(this.path), { recursive: true, force: true });
+  }
+}