@gong-ym/ai-spec-auto 0.2.3

package/src/incident/incident-writer.js

@@ -0,0 +1,47 @@
+const crypto = require('crypto');
+const path = require('path');
+const { writeJson } = require('../run/run-store');
+const { INCIDENT_SCHEMA_VERSION, normalizeIncidentType } = require('./types');
+const { VisualReporter } = require('../visual/visual-reporter');
+
+function createIncidentId(type) {
+  return `incident-${Date.now()}-${crypto.createHash('sha256').update(`${type}-${Math.random()}`).digest('hex').slice(0, 6)}`;
+}
+
+function sanitizeText(value) {
+  return String(value || '')
+    .replace(/\/Users\/[^/\s]+/g, '<user-home>')
+    .slice(0, 1000);
+}
+
+class IncidentWriter {
+  constructor(options = {}) {
+    this.visualReporter = options.visualReporter || new VisualReporter();
+    this.visualOptions = options.visualOptions || {};
+  }
+
+  write(input = {}) {
+    const incident = {
+      schemaVersion: INCIDENT_SCHEMA_VERSION,
+      incidentId: input.incidentId || createIncidentId(input.type || 'unknown'),
+      runId: input.runId || '',
+      type: normalizeIncidentType(input.type),
+      level: input.level || 'error',
+      stage: input.stage || '',
+      message: sanitizeText(input.message || '发生未知异常'),
+      suggestion: sanitizeText(input.suggestion || '请查看 run.json 和相关日志后人工处理'),
+      createdAt: new Date().toISOString(),
+    };
+    const filePath = path.join(input.rootDir, '.ai-spec/runs', incident.runId, 'incidents', `${incident.incidentId}.json`);
+    writeJson(filePath, incident);
+    this.visualReporter.reportIncidentNonBlocking(input.rootDir, incident, {
+      ...this.visualOptions,
+      visualUrl: input.visualUrl || this.visualOptions.visualUrl,
+    });
+    return incident;
+  }
+}
+
+module.exports = {
+  IncidentWriter,
+};

package/src/incident/types.js

@@ -0,0 +1,22 @@
+const INCIDENT_SCHEMA_VERSION = '1.0.0';
+
+const INCIDENT_TYPES = [
+  'token-budget-exceeded',
+  'invalid-state-transition',
+  'executor-timeout',
+  'stage-failed',
+  'asset-check-failed',
+  'context-build-failed',
+  'worktree-create-failed',
+  'unknown',
+];
+
+function normalizeIncidentType(type) {
+  return INCIDENT_TYPES.includes(type) ? type : 'unknown';
+}
+
+module.exports = {
+  INCIDENT_SCHEMA_VERSION,
+  INCIDENT_TYPES,
+  normalizeIncidentType,
+};

package/src/init/ide-linker.js

@@ -0,0 +1,126 @@
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_IDES = ['claude', 'cursor'];
+
+/**
+ * 为目标项目的 .claude/ 和 .cursor/ 创建到 .agents/ 的符号链接，
+ * 并同步命令文件和配置文件。
+ */
+class IdeLinker {
+  constructor(options = {}) {
+    this.pkgRoot = options.pkgRoot || path.join(__dirname, '..', '..');
+  }
+
+  /**
+   * 为目标项目创建所有 IDE 链接
+   * @param {string} targetDir 目标项目根目录
+   * @param {string[]} ides 要配置的 IDE 列表
+   */
+  link(targetDir, ides = DEFAULT_IDES) {
+    const agentsDir = path.join(targetDir, '.agents');
+
+    for (const ide of ides) {
+      const ideDir = path.join(targetDir, `.${ide}`);
+      this._ensureIdeDir(ideDir);
+
+      // rules symlink
+      this._createSymlink(
+        path.join(agentsDir, 'rules'),
+        path.join(ideDir, 'rules'),
+      );
+
+      // skills per-skill symlinks
+      this._linkSkills(ideDir, agentsDir);
+
+      // commands: copy from .agents/commands/common + .agents/commands/<ide>
+      this._syncCommands(targetDir, ide);
+    }
+
+    // cursor-specific: copy mcp.json
+    if (ides.includes('cursor')) {
+      this._copyMcpJson(targetDir);
+    }
+  }
+
+  _ensureIdeDir(ideDir) {
+    fs.mkdirSync(ideDir, { recursive: true });
+  }
+
+  _createSymlink(target, linkPath) {
+    // 如果已存在且是正确指向的 symlink，跳过
+    try {
+      if (fs.lstatSync(linkPath).isSymbolicLink()) {
+        const current = fs.readlinkSync(linkPath);
+        const expected = path.relative(path.dirname(linkPath), target);
+        if (current === expected) return;
+      }
+    } catch (_) {
+      // 不存在或不是 symlink
+    }
+
+    // 删除已存在的文件/目录/错误 symlink
+    try { fs.rmSync(linkPath, { recursive: true, force: true }); } catch (_) {}
+
+    const rel = path.relative(path.dirname(linkPath), target);
+    fs.symlinkSync(rel, linkPath);
+  }
+
+  _linkSkills(ideDir, agentsDir) {
+    const ideSkillsDir = path.join(ideDir, 'skills');
+    const agentsSkillsDir = path.join(agentsDir, 'skills');
+
+    // 确保 IDE skills 目录存在
+    fs.mkdirSync(ideSkillsDir, { recursive: true });
+
+    if (!fs.existsSync(agentsSkillsDir)) return;
+
+    for (const entry of fs.readdirSync(agentsSkillsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const skillName = entry.name;
+      const linkPath = path.join(ideSkillsDir, skillName);
+      const target = path.join(agentsSkillsDir, skillName);
+      this._createSymlink(target, linkPath);
+    }
+  }
+
+  _syncCommands(targetDir, ide) {
+    const agentsCommandsDir = path.join(targetDir, '.agents', 'commands');
+    const destDir = path.join(targetDir, `.${ide}`, 'commands');
+
+    // 收集所有命令文件
+    const commandFiles = new Map(); // filename -> sourcePath
+
+    for (const subdir of ['common', ide]) {
+      const srcDir = path.join(agentsCommandsDir, subdir);
+      if (!fs.existsSync(srcDir)) continue;
+      for (const entry of fs.readdirSync(srcDir)) {
+        if (!entry.endsWith('.md')) continue;
+        // ide 特定命令优先（覆盖同名 common 命令）
+        commandFiles.set(entry, path.join(srcDir, entry));
+      }
+    }
+
+    if (commandFiles.size === 0) return;
+
+    // 确保目标目录存在
+    fs.mkdirSync(destDir, { recursive: true });
+
+    for (const [filename, srcPath] of commandFiles) {
+      const destPath = path.join(destDir, filename);
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+
+  _copyMcpJson(targetDir) {
+    const mcpDest = path.join(targetDir, '.cursor', 'mcp.json');
+    if (fs.existsSync(mcpDest)) return; // 已存在则保留
+
+    const mcpSrc = path.join(this.pkgRoot, '.cursor', 'mcp.json');
+    if (fs.existsSync(mcpSrc)) {
+      fs.copyFileSync(mcpSrc, mcpDest);
+    }
+  }
+}
+
+module.exports = { IdeLinker, DEFAULT_IDES };

package/src/init/ide-pointer-injector.js

@@ -0,0 +1,75 @@
+const fs = require('fs');
+const path = require('path');
+const { ensureDir } = require('../project/json-utils');
+
+const START_MARKER = '<!-- AI-SPEC-AUTO:START -->';
+const END_MARKER = '<!-- AI-SPEC-AUTO:END -->';
+const POINTER_FILES = [
+  '.codex/instructions.md',
+  '.cursor/rules/ai-spec-auto.mdc',
+  'CLAUDE.md',
+  'memory.md',
+];
+
+function buildManagedBlock() {
+  return [
+    START_MARKER,
+    '此区域由 ai-spec-auto 管理，请勿手动修改。',
+    '',
+    '请优先读取以下索引文件：',
+    '- .ai-spec/project.json',
+    '- .ai-spec/policy.json',
+    '- .ai-spec/context-index.json',
+    '- .agents/registry.index.json',
+    '',
+    '常用命令：',
+    '- ai-spec-auto scan . --explain',
+    '- ai-spec-auto init . --recommend --dry-run',
+    END_MARKER,
+  ].join('\n');
+}
+
+function upsertManagedBlock(existingContent, managedBlock) {
+  const content = existingContent || '';
+  const startIndex = content.indexOf(START_MARKER);
+  const endIndex = content.indexOf(END_MARKER);
+  if (startIndex >= 0 && endIndex >= startIndex) {
+    const before = content.slice(0, startIndex).replace(/\s+$/, '');
+    const after = content.slice(endIndex + END_MARKER.length).replace(/^\s+/, '');
+    return [before, managedBlock, after].filter(Boolean).join('\n\n') + '\n';
+  }
+
+  if (!content.trim()) {
+    return `${managedBlock}\n`;
+  }
+  return `${content.replace(/\s+$/, '')}\n\n${managedBlock}\n`;
+}
+
+class IdePointerInjector {
+  write(rootDir) {
+    const managedBlock = buildManagedBlock();
+    const results = [];
+    for (const relativePath of POINTER_FILES) {
+      const filePath = path.join(rootDir, relativePath);
+      const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+      const next = upsertManagedBlock(existing, managedBlock);
+      ensureDir(path.dirname(filePath));
+      fs.writeFileSync(filePath, next, 'utf8');
+      results.push({
+        path: relativePath,
+        fullPath: filePath,
+        action: existing ? 'update' : 'create',
+      });
+    }
+    return results;
+  }
+}
+
+module.exports = {
+  END_MARKER,
+  IdePointerInjector,
+  POINTER_FILES,
+  START_MARKER,
+  buildManagedBlock,
+  upsertManagedBlock,
+};

package/src/init/init-applier.js

@@ -0,0 +1,197 @@
+const fs = require('fs');
+const path = require('path');
+const { ConfigWriter } = require('../project/config-writer');
+const { ContextIndexWriter } = require('../project/context-index-writer');
+const { LocalStateWriter } = require('../project/local-state-writer');
+const { LockFileWriter } = require('../project/lock-file-writer');
+const { ManifestWriter } = require('../project/manifest-writer');
+const { PolicyConfigWriter } = require('../project/policy-config-writer');
+const { ProjectConfigWriter } = require('../project/project-config-writer');
+const { RegistryIndexWriter } = require('../project/registry-index-writer');
+const { WorkspaceConfigWriter } = require('../project/workspace-config-writer');
+const { ClaudeAdapter } = require('../ide/adapters/claude-adapter');
+const { CursorAdapter } = require('../ide/adapters/cursor-adapter');
+const { HookConfigWriter } = require('../hook/hook-config-writer');
+const { IdePointerInjector } = require('./ide-pointer-injector');
+const { IdeLinker } = require('./ide-linker');
+const { ManifestInstaller } = require('./manifest-installer');
+const { HubClient } = require('../hub/hub-client');
+const { resolveHubConfig } = require('../hub/hub-config');
+const { VisualReporter } = require('../visual/visual-reporter');
+const pkg = require('../../package.json');
+
+class InitApplier {
+  constructor(options = {}) {
+    this.manifestInstaller = options.manifestInstaller || new ManifestInstaller();
+    this.claudeAdapter = options.claudeAdapter || new ClaudeAdapter();
+    this.cursorAdapter = options.cursorAdapter || new CursorAdapter();
+    this.configWriter = options.configWriter || new ConfigWriter();
+    this.projectConfigWriter = options.projectConfigWriter || new ProjectConfigWriter();
+    this.policyConfigWriter = options.policyConfigWriter || new PolicyConfigWriter();
+    this.workspaceConfigWriter = options.workspaceConfigWriter || new WorkspaceConfigWriter();
+    this.lockFileWriter = options.lockFileWriter || new LockFileWriter();
+    this.manifestWriter = options.manifestWriter || new ManifestWriter();
+    this.registryIndexWriter = options.registryIndexWriter || new RegistryIndexWriter();
+    this.contextIndexWriter = options.contextIndexWriter || new ContextIndexWriter();
+    this.localStateWriter = options.localStateWriter || new LocalStateWriter();
+    this.hookConfigWriter = options.hookConfigWriter || new HookConfigWriter();
+    this.idePointerInjector = options.idePointerInjector || new IdePointerInjector();
+    this.ideLinker = options.ideLinker || new IdeLinker();
+    this.hubClient = options.hubClient || new HubClient();
+    this.visualReporter = options.visualReporter || new VisualReporter();
+  }
+
+  async apply(rootDir, plan, options = {}) {
+    const writtenFiles = [];
+    const installResult = this.manifestInstaller.install(plan);
+    for (const asset of installResult.assets || []) {
+      writtenFiles.push({
+        path: asset,
+        action: 'create',
+        description: '安装本地资产文件',
+      });
+    }
+    // 在写入 IDE 指针文件之前先创建符号链接，防止 IdePointerInjector
+    // 把 .cursor/rules/ 创建为普通目录
+    this.ideLinker.link(rootDir);
+
+    const now = options.now || new Date().toISOString();
+
+    // 写入 .ai-spec/config.json（P0.2 新增）
+    const configResult = this.configWriter.write(rootDir, plan, { now });
+    writtenFiles.push(configResult);
+
+    // 创建项目内轻量目录（P0.2 新增）
+    for (const dir of ['.memory', '.harness', 'reports/ai-spec']) {
+      const dirPath = path.join(rootDir, dir);
+      if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+        writtenFiles.push({
+          path: dir,
+          fullPath: dirPath,
+          action: 'create',
+          description: `创建 ${dir} 目录`,
+        });
+      }
+    }
+
+    // 创建用户本机运行态目录（P0.2 新增）
+    const localStateDir = configResult.data.localStateDir;
+    const localStateResult = this.localStateWriter.write(localStateDir);
+    if (localStateResult.created.length > 0) {
+      writtenFiles.push({
+        path: localStateDir,
+        action: 'create',
+        description: `创建本机运行态目录：${localStateResult.created.join(', ')}`,
+      });
+    }
+
+    // 生成 Hook 配置（P0.7）
+    const hookResult = this.hookConfigWriter.write(rootDir, { projectId: configResult.data.projectId });
+    writtenFiles.push(hookResult);
+
+    const projectResult = this.projectConfigWriter.write(rootDir, plan, { now });
+    writtenFiles.push(projectResult);
+
+    const policyResult = this.policyConfigWriter.write(rootDir, plan, { now, visualUrl: options.visualUrl });
+    writtenFiles.push(policyResult);
+
+    const workspaceResult = this.workspaceConfigWriter.write(rootDir, plan, { now });
+    if (workspaceResult) {
+      writtenFiles.push(workspaceResult);
+    }
+
+    const context = {
+      projectId: configResult.data.projectId,
+      workspaceId: workspaceResult?.data?.workspaceId || '',
+    };
+
+    // 写入 manifest.json（P0.3 增强：完整资产清单 + checksum）
+    const manifestResult = this.manifestWriter.write(rootDir, plan, context, { now });
+    writtenFiles.push(manifestResult);
+
+    // 写入 lock 文件（P0.3 增强：generatedFiles + adapterOutputs）
+    writtenFiles.push(this.lockFileWriter.write(rootDir, plan, context, { now, writtenFiles: writtenFiles.map((f) => ({ path: f.path })) }));
+    writtenFiles.push(this.registryIndexWriter.write(rootDir, plan, context, { now }));
+    writtenFiles.push(this.contextIndexWriter.write(rootDir, context, { now }));
+
+    // 生成 Cursor 适配文件（P0.4）
+    const manifestData = manifestResult.data;
+    const profile = manifestData.profile || manifestData.profiles?.[0] || 'auto';
+    const cursorResults = this.cursorAdapter.write(rootDir, { profile });
+    writtenFiles.push(...cursorResults.map((r) => ({
+      path: r.path,
+      action: r.action,
+      description: '生成 Cursor 适配规则',
+    })));
+
+    // 生成 Claude Code 适配文件（P0.5）
+    const claudeResults = this.claudeAdapter.write(rootDir, { profile });
+    writtenFiles.push(...claudeResults.map((r) => ({
+      path: r.path,
+      action: r.action,
+      description: '生成 Claude Code 适配文件',
+    })));
+
+    writtenFiles.push(...this.idePointerInjector.write(rootDir));
+
+    const result = {
+      projectId: context.projectId,
+      workspaceId: context.workspaceId,
+      localStateDir,
+      writtenFiles: writtenFiles.map((item) => ({
+        path: item.path,
+        action: item.action,
+      })),
+      warnings: [],
+    };
+    await this.reportInstallRecord(rootDir, plan, context, result, options);
+    await this.reportProjectState(rootDir, result, options);
+    return result;
+  }
+
+  async reportInstallRecord(rootDir, plan, context, result, options = {}) {
+    const hubConfig = resolveHubConfig(rootDir, { hubUrl: options.hubUrl });
+    const manifest = plan.packages.find((item) => item.recommendedManifest)?.recommendedManifest || null;
+    if (!hubConfig.url || !manifest) return;
+    try {
+      await this.hubClient.createInstallRecord({
+        projectId: context.projectId,
+        workspaceId: context.workspaceId || '',
+        manifest: {
+          slug: manifest.slug,
+          version: manifest.version || '1.0.0',
+        },
+        packages: plan.packages.map((item) => ({
+          packageId: item.packageId,
+          path: item.path,
+          manifest: item.recommendedManifest ? {
+            slug: item.recommendedManifest.slug,
+            version: item.recommendedManifest.version || '1.0.0',
+          } : null,
+        })),
+        installedAt: new Date().toISOString(),
+        client: {
+          name: 'br-ai-spec',
+          version: pkg.version || '',
+        },
+      }, { hubUrl: hubConfig.url });
+    } catch (error) {
+      result.warnings.push(`Install Record 上报失败，不影响本地 init：${error.message}`);
+    }
+  }
+
+  async reportProjectState(rootDir, result, options = {}) {
+    const report = await this.visualReporter.reportProjectState(rootDir, {
+      visualUrl: options.visualUrl,
+      eventId: `project-state:${result.projectId}:init-apply`,
+    });
+    if (report.warning) {
+      result.warnings.push(report.warning);
+    }
+  }
+}
+
+module.exports = {
+  InitApplier,
+};