@gong-ym/ai-spec-auto 0.2.3

package/src/project/config-writer.js

@@ -0,0 +1,83 @@
+const path = require('path');
+const os = require('os');
+const { mergeMissing, readJsonIfExists, stableHash, writeJson } = require('./json-utils');
+
+function resolveProjectName(rootDir, planPackage) {
+  if (planPackage?.name) return planPackage.name;
+  return path.basename(rootDir);
+}
+
+function buildProjectHash(rootDir) {
+  return stableHash(rootDir, 12);
+}
+
+function buildProjectId(projectName, projectHash) {
+  const slug = projectName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  return `${slug}-${projectHash}`;
+}
+
+function resolveLocalStateDir(projectId) {
+  return path.join(os.homedir(), '.ai-spec-auto', 'projects', projectId);
+}
+
+class ConfigWriter {
+  write(rootDir, plan, options = {}) {
+    const filePath = path.join(rootDir, '.ai-spec', 'config.json');
+    const existing = readJsonIfExists(filePath);
+    const now = options.now || new Date().toISOString();
+    const planPackage = plan.packages[0] || null;
+    const projectName = resolveProjectName(rootDir, planPackage);
+    const projectHash = buildProjectHash(rootDir);
+    const projectId = buildProjectId(projectName, projectHash);
+    const localStateDir = resolveLocalStateDir(projectId);
+
+    const defaultDoc = {
+      version: '0.1.0',
+      projectName,
+      projectId,
+      projectRoot: rootDir,
+      projectHash,
+      localStateDir,
+      adapters: {
+        cursor: true,
+        claudeCode: true,
+        codex: false,
+      },
+      runtime: {
+        maxRepairAttempts: 2,
+        requireTestBeforeDone: true,
+        requireReviewBeforeArchive: true,
+      },
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    const nextDoc = mergeMissing(defaultDoc, existing || {});
+    nextDoc.updatedAt = now;
+    // 保证 projectId 和 localStateDir 基于实际路径计算，不被旧值覆盖
+    nextDoc.projectId = projectId;
+    nextDoc.projectHash = projectHash;
+    nextDoc.localStateDir = localStateDir;
+    nextDoc.projectRoot = rootDir;
+
+    writeJson(filePath, nextDoc);
+    return {
+      path: '.ai-spec/config.json',
+      fullPath: filePath,
+      action: existing ? 'update' : 'create',
+      data: nextDoc,
+    };
+  }
+}
+
+module.exports = {
+  ConfigWriter,
+  buildProjectHash,
+  buildProjectId,
+  resolveLocalStateDir,
+  resolveProjectName,
+};

package/src/project/context-index-writer.js

@@ -0,0 +1,82 @@
+const path = require('path');
+const { readJsonIfExists, writeJson } = require('./json-utils');
+
+function createContextIndex(projectId) {
+  return {
+    schemaVersion: '1.0.0',
+    projectId,
+    contextStrategy: 'progressive',
+    levels: {
+      L0: {
+        name: '命令入口与状态机阶段',
+        alwaysLoad: [
+          '.ai-spec/project.json',
+          '.ai-spec/policy.json',
+        ],
+      },
+      L1: {
+        name: '项目画像',
+        loadFiles: [
+          '.ai-spec/project.json',
+          '.ai-spec/workspace.json',
+        ],
+      },
+      L2: {
+        name: 'Manifest 与 Registry 索引',
+        loadFiles: [
+          '.ai-spec/ai-spec.lock.json',
+          '.agents/registry.index.json',
+        ],
+      },
+      L3: {
+        name: '阶段相关资产全文',
+        loadByRegistry: true,
+      },
+    },
+    stageLoadRules: [
+      {
+        stage: 'planning',
+        loadKinds: ['role', 'flow'],
+        maxAssets: 5,
+      },
+      {
+        stage: 'implementation',
+        loadKinds: ['rule', 'skill', 'agent-profile'],
+        maxAssets: 8,
+      },
+      {
+        stage: 'verification',
+        loadKinds: ['rule', 'flow'],
+        maxAssets: 6,
+      },
+      {
+        stage: 'diagnosing',
+        loadKinds: ['rule', 'skill', 'agent-profile'],
+        requiredAgents: ['diagnostic-agent'],
+        maxAssets: 6,
+      },
+    ],
+    sharedContracts: [],
+  };
+}
+
+class ContextIndexWriter {
+  write(rootDir, context = {}) {
+    const filePath = path.join(rootDir, '.ai-spec/context-index.json');
+    const existing = readJsonIfExists(filePath);
+    const doc = createContextIndex(context.projectId || '');
+
+    writeJson(filePath, doc);
+    return {
+      path: '.ai-spec/context-index.json',
+      fullPath: filePath,
+      action: existing ? 'update' : 'create',
+      data: doc,
+    };
+  }
+}
+
+module.exports = {
+  ContextIndexWriter,
+  createContextIndex,
+};

package/src/project/json-utils.js

@@ -0,0 +1,72 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeMissing(defaultValue, existingValue) {
+  if (Array.isArray(defaultValue)) {
+    return Array.isArray(existingValue) ? existingValue : defaultValue;
+  }
+  if (!isPlainObject(defaultValue)) {
+    return existingValue === undefined ? defaultValue : existingValue;
+  }
+
+  const result = isPlainObject(existingValue) ? { ...existingValue } : {};
+  for (const [key, value] of Object.entries(defaultValue)) {
+    if (result[key] === undefined) {
+      result[key] = value;
+    } else if (isPlainObject(value) && isPlainObject(result[key])) {
+      result[key] = mergeMissing(value, result[key]);
+    }
+  }
+  return result;
+}
+
+function stableHash(input, length = 16) {
+  return crypto.createHash('sha256').update(String(input)).digest('hex').slice(0, length);
+}
+
+function createChecksum(input) {
+  return `sha256:${crypto.createHash('sha256').update(String(input)).digest('hex')}`;
+}
+
+function toPosixPath(filePath) {
+  return String(filePath).replace(/\\/g, '/');
+}
+
+function toRelativePath(rootDir, targetPath) {
+  const relativePath = path.relative(rootDir, targetPath) || '.';
+  return toPosixPath(relativePath);
+}
+
+module.exports = {
+  ensureDir,
+  readJsonIfExists,
+  writeJson,
+  mergeMissing,
+  stableHash,
+  createChecksum,
+  toRelativePath,
+  toPosixPath,
+};

package/src/project/local-state-writer.js

@@ -0,0 +1,50 @@
+const fs = require('fs');
+const path = require('path');
+const { ensureDir } = require('./json-utils');
+
+const LOCAL_STATE_SUBDIRS = [
+  'runs',
+  'cache',
+  'logs',
+  'context',
+  'repair',
+  'secrets',
+  'workspaces',
+  'telemetry',
+  'tmp',
+];
+
+class LocalStateWriter {
+  /**
+   * 创建用户本机运行态目录
+   * @param {string} localStateDir 本机运行态根目录（~/.ai-spec-auto/projects/{projectId}）
+   * @returns {{ created: string[], existed: string[] }}
+   */
+  write(localStateDir) {
+    const created = [];
+    const existed = [];
+
+    for (const subdir of LOCAL_STATE_SUBDIRS) {
+      const dirPath = path.join(localStateDir, subdir);
+      if (fs.existsSync(dirPath)) {
+        existed.push(subdir);
+      } else {
+        ensureDir(dirPath);
+        created.push(subdir);
+      }
+    }
+
+    // 确保 secrets 目录有 .gitignore
+    const secretsGitignore = path.join(localStateDir, 'secrets', '.gitignore');
+    if (!fs.existsSync(secretsGitignore)) {
+      fs.writeFileSync(secretsGitignore, '*\n!.gitignore\n', 'utf8');
+    }
+
+    return { created, existed };
+  }
+}
+
+module.exports = {
+  LOCAL_STATE_SUBDIRS,
+  LocalStateWriter,
+};

package/src/project/lock-file-writer.js

@@ -0,0 +1,98 @@
+const fs = require('fs');
+const path = require('path');
+const { createChecksum, readJsonIfExists, writeJson } = require('./json-utils');
+
+class LockFileWriter {
+  write(rootDir, plan, context = {}, options = {}) {
+    const filePath = path.join(rootDir, '.ai-spec/ai-spec.lock.json');
+    const existing = readJsonIfExists(filePath);
+    const now = options.now || new Date().toISOString();
+    const manifest = plan.packages[0]?.recommendedManifest || null;
+    const writtenFiles = options.writtenFiles || [];
+
+    // 构建 adapterOutputs：按 IDE 分组生成文件
+    const adapterOutputs = {
+      cursor: [],
+      claudeCode: [],
+      codex: [],
+    };
+    for (const file of writtenFiles) {
+      const filePathStr = file.path || '';
+      if (filePathStr.startsWith('.cursor/')) {
+        adapterOutputs.cursor.push(filePathStr);
+      } else if (filePathStr.startsWith('.claude/') || filePathStr === 'CLAUDE.md') {
+        adapterOutputs.claudeCode.push(filePathStr);
+      } else if (filePathStr.startsWith('.codex/')) {
+        adapterOutputs.codex.push(filePathStr);
+      }
+    }
+
+    // 构建 assets：从 writtenFiles 中提取非适配器文件
+    const assets = writtenFiles
+      .filter((f) => !f.path.startsWith('.cursor/') && !f.path.startsWith('.claude/') && !f.path.startsWith('.codex/'))
+      .map((f) => ({
+        assetId: f.path.replace(/\//g, '-').replace(/^-|-$/g, ''),
+        assetType: guessAssetType(f.path),
+        version: '0.1.0',
+        source: 'local',
+        checksum: createContentChecksum(rootDir, f.path),
+        lockedAt: now,
+        generatedFiles: [f.path],
+      }));
+
+    const doc = {
+      schemaVersion: '1.0.0',
+      lockfileVersion: '0.1.0',
+      projectId: context.projectId || '',
+      workspaceId: context.workspaceId || '',
+      lockedAt: now,
+      hub: {
+        url: plan.hub?.url || '',
+      },
+      manifest: manifest ? {
+        slug: manifest.slug,
+        version: manifest.version || '1.0.0',
+        checksum: manifest.checksum || createChecksum(`${manifest.slug}@${manifest.version || '1.0.0'}`),
+        installedAt: existing?.manifest?.installedAt || now,
+      } : null,
+      assets,
+      adapterOutputs,
+      generatedFiles: writtenFiles.map((f) => f.path),
+      overlays: [],
+      sharedContracts: [],
+    };
+
+    writeJson(filePath, doc);
+    return {
+      path: '.ai-spec/ai-spec.lock.json',
+      fullPath: filePath,
+      action: existing ? 'update' : 'create',
+      data: doc,
+    };
+  }
+}
+
+function createContentChecksum(rootDir, relativePath) {
+  const fullPath = path.join(rootDir, relativePath);
+  if (fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+    const content = fs.readFileSync(fullPath, 'utf8');
+    return createChecksum(content);
+  }
+  // 目录或不存在的文件回退到路径 hash
+  return createChecksum(relativePath);
+}
+
+function guessAssetType(filePath) {
+  if (filePath.startsWith('.agents/rules/')) return 'rule';
+  if (filePath.startsWith('.agents/skills/')) return 'skill';
+  if (filePath.startsWith('.agents/roles/')) return 'agentProfile';
+  if (filePath.startsWith('.agents/commands/')) return 'command';
+  if (filePath.startsWith('.harness/')) return 'hook';
+  if (filePath.startsWith('.memory/')) return 'memory';
+  if (filePath.startsWith('.ai-spec/')) return 'config';
+  return 'other';
+}
+
+module.exports = {
+  LockFileWriter,
+};

package/src/project/manifest-writer.js

@@ -0,0 +1,126 @@
+const fs = require('fs');
+const path = require('path');
+const { createChecksum, readJsonIfExists, toRelativePath, writeJson } = require('./json-utils');
+
+const ASSET_SUBDIRS = ['rules', 'skills', 'roles', 'commands', 'flows', 'orchestration', 'templates'];
+
+const MANIFEST_TO_PROFILE = Object.freeze({
+  'frontend-vue-vite-standard': 'vue',
+  'frontend-react-vite-standard': 'react',
+  'frontend-react-standard': 'react',
+  'frontend-react-nextjs-standard': 'react',
+  'backend-java-springboot-standard': 'springboot',
+  'backend-java-springmvc-legacy-standard': 'springboot',
+  'backend-java-springcloud-standard': 'springboot',
+  'backend-node-nestjs-standard': 'nestjs',
+});
+
+function scanAssets(rootDir, subdir) {
+  const dirPath = path.join(rootDir, '.agents', subdir);
+  if (!fs.existsSync(dirPath)) return [];
+  const files = [];
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    if (entry.isFile()) {
+      const fullPath = path.join(dirPath, entry.name);
+      const relativePath = toRelativePath(rootDir, fullPath);
+      files.push({
+        id: `${subdir}/${entry.name.replace(/\.[^.]+$/, '')}`,
+        version: '0.1.0',
+        path: relativePath,
+      });
+    }
+  }
+  return files;
+}
+
+class ManifestWriter {
+  write(rootDir, plan, context = {}, options = {}) {
+    const filePath = path.join(rootDir, '.ai-spec', 'manifest.json');
+    const existing = readJsonIfExists(filePath);
+    const now = options.now || new Date().toISOString();
+    const manifest = plan.packages[0]?.recommendedManifest || null;
+
+    const rules = scanAssets(rootDir, 'rules');
+    const skills = scanAssets(rootDir, 'skills');
+    const commands = scanAssets(rootDir, 'commands');
+    const agentProfiles = scanAssets(rootDir, 'roles');
+
+    const adapters = {
+      cursor: {
+        enabled: true,
+        outputDir: '.cursor/rules',
+      },
+      claudeCode: {
+        enabled: true,
+        outputDir: '.claude',
+      },
+      codex: {
+        enabled: false,
+      },
+    };
+
+    const memory = {
+      project: '.memory/project.md',
+      conventions: '.memory/conventions.md',
+    };
+
+    const hooks = [];
+    const hooksConfigPath = path.join(rootDir, '.harness', 'hooks.config.json');
+    if (fs.existsSync(hooksConfigPath)) {
+      hooks.push({
+        id: 'hooks-config',
+        path: '.harness/hooks.config.json',
+      });
+    }
+
+    const profile = manifest ? MANIFEST_TO_PROFILE[manifest.slug] || null : null;
+    const profiles = profile ? [profile] : [];
+
+    const doc = {
+      version: '0.1.0',
+      projectId: context.projectId || '',
+      manifestSlug: manifest ? manifest.slug : null,
+      manifestVersion: manifest ? manifest.version || '1.0.0' : null,
+      profiles,
+      profile: profiles[0] || null,
+      rules,
+      skills,
+      agentProfiles,
+      commands,
+      hooks,
+      adapters,
+      memory,
+      specs: [],
+      generatedAt: now,
+    };
+
+    // 计算 checksum（排除 checksum 字段本身）
+    const checksumInput = JSON.stringify({
+      version: doc.version,
+      projectId: doc.projectId,
+      manifestSlug: doc.manifestSlug,
+      rules: doc.rules,
+      skills: doc.skills,
+      agentProfiles: doc.agentProfiles,
+      commands: doc.commands,
+      hooks: doc.hooks,
+      adapters: doc.adapters,
+      memory: doc.memory,
+      specs: doc.specs,
+    });
+    doc.checksum = createChecksum(checksumInput);
+
+    writeJson(filePath, doc);
+    return {
+      path: '.ai-spec/manifest.json',
+      fullPath: filePath,
+      action: existing ? 'update' : 'create',
+      data: doc,
+    };
+  }
+}
+
+module.exports = {
+  ManifestWriter,
+  scanAssets,
+};

package/src/project/policy-config-writer.js

@@ -0,0 +1,91 @@
+const path = require('path');
+const { mergeMissing, readJsonIfExists, writeJson } = require('./json-utils');
+
+const FORCED_PRIVACY_FALSE_FIELDS = [
+  'uploadSourceCode',
+  'uploadAbsolutePath',
+  'uploadUserName',
+  'uploadRawPrompt',
+  'uploadRawResponse',
+  'uploadFileContent',
+];
+
+function createDefaultPolicy() {
+  return {
+    schemaVersion: '1.0.0',
+    execution: {
+      mode: 'local-assisted',
+      defaultExecutor: 'cursor',
+      fallbackExecutors: ['claude-code', 'codex'],
+      executorSelectionStrategy: 'policy-first',
+    },
+    branchPolicy: {
+      autoCreateBranch: true,
+      autoCreateWorktree: true,
+      baseBranch: 'develop',
+      branchPrefix: 'ai',
+      worktreeRoot: '../.ai-worktrees',
+      dirtyStrategy: 'block',
+      cleanupAfterMerge: false,
+    },
+    privacyPolicy: {
+      uploadSourceCode: false,
+      uploadAbsolutePath: false,
+      uploadUserName: false,
+      uploadRawPrompt: false,
+      uploadRawResponse: false,
+      uploadFileContent: false,
+      allowRelativePath: true,
+      allowFailureSummary: true,
+      allowTestSummary: true,
+    },
+    scanPolicy: {
+      readonly: true,
+      maxDepth: 5,
+      useCache: true,
+      confidenceAutoSelectThreshold: 80,
+      confidenceRequireConfirmThreshold: 60,
+    },
+    hub: {
+      url: '',
+      enabled: false,
+      fallbackToLocal: true,
+    },
+    visual: {
+      url: '',
+      enabled: false,
+      nonBlocking: true,
+    },
+  };
+}
+
+class PolicyConfigWriter {
+  write(rootDir, _plan, options = {}) {
+    const filePath = path.join(rootDir, '.ai-spec/policy.json');
+    const existing = readJsonIfExists(filePath);
+    const nextDoc = mergeMissing(createDefaultPolicy(), existing || {});
+    nextDoc.schemaVersion = nextDoc.schemaVersion || '1.0.0';
+    nextDoc.privacyPolicy = nextDoc.privacyPolicy || {};
+    for (const field of FORCED_PRIVACY_FALSE_FIELDS) {
+      nextDoc.privacyPolicy[field] = false;
+    }
+    if (options.visualUrl) {
+      nextDoc.visual = nextDoc.visual || {};
+      nextDoc.visual.url = options.visualUrl;
+      nextDoc.visual.enabled = true;
+    }
+    writeJson(filePath, nextDoc);
+    return {
+      path: '.ai-spec/policy.json',
+      fullPath: filePath,
+      action: existing ? 'update' : 'create',
+      data: nextDoc,
+    };
+  }
+}
+
+module.exports = {
+  FORCED_PRIVACY_FALSE_FIELDS,
+  PolicyConfigWriter,
+  createDefaultPolicy,
+};

package/src/project/project-config-writer.js

@@ -0,0 +1,74 @@
+const path = require('path');
+const {
+  createChecksum,
+  mergeMissing,
+  readJsonIfExists,
+  stableHash,
+  writeJson,
+} = require('./json-utils');
+
+function resolveProjectName(rootDir, planPackage) {
+  if (planPackage?.name) return planPackage.name;
+  return path.basename(rootDir);
+}
+
+function selectPrimaryPackage(plan) {
+  return plan.packages[0] || null;
+}
+
+function buildManifestConfig(manifest) {
+  if (!manifest) return null;
+  return {
+    slug: manifest.slug,
+    version: manifest.version || '1.0.0',
+    checksum: createChecksum(`${manifest.slug}@${manifest.version || '1.0.0'}`),
+  };
+}
+
+class ProjectConfigWriter {
+  write(rootDir, plan, options = {}) {
+    const filePath = path.join(rootDir, '.ai-spec/project.json');
+    const existing = readJsonIfExists(filePath);
+    const now = options.now || new Date().toISOString();
+    const planPackage = selectPrimaryPackage(plan);
+    const manifest = planPackage?.recommendedManifest || null;
+    const defaultDoc = {
+      schemaVersion: '1.0.0',
+      projectId: `proj_${stableHash(rootDir, 20)}`,
+      projectName: resolveProjectName(rootDir, planPackage),
+      projectType: plan.packages.length > 1 || planPackage?.path !== '.' ? 'package' : 'single',
+      relativePath: '.',
+      techProfile: {
+        domain: planPackage?.techProfile?.domain || '',
+        language: planPackage?.techProfile?.language || [],
+        frameworks: planPackage?.techProfile?.frameworks || [],
+        buildTool: planPackage?.techProfile?.buildTool || '',
+        confidence: planPackage?.techProfile?.confidence || 0,
+        reasons: planPackage?.techProfile?.reasons || [],
+      },
+      projectKind: planPackage?.projectKind || 'unknown',
+      manifest: buildManifestConfig(manifest),
+      warnings: planPackage?.warnings || [],
+      defaultExecutor: 'cursor',
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    const nextDoc = mergeMissing(defaultDoc, existing || {});
+    if (!manifest) {
+      nextDoc.manifest = null;
+    }
+    nextDoc.updatedAt = now;
+    writeJson(filePath, nextDoc);
+    return {
+      path: '.ai-spec/project.json',
+      fullPath: filePath,
+      action: existing ? 'update' : 'create',
+      data: nextDoc,
+    };
+  }
+}
+
+module.exports = {
+  ProjectConfigWriter,
+};