spectra-cli 4.1.1

package/plugins/spec-driver/scripts/validate-wrapper-sources.mjs

@@ -0,0 +1,302 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseYamlDocument } from './lib/simple-yaml.mjs';
+
+function parseArgs(argv) {
+  const options = {
+    projectRoot: process.cwd(),
+    json: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--project-root') {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error('缺少 --project-root 参数值');
+      }
+      options.projectRoot = path.resolve(value);
+      index += 1;
+      continue;
+    }
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+    throw new Error(`未知参数: ${arg}`);
+  }
+
+  return options;
+}
+
+function createCheck(id, title, status, evidence = {}) {
+  return { id, title, status, evidence };
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+}
+
+function ensureFileExists(filePath, message) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(message ?? `缺少文件: ${filePath}`);
+  }
+}
+
+export function loadWrapperSourceContract(projectRoot) {
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const contractPath = path.resolve(scriptDir, '..', 'contracts', 'wrapper-source-of-truth.yaml');
+  const contract = parseYamlDocument(fs.readFileSync(contractPath, 'utf-8'));
+  return {
+    projectRoot: path.resolve(projectRoot),
+    contractPath,
+    contract,
+  };
+}
+
+function validateWrapperMarkers(projectRoot, entries, errors) {
+  const requiredFragments = [
+    '## Wrapper Source Contract',
+    'Generated by:',
+    'Contract:',
+    'do not edit this wrapper directly',
+  ];
+  const checked = [];
+  const missingFiles = [];
+  const invalidMarkers = [];
+
+  for (const entry of entries) {
+    const targetPath = path.resolve(projectRoot, entry.target);
+    if (!fs.existsSync(targetPath)) {
+      missingFiles.push(entry.target);
+      continue;
+    }
+
+    const content = fs.readFileSync(targetPath, 'utf-8');
+    const missingFragments = requiredFragments.filter((fragment) => !content.includes(fragment));
+    const sourceMarker = `Canonical source: \`$PLUGIN_DIR/skills/${entry.id}/SKILL.md\``;
+    const contractMarker = 'Contract: `$PLUGIN_DIR/contracts/wrapper-source-of-truth.yaml`';
+    if (!content.includes(sourceMarker)) {
+      missingFragments.push(sourceMarker);
+    }
+    if (!content.includes(contractMarker)) {
+      missingFragments.push(contractMarker);
+    }
+
+    if (missingFragments.length > 0) {
+      invalidMarkers.push({
+        target: entry.target,
+        missingFragments,
+      });
+      continue;
+    }
+
+    checked.push(entry.target);
+  }
+
+  if (missingFiles.length > 0) {
+    errors.push(
+      `缺少 Codex 包装技能，请先运行 npm run codex:spec-driver:install：${missingFiles.join(', ')}`,
+    );
+  }
+
+  if (invalidMarkers.length > 0) {
+    errors.push(
+      `以下 Codex 包装技能缺少 wrapper source contract 标记：${invalidMarkers
+        .map((item) => `${item.target} [${item.missingFragments.join('; ')}]`)
+        .join(', ')}`,
+    );
+  }
+
+  return createCheck(
+    'codex-wrapper-markers',
+    'Codex 包装技能 source-of-truth 标记',
+    missingFiles.length === 0 && invalidMarkers.length === 0 ? 'pass' : 'fail',
+    {
+      checkedCount: checked.length,
+      missingFiles,
+      invalidMarkers,
+    },
+  );
+}
+
+function validateContract(projectRoot, contract) {
+  const errors = [];
+  const warnings = [];
+  const checks = [];
+
+  const pluginMetadataPath = path.resolve(projectRoot, contract.plugin?.metadataSource ?? '');
+  const marketplacePath = path.resolve(projectRoot, contract.plugin?.marketplaceManifest ?? '');
+  ensureFileExists(pluginMetadataPath, `缺少 plugin metadata: ${contract.plugin?.metadataSource ?? ''}`);
+  ensureFileExists(
+    marketplacePath,
+    `缺少 marketplace manifest: ${contract.plugin?.marketplaceManifest ?? ''}`,
+  );
+
+  const codexEntries = Array.isArray(contract.codexWrappers?.entries)
+    ? contract.codexWrappers.entries
+    : [];
+  const claudeEntries = Array.isArray(contract.claudeProjectOverrides?.entries)
+    ? contract.claudeProjectOverrides.entries
+    : [];
+
+  const missingSourceFiles = codexEntries
+    .filter((entry) => !fs.existsSync(path.resolve(projectRoot, entry.source)))
+    .map((entry) => entry.source);
+  if (missingSourceFiles.length > 0) {
+    errors.push(`缺少 canonical source skill: ${missingSourceFiles.join(', ')}`);
+  }
+  checks.push(
+    createCheck('source-skills', 'Canonical source skills', missingSourceFiles.length === 0 ? 'pass' : 'fail', {
+      count: codexEntries.length,
+      missing: missingSourceFiles,
+    }),
+  );
+
+  checks.push(validateWrapperMarkers(projectRoot, codexEntries, errors));
+
+  const missingClaudeOverrides = claudeEntries
+    .filter((entry) => !fs.existsSync(path.resolve(projectRoot, entry.target)))
+    .map((entry) => entry.target);
+  if (missingClaudeOverrides.length > 0) {
+    errors.push(`缺少 Claude project override: ${missingClaudeOverrides.join(', ')}`);
+  }
+  checks.push(
+    createCheck(
+      'claude-project-overrides',
+      'Claude 项目级 override',
+      missingClaudeOverrides.length === 0 ? 'pass' : 'fail',
+      {
+        count: claudeEntries.length,
+        missing: missingClaudeOverrides,
+      },
+    ),
+  );
+
+  const pluginMetadata = readJson(pluginMetadataPath);
+  const marketplace = readJson(marketplacePath);
+  const marketplaceEntry = Array.isArray(marketplace.plugins)
+    ? marketplace.plugins.find((entry) => entry.name === pluginMetadata.name)
+    : null;
+
+  if (!marketplaceEntry) {
+    errors.push(`marketplace.json 中缺少插件条目: ${pluginMetadata.name}`);
+  } else {
+    const expectedSource = `./${contract.plugin.sourceRoot}`;
+    if (marketplaceEntry.source !== expectedSource) {
+      errors.push(
+        `marketplace 插件 source 不匹配：期望 ${expectedSource}，实际 ${marketplaceEntry.source}`,
+      );
+    }
+    if (marketplaceEntry.version !== pluginMetadata.version) {
+      errors.push(
+        `marketplace 插件 version 不匹配：期望 ${pluginMetadata.version}，实际 ${marketplaceEntry.version}`,
+      );
+    }
+    if (marketplaceEntry.name !== pluginMetadata.name) {
+      errors.push(
+        `marketplace 插件 name 不匹配：期望 ${pluginMetadata.name}，实际 ${marketplaceEntry.name}`,
+      );
+    }
+  }
+
+  checks.push(
+    createCheck(
+      'plugin-metadata-sync',
+      'Plugin metadata 与 marketplace 同步',
+      marketplaceEntry && errors.every((error) => !error.includes('marketplace 插件') && !error.includes('marketplace.json 中缺少插件条目'))
+        ? 'pass'
+        : 'fail',
+      {
+        pluginName: pluginMetadata.name,
+        version: pluginMetadata.version,
+        sourceRoot: contract.plugin.sourceRoot,
+      },
+    ),
+  );
+
+  const status = errors.length > 0 ? 'fail' : warnings.length > 0 ? 'warn' : 'pass';
+  return {
+    schemaVersion: contract.schemaVersion ?? 1,
+    status,
+    contractPath: path.relative(projectRoot, path.resolve(projectRoot, 'plugins/spec-driver/contracts/wrapper-source-of-truth.yaml')).split(path.sep).join('/'),
+    checks,
+    warnings,
+    errors,
+  };
+}
+
+function formatTextResult(result) {
+  const lines = [
+    `[wrapper-source] status=${result.status}`,
+    `contract: ${result.contractPath}`,
+    '',
+  ];
+
+  for (const check of result.checks) {
+    lines.push(`- ${check.id}: ${check.status}`);
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push('', 'warnings:');
+    for (const warning of result.warnings) {
+      lines.push(`  - ${warning}`);
+    }
+  }
+
+  if (result.errors.length > 0) {
+    lines.push('', 'errors:');
+    for (const error of result.errors) {
+      lines.push(`  - ${error}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function validateWrapperSources(options = {}) {
+  // realpathSync 解决 macOS /var → /private/var symlink 导致 path.relative 计算错误的问题
+  const projectRoot = fs.realpathSync(path.resolve(options.projectRoot ?? process.cwd()));
+  const { contractPath, contract } = loadWrapperSourceContract(projectRoot);
+  const result = validateContract(projectRoot, contract);
+  return {
+    ...result,
+    contractPath: path.relative(projectRoot, contractPath).split(path.sep).join('/'),
+  };
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    console.log('用法: node plugins/spec-driver/scripts/validate-wrapper-sources.mjs --project-root . [--json]');
+    return;
+  }
+
+  const result = validateWrapperSources(options);
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatTextResult(result));
+  }
+
+  if (result.status === 'fail') {
+    process.exitCode = 1;
+  }
+}
+
+function isDirectExecution() {
+  if (!process.argv[1]) {
+    return false;
+  }
+  return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+}
+
+if (isDirectExecution()) {
+  main();
+}

package/plugins/spec-driver/skills/spec-driver-constitution/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: spec-driver-constitution
+description: "创建或更新项目宪法，并同步计划/规范/任务模板与运行时约束"
+disable-model-invocation: false
+allowed-tools: [Read, Write, Edit, Glob, Bash]
+model: sonnet
+effort: low
+---
+
+# Spec Driver — 项目宪法维护器
+
+你负责创建或更新项目宪法，确保 `.specify/memory/constitution.md` 与相关模板、命令覆盖和运行时约束保持一致。
+
+## 触发方式
+
+```text
+/spec-driver:spec-driver-constitution [原则更新说明]
+$spec-driver-constitution [原则更新说明]
+```
+
+你 **必须** 先考虑 `$ARGUMENTS` 中的用户输入（如果不为空）。
+
+## 执行流程
+
+1. 读取现有宪法文件 `.specify/memory/constitution.md`
+   - 若文件不存在，先从 `.specify/templates/constitution-template.md` 复制
+   - 识别所有 `[ALL_CAPS_IDENTIFIER]` 占位符
+   - 如果用户指定原则数量，按用户要求调整，不机械沿用模板条数
+
+2. 收集并推导占位值
+   - 优先使用用户输入
+   - 其次从仓库上下文推导（README、docs、现有 constitution、AGENTS/CLAUDE 约束等）
+   - `RATIFICATION_DATE` 表示首次采纳日期；未知则写 `TODO(RATIFICATION_DATE): ...`
+   - `LAST_AMENDED_DATE` 在本次有改动时更新为今天
+   - `CONSTITUTION_VERSION` 按语义化规则递增：
+     - MAJOR: 删除/重定义原则，产生不兼容治理变化
+     - MINOR: 新增原则或实质扩展治理范围
+     - PATCH: 纯澄清、措辞优化、错字修复
+
+3. 生成更新后的宪法正文
+   - 替换所有应落地的占位符，不保留未解释的方括号 token
+   - 保持原有标题层级
+   - 每条原则必须可执行、可验证，避免模糊措辞
+   - Governance 段必须明确修订流程、版本策略与合规检查要求
+
+4. 同步检查并修正相关制品
+   - 读取 `.specify/templates/plan-template.md`，确保 Constitution Check 与最新原则一致
+   - 读取 `.specify/templates/spec-template.md`，确保需求规范包含新的必填约束
+   - 读取 `.specify/templates/tasks-template.md`，确保任务模板反映新的质量与治理要求
+   - 如存在，读取 `.claude/commands/*.md` 与 `.codex/commands/*.md`，修正过时引用
+   - 读取运行时指导文档（如 README、AGENTS、CLAUDE、docs/quickstart）并同步必要引用
+
+5. 在宪法顶部写入 Sync Impact Report（HTML 注释）
+   - 版本变更：old -> new
+   - 修改/重命名的原则
+   - 新增/删除的章节
+   - 受影响模板清单（✅ 已更新 / ⚠ 待处理）
+   - 延后处理的 TODO
+
+6. 写回文件前自检
+   - 无未解释的方括号占位符
+   - 版本号与影响报告一致
+   - 日期为 `YYYY-MM-DD`
+   - 原则使用明确的 MUST/SHOULD 语义
+
+7. 覆写 `.specify/memory/constitution.md`
+
+8. 向用户输出摘要
+   - 新版本号与 bump 原因
+   - 仍需人工跟进的文件
+   - 建议 commit message，例如 `docs: amend constitution to vX.Y.Z`
+
+## 约束
+
+- 只修改宪法及其直接同步依赖制品
+- 不新建第二份模板或旁路文件
+- 若关键信息无法推导，明确写入 `TODO(...)`，不要静默省略