diffsplain 0.5.0 → 0.6.0

package/scripts/coding-agents.mjs

@@ -1,21 +1,77 @@
 import { constants } from 'node:fs';
 import { access } from 'node:fs/promises';
 import {
-  basename,
   delimiter,
   dirname,
   isAbsolute,
   join,
 } from 'node:path';
 
-export const codingAgents = [
-  'codex',
-  'claude',
-  'copilot',
-  'cursor',
-  'opencode',
+export const codingAgentCapabilities = {
+  codex: { binary: 'codex', model: true, reasoning: true },
+  claude: { binary: 'claude', model: true, reasoning: false },
+  copilot: { binary: 'copilot', model: true, reasoning: false },
+  cursor: { binary: 'cursor-agent', model: true, reasoning: false },
+  opencode: { binary: 'opencode', model: true, reasoning: true },
+};
+
+export const codingAgents = Object.keys(codingAgentCapabilities);
+
+export function agentSupportsReasoning(agent) {
+  return codingAgentCapabilities[agent]?.reasoning === true;
+}
+
+export function assertReasoningSupported(agent, reasoning) {
+  if (reasoning && !agentSupportsReasoning(agent)) {
+    throw new Error(
+      `--reasoning is supported only by codex and opencode; ${agent} does not support it.`,
+    );
+  }
+}
+
+const summaryEnvironmentNames = [
+  'CODEX_HOME',
+  'COMSPEC',
+  'HOME',
+  'HOMEDRIVE',
+  'HOMEPATH',
+  'HTTP_PROXY',
+  'HTTPS_PROXY',
+  'LANG',
+  'LC_ALL',
+  'NODE_EXTRA_CA_CERTS',
+  'NO_PROXY',
+  'PATH',
+  'SSL_CERT_FILE',
+  'SystemRoot',
+  'SYSTEMROOT',
+  'TEMP',
+  'TERM',
+  'TMP',
+  'TMPDIR',
+  'USERPROFILE',
 ];
 
+export function summaryAgentEnvironment(env = process.env) {
+  return Object.fromEntries(
+    summaryEnvironmentNames
+      .filter((name) => typeof env[name] === 'string')
+      .map((name) => [name, env[name]]),
+  );
+}
+
+const cursorDisabledReason =
+  'Cursor review is disabled: Cursor Agent has no supported read-only, no-network, no-tool mode.';
+
+export function agentDisabledReason(agent) {
+  if (agent === 'cursor') return cursorDisabledReason;
+  return undefined;
+}
+
+export const enabledCodingAgents = codingAgents.filter(
+  (agent) => !agentDisabledReason(agent),
+);
+
 async function executable(path) {
   try {
     await access(
@@ -28,25 +84,15 @@ async function executable(path) {
   }
 }
 
-export async function findCommand(
-  command,
-  {
-    env = process.env,
-    platform = process.platform,
-  } = {},
-) {
-  if (
-    isAbsolute(command) ||
-    command.includes('/') ||
-    command.includes('\\')
-  ) {
-    return (await executable(command)) ? command : undefined;
-  }
+function commandExtensions(platform, env) {
+  return platform === 'win32'
+    ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')
+    : [''];
+}
 
+async function findOnPath(command, env, platform) {
   const extensions =
-    platform === 'win32'
-      ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')
-      : [''];
+    commandExtensions(platform, env);
   const directories = (env.PATH || '').split(delimiter).filter(Boolean);
   for (const directory of directories) {
     for (const extension of extensions) {
@@ -58,10 +104,26 @@ export async function findCommand(
   return undefined;
 }
 
+export async function findCommand(
+  command,
+  {
+    env = process.env,
+    platform = process.platform,
+  } = {},
+) {
+  const direct =
+    isAbsolute(command) ||
+    command.includes('/') ||
+    command.includes('\\');
+  if (direct) return (await executable(command)) ? command : undefined;
+  return findOnPath(command, env, platform);
+}
+
 export async function commandAvailable(command, options) {
   return Boolean(await findCommand(command, options));
 }
 
+// fallow-ignore-next-line complexity -- validation and fallback share one public selector.
 export async function selectCodingAgent(
   requested,
   available = commandAvailable,
@@ -69,23 +131,26 @@ export async function selectCodingAgent(
   if (requested) {
     if (!codingAgents.includes(requested)) {
       throw new Error(
-        `Unsupported agent "${requested}". Choose ${codingAgents.join(', ')}.`,
+        `Unsupported agent "${requested}". Choose ${enabledCodingAgents.join(', ')}.`,
       );
     }
+    const disabled = agentDisabledReason(requested);
+    if (disabled) throw new Error(disabled);
     if (!(await available(requested))) {
       throw new Error(`Coding agent "${requested}" is not available.`);
     }
     return requested;
   }
 
-  for (const agent of codingAgents) {
+  for (const agent of enabledCodingAgents) {
     if (await available(agent)) return agent;
   }
   throw new Error(
-    `No coding agent is available. Install one of: ${codingAgents.join(', ')}.`,
+    `No coding agent is available. Install one of: ${enabledCodingAgents.join(', ')}. ${cursorDisabledReason}`,
   );
 }
 
+// fallow-ignore-next-line complexity -- each supported agent has one override rule.
 export function codingAgentBinary(
   agent,
   {
@@ -94,8 +159,14 @@ export function codingAgentBinary(
   } = {},
 ) {
   if (agent === 'codex') return codexBin || env.CODEX_BIN || agent;
-  if (agent === 'cursor') return env.CURSOR_BIN || 'cursor-agent';
-  return env[`${agent.toUpperCase()}_BIN`] || agent;
+  if (agent === 'cursor') {
+    return env.CURSOR_BIN || codingAgentCapabilities.cursor.binary;
+  }
+  return (
+    env[`${agent.toUpperCase()}_BIN`] ||
+    codingAgentCapabilities[agent]?.binary ||
+    agent
+  );
 }
 
 function parseJsonText(text, agent) {
@@ -108,161 +179,179 @@ function parseJsonText(text, agent) {
   }
 }
 
-export function parseAgentResponse(agent, stdout) {
-  if (agent === 'claude') {
-    const envelope = parseJsonText(stdout, 'Claude');
-    if (envelope?.structured_output) return envelope.structured_output;
-    if (typeof envelope?.result === 'string') {
-      return parseJsonText(envelope.result, 'Claude');
-    }
-    return envelope;
+function parseClaudeResponse(stdout) {
+  const envelope = parseJsonText(stdout, 'Claude');
+  if (envelope?.structured_output) return envelope.structured_output;
+  if (typeof envelope?.result === 'string') {
+    return parseJsonText(envelope.result, 'Claude');
   }
+  return envelope;
+}
 
-  if (agent === 'opencode') {
-    const events = stdout
-      .split('\n')
-      .filter(Boolean)
-      .map((line) => {
-        try {
-          return JSON.parse(line);
-        } catch {
-          return undefined;
-        }
-      });
-    const parts = events
-      .filter((event) => event?.type === 'text' && event.part?.text)
-      .map((event) => event.part.text);
-    if (parts.length) return parseJsonText(parts.join(''), 'OpenCode');
-    throw new Error('OpenCode did not return summary JSON');
+function parseEvent(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return undefined;
   }
+}
 
-  if (agent === 'cursor') {
-    const envelope = parseJsonText(stdout, 'Cursor');
-    if (typeof envelope?.result === 'string') {
-      return parseJsonText(envelope.result, 'Cursor');
-    }
-    return envelope;
+function parseOpenCodeResponse(stdout) {
+  const parts = stdout
+    .split('\n')
+    .filter(Boolean)
+    .map(parseEvent)
+    .filter((event) => event?.type === 'text' && event.part?.text)
+    .map((event) => event.part.text);
+  if (!parts.length) throw new Error('OpenCode did not return summary JSON');
+  return parseJsonText(parts.join(''), 'OpenCode');
+}
+
+function parseCursorResponse(stdout) {
+  const envelope = parseJsonText(stdout, 'Cursor');
+  if (typeof envelope?.result === 'string') {
+    return parseJsonText(envelope.result, 'Cursor');
   }
+  return envelope;
+}
 
+export function parseAgentResponse(agent, stdout) {
+  if (agent === 'claude') return parseClaudeResponse(stdout);
+  if (agent === 'opencode') return parseOpenCodeResponse(stdout);
+  if (agent === 'cursor') return parseCursorResponse(stdout);
   const label = agent === 'copilot' ? 'Copilot' : 'Codex';
   return parseJsonText(stdout, label);
 }
 
-export function agentCommand({
-  agent,
-  binary = agent,
+function codexCommand({
+  binary,
   model,
   reasoning,
   prompt,
-  schema,
   schemaPath,
-  inputPath,
-  workingDirectory,
-  env = process.env,
+  summaryDirectory,
+  summaryEnv,
 }) {
-  if (agent === 'codex') {
-    const args = [
-      'exec',
-      '--ephemeral',
-      '--sandbox',
-      'read-only',
-      '--ignore-user-config',
-      '--color',
-      'never',
-      '--skip-git-repo-check',
-      '-C',
-      workingDirectory,
-      '--output-schema',
-      schemaPath,
-    ];
-    if (model) args.push('--model', model);
-    if (reasoning) {
-      args.push(
-        '--config',
-        `model_reasoning_effort=${JSON.stringify(reasoning)}`,
-      );
-    }
-    args.push(prompt);
-    return { command: binary, args, input: 'stdin' };
-  }
-
-  if (agent === 'claude') {
-    const args = [
-      '--print',
-      '--output-format',
-      'json',
-      '--json-schema',
-      JSON.stringify(schema),
-      '--tools',
-      '',
-      '--no-session-persistence',
-    ];
-    if (model) args.push('--model', model);
-    args.push(prompt);
-    return { command: binary, args, input: 'stdin' };
-  }
-
-  if (agent === 'copilot') {
-    const schemaText = JSON.stringify(schema);
-    const args = [
-      '--silent',
-      '--no-ask-user',
-      '--no-color',
-      '--no-custom-instructions',
-      '--no-remote',
-      '--no-remote-export',
-      `--add-dir=${dirname(inputPath)}`,
-    ];
-    if (model) args.push('--model', model);
+  const args = [
+    'exec',
+    '--ephemeral',
+    '--sandbox',
+    'read-only',
+    '--ignore-user-config',
+    '--ignore-rules',
+    '--color',
+    'never',
+    '--skip-git-repo-check',
+    '-C',
+    summaryDirectory,
+    '--output-schema',
+    schemaPath,
+    '--config',
+    'mcp_servers={}',
+    '--config',
+    'plugins={}',
+    '--config',
+    'shell_environment_policy.inherit="none"',
+    '--config',
+    'sandbox_workspace_write.network_access=false',
+    '--config',
+    'web_search="disabled"',
+  ];
+  if (model) args.push('--model', model);
+  if (reasoning) {
     args.push(
-      '--prompt',
-      `${prompt}\n\nRead the snapshot from @${inputPath}. Return JSON that matches this schema:\n${schemaText}`,
+      '--config',
+      `model_reasoning_effort=${JSON.stringify(reasoning)}`,
     );
-    return { command: binary, args, input: 'none' };
   }
+  args.push(prompt);
+  return {
+    command: binary,
+    args,
+    input: 'stdin',
+    cwd: summaryDirectory,
+    env: summaryEnv,
+  };
+}
 
-  if (agent === 'cursor') {
-    const args = ['--print', '--trust', '--output-format', 'json'];
-    if (model) args.push('--model', model);
-    args.push(
-      `${prompt}\n\nRead the snapshot from @${basename(inputPath)}. Return only JSON that matches this schema:\n${JSON.stringify(schema)}`,
-    );
-    return {
-      command: binary,
-      args,
-      input: 'none',
-      cwd: dirname(inputPath),
-    };
-  }
+function claudeCommand({
+  binary,
+  model,
+  prompt,
+  schema,
+  summaryDirectory,
+  summaryEnv,
+}) {
+  const args = [
+    '--print',
+    '--output-format',
+    'json',
+    '--json-schema',
+    JSON.stringify(schema),
+    '--tools',
+    '',
+    '--no-session-persistence',
+  ];
+  if (model) args.push('--model', model);
+  args.push(prompt);
+  return {
+    command: binary,
+    args,
+    input: 'stdin',
+    cwd: summaryDirectory,
+    env: summaryEnv,
+  };
+}
 
-  let config = {};
-  try {
-    const parsed = JSON.parse(env.OPENCODE_CONFIG_CONTENT || '{}');
-    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-      config = parsed;
-    }
-  } catch {
-    // Replace invalid inline config with the safe settings for this run.
-  }
-  const configuredAgents =
-    config.agent &&
-    typeof config.agent === 'object' &&
-    !Array.isArray(config.agent)
-      ? config.agent
-      : {};
-  const configuredBuild =
-    configuredAgents.build &&
-    typeof configuredAgents.build === 'object' &&
-    !Array.isArray(configuredAgents.build)
-      ? configuredAgents.build
-      : {};
+function copilotCommand({
+  binary,
+  inputPath,
+  model,
+  prompt,
+  schema,
+  summaryDirectory,
+  summaryEnv,
+}) {
+  const schemaText = JSON.stringify(schema);
+  const args = [
+    '--silent',
+    '--no-ask-user',
+    '--no-color',
+    '--no-custom-instructions',
+    '--no-remote',
+    '--no-remote-export',
+    `--add-dir=${dirname(inputPath)}`,
+  ];
+  if (model) args.push('--model', model);
+  args.push(
+    '--prompt',
+    `${prompt}\n\nRead the snapshot from @${inputPath}. Return JSON that matches this schema:\n${schemaText}`,
+  );
+  return {
+    command: binary,
+    args,
+    input: 'none',
+    cwd: summaryDirectory,
+    env: summaryEnv,
+  };
+}
+
+function openCodeCommand({
+  binary,
+  model,
+  reasoning,
+  prompt,
+  schema,
+  summaryDirectory,
+  summaryEnv,
+}) {
   const args = [
     'run',
     '--pure',
     '--format',
     'json',
     '--dir',
-    dirname(inputPath),
+    summaryDirectory,
     '--agent',
     'build',
   ];
@@ -275,16 +364,14 @@ export function agentCommand({
     command: binary,
     args,
     input: 'stdin',
-    cwd: dirname(inputPath),
+    cwd: summaryDirectory,
     env: {
+      ...summaryEnv,
       OPENCODE_DB: ':memory:',
       OPENCODE_CONFIG_CONTENT: JSON.stringify({
-        ...config,
         permission: { '*': 'deny' },
         agent: {
-          ...configuredAgents,
           build: {
-            ...configuredBuild,
             permission: { '*': 'deny' },
           },
         },
@@ -292,3 +379,33 @@ export function agentCommand({
     },
   };
 }
+
+export function agentCommand({
+  agent,
+  binary = agent,
+  model,
+  reasoning,
+  prompt,
+  schema,
+  schemaPath,
+  inputPath,
+  env = process.env,
+}) {
+  const disabled = agentDisabledReason(agent);
+  if (disabled) throw new Error(disabled);
+  const options = {
+    binary,
+    inputPath,
+    model,
+    prompt,
+    reasoning,
+    schema,
+    schemaPath,
+    summaryDirectory: dirname(inputPath),
+    summaryEnv: summaryAgentEnvironment(env),
+  };
+  if (agent === 'codex') return codexCommand(options);
+  if (agent === 'claude') return claudeCommand(options);
+  if (agent === 'copilot') return copilotCommand(options);
+  return openCodeCommand(options);
+}