@gong-ym/ai-spec-auto 0.2.3

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

@@ -0,0 +1,99 @@
+const fs = require('fs');
+const path = require('path');
+const {
+  ExecutorCapability,
+  ExecutorStatus,
+  ExecutorType,
+  IExecutorProvider,
+  createExecutionResult,
+} = require('../types');
+const {
+  commandExists,
+  getExecutionRoot,
+  hasCursorConfig,
+  renderCommonTaskMarkdown,
+  toRelative,
+  writeText,
+} = require('./base-provider-utils');
+
+class CursorExecutorProvider extends IExecutorProvider {
+  get name() {
+    return ExecutorType.CURSOR;
+  }
+
+  get displayName() {
+    return 'Cursor';
+  }
+
+  get capabilities() {
+    return [
+      ExecutorCapability.READ,
+      ExecutorCapability.WRITE,
+      ExecutorCapability.INTERACTIVE,
+    ];
+  }
+
+  async checkAvailability(input = {}) {
+    const available = commandExists('cursor', input.env || process.env) || hasCursorConfig();
+    return {
+      available,
+      reason: available ? null : '未检测到 Cursor CLI 或 Cursor 配置',
+      fixSuggestion: available ? null : '请安装 Cursor，或切换为 codex / 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 taskPath = path.join(executionRoot, '.cursor/tmp', runId, 'task.md');
+    const warnings = [];
+    const rulePath = path.join(executionRoot, '.cursor/rules/ai-spec-auto.mdc');
+    if (!fs.existsSync(rulePath)) {
+      warnings.push({
+        code: 'CURSOR_RULE_MISSING',
+        message: '未检测到 .cursor/rules/ai-spec-auto.mdc，请先执行 init 或在 Cursor 中确认指针文件。',
+      });
+    }
+    writeText(taskPath, renderCommonTaskMarkdown(input, 'Cursor'));
+    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: 'Cursor dry-run 已完成：仅生成任务文件，未进行无头执行。',
+      });
+    }
+    return createExecutionResult({
+      success: false,
+      status: ExecutorStatus.HUMAN_REVIEW_REQUIRED,
+      summary: '当前 Cursor 环境更适合人工辅助模式，请在 IDE 中打开任务文件继续。',
+      error: {
+        code: 'EXECUTOR_PERMISSION_DENIED',
+        message: '当前 Cursor 环境不支持无头自动执行。',
+        suggestion: '请切换 Codex / Claude Code，或在 Cursor 中手动执行任务文件。',
+      },
+    });
+  }
+
+  async verify() {
+    return { executed: false, passed: null, command: null, summary: '本轮未接入 Cursor verify。' };
+  }
+
+  async cleanup() {
+    return { cleaned: true, warnings: [] };
+  }
+}
+
+module.exports = {
+  CursorExecutorProvider,
+};

package/src/executor/types.js

@@ -0,0 +1,137 @@
+const ExecutorType = {
+  CODEX: 'codex',
+  CURSOR: 'cursor',
+  CLAUDE_CODE: 'claude-code',
+  CUSTOM: 'custom',
+};
+
+const ExecutorCapability = {
+  READ: 'read',
+  WRITE: 'write',
+  SHELL: 'shell',
+  TEST: 'test',
+  INTERACTIVE: 'interactive',
+  HEADLESS: 'headless',
+  LONG_RUNNING: 'long-running',
+  STRUCTURED_OUTPUT: 'structured-output',
+};
+
+const ExecutorStatus = {
+  SUCCEEDED: 'succeeded',
+  FAILED: 'failed',
+  TIMEOUT: 'timeout',
+  SKIPPED: 'skipped',
+  HUMAN_REVIEW_REQUIRED: 'human_review_required',
+};
+
+const DEFAULT_EXECUTOR_TIMEOUT_MS = 10 * 60 * 1000;
+
+class ExecutorError extends Error {
+  constructor(code, message, suggestion) {
+    super(message);
+    this.name = 'ExecutorError';
+    this.code = code;
+    this.suggestion = suggestion || '';
+  }
+}
+
+class IExecutorProvider {
+  get name() {
+    throw new ExecutorError('EXECUTOR_PROVIDER_NOT_IMPLEMENTED', '执行器 Provider 未实现 name。');
+  }
+
+  get displayName() {
+    throw new ExecutorError('EXECUTOR_PROVIDER_NOT_IMPLEMENTED', '执行器 Provider 未实现 displayName。');
+  }
+
+  get capabilities() {
+    throw new ExecutorError('EXECUTOR_PROVIDER_NOT_IMPLEMENTED', '执行器 Provider 未实现 capabilities。');
+  }
+
+  async checkAvailability() {
+    throw new ExecutorError('EXECUTOR_PROVIDER_NOT_IMPLEMENTED', '执行器 Provider 未实现 checkAvailability。');
+  }
+
+  async prepare() {
+    throw new ExecutorError('EXECUTOR_PROVIDER_NOT_IMPLEMENTED', '执行器 Provider 未实现 prepare。');
+  }
+
+  async execute() {
+    throw new ExecutorError('EXECUTOR_PROVIDER_NOT_IMPLEMENTED', '执行器 Provider 未实现 execute。');
+  }
+
+  async verify() {
+    throw new ExecutorError('EXECUTOR_PROVIDER_NOT_IMPLEMENTED', '执行器 Provider 未实现 verify。');
+  }
+
+  async cleanup() {
+    throw new ExecutorError('EXECUTOR_PROVIDER_NOT_IMPLEMENTED', '执行器 Provider 未实现 cleanup。');
+  }
+}
+
+function createEmptyVerification() {
+  return {
+    executed: false,
+    passed: null,
+    command: null,
+    summary: null,
+  };
+}
+
+function createEmptyTokenUsage() {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+  };
+}
+
+function createExecutionResult(overrides = {}) {
+  return {
+    success: false,
+    status: ExecutorStatus.FAILED,
+    summary: '',
+    changedFiles: [],
+    verification: createEmptyVerification(),
+    tokenUsage: createEmptyTokenUsage(),
+    riskList: [],
+    error: null,
+    ...overrides,
+    verification: {
+      ...createEmptyVerification(),
+      ...(overrides.verification || {}),
+    },
+    tokenUsage: {
+      ...createEmptyTokenUsage(),
+      ...(overrides.tokenUsage || {}),
+    },
+    changedFiles: Array.isArray(overrides.changedFiles) ? overrides.changedFiles : [],
+    riskList: Array.isArray(overrides.riskList) ? overrides.riskList : [],
+  };
+}
+
+function createExecutorErrorResult(code, message, suggestion, status = ExecutorStatus.FAILED) {
+  return createExecutionResult({
+    success: false,
+    status,
+    summary: message,
+    error: {
+      code,
+      message,
+      suggestion: suggestion || '',
+    },
+  });
+}
+
+module.exports = {
+  DEFAULT_EXECUTOR_TIMEOUT_MS,
+  ExecutorCapability,
+  ExecutorError,
+  ExecutorStatus,
+  ExecutorType,
+  IExecutorProvider,
+  createEmptyTokenUsage,
+  createEmptyVerification,
+  createExecutionResult,
+  createExecutorErrorResult,
+};

package/src/git/branch-manager.js

@@ -0,0 +1,71 @@
+const { GitRepositoryDetector } = require('./git-repository-detector');
+const { runGit } = require('./git-command');
+const { createBranchName, createIssue } = require('./types');
+
+class BranchManager {
+  constructor(options = {}) {
+    this.detector = options.detector || new GitRepositoryDetector();
+  }
+
+  branchExists(repoRoot, branchName) {
+    return runGit(repoRoot, ['rev-parse', '--verify', '--quiet', `${branchName}^{commit}`], { allowFailure: true }).ok;
+  }
+
+  baseBranchExists(repoRoot, baseBranch) {
+    if (!baseBranch) return false;
+    return runGit(repoRoot, ['rev-parse', '--verify', '--quiet', `${baseBranch}^{commit}`], { allowFailure: true }).ok;
+  }
+
+  createUniqueBranchName(repoRoot, baseName, warnings) {
+    if (!this.branchExists(repoRoot, baseName)) return baseName;
+    warnings.push(createIssue('warning', 'BRANCH_ALREADY_EXISTS', `分支已存在，自动生成新分支名：${baseName}`, '无需处理'));
+    let index = 2;
+    let candidate = `${baseName}-${index}`;
+    while (this.branchExists(repoRoot, candidate)) {
+      index += 1;
+      candidate = `${baseName}-${index}`;
+    }
+    return candidate;
+  }
+
+  async createBranch(input = {}) {
+    const warnings = [];
+    const errors = [];
+    const detectorResult = this.detector.detect({ rootDir: input.repoRoot });
+    const baseBranch = input.baseBranch || detectorResult.currentBranch || '';
+    const branchNameBase = createBranchName({
+      branchPrefix: input.branchPrefix || 'ai',
+      runId: input.runId || 'run-local',
+      requirementSummary: input.requirementSummary || '需求执行',
+    });
+
+    if (!detectorResult.isGitRepository) {
+      errors.push(createIssue('error', 'GIT_REPOSITORY_NOT_FOUND', '目标目录不是 Git 仓库，无法创建分支', '请在 Git 仓库中执行'));
+      return { branchName: branchNameBase, baseBranch, created: false, warnings, errors };
+    }
+    if (detectorResult.isDetachedHead) {
+      errors.push(createIssue('error', 'GIT_DETACHED_HEAD', '当前仓库处于 detached HEAD，必须先切回分支', '请执行 git switch <branch> 后重试'));
+      return { branchName: branchNameBase, baseBranch, created: false, warnings, errors };
+    }
+    if (!this.baseBranchExists(detectorResult.repoRoot, baseBranch)) {
+      errors.push(createIssue('error', 'BASE_BRANCH_NOT_FOUND', `baseBranch 不存在：${baseBranch}`, '请检查 policy.branchPolicy.baseBranch 或切换到有效分支'));
+      return { branchName: branchNameBase, baseBranch, created: false, warnings, errors };
+    }
+
+    const branchName = this.createUniqueBranchName(detectorResult.repoRoot, branchNameBase, warnings);
+    const created = runGit(detectorResult.repoRoot, ['branch', branchName, baseBranch], { allowFailure: true });
+    if (!created.ok) {
+      errors.push(createIssue('error', 'BRANCH_CREATE_FAILED', `分支创建失败：${created.stderr.trim() || branchName}`, '请检查 Git 仓库状态'));
+      return { branchName, baseBranch, created: false, warnings, errors };
+    }
+    return { branchName, baseBranch, created: true, warnings, errors };
+  }
+
+  deleteBranch(repoRoot, branchName) {
+    return runGit(repoRoot, ['branch', '-D', branchName], { allowFailure: true });
+  }
+}
+
+module.exports = {
+  BranchManager,
+};

package/src/git/dirty-checker.js

@@ -0,0 +1,43 @@
+const { runGit } = require('./git-command');
+
+function parsePorcelainLine(line) {
+  const status = line.slice(0, 2);
+  const rawPath = line.slice(3).trim();
+  const filePath = rawPath.includes(' -> ') ? rawPath.split(' -> ').pop() : rawPath;
+  const indexStatus = status[0];
+  const worktreeStatus = status[1];
+  const untracked = status === '??';
+  return {
+    path: filePath,
+    status,
+    staged: !untracked && indexStatus !== ' ' && indexStatus !== '?',
+    unstaged: !untracked && worktreeStatus !== ' ' && worktreeStatus !== '?',
+    untracked,
+  };
+}
+
+class DirtyChecker {
+  check(input = {}) {
+    const repoRoot = input.repoRoot;
+    const status = runGit(repoRoot, ['status', '--porcelain'], { allowFailure: false });
+    const changedFiles = status.stdout
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map(parsePorcelainLine);
+
+    return {
+      clean: changedFiles.length === 0,
+      changedFiles,
+      summary: {
+        stagedCount: changedFiles.filter((item) => item.staged).length,
+        unstagedCount: changedFiles.filter((item) => item.unstaged).length,
+        untrackedCount: changedFiles.filter((item) => item.untracked).length,
+      },
+    };
+  }
+}
+
+module.exports = {
+  DirtyChecker,
+  parsePorcelainLine,
+};

package/src/git/dirty-strategy-handler.js

@@ -0,0 +1,29 @@
+const { BlockDirtyStrategy } = require('./strategies/block-dirty-strategy');
+const { IgnoreDirtyStrategy } = require('./strategies/ignore-dirty-strategy');
+const { PatchSnapshotStrategy } = require('./strategies/patch-snapshot-strategy');
+const { WipCommitStrategy } = require('./strategies/wip-commit-strategy');
+const { normalizeDirtyStrategy } = require('./types');
+
+class DirtyStrategyHandler {
+  constructor(options = {}) {
+    this.strategies = options.strategies || {
+      block: new BlockDirtyStrategy(options),
+      'patch-snapshot': new PatchSnapshotStrategy(options),
+      'wip-commit': new WipCommitStrategy(options),
+      ignore: new IgnoreDirtyStrategy(options),
+    };
+  }
+
+  async handle(input = {}) {
+    const strategy = normalizeDirtyStrategy(input.strategy);
+    return this.strategies[strategy].handle({
+      ...input,
+      strategy,
+      runId: input.runId || 'run-local',
+    });
+  }
+}
+
+module.exports = {
+  DirtyStrategyHandler,
+};

package/src/git/git-command.js

@@ -0,0 +1,37 @@
+const { spawnSync } = require('child_process');
+
+function runGit(repoRoot, args, options = {}) {
+  if (!repoRoot) {
+    throw new Error('缺少 repoRoot，无法执行 git 命令');
+  }
+  const result = spawnSync('git', args, {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      ...(options.env || {}),
+    },
+  });
+  const output = {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    args,
+  };
+  if (!output.ok && !options.allowFailure) {
+    const detail = (output.stderr || output.stdout || '').trim();
+    throw new Error(`git 命令执行失败：git ${args.join(' ')}${detail ? `，${detail}` : ''}`);
+  }
+  return output;
+}
+
+function isGitAvailable() {
+  const result = spawnSync('git', ['--version'], { encoding: 'utf8' });
+  return result.status === 0;
+}
+
+module.exports = {
+  isGitAvailable,
+  runGit,
+};

package/src/git/git-repository-detector.js

@@ -0,0 +1,45 @@
+const path = require('path');
+const { runGit } = require('./git-command');
+const { createIssue } = require('./types');
+
+class GitRepositoryDetector {
+  detect(input = {}) {
+    const rootDir = path.resolve(input.rootDir || process.cwd());
+    const result = {
+      isGitRepository: false,
+      repoRoot: null,
+      currentBranch: null,
+      isDetachedHead: false,
+      hasRemote: false,
+      remotes: [],
+      warnings: [],
+      errors: [],
+    };
+
+    const inside = runGit(rootDir, ['rev-parse', '--is-inside-work-tree'], { allowFailure: true });
+    if (!inside.ok || inside.stdout.trim() !== 'true') {
+      result.warnings.push(createIssue('warning', 'GIT_REPOSITORY_NOT_FOUND', '目标目录不是 Git 仓库', '请在 Git 仓库内执行该命令'));
+      return result;
+    }
+
+    const root = runGit(rootDir, ['rev-parse', '--show-toplevel'], { allowFailure: true });
+    if (!root.ok) {
+      result.errors.push(createIssue('error', 'GIT_REPOSITORY_ROOT_FAILED', '无法识别 Git 仓库根目录', '请确认 git 状态正常'));
+      return result;
+    }
+
+    const branch = runGit(rootDir, ['symbolic-ref', '--short', 'HEAD'], { allowFailure: true });
+    const remotes = runGit(rootDir, ['remote'], { allowFailure: true });
+    result.isGitRepository = true;
+    result.repoRoot = path.resolve(root.stdout.trim());
+    result.currentBranch = branch.ok ? branch.stdout.trim() : null;
+    result.isDetachedHead = !branch.ok;
+    result.remotes = remotes.ok ? remotes.stdout.split(/\r?\n/).map((item) => item.trim()).filter(Boolean) : [];
+    result.hasRemote = result.remotes.length > 0;
+    return result;
+  }
+}
+
+module.exports = {
+  GitRepositoryDetector,
+};

package/src/git/multi-repo-worktree-planner.js

@@ -0,0 +1,88 @@
+const path = require('path');
+const { BranchManager } = require('./branch-manager');
+const { WorktreeManager } = require('./worktree-manager');
+const { createBranchName, createIssue, createWorktreeName, safeSegment } = require('./types');
+
+class MultiRepoWorktreePlanner {
+  constructor(options = {}) {
+    this.worktreeManager = options.worktreeManager || new WorktreeManager(options);
+    this.branchManager = options.branchManager || new BranchManager(options);
+  }
+
+  plan(input = {}) {
+    const runLeaf = createWorktreeName({
+      runId: input.runId || 'run-local',
+      requirementSummary: input.requirementSummary || '需求执行',
+    });
+    return {
+      runId: input.runId || 'run-local',
+      repos: (input.repos || []).map((repo) => {
+        const repoId = repo.repoId || 'repo';
+        return {
+          repoId,
+          repoRoot: repo.repoRoot,
+          branchName: createBranchName({
+            branchPrefix: input.branchPrefix || 'ai',
+            runId: input.runId || 'run-local',
+            requirementSummary: input.requirementSummary || repoId,
+          }),
+          worktreePath: path.join(input.worktreeRoot || '../.ai-worktrees', runLeaf, safeSegment(repoId, 'repo')),
+          status: 'planned',
+        };
+      }),
+      warnings: [],
+      errors: [],
+    };
+  }
+
+  async create(input = {}) {
+    const plan = this.plan(input);
+    const created = [];
+
+    for (const repoPlan of plan.repos) {
+      const result = await this.worktreeManager.create({
+        repoRoot: repoPlan.repoRoot,
+        baseBranch: (input.repos || []).find((repo) => repo.repoId === repoPlan.repoId)?.baseBranch,
+        branchPrefix: input.branchPrefix || 'ai',
+        worktreeRoot: input.worktreeRoot || '../.ai-worktrees',
+        worktreeName: path.join(createWorktreeName({
+          runId: input.runId || 'run-local',
+          requirementSummary: input.requirementSummary || '需求执行',
+        }), safeSegment(repoPlan.repoId, 'repo')),
+        runId: input.runId || 'run-local',
+        requirementSummary: input.requirementSummary || '需求执行',
+      });
+      repoPlan.branchName = result.branchName;
+      repoPlan.worktreePath = result.worktreePath;
+      plan.warnings.push(...result.warnings);
+      plan.errors.push(...result.errors);
+      if (!result.created) {
+        repoPlan.status = 'failed';
+        await this.rollbackCreated(created, plan);
+        return plan;
+      }
+      repoPlan.status = 'created';
+      created.push({ ...repoPlan });
+    }
+    return plan;
+  }
+
+  async rollbackCreated(createdRepos, plan) {
+    for (const repo of createdRepos.reverse()) {
+      const removeResult = this.worktreeManager.removeWorktree(repo.repoRoot, repo.worktreePath);
+      if (!removeResult.ok) {
+        plan.warnings.push(createIssue('warning', 'WORKTREE_ROLLBACK_FAILED', `回滚 worktree 失败：${repo.repoId}`, '请手动执行 git worktree remove --force'));
+      }
+      const branchResult = this.branchManager.deleteBranch(repo.repoRoot, repo.branchName);
+      if (!branchResult.ok) {
+        plan.warnings.push(createIssue('warning', 'BRANCH_ROLLBACK_FAILED', `回滚分支失败：${repo.branchName}`, '请手动删除临时分支'));
+      }
+      const target = plan.repos.find((item) => item.repoId === repo.repoId);
+      if (target) target.status = 'rolled-back';
+    }
+  }
+}
+
+module.exports = {
+  MultiRepoWorktreePlanner,
+};

package/src/git/policy.js

@@ -0,0 +1,19 @@
+const path = require('path');
+const { readJsonFile } = require('../project/project-files');
+const { DEFAULT_BRANCH_POLICY, normalizeDirtyStrategy } = require('./types');
+
+function readBranchPolicy(rootDir) {
+  const policyPath = path.join(rootDir, '.ai-spec/policy.json');
+  const policy = readJsonFile(policyPath) || {};
+  const branchPolicy = policy.branchPolicy || {};
+  const merged = {
+    ...DEFAULT_BRANCH_POLICY,
+    ...branchPolicy,
+  };
+  merged.dirtyStrategy = normalizeDirtyStrategy(merged.dirtyStrategy);
+  return merged;
+}
+
+module.exports = {
+  readBranchPolicy,
+};

package/src/git/strategies/block-dirty-strategy.js

@@ -0,0 +1,34 @@
+const { DirtyChecker } = require('../dirty-checker');
+const { summarizeChangedFiles } = require('../types');
+
+class BlockDirtyStrategy {
+  constructor(options = {}) {
+    this.dirtyChecker = options.dirtyChecker || new DirtyChecker();
+  }
+
+  handle(input) {
+    const dirty = this.dirtyChecker.check({ repoRoot: input.repoRoot });
+    if (dirty.clean) {
+      return {
+        canContinue: true,
+        strategy: 'block',
+        message: '工作区干净，可以继续创建分支和 worktree',
+        warning: null,
+        patchPath: null,
+        wipCommitHash: null,
+      };
+    }
+    return {
+      canContinue: false,
+      strategy: 'block',
+      message: `当前工作区存在未提交变更，已按 block 策略阻断。\n变更文件：\n${summarizeChangedFiles(dirty.changedFiles)}`,
+      warning: '未暂存内容不会自动进入新 worktree，请先提交、清理或显式选择其他 dirtyStrategy',
+      patchPath: null,
+      wipCommitHash: null,
+    };
+  }
+}
+
+module.exports = {
+  BlockDirtyStrategy,
+};

package/src/git/strategies/ignore-dirty-strategy.js

@@ -0,0 +1,33 @@
+const { DirtyChecker } = require('../dirty-checker');
+
+class IgnoreDirtyStrategy {
+  constructor(options = {}) {
+    this.dirtyChecker = options.dirtyChecker || new DirtyChecker();
+  }
+
+  handle(input) {
+    const dirty = this.dirtyChecker.check({ repoRoot: input.repoRoot });
+    if (dirty.clean) {
+      return {
+        canContinue: true,
+        strategy: 'ignore',
+        message: '工作区干净，可以继续',
+        warning: null,
+        patchPath: null,
+        wipCommitHash: null,
+      };
+    }
+    return {
+      canContinue: true,
+      strategy: 'ignore',
+      message: '已按 ignore 策略允许继续',
+      warning: '当前仓库 dirty，未暂存内容不会自动进入新 worktree，请确认风险',
+      patchPath: null,
+      wipCommitHash: null,
+    };
+  }
+}
+
+module.exports = {
+  IgnoreDirtyStrategy,
+};