@gong-ym/ai-spec-auto 0.2.3

package/src/ide/ide-service.js

@@ -0,0 +1,270 @@
+const fs = require('fs');
+const path = require('path');
+const { IdeRegistryBuilder } = require('./registry/ide-registry-builder');
+const { MarkdownAnchorWriter } = require('./anchors/markdown-anchor-writer');
+const { CursorAdapter } = require('./adapters/cursor-adapter');
+const { ClaudeAdapter } = require('./adapters/claude-adapter');
+const { LinkModeResolver } = require('./links/link-mode-resolver');
+const { IDE_TYPES, LINK_MODES, PROFILES, DOCTOR_CHECKLIST } = require('./ide-types');
+
+class IdeService {
+  constructor(options = {}) {
+    this.registryBuilder = options.registryBuilder || new IdeRegistryBuilder();
+    this.anchorWriter = options.anchorWriter || new MarkdownAnchorWriter();
+    this.cursorAdapter = options.cursorAdapter || new CursorAdapter();
+    this.claudeAdapter = options.claudeAdapter || new ClaudeAdapter();
+    this.linkResolver = options.linkResolver || new LinkModeResolver();
+  }
+
+  /**
+   * 同步 IDE 指针文件到目标项目
+   * @param {string} rootDir
+   * @param {{
+   *   ide?: string[],
+   *   profile?: string,
+   *   linkMode?: string,
+   *   writeMemoryAnchor?: boolean,
+   *   writeAgentAnchor?: boolean,
+   *   dryRun?: boolean,
+   * }} options
+   * @returns {Promise<{
+   *   writtenFiles: Array<{ path: string, action: string }>,
+   *   skippedFiles: string[],
+   *   repairedFiles: string[],
+   *   linkModeUsed: string,
+   *   warnings: string[]
+   * }>}
+   */
+  async sync(rootDir, options = {}) {
+    const ideList = this._parseIdeList(options.ide);
+    const profile = options.profile || PROFILES.AUTO;
+    const linkMode = options.linkMode || LINK_MODES.AUTO;
+    const writtenFiles = [];
+    const skippedFiles = [];
+    const allWarnings = [];
+
+    // 1. 校验项目是否已 init
+    const projectJsonPath = path.join(rootDir, '.ai-spec', 'project.json');
+    if (!fs.existsSync(projectJsonPath)) {
+      throw new Error('目标项目尚未初始化，请先运行 init --recommend --yes');
+    }
+
+    // 2. 生成 ide-registry.json
+    const registryResult = this.registryBuilder.write(rootDir, {
+      profile,
+      ide: ideList,
+      linkMode,
+      writeAgentAnchor: options.writeAgentAnchor,
+      writeMemoryAnchor: options.writeMemoryAnchor,
+      dryRun: options.dryRun,
+    });
+    writtenFiles.push({ path: registryResult.path, action: registryResult.action });
+    allWarnings.push(...(registryResult.warnings || []));
+
+    // 3. 生成 ide-integration.json
+    const integrationResult = this.registryBuilder.writeIntegrationConfig(rootDir, {
+      profile,
+      ide: ideList,
+      linkMode,
+      writeAgentAnchor: options.writeAgentAnchor,
+      writeMemoryAnchor: options.writeMemoryAnchor,
+      dryRun: options.dryRun,
+    });
+    writtenFiles.push({ path: integrationResult.path, action: integrationResult.action });
+
+    // 4. 生成 Cursor 指针文件
+    let linkModeUsed = LINK_MODES.COPY;
+    if (ideList.includes(IDE_TYPES.CURSOR)) {
+      const cursorOutput = this.cursorAdapter.generateFiles({ profile });
+      for (const file of cursorOutput.files) {
+        try {
+          const result = this.linkResolver.write(rootDir, file.relativePath, file.content, {
+            mode: linkMode,
+            dryRun: options.dryRun,
+          });
+          writtenFiles.push({ path: result.path, action: result.action });
+          linkModeUsed = result.modeUsed;
+          allWarnings.push(...(result.warnings || []));
+        } catch (error) {
+          allWarnings.push(`Cursor 文件 ${file.relativePath} 写入失败：${error.message}`);
+          skippedFiles.push(file.relativePath);
+        }
+      }
+    }
+
+    // 5. 生成 Claude 指针文件
+    if (ideList.includes(IDE_TYPES.CLAUDE)) {
+      const claudeOutput = this.claudeAdapter.generateFiles({ profile });
+      for (const file of claudeOutput.files) {
+        try {
+          const result = this.linkResolver.write(rootDir, file.relativePath, file.content, {
+            mode: linkMode,
+            dryRun: options.dryRun,
+          });
+          writtenFiles.push({ path: result.path, action: result.action });
+          linkModeUsed = result.modeUsed;
+          allWarnings.push(...(result.warnings || []));
+        } catch (error) {
+          allWarnings.push(`Claude 文件 ${file.relativePath} 写入失败：${error.message}`);
+          skippedFiles.push(file.relativePath);
+        }
+      }
+    }
+
+    // 6. 注入 markdown 锚点
+    if (options.writeAgentAnchor !== false) {
+      ['AGENTS.md', 'CLAUDE.md'].forEach((fileName) => {
+        try {
+          const result = this.anchorWriter.write(rootDir, fileName, { dryRun: options.dryRun });
+          writtenFiles.push({ path: result.path, action: result.action });
+        } catch (error) {
+          allWarnings.push(`${fileName} 锚点写入失败：${error.message}`);
+        }
+      });
+    }
+    if (options.writeMemoryAnchor !== false) {
+      try {
+        const result = this.anchorWriter.write(rootDir, 'memory.md', { dryRun: options.dryRun });
+        writtenFiles.push({ path: result.path, action: result.action });
+      } catch (error) {
+        allWarnings.push(`memory.md 锚点写入失败：${error.message}`);
+      }
+    }
+
+    return {
+      writtenFiles,
+      skippedFiles,
+      repairedFiles: [],
+      linkModeUsed,
+      warnings: allWarnings,
+    };
+  }
+
+  /**
+   * 检查 IDE 指针文件完整性
+   * @param {string} rootDir
+   * @returns {{
+   *   ok: boolean,
+   *   items: Array<{ path: string, exists: boolean, hasAnchor?: boolean, category: string, required: boolean }>,
+   *   missingCount: number,
+   *   suggestions: string[]
+   * }}
+   */
+  doctor(rootDir) {
+    const items = [];
+    const suggestions = [];
+
+    for (const check of DOCTOR_CHECKLIST) {
+      const filePath = path.join(rootDir, check.path);
+      const exists = fs.existsSync(filePath);
+
+      const item = {
+        path: check.path,
+        exists,
+        category: check.category,
+        required: check.required,
+      };
+
+      // 检查锚点完整性（针对 markdown 文件）
+      if (exists && check.path.endsWith('.md') && !check.path.includes('commands/')) {
+        try {
+          const content = fs.readFileSync(filePath, 'utf8');
+          item.hasAnchor = content.includes('AI-SPEC-AUTO');
+        } catch (_) {
+          item.hasAnchor = false;
+        }
+      }
+
+      items.push(item);
+
+      if (!exists && check.required) {
+        suggestions.push(`缺少必要文件：${check.path}（${check.category}），请运行 ide repair 修复`);
+      } else if (!exists && !check.required) {
+        suggestions.push(`可选文件缺失：${check.path}（${check.category}），建议运行 ide sync 补齐`);
+      }
+    }
+
+    // 额外检查锚点完整性
+    ['AGENTS.md', 'CLAUDE.md', 'memory.md'].forEach((fileName) => {
+      const result = this.anchorWriter.check(rootDir, fileName);
+      if (result.exists && !result.hasAnchor) {
+        suggestions.push(`${fileName} 存在但缺少 AI-SPEC-AUTO 锚点，请运行 ide repair 修复`);
+      }
+    });
+
+    const missingCount = items.filter((item) => !item.exists && item.required).length;
+
+    return {
+      ok: missingCount === 0 && suggestions.length === 0,
+      items,
+      missingCount,
+      suggestions,
+    };
+  }
+
+  /**
+   * 修复缺失的 IDE 指针文件
+   * @param {string} rootDir
+   * @param {{ dryRun?: boolean }} options
+   * @returns {Promise<{
+   *   repairedFiles: Array<{ path: string, action: string }>,
+   *   doctorResult: object
+   * }>}
+   */
+  async repair(rootDir, options = {}) {
+    const doctorResult = this.doctor(rootDir);
+    const repairedFiles = [];
+
+    // 如果已全部正常，无需修复
+    if (doctorResult.ok && doctorResult.suggestions.length === 0) {
+      return { repairedFiles, doctorResult };
+    }
+
+    // 补齐缺失文件：使用 sync 的 dry-run 先看看哪些需要修复
+    const syncResult = await this.sync(rootDir, {
+      ide: ['cursor', 'claude'],
+      profile: PROFILES.AUTO,
+      linkMode: LINK_MODES.COPY,
+      writeMemoryAnchor: true,
+      writeAgentAnchor: true,
+      dryRun: false,
+    });
+
+    // 只标记实际修复的文件
+    const doctorMissing = new Set(
+      doctorResult.items
+        .filter((item) => !item.exists)
+        .map((item) => item.path)
+    );
+
+    for (const file of syncResult.writtenFiles) {
+      if (doctorMissing.has(file.path)) {
+        repairedFiles.push({ path: file.path, action: file.action });
+      }
+    }
+
+    // 修复锚点（重新注入）
+    ['AGENTS.md', 'CLAUDE.md', 'memory.md'].forEach((fileName) => {
+      const checkResult = this.anchorWriter.check(rootDir, fileName);
+      if (checkResult.exists && !checkResult.hasAnchor) {
+        const result = this.anchorWriter.write(rootDir, fileName, { dryRun: false });
+        repairedFiles.push({ path: result.path, action: 'update' });
+      }
+    });
+
+    return { repairedFiles, doctorResult };
+  }
+
+  _parseIdeList(ide) {
+    if (!ide || ide.length === 0) return [IDE_TYPES.CURSOR, IDE_TYPES.CLAUDE];
+    if (Array.isArray(ide)) return ide.filter((item) => IDE_TYPES[item.toUpperCase()] || Object.values(IDE_TYPES).includes(item));
+    if (typeof ide === 'string') {
+      return ide.split(',').map((item) => item.trim()).filter((item) => Object.values(IDE_TYPES).includes(item));
+    }
+    return [IDE_TYPES.CURSOR, IDE_TYPES.CLAUDE];
+  }
+}
+
+module.exports = {
+  IdeService,
+};

package/src/ide/ide-types.js

@@ -0,0 +1,94 @@
+const IDE_SCHEMA_VERSION = '1.0.0';
+
+const IDE_TYPES = Object.freeze({
+  CURSOR: 'cursor',
+  CLAUDE: 'claude',
+  CODEX: 'codex',
+});
+
+const LINK_MODES = Object.freeze({
+  AUTO: 'auto',
+  COPY: 'copy',
+  SYMLINK: 'symlink',
+});
+
+const PROFILES = Object.freeze({
+  AUTO: 'auto',
+  REACT: 'react',
+  VUE: 'vue',
+});
+
+const SYNC_ACTIONS = Object.freeze({
+  CREATE: 'create',
+  UPDATE: 'update',
+  SKIP: 'skip',
+  DELETE: 'delete',
+});
+
+/** doctor 检查时需要的所有文件清单 */
+const DOCTOR_CHECKLIST = [
+  { path: '.ai-spec/project.json', category: '项目配置', required: true },
+  { path: '.ai-spec/ai-spec.lock.json', category: '锁定文件', required: true },
+  { path: '.ai-spec/context-index.json', category: '上下文索引', required: true },
+  { path: '.agents/registry.index.json', category: '资产注册表', required: true },
+  { path: '.agents/registry/ide-registry.json', category: 'IDE 注册表', required: true },
+  { path: '.ai-spec/ide-integration.json', category: 'IDE 集成状态', required: true },
+  { path: '.cursor/rules/ai-spec-auto.mdc', category: 'Cursor 指针', required: false },
+  { path: '.cursor/commands/spec-start.md', category: 'Cursor 命令', required: false },
+  { path: '.cursor/commands/spec-update.md', category: 'Cursor 命令', required: false },
+  { path: '.cursor/commands/spec-status.md', category: 'Cursor 命令', required: false },
+  { path: '.claude/ai-spec-auto.md', category: 'Claude 指针', required: false },
+  { path: '.claude/commands/spec-start.md', category: 'Claude 命令', required: false },
+  { path: '.claude/commands/spec-update.md', category: 'Claude 命令', required: false },
+  { path: '.claude/commands/spec-status.md', category: 'Claude 命令', required: false },
+];
+
+/** IDE sync 生成的文件清单（仅 AI 管理文件） */
+const SYNC_FILE_TEMPLATES = {
+  cursor: [
+    { path: '.cursor/rules/ai-spec-auto.mdc', type: 'pointer-rule' },
+    { path: '.cursor/commands/spec-start.md', type: 'command' },
+    { path: '.cursor/commands/spec-update.md', type: 'command' },
+    { path: '.cursor/commands/spec-status.md', type: 'command' },
+  ],
+  claude: [
+    { path: '.claude/ai-spec-auto.md', type: 'pointer-entry' },
+    { path: '.claude/commands/spec-start.md', type: 'command' },
+    { path: '.claude/commands/spec-update.md', type: 'command' },
+    { path: '.claude/commands/spec-status.md', type: 'command' },
+  ],
+};
+
+/** React profile 优先级资产 */
+const REACT_PRIORITY_ASSETS = {
+  rules: ['frontend-common-rule', 'frontend-react-rule'],
+  skills: ['frontend-implementer', 'component-refactor', 'route-change', 'state-management', 'unit-test-writer'],
+  commands: ['project-init', 'spec-start', 'spec-update', 'spec-status', 'spec-continue'],
+};
+
+/** Vue profile 优先级资产 */
+const VUE_PRIORITY_ASSETS = {
+  rules: ['frontend-common-rule', 'frontend-vue-rule'],
+  skills: ['frontend-implementer', 'vue-component-implementer', 'vite-build-checker', 'unit-test-writer'],
+  commands: ['project-init', 'spec-start', 'spec-update', 'spec-status', 'spec-continue'],
+};
+
+function getPriorityAssets(profile) {
+  if (profile === PROFILES.REACT) return REACT_PRIORITY_ASSETS;
+  if (profile === PROFILES.VUE) return VUE_PRIORITY_ASSETS;
+  // auto: 默认使用 React 资产（前端常见）
+  return REACT_PRIORITY_ASSETS;
+}
+
+module.exports = {
+  IDE_SCHEMA_VERSION,
+  IDE_TYPES,
+  LINK_MODES,
+  PROFILES,
+  SYNC_ACTIONS,
+  DOCTOR_CHECKLIST,
+  SYNC_FILE_TEMPLATES,
+  REACT_PRIORITY_ASSETS,
+  VUE_PRIORITY_ASSETS,
+  getPriorityAssets,
+};

package/src/ide/links/link-mode-resolver.js

@@ -0,0 +1,160 @@
+const fs = require('fs');
+const path = require('path');
+const { LINK_MODES, SYNC_ACTIONS } = require('../ide-types');
+const { ensureDir } = require('../../project/json-utils');
+
+class LinkModeResolver {
+  /**
+   * 按指定模式写入文件
+   * @param {string} rootDir - 项目根目录
+   * @param {string} relativePath - 相对路径
+   * @param {string} content - 文件内容（copy 模式使用）
+   * @param {{ mode: string, dryRun?: boolean }} options
+   * @returns {{ path: string, action: string, modeUsed: string, warnings: string[] }}
+   */
+  write(rootDir, relativePath, content, options = {}) {
+    const mode = options.mode || LINK_MODES.AUTO;
+    const dryRun = options.dryRun || false;
+    const filePath = path.join(rootDir, relativePath);
+    const warnings = [];
+    let modeUsed = mode;
+
+    if (dryRun) {
+      const exists = fs.existsSync(filePath);
+      return {
+        path: relativePath,
+        action: exists ? SYNC_ACTIONS.UPDATE : SYNC_ACTIONS.CREATE,
+        modeUsed: mode,
+        warnings: [],
+      };
+    }
+
+    if (mode === LINK_MODES.SYMLINK) {
+      return this._symlinkWrite(rootDir, relativePath, content, warnings);
+    }
+
+    if (mode === LINK_MODES.COPY) {
+      return this._copyWrite(rootDir, relativePath, content, warnings);
+    }
+
+    // auto 模式：优先 symlink，失败降级 copy
+    const symlinkResult = this._trySymlink(rootDir, relativePath);
+    if (symlinkResult.success) {
+      modeUsed = LINK_MODES.SYMLINK;
+      return {
+        path: relativePath,
+        action: symlinkResult.action,
+        modeUsed,
+        warnings: [],
+      };
+    }
+
+    warnings.push(`symlink 失败，自动降级为 copy：${symlinkResult.error}`);
+    modeUsed = LINK_MODES.COPY;
+    return this._copyWrite(rootDir, relativePath, content, warnings);
+  }
+
+  _symlinkWrite(rootDir, relativePath, content, warnings) {
+    const result = this._trySymlink(rootDir, relativePath);
+    if (!result.success) {
+      throw new Error(`symlink 写入失败：${result.error}`);
+    }
+    return {
+      path: relativePath,
+      action: result.action,
+      modeUsed: LINK_MODES.SYMLINK,
+      warnings,
+    };
+  }
+
+  _copyWrite(rootDir, relativePath, content, warnings) {
+    const filePath = path.join(rootDir, relativePath);
+    const exists = fs.existsSync(filePath);
+
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, `${content}\n`, 'utf8');
+
+    return {
+      path: relativePath,
+      action: exists ? SYNC_ACTIONS.UPDATE : SYNC_ACTIONS.CREATE,
+      modeUsed: LINK_MODES.COPY,
+      warnings,
+    };
+  }
+
+  _trySymlink(rootDir, relativePath) {
+    try {
+      const filePath = path.join(rootDir, relativePath);
+      const exists = fs.existsSync(filePath);
+
+      // 查找源文件（在 br-ai-spec 项目自身中）
+      // 指针文件的源内容由 adapters 提供，symlink 模式指向 .agents/ 下的真实资产
+      // 由于 IDE 指针文件是轻量内容文件而非目录链接，symlink 模式在此场景下
+      // 主要用于 .cursor/commands/ 和 .claude/commands/ 指向 .agents/commands/
+      // 对于单个文件，我们使用 copy 作为 fallback
+      ensureDir(path.dirname(filePath));
+
+      // 尝试 symlink: 对于 commands 目录，可以 symlink 整个目录
+      // 对于单个 pointer 文件，直接写入文件内容
+      if (relativePath.includes('commands/')) {
+        // commands 目录尝试 symlink 到 .agents/commands/
+        return this._symlinkCommandsDir(rootDir, relativePath, exists);
+      }
+
+      // 单个文件无法 symlink（没有合适的源），报错
+      return {
+        success: false,
+        error: `单个文件 ${relativePath} 没有可 symlink 的源，请使用 copy 模式`,
+      };
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  }
+
+  _symlinkCommandsDir(rootDir, relativePath, exists) {
+    const filePath = path.join(rootDir, relativePath);
+    const targetDir = path.dirname(filePath);
+
+    // 尝试找到对应的源目录
+    const sourceCandidates = [
+      path.join(rootDir, '.agents', 'commands', 'common'),
+      path.join(rootDir, '.agents', 'commands', path.basename(path.dirname(relativePath))),
+    ];
+
+    for (const source of sourceCandidates) {
+      if (fs.existsSync(source)) {
+        if (exists) {
+          try { fs.unlinkSync(filePath); } catch (_) { /* ignore */ }
+        }
+        ensureDir(targetDir);
+        fs.symlinkSync(path.relative(targetDir, source), filePath, 'dir');
+        return {
+          success: true,
+          action: exists ? SYNC_ACTIONS.UPDATE : SYNC_ACTIONS.CREATE,
+        };
+      }
+    }
+
+    return {
+      success: false,
+      error: `找不到 commands 源目录（尝试了 ${sourceCandidates.join(', ')}）`,
+    };
+  }
+
+  /**
+   * 判断给定路径在当前系统中推荐使用的模式
+   * @returns {'copy' | 'symlink'}
+   */
+  static recommendMode() {
+    // macOS / Linux 上 symlink 通常可用
+    // Windows 或受限环境推荐 copy
+    if (process.platform === 'win32') {
+      return LINK_MODES.COPY;
+    }
+    return LINK_MODES.AUTO;
+  }
+}
+
+module.exports = {
+  LinkModeResolver,
+};

package/src/ide/registry/ide-registry-builder.js

@@ -0,0 +1,165 @@
+const path = require('path');
+const { readJsonIfExists, writeJson } = require('../../project/json-utils');
+const { IDE_SCHEMA_VERSION, PROFILES, getPriorityAssets } = require('../ide-types');
+
+class IdeRegistryBuilder {
+  /**
+   * 根据项目配置生成 IDE 消费索引
+   * @param {string} rootDir - 项目根目录
+   * @param {{ profile?: string, ide?: string[] }} options
+   * @returns {{ registry: object, warnings: string[] }}
+   */
+  build(rootDir, options = {}) {
+    const projectConfig = readJsonIfExists(path.join(rootDir, '.ai-spec', 'project.json'));
+    const workspaceConfig = readJsonIfExists(path.join(rootDir, '.ai-spec', 'workspace.json'));
+    const lockFile = readJsonIfExists(path.join(rootDir, '.ai-spec', 'ai-spec.lock.json'));
+    const assetRegistry = readJsonIfExists(path.join(rootDir, '.agents', 'registry.index.json'));
+
+    const warnings = [];
+    if (!projectConfig) {
+      warnings.push('未找到 .ai-spec/project.json，请先运行 init --recommend --yes');
+    }
+    if (!lockFile) {
+      warnings.push('未找到 .ai-spec/ai-spec.lock.json');
+    }
+    if (!assetRegistry) {
+      warnings.push('未找到 .agents/registry.index.json');
+    }
+
+    // 推断 profile
+    const profile = this._resolveProfile(projectConfig, options.profile);
+
+    // 从 projectConfig 推断语言和框架信息
+    const language = projectConfig?.language || (profile === PROFILES.VUE ? ['TypeScript', 'JavaScript'] : ['TypeScript', 'JavaScript']);
+    const framework = profile === PROFILES.VUE ? 'Vue' : profile === PROFILES.REACT ? 'React' : '';
+
+    // 推断包管理器
+    const packageManager = workspaceConfig?.packageManager || 'pnpm';
+
+    const priorityAssets = getPriorityAssets(profile);
+
+    const registry = {
+      schemaVersion: IDE_SCHEMA_VERSION,
+      generatedBy: 'ai-spec-auto',
+      updatedAt: new Date().toISOString(),
+      project: {
+        profile,
+        framework,
+        language,
+        packageManager,
+      },
+      ide: {
+        enabled: options.ide || ['cursor', 'claude'],
+        linkMode: options.linkMode || 'auto',
+        anchors: {
+          agentsMd: options.writeAgentAnchor !== false,
+          claudeMd: options.writeAgentAnchor !== false,
+          memoryMd: options.writeMemoryAnchor !== false,
+        },
+      },
+      indexes: {
+        assetRegistry: '.agents/registry.index.json',
+        lockFile: '.ai-spec/ai-spec.lock.json',
+        contextIndex: '.ai-spec/context-index.json',
+        projectConfig: '.ai-spec/project.json',
+        workspaceConfig: '.ai-spec/workspace.json',
+        policyConfig: '.ai-spec/policy.json',
+      },
+      priorityAssets,
+      privacy: {
+        sourceCodeIncluded: false,
+        rawPromptIncluded: false,
+        rawResponseIncluded: false,
+        absolutePathIncluded: false,
+      },
+    };
+
+    return { registry, warnings };
+  }
+
+  /**
+   * 写入 ide-registry.json 到目标项目
+   * @param {string} rootDir
+   * @param {{ dryRun?: boolean, profile?: string, ide?: string[] }} options
+   * @returns {{ path: string, action: string, data: object }}
+   */
+  write(rootDir, options = {}) {
+    const { registry, warnings } = this.build(rootDir, options);
+    const filePath = path.join(rootDir, '.agents', 'registry', 'ide-registry.json');
+    const { readJsonIfExists: readJson } = require('../../project/json-utils');
+    const existing = readJson(filePath);
+    const action = existing ? 'update' : 'create';
+
+    if (!options.dryRun) {
+      writeJson(filePath, registry);
+    }
+
+    return {
+      path: '.agents/registry/ide-registry.json',
+      action,
+      data: registry,
+      warnings,
+    };
+  }
+
+  /**
+   * 写入 ide-integration.json 到目标项目
+   * @param {string} rootDir
+   * @param {{ dryRun?: boolean, ide?: string[], linkMode?: string, profile?: string }} options
+   * @returns {{ path: string, action: string, data: object }}
+   */
+  writeIntegrationConfig(rootDir, options = {}) {
+    const filePath = path.join(rootDir, '.ai-spec', 'ide-integration.json');
+    const existing = readJsonIfExists(filePath);
+
+    const config = {
+      schemaVersion: IDE_SCHEMA_VERSION,
+      profile: this._resolveProfile(readJsonIfExists(path.join(rootDir, '.ai-spec', 'project.json')), options.profile),
+      ide: {
+        cursor: {
+          enabled: !options.ide || options.ide.includes('cursor'),
+          rulesFile: '.cursor/rules/ai-spec-auto.mdc',
+          commandsDir: '.cursor/commands',
+        },
+        claude: {
+          enabled: !options.ide || options.ide.includes('claude'),
+          entryFile: '.claude/ai-spec-auto.md',
+          commandsDir: '.claude/commands',
+        },
+      },
+      memoryAnchors: {
+        'AGENTS.md': options.writeAgentAnchor !== false,
+        'CLAUDE.md': options.writeAgentAnchor !== false,
+        'memory.md': options.writeMemoryAnchor !== false,
+      },
+      linkMode: options.linkMode || 'auto',
+      lastSyncAt: new Date().toISOString(),
+    };
+
+    if (!options.dryRun) {
+      writeJson(filePath, config);
+    }
+
+    return {
+      path: '.ai-spec/ide-integration.json',
+      action: existing ? 'update' : 'create',
+      data: config,
+    };
+  }
+
+  _resolveProfile(projectConfig, explicitProfile) {
+    if (explicitProfile && explicitProfile !== PROFILES.AUTO) {
+      return explicitProfile;
+    }
+    if (projectConfig?.manifest?.slug) {
+      const slug = projectConfig.manifest.slug.toLowerCase();
+      if (slug.includes('vue')) return PROFILES.VUE;
+      if (slug.includes('react') || slug.includes('next')) return PROFILES.REACT;
+    }
+    return PROFILES.AUTO;
+  }
+}
+
+module.exports = {
+  IdeRegistryBuilder,
+};