Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

24.1 KB
Raw Blame
import { stat } from 'node:fs/promises';
import { relative, resolve } from 'node:path';
import {
  type PersistedLinterConfig,
  selectAdvertisedFrontmatterMappings,
  toEffectiveBase,
} from '@inkeep/open-knowledge-core';
import { z } from 'zod';
import { expandGlobStages } from '../../bash/expand-globs.ts';
import { extractReferencedPaths, isWikiPath, pathArgs } from '../../bash/extract-paths.ts';
import {
  createBashInstance,
  erofsTarget,
  execBash,
  StdoutOverflowError,
} from '../../bash/index.ts';
import {
  deriveScanRoots,
  diffMtimes,
  SCAN_CAP,
  snapshotMtimesForRoots,
} from '../../bash/mtime-scan.ts';
import {
  augmentStagesWithExcludes,
  type ErrorCategory,
  parseCommand,
  type Stage,
  serializeStages,
} from '../../bash/parse-command.ts';
import {
  type DirectoryMeta,
  type EnrichedEntry,
  type EnrichedMeta,
  enrichDirectoryRecursive,
  enrichPath,
  fetchBacklinkCountsBatch,
  fetchCommentCountsBatch,
  pathToDocName,
} from '../../content/enrichment.ts';
import { getLogger } from '../../logger.ts';
import { resolveWithinRoot } from './path-safety.ts';
import { buildListResolver, docNameFromPath, type PreviewUrlSource } from './preview-url.ts';
import type { ConfigOrResolver, ServerInstance, ServerUrlOrResolver } from './shared.ts';
import {
  looseObjectArray,
  outputSchemaWithText,
  resolveProjectServerContext,
  textPlusStructured,
} from './shared.ts';

const log = getLogger('mcp:exec');

const SOFT_CAP_LINES = 500;
export const WIRE_BODY_COPIES = 2;
export const RESULT_BODY_BUDGET_BYTES = 64 * 1024;
const PER_COPY_DECORATION_HEADROOM_BYTES = 8 * 1024;
const SOFT_CAP_BYTES =
  Math.floor(RESULT_BODY_BUDGET_BYTES / WIRE_BODY_COPIES) - PER_COPY_DECORATION_HEADROOM_BYTES;

const BINARY_EXT_RE = /\.(png|jpe?g|gif|webp|svg|pdf|zip|tar|gz|tgz|mp4|mov|mp3|wav|ico|bmp)$/i;

export const DESCRIPTION = [
  'STOP: with `.ok/`, use exec for in-scope .md/.mdx; native Read/Grep/Glob omit wiki context. Native tools are for source code, non-markdown or projects without .ok/. See the open-knowledge skill for the full rule and escape hatch.',
  'Read-only bash-like command; returns stdout and enrichedPaths with frontmatter, backlinks/forward links, unresolved comments, shadow-repo activity and git history with human/agent attribution. Unresolved comments are open human review requests: consider before editing and report them.',
  'Allowlist: cat, ls, grep, find, head, tail, wc, sort, uniq, cut. One command or pipe per call. No &&, ;, subshells, writes or redirection (including <). Use multiple paths or separate calls.',
  "cwd: command paths resolve inside explicit absolute cwd, or the client's sole advertised root. With zero/multiple roots pass cwd; traversal above it is rejected.",
  'Stdout provenance: ls <dir>/ labels the directory; single-file cat/head/tail labels its path. Multi-file cat has no header; enrichedPaths still lists files. Piped head/tail preserve upstream provenance.',
  "Examples: exec({command:'cat notes/a.md'}); exec({command:'grep -rn oauth notes/ | head -5'}); exec({command:'ls',cwd:'/abs/project'}).",
].join('\n');

interface ExecDeps {
  resolveCwd: (explicit?: string) => Promise<string>;
  serverUrl: ServerUrlOrResolver;
  config: ConfigOrResolver;
}

type ExecEnrichedEntry = EnrichedEntry & {
  previewUrl: string | null;
  previewUrlSource?: PreviewUrlSource;
};

export interface ExecStructuredResult {
  enrichedPaths: ExecEnrichedEntry[];
  cwd?: string;
  warnings?: string[];
  stdoutTruncated?: boolean;
  error?: { category: ErrorCategory; message: string };
}

interface CapResult {
  text: string;
  truncated: boolean;
  omittedLines: number;
}

function applySoftCap(stdout: string): CapResult {
  const lines = stdout.split('\n');
  const contentLineCount = lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
  if (contentLineCount <= SOFT_CAP_LINES && stdout.length <= SOFT_CAP_BYTES) {
    return { text: stdout, truncated: false, omittedLines: 0 };
  }
  const cutoff = Math.min(contentLineCount, SOFT_CAP_LINES);
  let keptBytes = 0;
  let keptLines = 0;
  for (let i = 0; i < cutoff; i++) {
    const line = lines[i];
    keptBytes += line.length + 1;
    if (keptBytes > SOFT_CAP_BYTES) break;
    keptLines++;
  }
  const kept = lines.slice(0, keptLines).join('\n');
  const omitted = contentLineCount - keptLines;
  return {
    text: `${kept}\n<truncated: ${omitted} more lines — re-run with a more-specific query>`,
    truncated: true,
    omittedLines: omitted,
  };
}

function detectBinaryArgs(stages: Stage[]): string[] {
  const hits: string[] = [];
  for (const s of stages) {
    if (s.command !== 'cat') continue;
    for (const arg of s.args.slice(1)) {
      if (arg.startsWith('-')) continue;
      if (BINARY_EXT_RE.test(arg)) hits.push(arg);
    }
  }
  return hits;
}

function extractHeadTailLimit(args: string[]): number {
  for (let i = 1; i < args.length; i++) {
    const arg = args[i];
    const longEq = arg.match(/^--lines=(\d+)$/);
    if (longEq) return Number(longEq[1]);
    if (arg === '--lines' && i + 1 < args.length) {
      const n = Number(args[i + 1]);
      if (Number.isFinite(n)) return n;
    }
    if (arg === '-n' && i + 1 < args.length) {
      const n = Number(args[i + 1]);
      if (Number.isFinite(n)) return n;
    }
    const nJoined = arg.match(/^-n(\d+)$/);
    if (nJoined) return Number(nJoined[1]);
    const shortN = arg.match(/^-(\d+)$/);
    if (shortN) return Number(shortN[1]);
  }
  return 10;
}

function detectHeadTailTruncation(stages: Stage[], stdout: string): { banner: string } | null {
  if (stages.length < 2) return null;
  const last = stages[stages.length - 1];
  if (last.command !== 'head' && last.command !== 'tail') return null;
  const limit = extractHeadTailLimit(last.args);
  const rawLines = stdout.split('\n');
  const contentLineCount =
    rawLines[rawLines.length - 1] === '' ? rawLines.length - 1 : rawLines.length;
  if (contentLineCount < limit) return null;
  const countedLines = rawLines.slice(0, contentLineCount);
  const uniqueFiles = new Set(
    countedLines.map((l) => {
      const colon = l.indexOf(':');
      return colon > 0 ? l.slice(0, colon) : l;
    }),
  ).size;
  const upstream = stages
    .slice(0, -1)
    .map((s) => s.command)
    .join(' | ');
  return {
    banner:
      `Output hit \`${last.command} -${limit}\` cap (${contentLineCount} lines, ${uniqueFiles} unique file${uniqueFiles === 1 ? '' : 's'}). ` +
      `The \`${upstream}\` stage may have had more matches that never reached stdout. ` +
      `For existence checks across many files, prefer \`grep -rl PATTERN <dir>\` (list files only, no head). ` +
      `For enumeration, drop the \`| ${last.command}\` or widen the cap.`,
  };
}

function isDirectoryMeta(e: EnrichedEntry): e is DirectoryMeta {
  return (e as DirectoryMeta).type === 'directory';
}

export function formatDirectoryEntry(d: DirectoryMeta): string {
  const leader = d.title ? `**${d.title}** (${d.path}/)` : `**${d.path}/** (directory)`;
  const parts: string[] = [leader];
  if (d.description) parts.push(d.description);
  if (d.tags && d.tags.length > 0) parts.push(`tags: ${d.tags.join(', ')}`);
  if (d.templates_available && d.templates_available.length > 0) {
    const tpl = d.templates_available
      .map((t) =>
        t.description ? `${t.name} — ${t.description} (${t.scope})` : `${t.name} (${t.scope})`,
      )
      .join(', ');
    parts.push(`templates: ${tpl}`);
  }
  if (d.schemas_applicable && d.schemas_applicable.length > 0) {
    parts.push(`schemas: ${d.schemas_applicable.join(', ')}`);
  }
  const counts: string[] = [];
  counts.push(
    d.recursiveMdCount > d.directMdCount
      ? `${d.directMdCount} md file${d.directMdCount === 1 ? '' : 's'} here (${d.recursiveMdCount} in tree)`
      : `${d.directMdCount} md file${d.directMdCount === 1 ? '' : 's'}`,
  );
  if (d.childDirCount > 0) {
    counts.push(`${d.childDirCount} subdir${d.childDirCount === 1 ? '' : 's'}`);
  }
  parts.push(counts.join(', '));
  if (d.mostRecentMd) {
    const when = d.mostRecentMd.updatedAt ? `, ${d.mostRecentMd.updatedAt.slice(0, 10)}` : '';
    parts.push(
      `most recent: ${d.mostRecentMd.title ?? d.mostRecentMd.path} (${d.mostRecentMd.path}${when})`,
    );
  }
  if (d.commentCount !== undefined && d.commentCount > 0) {
    let line = `⚠ ${d.commentCount} unresolved comment${d.commentCount === 1 ? '' : 's'} in tree`;
    if (d.commentedDocs && d.commentedDocs.length > 0) {
      const where = d.commentedDocs.map((c) => `${c.docName} (${c.count})`).join(', ');
      const listed = d.commentedDocs.reduce((sum, c) => sum + c.count, 0);
      line += `: ${where}${listed < d.commentCount ? ', …' : ''}`;
    }
    parts.push(line);
  }
  if (d.truncated) parts.push('scan truncated');
  return `- ${parts.join(' — ')}`;
}

const COMMENT_PREVIEW_CAP = 3;

function formatCommentPreview(c: NonNullable<EnrichedMeta['comments']>[number]): string {
  const flags = [c.state === 'orphaned' ? 'passage gone' : null, c.queued ? 'queued' : null].filter(
    (f) => f !== null,
  );
  const suffix = flags.length > 0 ? ` [${flags.join(', ')}]` : '';
  return c.quote === '' ? `"${c.body}"${suffix}` : `"${c.body}" on “${c.quote}”${suffix}`;
}

export function formatFileEntry(m: EnrichedMeta): string {
  const title = m.title ?? m.path;
  const parts: string[] = [`**${title}** (${m.path})`];
  if (m.description) parts.push(m.description);
  if (m.tags.length > 0) parts.push(`tags: ${m.tags.join(', ')}`);
  if (m.graphRole) parts.push(`graph: ${m.graphRole}`);
  const fmStatus = typeof m.frontmatter.status === 'string' ? m.frontmatter.status : null;
  const fmType = typeof m.frontmatter.type === 'string' ? m.frontmatter.type : null;
  if (fmStatus) parts.push(`status: ${fmStatus}`);
  if (fmType) parts.push(`type: ${fmType}`);
  if (m.schemas_applicable && m.schemas_applicable.length > 0) {
    parts.push(`schemas: ${m.schemas_applicable.join(', ')}`);
  }
  if (m.commentCount !== null && m.commentCount > 0) {
    let line = `⚠ ${m.commentCount} unresolved comment${m.commentCount === 1 ? '' : 's'}`;
    if (m.comments && m.comments.length > 0) {
      const notes = m.comments.slice(0, COMMENT_PREVIEW_CAP).map(formatCommentPreview);
      line += `: ${notes.join('; ')}${m.comments.length > COMMENT_PREVIEW_CAP ? '; …' : ''}`;
    }
    parts.push(line);
  }
  if (m.backlinkCount !== null) {
    let line = `backlinks: ${m.backlinkCount}`;
    if (m.backlinks && m.backlinks.length > 0) {
      const names = m.backlinks.slice(0, 5).map((b) => b.source);
      line += ` (${names.join(', ')}${m.backlinks.length > 5 ? ', …' : ''})`;
    }
    parts.push(line);
  }
  if (m.forwardLinkCount !== null) {
    let line = `forward links: ${m.forwardLinkCount}`;
    if (m.forwardLinks && m.forwardLinks.length > 0) {
      const names = m.forwardLinks.slice(0, 5).map((f) => (f.kind === 'doc' ? f.docName : f.url));
      line += ` (${names.join(', ')}${m.forwardLinks.length > 5 ? ', …' : ''})`;
    }
    parts.push(line);
  }
  if (m.history && m.history.length > 0) {
    const entries = m.history.map((h) => {
      const who =
        h.writerClassification === 'agent'
          ? `agent: ${h.writerName}`
          : h.writerClassification === 'principal'
            ? `human: ${h.writerName}`
            : `${h.writerClassification}: ${h.writerName}`;
      return `${h.hash.slice(0, 7)} [${who}] ${h.message}`;
    });
    parts.push(`OK edits: ${entries.join(' · ')}`);
  }
  if (m.projectHistory && m.projectHistory.length > 0) {
    const entries = m.projectHistory.map(
      (c) => `${c.hash.slice(0, 7)} ${c.authorName}: ${c.subject}`,
    );
    parts.push(`commits: ${entries.join(' · ')}`);
  }
  return `- ${parts.join(' — ')}`;
}

function buildStdoutProvenance(
  stages: Stage[],
  dirByPath: Map<string, DirectoryMeta>,
  fileByPath: Map<string, EnrichedMeta>,
  rebase: (p: string) => string,
): string {
  let stage: Stage | null = null;
  for (let i = stages.length - 1; i >= 0; i--) {
    const s = stages[i];
    const cmd = s.command;
    if (cmd === 'ls' || cmd === 'cat') {
      stage = s;
      break;
    }
    if ((cmd === 'head' || cmd === 'tail') && pathArgs(s).length > 0) {
      stage = s;
      break;
    }
  }
  if (!stage) return '';

  const operands = pathArgs(stage);

  if (stage.command === 'ls') {
    const dirArg = operands[operands.length - 1];
    if (!dirArg || dirArg === '.') return '';
    let n = dirArg.replace(/\/+/g, '/');
    if (n.startsWith('./')) n = n.slice(2);
    if (n.endsWith('/')) n = n.slice(0, -1);
    if (!n) return '';
    const key = rebase(n);
    if (!dirByPath.has(key)) return '';
    return `${key}/:\n`;
  }

  const wikiFiles = operands.filter((p) => isWikiPath(p) && fileByPath.has(rebase(p)));
  if (wikiFiles.length !== 1) return '';
  return `==> ${rebase(wikiFiles[0])} <==\n`;
}

function formatEnrichedBlock(enriched: EnrichedEntry[]): string {
  if (enriched.length === 0) return '';
  const lines: string[] = ['', '### Referenced files', ''];
  for (const e of enriched) {
    lines.push(isDirectoryMeta(e) ? formatDirectoryEntry(e) : formatFileEntry(e));
  }
  return lines.join('\n');
}

async function classifyPaths(
  cwd: string,
  paths: string[],
): Promise<{ files: string[]; dirs: string[] }> {
  const files: string[] = [];
  const dirs: string[] = [];
  await Promise.all(
    paths.map(async (p) => {
      try {
        const st = await stat(resolve(cwd, p));
        if (st.isDirectory()) {
          dirs.push(p);
        } else if (st.isFile()) {
          files.push(p);
        }
      } catch (err) {
        const code = (err as { code?: string }).code;
        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
          log.warn({ path: p, code }, 'stat failed for a reported path; dropping it');
        }
        return;
      }
    }),
  );
  return { files, dirs };
}

function errorCategoryResult(category: ErrorCategory, message: string) {
  const structured: ExecStructuredResult = {
    enrichedPaths: [],
    error: { category, message },
  };
  return textPlusStructured(message, structured, true);
}

function withPreviewUrls(
  entries: EnrichedEntry[],
  resolve: (docName: string) => { url: string; source: PreviewUrlSource } | null,
): ExecEnrichedEntry[] {
  return entries.map((entry) => {
    const docName = docNameFromPath(entry.path);
    const resolved = resolve(docName);
    const withFields: ExecEnrichedEntry = {
      ...entry,
      previewUrl: resolved?.url ?? null,
      ...(resolved ? { previewUrlSource: resolved.source } : {}),
    } as ExecEnrichedEntry;
    return withFields;
  });
}

function writeBlockedResult(target: string | null) {
  if (target === null) log.warn({}, 'the engine refused a write without naming the file');
  const named = target === null ? 'a file' : `'${target}'`;
  return errorCategoryResult(
    'write_blocked',
    `Write operation blocked: the command tried to write ${named}. exec is read-only. For document changes, use the \`write\` or \`edit\` tool.`,
  );
}

export async function buildExecResult(
  args: { command: string; cwd?: string },
  deps: ExecDeps,
): Promise<ReturnType<typeof textPlusStructured>> {
  const context = await resolveProjectServerContext(
    deps.resolveCwd,
    deps.config,
    deps.serverUrl,
    args.cwd,
  );
  if (!context.ok) {
    return errorCategoryResult('shell_construct_blocked', `exec failed: ${context.error}`);
  }
  const { cwd, executionCwd, config, url: resolvedServerUrl } = context;

  const advertisedSchemas = selectAdvertisedFrontmatterMappings(
    toEffectiveBase(config.contentRules as PersistedLinterConfig),
  );
  const enrichSchemaDeps =
    advertisedSchemas.length > 0
      ? {
          contentDir: resolve(cwd, config.content.dir),
          frontmatterSchemas: advertisedSchemas,
        }
      : {};

  const rebaseToProject =
    executionCwd === cwd
      ? (p: string) => p
      : (p: string) => relative(cwd, resolve(executionCwd, p));

  const parsed = parseCommand(args.command);
  if ('error' in parsed) {
    return errorCategoryResult(parsed.error.category, parsed.error.message);
  }
  const expanded = await expandGlobStages(parsed.stages, executionCwd);
  if ('error' in expanded) {
    return errorCategoryResult(expanded.error.category, expanded.error.message);
  }
  const stages = augmentStagesWithExcludes(expanded.stages);
  const effectiveCommand = serializeStages(stages);

  const scanRoots = [
    ...new Set(
      deriveScanRoots(parsed.stages)
        .map((r) => resolveWithinRoot(executionCwd, r))
        .filter((r) => r.ok)
        .map((r) => r.rel),
    ),
  ];
  const pre = await snapshotMtimesForRoots(executionCwd, scanRoots);

  const bash = createBashInstance(executionCwd);
  let stdout = '';
  let stderr = '';
  try {
    const result = await execBash(bash, effectiveCommand);
    if (result.exitCode !== 0) {
      const refused = erofsTarget(result.stderr);
      if (refused.blocked) return writeBlockedResult(refused.target);
    }
    stdout = result.stdout;
    stderr = result.stderr;
  } catch (err) {
    if (err instanceof StdoutOverflowError) {
      return errorCategoryResult(
        'output_overflow',
        `Output exceeded 16 MB buffer. Narrow the command (e.g., add a more specific grep pattern, use head, restrict the path).`,
      );
    }
    const refused = erofsTarget(err);
    if (refused.blocked) return writeBlockedResult(refused.target);
    log.warn({ err, command: args.command }, 'exec failed');
    return errorCategoryResult(
      'shell_construct_blocked',
      `exec failed: ${err instanceof Error ? err.message : String(err)}`,
    );
  }

  const post = await snapshotMtimesForRoots(executionCwd, scanRoots);
  const mtimeDiff = diffMtimes(pre.snapshot, post.snapshot);
  if (mtimeDiff.changed.length > 0) {
    log.error({ command: args.command, changed: mtimeDiff.changed }, 'files changed during exec');
    return errorCategoryResult(
      'security_invariant_violation',
      `Security invariant violated: file(s) in the content directory were modified during a read-only exec call: ${mtimeDiff.changed.join(', ')}. Either the read-only mount let a write through, or another writer (the live server, a human editor) touched these files at the same time. Logged.`,
    );
  }
  const sweepPartial = pre.truncated || post.truncated;

  const capped = applySoftCap(stdout);

  const rawPaths = extractReferencedPaths(stdout, stages);
  const paths = rawPaths.filter((p) => resolveWithinRoot(executionCwd, p).ok).map(rebaseToProject);
  const { files, dirs } = await classifyPaths(cwd, paths);
  const isSinglePathCat = stages.length === 1 && stages[0].command === 'cat' && files.length === 1;
  const fileEnriched: EnrichedMeta[] = await Promise.all(
    files.map((p) =>
      enrichPath(
        p,
        { projectDir: cwd, serverUrl: resolvedServerUrl, ...enrichSchemaDeps },
        {
          includeRichFields: isSinglePathCat,
        },
      ).catch(
        (): EnrichedMeta => ({
          path: p,
          tags: [],
          frontmatter: {},
          backlinkCount: null,
          backlinks: null,
          forwardLinkCount: null,
          forwardLinks: null,
          history: null,
          historySource: null,
          projectHistory: null,
          projectHistorySource: null,
          graphRole: null,
          commentCount: null,
          comments: null,
        }),
      ),
    ),
  );
  const dirEnriched: DirectoryMeta[] = await Promise.all(
    dirs.map((p) =>
      enrichDirectoryRecursive(p, 1, {
        projectDir: cwd,
        serverUrl: resolvedServerUrl,
        ...enrichSchemaDeps,
      }).catch(
        (): DirectoryMeta => ({
          path: p,
          type: 'directory',
          directMdCount: 0,
          recursiveMdCount: 0,
          childDirCount: 0,
          truncated: false,
        }),
      ),
    ),
  );
  if (!isSinglePathCat && resolvedServerUrl && fileEnriched.length > 0) {
    const docNames = fileEnriched.map((f) => pathToDocName(f.path));
    const [counts, commentCounts] = await Promise.all([
      fetchBacklinkCountsBatch(resolvedServerUrl, docNames).catch(() => null),
      fetchCommentCountsBatch(resolvedServerUrl, docNames).catch(() => null),
    ]);
    for (const f of fileEnriched) {
      const docName = pathToDocName(f.path);
      const c = counts?.get(docName);
      if (typeof c === 'number') f.backlinkCount = c;
      const comments = commentCounts?.get(docName);
      if (typeof comments === 'number') f.commentCount = comments;
    }
  }
  const fileByPath = new Map(fileEnriched.map((e) => [e.path, e]));
  const dirByPath = new Map(dirEnriched.map((e) => [e.path, e]));
  const enriched: EnrichedEntry[] = [];
  for (const p of paths) {
    const f = fileByPath.get(p);
    if (f) {
      enriched.push(f);
      continue;
    }
    const d = dirByPath.get(p);
    if (d) enriched.push(d);
  }

  const binaryHits = detectBinaryArgs(stages);
  const banners: string[] = [];
  if (binaryHits.length > 0) {
    banners.push(
      `File${binaryHits.length > 1 ? 's' : ''} ${binaryHits.join(', ')} appear${binaryHits.length === 1 ? 's' : ''} to be binary (image/PDF/etc.) — exec returns text only (NG8). For binary retrieval, use native Read.`,
    );
  }
  const truncation = detectHeadTailTruncation(stages, stdout);
  if (truncation) {
    banners.push(truncation.banner);
  }
  if (stderr) {
    banners.push(`stderr: ${stderr.trim()}`);
  }
  if (sweepPartial) {
    banners.push(
      `Read-only mutation sweep was partial: the files in scope exceed the ${SCAN_CAP}-file cap, so only the first ${SCAN_CAP} were checked for unexpected writes. Narrow the command to a subdirectory for full sweep coverage.`,
    );
  }

  const bannerText = banners.length > 0 ? `${banners.join('\n')}\n\n` : '';
  const provenance = buildStdoutProvenance(stages, dirByPath, fileByPath, rebaseToProject);
  const stdoutText = provenance + capped.text;
  const enrichmentBlock = formatEnrichedBlock(enriched);
  const content = `${bannerText}${stdoutText}${enrichmentBlock}`;

  const { resolve: resolvePreviewUrl } = await buildListResolver({
    config,
    resolveCwd: async () => cwd,
  });
  const enrichedWithPreview: ExecEnrichedEntry[] = withPreviewUrls(enriched, resolvePreviewUrl);

  const structured: ExecStructuredResult = {
    enrichedPaths: enrichedWithPreview,
    stdoutTruncated: capped.truncated,
    cwd: executionCwd,
    ...(banners.length > 0 ? { warnings: banners } : {}),
  };
  return textPlusStructured(content, structured);
}

export function register(server: ServerInstance, deps: ExecDeps): void {
  server.registerTool(
    'exec',
    {
      description: DESCRIPTION,
      inputSchema: {
        command: z
          .string()
          .describe(
            'Read-only bash command (allowlist: cat, ls, grep, find, head, tail, wc, sort, uniq, cut; pipes OK)',
          ),
        cwd: z
          .string()
          .optional()
          .describe(
            'Absolute host path to run the command from. Defaults only when the MCP client advertises exactly one root; otherwise pass `cwd` explicitly.',
          ),
      },
      outputSchema: outputSchemaWithText({
        enrichedPaths: looseObjectArray.describe(
          'Per-referenced-file metadata: frontmatter, backlink/forward-link counts, unresolved comment threads (`commentCount`, plus `comments` on a single-file read), recent shadow-repo activity, and a route-only previewUrl. Directory entries carry a recursive `commentCount` + `commentedDocs`.',
        ),
        stdoutTruncated: z
          .boolean()
          .optional()
          .describe('True when stdout was truncated by the soft cap.'),
        warnings: z
          .array(z.string())
          .optional()
          .describe(
            'Tool-level warnings — head/tail truncation, binary detection, stderr, partial mutation-sweep coverage.',
          ),
        cwd: z.string().optional().describe('Absolute directory the command ran in.'),
        error: z
          .object({ category: z.string(), message: z.string() })
          .optional()
          .describe('Present on failure — the error category + message.'),
      }),
    },
    async (args: { command: string; cwd?: string }) => {
      try {
        return await buildExecResult(args, deps);
      } catch (err) {
        const message = `exec handler error: ${err instanceof Error ? err.message : String(err)}`;
        return errorCategoryResult('shell_construct_blocked', message);
      }
    },
  );
}