@gong-ym/ai-spec-auto 0.2.3

package/src/executor/executor-selector.js

@@ -0,0 +1,139 @@
+const { ExecutorError } = require('./types');
+
+const MODE_DEFAULTS = {
+  'local-assisted': 'cursor',
+  'local-auto': 'codex',
+  'remote-orchestrated': 'codex',
+};
+
+const DEFAULT_FALLBACK_EXECUTORS = ['claude-code', 'codex', 'cursor'];
+
+function normalizeExecutorName(name) {
+  return String(name || '').trim();
+}
+
+function pushCandidate(candidates, name, source, reason) {
+  const executor = normalizeExecutorName(name);
+  if (!executor) return;
+  candidates.push({ executor, source, reason });
+}
+
+function uniqueCandidates(candidates) {
+  const seen = new Set();
+  const result = [];
+  for (const item of candidates) {
+    if (seen.has(item.executor)) continue;
+    seen.add(item.executor);
+    result.push(item);
+  }
+  return result;
+}
+
+class ExecutorSelector {
+  async select(input = {}) {
+    const registry = input.registry;
+    if (!registry) {
+      throw new ExecutorError('EXECUTOR_REGISTRY_REQUIRED', '缺少 ExecutorRegistry，无法选择执行器。');
+    }
+
+    const warnings = [];
+    const fallbackTried = [];
+    const candidates = [];
+    const mode = input.mode || 'local-assisted';
+    const policyExecution = input.policy && input.policy.execution ? input.policy.execution : {};
+    const agentProfile = input.agentProfile || {};
+
+    pushCandidate(candidates, input.cliExecutor, 'cli', 'CLI 显式指定 executor');
+    pushCandidate(candidates, agentProfile.defaultExecutor || agentProfile.executor, 'agent-profile', 'Agent Profile 指定 defaultExecutor');
+    pushCandidate(candidates, policyExecution.defaultExecutor, 'policy', 'policy.execution.defaultExecutor 指定执行器');
+    pushCandidate(candidates, MODE_DEFAULTS[mode] || MODE_DEFAULTS['local-assisted'], 'mode', `${mode} 模式默认执行器`);
+
+    const fallbackExecutors = agentProfile.fallbackExecutors ||
+      policyExecution.fallbackExecutors ||
+      DEFAULT_FALLBACK_EXECUTORS;
+    for (const fallback of fallbackExecutors) {
+      pushCandidate(candidates, fallback, 'fallback', 'fallbackExecutors 候选执行器');
+    }
+
+    for (const candidate of uniqueCandidates(candidates)) {
+      const provider = registry.get(candidate.executor);
+      if (!provider) {
+        fallbackTried.push(candidate.executor);
+        warnings.push({
+          code: 'EXECUTOR_NOT_REGISTERED',
+          message: `执行器 ${candidate.executor} 未注册，已尝试下一个候选。`,
+        });
+        continue;
+      }
+
+      if (input.dryRun === true) {
+        return {
+          executor: candidate.executor,
+          provider,
+          reason: `${candidate.reason}（dry-run 仅验证选择和 prepare）`,
+          availability: {
+            available: true,
+            reason: null,
+            fixSuggestion: null,
+            version: 'dry-run',
+          },
+          fallbackTried,
+          warnings,
+        };
+      }
+
+      let availability;
+      try {
+        availability = await provider.checkAvailability({
+          projectRoot: input.projectRoot,
+          worktreePath: input.worktreePath || null,
+          env: input.env || process.env,
+        });
+      } catch (error) {
+        availability = {
+          available: false,
+          reason: `执行器可用性检查失败：${error.message}`,
+          fixSuggestion: '请检查执行器安装状态，或切换其他执行器。',
+          version: null,
+        };
+      }
+
+      if (availability.available) {
+        if (fallbackTried.length > 0 && input.cliExecutor) {
+          warnings.push({
+            code: 'CLI_EXECUTOR_FALLBACK',
+            message: 'CLI 指定的执行器不可用，已尝试 fallback 执行器。',
+          });
+        }
+        return {
+          executor: candidate.executor,
+          provider,
+          reason: candidate.reason,
+          availability,
+          fallbackTried,
+          warnings,
+        };
+      }
+
+      fallbackTried.push(candidate.executor);
+      if (candidate.source === 'cli') {
+        warnings.push({
+          code: 'CLI_EXECUTOR_UNAVAILABLE',
+          message: `CLI 指定的执行器不可用：${availability.reason || candidate.executor}`,
+        });
+      }
+    }
+
+    throw new ExecutorError(
+      'EXECUTOR_NOT_AVAILABLE',
+      '没有可用执行器，请安装 Codex / Cursor / Claude Code，或调整 policy.execution.defaultExecutor。',
+      '请执行 ai-spec-auto executor check 查看修复建议。'
+    );
+  }
+}
+
+module.exports = {
+  DEFAULT_FALLBACK_EXECUTORS,
+  ExecutorSelector,
+  MODE_DEFAULTS,
+};

package/src/executor/executor-timeout.js

@@ -0,0 +1,36 @@
+const { ExecutorError } = require('./types');
+
+function withExecutorTimeout(taskFactory, timeoutMs) {
+  const effectiveTimeout = Number(timeoutMs) > 0 ? Number(timeoutMs) : 10 * 60 * 1000;
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      reject(new ExecutorError(
+        'EXECUTOR_TIMEOUT',
+        `执行器执行超时，已超过 ${effectiveTimeout}ms。`,
+        '请缩小任务范围，或提高 timeoutMs 后重试。'
+      ));
+    }, effectiveTimeout);
+
+    Promise.resolve()
+      .then(taskFactory)
+      .then((result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(result);
+      })
+      .catch((error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        reject(error);
+      });
+  });
+}
+
+module.exports = {
+  withExecutorTimeout,
+};

package/src/executor/providers/base-provider-utils.js

@@ -0,0 +1,189 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFile } = require('child_process');
+
+function getExecutionRoot(projectRoot, worktreePath) {
+  return path.resolve(worktreePath || projectRoot || process.cwd());
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function writeJson(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function writeText(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function toRelative(rootDir, targetPath) {
+  if (!targetPath) return null;
+  if (!path.isAbsolute(targetPath)) return targetPath.replace(/\\/g, '/');
+  const relative = path.relative(rootDir, targetPath);
+  if (!relative || relative === '') return '.';
+  if (relative.startsWith('..') || path.isAbsolute(relative)) return '<external-path>';
+  return relative.replace(/\\/g, '/');
+}
+
+function commandExists(command, env = process.env) {
+  const pathValue = env.PATH || '';
+  if (!pathValue) return false;
+  const extensions = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+  return pathValue.split(path.delimiter).some((dir) => {
+    if (!dir) return false;
+    return extensions.some((ext) => {
+      const candidate = path.join(dir, `${command}${ext}`);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return true;
+      } catch (_error) {
+        return false;
+      }
+    });
+  });
+}
+
+function hasCursorConfig() {
+  const home = os.homedir();
+  return fs.existsSync(path.join(home, 'Library/Application Support/Cursor')) ||
+    fs.existsSync(path.join(home, '.cursor'));
+}
+
+function sanitizeContextBundle(contextBundle = {}) {
+  return {
+    schemaVersion: contextBundle.schemaVersion || '1.0.0',
+    stage: contextBundle.stage || null,
+    tokenEstimate: contextBundle.tokenEstimate || null,
+    loadedAssets: Array.isArray(contextBundle.loadedAssets)
+      ? contextBundle.loadedAssets.map((asset) => ({
+        kind: asset.kind,
+        slug: asset.slug,
+        version: asset.version,
+        checksum: asset.checksum,
+        source: asset.source,
+        tokenEstimate: asset.tokenEstimate || 0,
+      }))
+      : [],
+    warnings: Array.isArray(contextBundle.warnings)
+      ? contextBundle.warnings.map((item) => (typeof item === 'string' ? item : item.message || String(item)))
+      : [],
+  };
+}
+
+function getRequirementSummary(input = {}) {
+  if (input.run && input.run.requirement && input.run.requirement.summary) return input.run.requirement.summary;
+  return String(input.requirement || '').trim().slice(0, 80) || '未命名需求';
+}
+
+function createCommonExecutorInput(input = {}, providerName) {
+  const run = input.run || {};
+  return {
+    schemaVersion: '1.0.0',
+    provider: providerName,
+    runId: run.runId || '',
+    requirementSummary: getRequirementSummary(input),
+    stage: input.stage || 'implementation',
+    context: sanitizeContextBundle(input.contextBundle),
+    indexFiles: [
+      '.ai-spec/project.json',
+      '.ai-spec/policy.json',
+      '.ai-spec/context-index.json',
+      '.agents/registry.index.json',
+    ],
+    privacy: {
+      sourceCodeIncluded: false,
+      rawPromptIncluded: false,
+      rawResponseIncluded: false,
+      absolutePathIncluded: false,
+    },
+  };
+}
+
+function renderCommonTaskMarkdown(input = {}, providerDisplayName) {
+  const executorInput = createCommonExecutorInput(input, providerDisplayName);
+  const assets = executorInput.context.loadedAssets
+    .map((asset) => `- ${asset.kind}：${asset.slug}@${asset.version}（${asset.checksum || '无 checksum'}）`)
+    .join('\n') || '- 无';
+  return [
+    `# ${providerDisplayName} 执行任务`,
+    '',
+    '此文件由 ai-spec-auto 生成，用于执行器读取任务摘要和上下文索引。',
+    '',
+    `- runId：${executorInput.runId}`,
+    `- 阶段：${executorInput.stage}`,
+    `- 需求摘要：${executorInput.requirementSummary}`,
+    `- Context 阶段：${executorInput.context.stage || '未构建'}`,
+    `- Context token 估算：${executorInput.context.tokenEstimate ? executorInput.context.tokenEstimate.inputTokens : 0}`,
+    '',
+    '## 允许读取的索引文件',
+    '',
+    '- .ai-spec/project.json',
+    '- .ai-spec/policy.json',
+    '- .ai-spec/context-index.json',
+    '- .agents/registry.index.json',
+    '',
+    '## 已加载资产索引',
+    '',
+    assets,
+    '',
+    '## 隐私与边界',
+    '',
+    '- 不要上传源码。',
+    '- 不要自动 push / merge / 创建 PR。',
+    '- 不要把源码正文、完整 prompt 或完整 response 写入结果。',
+    '- 如果需要人工确认，请返回 human_review_required。',
+    '',
+  ].join('\n');
+}
+
+function runCommand(command, args, options = {}) {
+  return new Promise((resolve) => {
+    execFile(command, args, {
+      cwd: options.cwd,
+      env: options.env || process.env,
+      timeout: options.timeoutMs || 10 * 60 * 1000,
+      maxBuffer: 1024 * 1024,
+    }, (error, stdout, stderr) => {
+      if (error) {
+        resolve({
+          ok: false,
+          code: error.code || 'COMMAND_FAILED',
+          signal: error.signal || null,
+          timedOut: error.killed || error.code === 'ETIMEDOUT',
+          stdout: stdout || '',
+          stderr: stderr || '',
+          message: error.message,
+        });
+        return;
+      }
+      resolve({
+        ok: true,
+        code: 0,
+        signal: null,
+        timedOut: false,
+        stdout: stdout || '',
+        stderr: stderr || '',
+        message: '',
+      });
+    });
+  });
+}
+
+module.exports = {
+  commandExists,
+  createCommonExecutorInput,
+  ensureDir,
+  getExecutionRoot,
+  hasCursorConfig,
+  renderCommonTaskMarkdown,
+  runCommand,
+  sanitizeContextBundle,
+  toRelative,
+  writeJson,
+  writeText,
+};

package/src/executor/providers/claude-code-executor-provider.js

@@ -0,0 +1,128 @@
+const fs = require('fs');
+const path = require('path');
+const {
+  ExecutorCapability,
+  ExecutorStatus,
+  ExecutorType,
+  IExecutorProvider,
+  createExecutionResult,
+} = require('../types');
+const {
+  commandExists,
+  getExecutionRoot,
+  renderCommonTaskMarkdown,
+  runCommand,
+  toRelative,
+  writeText,
+} = require('./base-provider-utils');
+
+class ClaudeCodeExecutorProvider extends IExecutorProvider {
+  get name() {
+    return ExecutorType.CLAUDE_CODE;
+  }
+
+  get displayName() {
+    return 'Claude Code';
+  }
+
+  get capabilities() {
+    return [
+      ExecutorCapability.READ,
+      ExecutorCapability.WRITE,
+      ExecutorCapability.SHELL,
+      ExecutorCapability.TEST,
+      ExecutorCapability.HEADLESS,
+      ExecutorCapability.LONG_RUNNING,
+    ];
+  }
+
+  async checkAvailability(input = {}) {
+    const available = commandExists('claude', input.env || process.env);
+    return {
+      available,
+      reason: available ? null : '未检测到 Claude Code CLI',
+      fixSuggestion: available ? null : '请安装 Claude Code CLI，或切换为 codex / cursor。',
+      version: available ? 'unknown' : null,
+    };
+  }
+
+  async prepare(input = {}) {
+    const executionRoot = getExecutionRoot(input.projectRoot, input.worktreePath);
+    const runId = input.run && input.run.runId ? input.run.runId : 'unknown-run';
+    const taskPath = path.join(executionRoot, '.ai-spec/runs', runId, 'claude-task.md');
+    const warnings = [];
+    if (!fs.existsSync(path.join(executionRoot, 'CLAUDE.md'))) {
+      warnings.push({
+        code: 'CLAUDE_POINTER_MISSING',
+        message: '未检测到 CLAUDE.md，请先执行 init 或确认 Claude Code 指针文件。',
+      });
+    }
+    writeText(taskPath, renderCommonTaskMarkdown(input, 'Claude Code'));
+    return {
+      prepared: true,
+      executorInputPath: null,
+      instructionFilePath: toRelative(executionRoot, taskPath),
+      warnings,
+      errors: [],
+    };
+  }
+
+  async execute(input = {}) {
+    if (input.dryRun) {
+      return createExecutionResult({
+        success: true,
+        status: ExecutorStatus.SKIPPED,
+        summary: 'Claude Code dry-run 已完成：仅生成任务文件，未调用真实外部命令。',
+      });
+    }
+
+    const availability = await this.checkAvailability(input);
+    if (!availability.available) {
+      return createExecutionResult({
+        success: false,
+        status: ExecutorStatus.FAILED,
+        summary: availability.reason,
+        error: {
+          code: 'EXECUTOR_NOT_AVAILABLE',
+          message: availability.reason,
+          suggestion: availability.fixSuggestion,
+        },
+      });
+    }
+
+    const result = await runCommand('claude', ['--file', input.instructionFilePath], {
+      cwd: getExecutionRoot(input.projectRoot, input.worktreePath),
+      timeoutMs: input.timeoutMs,
+      env: input.env || process.env,
+    });
+    if (!result.ok) {
+      return createExecutionResult({
+        success: false,
+        status: result.timedOut ? ExecutorStatus.TIMEOUT : ExecutorStatus.FAILED,
+        summary: result.timedOut ? 'Claude Code 执行超时。' : 'Claude Code 执行失败。',
+        error: {
+          code: result.timedOut ? 'EXECUTOR_TIMEOUT' : 'EXECUTOR_RUN_FAILED',
+          message: result.stderr || result.message || 'Claude Code 执行失败。',
+          suggestion: '请查看本地 Claude Code CLI 状态，或改用 dry-run / 其他执行器。',
+        },
+      });
+    }
+    return createExecutionResult({
+      success: true,
+      status: ExecutorStatus.SUCCEEDED,
+      summary: 'Claude Code 执行完成。',
+    });
+  }
+
+  async verify() {
+    return { executed: false, passed: null, command: null, summary: '本轮未接入 Claude Code verify。' };
+  }
+
+  async cleanup() {
+    return { cleaned: true, warnings: [] };
+  }
+}
+
+module.exports = {
+  ClaudeCodeExecutorProvider,
+};

package/src/executor/providers/codex-executor-provider.js

@@ -0,0 +1,126 @@
+const path = require('path');
+const {
+  ExecutorCapability,
+  ExecutorStatus,
+  ExecutorType,
+  IExecutorProvider,
+  createExecutionResult,
+} = require('../types');
+const {
+  commandExists,
+  createCommonExecutorInput,
+  getExecutionRoot,
+  renderCommonTaskMarkdown,
+  runCommand,
+  toRelative,
+  writeJson,
+  writeText,
+} = require('./base-provider-utils');
+
+class CodexExecutorProvider extends IExecutorProvider {
+  get name() {
+    return ExecutorType.CODEX;
+  }
+
+  get displayName() {
+    return 'Codex';
+  }
+
+  get capabilities() {
+    return [
+      ExecutorCapability.READ,
+      ExecutorCapability.WRITE,
+      ExecutorCapability.SHELL,
+      ExecutorCapability.TEST,
+      ExecutorCapability.HEADLESS,
+      ExecutorCapability.LONG_RUNNING,
+      ExecutorCapability.STRUCTURED_OUTPUT,
+    ];
+  }
+
+  async checkAvailability(input = {}) {
+    const available = commandExists('codex', input.env || process.env);
+    return {
+      available,
+      reason: available ? null : '未检测到 Codex CLI',
+      fixSuggestion: available ? null : '请安装 Codex CLI，或切换为 cursor / claude-code。',
+      version: available ? 'unknown' : null,
+    };
+  }
+
+  async prepare(input = {}) {
+    const executionRoot = getExecutionRoot(input.projectRoot, input.worktreePath);
+    const runId = input.run && input.run.runId ? input.run.runId : 'unknown-run';
+    const dir = path.join(executionRoot, '.codex/tmp', runId);
+    const executorInputPath = path.join(dir, 'executor-input.json');
+    const instructionFilePath = path.join(dir, 'instructions.md');
+    writeJson(executorInputPath, createCommonExecutorInput(input, this.name));
+    writeText(instructionFilePath, renderCommonTaskMarkdown(input, 'Codex'));
+    return {
+      prepared: true,
+      executorInputPath: toRelative(executionRoot, executorInputPath),
+      instructionFilePath: toRelative(executionRoot, instructionFilePath),
+      warnings: [],
+      errors: [],
+    };
+  }
+
+  async execute(input = {}) {
+    if (input.dryRun) {
+      return createExecutionResult({
+        success: true,
+        status: ExecutorStatus.SKIPPED,
+        summary: 'Codex dry-run 已完成：仅生成任务文件，未调用真实外部命令。',
+      });
+    }
+
+    const availability = await this.checkAvailability(input);
+    if (!availability.available) {
+      return createExecutionResult({
+        success: false,
+        status: ExecutorStatus.FAILED,
+        summary: availability.reason,
+        error: {
+          code: 'EXECUTOR_NOT_AVAILABLE',
+          message: availability.reason,
+          suggestion: availability.fixSuggestion,
+        },
+      });
+    }
+
+    const result = await runCommand('codex', ['exec', '--input', input.executorInputPath || input.instructionFilePath], {
+      cwd: getExecutionRoot(input.projectRoot, input.worktreePath),
+      timeoutMs: input.timeoutMs,
+      env: input.env || process.env,
+    });
+    if (!result.ok) {
+      return createExecutionResult({
+        success: false,
+        status: result.timedOut ? ExecutorStatus.TIMEOUT : ExecutorStatus.FAILED,
+        summary: result.timedOut ? 'Codex 执行超时。' : 'Codex 执行失败。',
+        error: {
+          code: result.timedOut ? 'EXECUTOR_TIMEOUT' : 'EXECUTOR_RUN_FAILED',
+          message: result.stderr || result.message || 'Codex 执行失败。',
+          suggestion: '请查看本地 Codex CLI 状态，或改用 dry-run / 其他执行器。',
+        },
+      });
+    }
+    return createExecutionResult({
+      success: true,
+      status: ExecutorStatus.SUCCEEDED,
+      summary: 'Codex 执行完成。',
+    });
+  }
+
+  async verify() {
+    return { executed: false, passed: null, command: null, summary: '本轮未接入执行器 verify。' };
+  }
+
+  async cleanup() {
+    return { cleaned: true, warnings: [] };
+  }
+}
+
+module.exports = {
+  CodexExecutorProvider,
+};