@jspg-ai/coding-bb 0.0.1

package/cbb/lib/openspec/index.js

@@ -0,0 +1,554 @@
+#!/usr/bin/env node
+
+/**
+ * OpenSpec 工作流管理模块
+ *
+ * 负责从 GitHub (Fission-AI/OpenSpec) 拉取官方 workflow 模板,
+ * 渲染并部署到本项目的 openspec/{commands,skills} 目录。
+ * 提供 `cbb update --upstream-openspec` 选项。
+ *
+ * 升级范围严格限定:只有 WORKFLOWS 白名单中的 commands/*.md 和
+ * skills/<workflow>/SKILL.md 会被覆盖写入。config/openspec/（schemas + config.yaml）、
+ * cbb/worktrees/ 等项目自有扩展位不会被触碰 —— 由 assertSafeDestination
+ * 兜底拦截,任何写入命中受保护前缀都会抛错退出。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const os = require('os');
+const zlib = require('zlib');
+
+const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
+
+// 部署目标根目录
+const OPENSPEC_DIR = path.join(SHARED_STANDARDS_DIR, 'openspec');
+const OPENSPEC_COMMANDS_DIR = path.join(OPENSPEC_DIR, 'commands');
+const OPENSPEC_SKILLS_DIR = path.join(OPENSPEC_DIR, 'skills');
+
+// 版本文件(commit SHA)
+const VERSION_FILE = path.join(OPENSPEC_DIR, '.version');
+
+// GitHub 配置
+const GITHUB_REPO = 'Fission-AI/OpenSpec';
+const GITHUB_BRANCH = 'main';
+// 使用 codeload (不走 API,无速率限制) 与 git ls-remote (拉 SHA,无速率限制)
+const GITHUB_TARBALL_URL = `https://codeload.github.com/${GITHUB_REPO}/tar.gz/refs/heads/${GITHUB_BRANCH}`;
+const GITHUB_GIT_URL = `https://github.com/${GITHUB_REPO}.git`;
+
+// 升级白名单:每个工作流的源文件名 → 命令文件名 + skill 目录名
+// 部署 strategy:
+//   - cmd 不为空 → 写入 commands/<cmd>.md
+//   - skill 不为空 → 写入 skills/<skill>/SKILL.md
+const WORKFLOWS = [
+  { name: 'propose',            cmd: 'propose',       skill: 'openspec-propose' },
+  { name: 'apply-change',       cmd: 'apply',         skill: 'openspec-apply-change' },
+  { name: 'archive-change',     cmd: 'archive',       skill: 'openspec-archive-change' },
+  { name: 'verify-change',      cmd: 'verify',        skill: 'openspec-verify-change' },
+  { name: 'ff-change',          cmd: 'ff',            skill: 'openspec-ff-change' },
+  { name: 'continue-change',    cmd: 'continue',      skill: 'openspec-continue-change' },
+  { name: 'new-change',         cmd: 'new',           skill: 'openspec-new-change' },
+  { name: 'explore',            cmd: 'explore',       skill: 'openspec-explore' },
+  { name: 'update-change',      cmd: 'update',        skill: 'openspec-update-change' },
+  { name: 'sync-specs',         cmd: 'sync',          skill: 'openspec-sync-specs' },
+  { name: 'bulk-archive-change',cmd: 'bulk-archive',  skill: 'openspec-bulk-archive-change' },
+  { name: 'onboard',            cmd: 'onboard',       skill: 'openspec-onboard' },
+];
+
+// ── 受保护路径（项目自有扩展位,绝对禁止覆盖写入）─────────────
+//
+// 与 AGENTS.md「原生内容保护与扩展位」一致:
+// - config/openspec/schemas/     项目自托管 schema 与模板（spec-driven）
+// - cbb/worktrees/              项目自有扩展(worktree 命令/技能/_shared)
+// - config/openspec/config.yaml 项目自托管
+//
+// 任何写入命中下列任一前缀,assertSafeDestination 立即抛错,
+// 避免后续重构意外把 schema.yaml / config.yaml / worktrees/ 冲掉。
+const PROTECTED_PATH_PREFIXES = [
+  path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'schemas'),
+  path.join(SHARED_STANDARDS_DIR, 'cbb', 'worktrees'),
+  path.join(SHARED_STANDARDS_DIR, 'config', 'openspec', 'config.yaml'),
+];
+
+function assertSafeDestination(destPath, op) {
+  const abs = path.resolve(destPath);
+  for (const prefix of PROTECTED_PATH_PREFIXES) {
+    if (abs === prefix || abs.startsWith(prefix + path.sep)) {
+      throw new Error(
+        `[cbb update --upstream-openspec] ${op} 试图写入受保护路径: ${abs}\n` +
+        `命中前缀: ${prefix}\n` +
+        `该路径属于项目自有扩展位,绝对禁止被 cbb update --upstream-openspec 覆盖。\n` +
+        `详见 AGENTS.md「原生内容保护与扩展位」一节。`
+      );
+    }
+  }
+}
+
+// 与 lib/install/init.js 共用输出辅助
+const { log } = require('../utils/output');
+
+// 嵌入的 STORE_SELECTION_GUIDANCE (来自 Fission-AI/OpenSpec store-selection.ts)
+// 用于替换官方 TS 模板中的 ${STORE_SELECTION_GUIDANCE} 占位符
+const STORE_SELECTION_GUIDANCE_TEXT =
+  '**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.';
+
+// ── HTTP 工具 ──────────────────────────────────────────────────
+
+function httpsGet(url, headers = {}, redirectCount = 0) {
+  if (redirectCount > 5) throw new Error('Too many redirects');
+
+  return new Promise((resolve, reject) => {
+    const defaultHeaders = { 'User-Agent': 'cbb-cli' };
+    https.get(url, { headers: { ...defaultHeaders, ...headers } }, (res) => {
+      if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location) {
+        res.resume();
+        return httpsGet(res.headers.location, headers, redirectCount + 1)
+          .then(resolve, reject);
+      }
+
+      const chunks = [];
+      res.on('data', chunk => chunks.push(chunk));
+      res.on('end', () => {
+        resolve({
+          statusCode: res.statusCode,
+          headers: res.headers,
+          body: Buffer.concat(chunks),
+        });
+      });
+      res.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+async function downloadToFile(url, destPath) {
+  const res = await httpsGet(url);
+  if (res.statusCode !== 200) {
+    throw new Error(`HTTP ${res.statusCode}: ${url}`);
+  }
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+  fs.writeFileSync(destPath, res.body);
+  return res;
+}
+
+/**
+ * HEAD 请求拿 ETag,用于无 API 限速的版本比对。
+ * codeload 对同一 ref 的 tarball 返回稳定 ETag;上游变更即变化。
+ */
+async function fetchEtag(url) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(url, { method: 'HEAD', headers: { 'User-Agent': 'cbb-cli' } }, (res) => {
+      const etag = (res.headers.etag || '').replace(/^W\//, '').replace(/^"|"$/g, '');
+      res.resume();
+      res.on('end', () => resolve({ statusCode: res.statusCode, etag }));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+// ── tar.gz 解压 ──────────────────────────────────────────────────
+
+/**
+ * 跨平台 .tar.gz 解压,用 zlib + 手写 tar parser,避开 OS shell tar。
+ * 支持路径嵌套目录创建,跳过权限/所有者字段。
+ */
+function extractTarGz(tarGzPath, destDir) {
+  const compressed = fs.readFileSync(tarGzPath);
+  const data = zlib.gunzipSync(compressed);
+
+  let off = 0;
+  while (off + 512 <= data.length) {
+    const header = data.subarray(off, off + 512);
+    off += 512;
+
+    // 空块 = 连续两个 512-byte 零 = tar 终止
+    if (header.every(b => b === 0)) break;
+
+    // 文件名在 header[0..100] (NUL 终止)
+    let nameEnd = 0;
+    while (nameEnd < 100 && header[nameEnd] !== 0) nameEnd++;
+    const name = header.subarray(0, nameEnd).toString('utf-8');
+
+    // 文件大小在 header[124..136] (octal ASCII)
+    const sizeStr = header.subarray(124, 136).toString('utf-8').trim();
+    const size = parseInt(sizeStr, 8) || 0;
+
+    const target = path.join(destDir, name);
+    if (name.endsWith('/')) {
+      fs.mkdirSync(target, { recursive: true });
+    } else {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, data.subarray(off, off + size));
+    }
+
+    // 数据按 512 字节对齐
+    off += Math.ceil(size / 512) * 512;
+  }
+}
+
+// ── 版本管理 ──────────────────────────────────────────────────
+
+function getLocalVersion() {
+  if (!fs.existsSync(VERSION_FILE)) return null;
+  try {
+    const content = fs.readFileSync(VERSION_FILE, 'utf-8').trim();
+    if (content.startsWith('{')) {
+      const data = JSON.parse(content);
+      return data.sha || null;
+    }
+    return content || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeVersion(sha) {
+  const data = {
+    sha,
+    branch: GITHUB_BRANCH,
+    repo: GITHUB_REPO,
+    updatedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(VERSION_FILE, JSON.stringify(data, null, 2) + '\n');
+}
+
+// ── 渲染:从 *.ts 文件中提取 template literal 并替换占位符 ──
+
+/**
+ * 反转义 TS 模板字符串中典型的转义:
+ *   \`  → `   (反引号)
+ *   \$  → $   (美元符,常用于 \${\w} 形式防止被当作插值)
+ *   \\  → \   (反斜杠本身)
+ */
+function unescapeTsTemplate(s) {
+  return s
+    .replace(/\\`/g, '`')
+    .replace(/\\\$/g, '$')
+    .replace(/\\\\/g, '\\');
+}
+
+/**
+ * 将模板字符串中的 ${STORE_SELECTION_GUIDANCE} 替换为实际内容。
+ * 上游 store-selection.ts 是常量,我们直接内嵌字符串,避免运行时求值。
+ */
+function substituteStoreGuidance(s) {
+  return s.split('${STORE_SELECTION_GUIDANCE}').join(STORE_SELECTION_GUIDANCE_TEXT);
+}
+
+/**
+ * 从 TS 源码中提取 SkillTemplate 函数体内的字段,并渲染成 SKILL.md。
+ * @param {string} tsContent - 整个 .ts 文件内容
+ * @param {string} functionName - 例如 'getProposeSkillTemplate' / 'getApplyChangeSkillTemplate'
+ * @returns {string|null} 渲染出的 SKILL.md 完整内容,若提取失败返回 null
+ */
+function renderSkillFromTs(tsContent, functionName) {
+  // 匹配 functionName(...): SkillTemplate { return { ... }; }
+  const fnRegex = new RegExp(
+    `function\\s+${functionName}\\s*\\(\\)\\s*:\\s*SkillTemplate\\s*\\{[\\s\\S]*?return\\s*\\{([\\s\\S]*?)\\}\\s*;\\s*\\}`,
+    'm'
+  );
+  const fnMatch = tsContent.match(fnRegex);
+  if (!fnMatch) return null;
+  const fields = fnMatch[1];
+
+  // 提取 name (单引号字符串)
+  const nameMatch = fields.match(/name:\s*'([^']+)'/);
+  const name = nameMatch ? nameMatch[1] : '';
+
+  // 提取 description (单引号字符串)
+  const descMatch = fields.match(/description:\s*'([\s\S]*?)',\s*\n\s*instructions/);
+  const description = descMatch ? descMatch[1].trim() : '';
+
+  // 提取 instructions (backtick 模板字符串,以 `\n    license:` 为锚点)
+  let instMatch = fields.match(/instructions:\s*`([\s\S]*?)`,\s*\n\s*license/);
+  if (!instMatch) {
+    // 兜底: instructions 可能是函数调用,如 instructions: getOnboardInstructions(),
+    const fnCallMatch = fields.match(/instructions:\s*(\w+)\(\)/);
+    if (fnCallMatch) {
+      const helperFnName = fnCallMatch[1];
+      const helperFnRegex = new RegExp(
+        `function\\s+${helperFnName}\\s*\\([^)]*\\)\\s*:\\s*string\\s*\\{[\\s\\S]*?return\\s*\`([\\s\\S]*?)\`\\s*;\\s*\\}`,
+        'm'
+      );
+      const helperMatch = tsContent.match(helperFnRegex);
+      if (helperMatch) {
+        instMatch = [null, helperMatch[1]];
+      }
+    }
+  }
+  if (!instMatch) return null;
+  let instructions = unescapeTsTemplate(substituteStoreGuidance(instMatch[1]));
+  // 去掉开头/结尾的多余换行
+  instructions = instructions.replace(/^\n+/, '').replace(/\n+$/, '') + '\n';
+
+  // 提取 license / compatibility / metadata
+  const licenseMatch = fields.match(/license:\s*'([^']+)'/);
+  const license = licenseMatch ? licenseMatch[1] : 'MIT';
+  const compatMatch = fields.match(/compatibility:\s*'([^']+)'/);
+  const compatibility = compatMatch ? compatMatch[1] : 'Requires openspec CLI.';
+  const metaMatch = fields.match(/metadata:\s*\{\s*author:\s*'([^']+)',\s*version:\s*'([^']+)'/);
+  const metaAuthor = metaMatch ? metaMatch[1] : 'openspec';
+  const metaVersion = metaMatch ? metaMatch[2] : '1.0';
+
+  // 构造 frontmatter (YAML)
+  const fm = [
+    '---',
+    `name: ${name}`,
+    `description: ${description}`,
+    `license: ${license}`,
+    `compatibility: ${compatibility}`,
+    'metadata:',
+    `  author: ${metaAuthor}`,
+    `  version: "${metaVersion}"`,
+    `  generatedBy: "1.6.0"`,
+    '---',
+    '',
+  ].join('\n');
+
+  return fm + instructions;
+}
+
+/**
+ * 从 TS 源码中提取 CommandTemplate 函数体内的 content,并渲染成 .md。
+ * @param {string} tsContent
+ * @param {string} functionName - 例如 'getOpsxProposeCommandTemplate'
+ * @returns {string|null}
+ */
+function renderCommandFromTs(tsContent, functionName) {
+  const fnRegex = new RegExp(
+    `function\\s+${functionName}\\s*\\(\\)\\s*:\\s*CommandTemplate\\s*\\{[\\s\\S]*?return\\s*\\{([\\s\\S]*?)\\}\\s*;\\s*\\}`,
+    'm'
+  );
+  const fnMatch = tsContent.match(fnRegex);
+  if (!fnMatch) return null;
+  const fields = fnMatch[1];
+
+  // 提取 description (单引号字符串)
+  const descMatch = fields.match(/description:\s*'([\s\S]*?)',\s*\n\s*category/);
+  const description = descMatch ? descMatch[1].trim() : '';
+
+  // 提取 category / tags
+  const catMatch = fields.match(/category:\s*'([^']+)'/);
+  const category = catMatch ? catMatch[1] : 'Workflow';
+  const tagsMatch = fields.match(/tags:\s*\[([^\]]+)\]/);
+  let tags = '[]';
+  if (tagsMatch) {
+    const tagList = tagsMatch[1]
+      .split(',')
+      .map(t => t.trim().replace(/^['"]|['"]$/g, ''))
+      .filter(Boolean);
+    tags = '[' + tagList.join(', ') + ']';
+  }
+
+  // 提取 content (backtick 模板字符串;content 是 CommandTemplate 的最末字段,
+  // 所以以字符串结尾 `$` 作为锚点即可,不带 /m 标志)
+  let contentMatch = fields.match(/content:\s*`([\s\S]*?)`\s*$/);
+  if (!contentMatch) {
+    // 兜底: content 可能是函数调用,如 content: getOnboardInstructions(),
+    const fnCallMatch = fields.match(/content:\s*(\w+)\(\)/);
+    if (fnCallMatch) {
+      const helperFnName = fnCallMatch[1];
+      const helperFnRegex = new RegExp(
+        `function\\s+${helperFnName}\\s*\\([^)]*\\)\\s*:\\s*string\\s*\\{[\\s\\S]*?return\\s*\`([\\s\\S]*?)\`\\s*;\\s*\\}`,
+        'm'
+      );
+      const helperMatch = tsContent.match(helperFnRegex);
+      if (helperMatch) {
+        contentMatch = [null, helperMatch[1]];
+      }
+    }
+  }
+  if (!contentMatch) return null;
+  let content = unescapeTsTemplate(substituteStoreGuidance(contentMatch[1]));
+  content = content.replace(/^\n+/, '').replace(/\n+$/, '') + '\n';
+
+  // 派生 name: 'OPSX: <Title>' 来自 description 的若干词
+  // 实际从 CommandTemplate.name 字段读取
+  const nameMatch = fields.match(/name:\s*'([^']+)'/);
+  const name = nameMatch ? nameMatch[1] : `OPSX: ${description.split(/[.,:!?]/)[0].slice(0, 24)}`;
+
+  const fm = [
+    '---',
+    `name: "${name}"`,
+    `description: ${description}`,
+    `category: ${category}`,
+    `tags: ${tags}`,
+    '---',
+    '',
+  ].join('\n');
+
+  return fm + content;
+}
+
+/**
+ * 把 workflow 名映射到它对应的 TS 函数名。
+ * 例如 'propose' → getOpsxProposeCommandTemplate / getOpsxProposeSkillTemplate
+ */
+function functionNamesForWorkflow(name, kind /* 'cmd' | 'skill' */) {
+  // 所有官方 cmd 函数都以 getOpsx 开头,skill 以 get 开头,Workflow 名驼峰式接续
+  // 我们手动列出(因为没法从文件名可靠推导)
+  const map = {
+    'propose':            { cmd: 'getOpsxProposeCommandTemplate',            skill: 'getOpsxProposeSkillTemplate' },
+    'apply-change':       { cmd: 'getOpsxApplyCommandTemplate',             skill: 'getApplyChangeSkillTemplate' },
+    'archive-change':     { cmd: 'getOpsxArchiveCommandTemplate',           skill: 'getArchiveChangeSkillTemplate' },
+    'verify-change':      { cmd: 'getOpsxVerifyCommandTemplate',            skill: 'getVerifyChangeSkillTemplate' },
+    'ff-change':          { cmd: 'getOpsxFfCommandTemplate',                skill: 'getFfChangeSkillTemplate' },
+    'continue-change':    { cmd: 'getOpsxContinueCommandTemplate',          skill: 'getContinueChangeSkillTemplate' },
+    'new-change':         { cmd: 'getOpsxNewCommandTemplate',               skill: 'getNewChangeSkillTemplate' },
+    'explore':            { cmd: 'getOpsxExploreCommandTemplate',           skill: 'getExploreSkillTemplate' },
+    'update-change':      { cmd: 'getOpsxUpdateCommandTemplate',            skill: 'getUpdateChangeSkillTemplate' },
+    'sync-specs':         { cmd: 'getOpsxSyncCommandTemplate',              skill: 'getSyncSpecsSkillTemplate' },
+    'bulk-archive-change':{ cmd: 'getOpsxBulkArchiveCommandTemplate',       skill: 'getBulkArchiveChangeSkillTemplate' },
+    'onboard':            { cmd: 'getOpsxOnboardCommandTemplate',           skill: 'getOnboardSkillTemplate' },
+  };
+  return map[name] ? map[name][kind] : null;
+}
+
+// ── 下载与部署 ──────────────────────────────────────────────────
+
+async function fetchLatestOpenSpec() {
+  log(`正在获取 OpenSpec 版本元数据...`, 'info');
+  // 1) 先 HEAD 拿 ETag,避免每次都下载完整 tarball
+  const head = await fetchEtag(GITHUB_TARBALL_URL);
+  if (head.statusCode !== 200 || !head.etag) {
+    throw new Error(`无法获取版本信息: HTTP ${head.statusCode}`);
+  }
+  const versionToken = head.etag;
+  const localToken = getLocalVersion();
+
+  if (versionToken === localToken) {
+    // 即使版本号一致,也要校验全部文件是否已部署(白名单可能新增了条目)
+    const { valid } = validateDeployed();
+    if (valid) {
+      log(`已是最新版本 (${versionToken.slice(0, 12)})`, 'success');
+      return { version: versionToken, cmdCount: 0, skillCount: 0, skipped: true };
+    }
+    log(`版本一致但文件不完整,强制重新部署...`, 'info');
+  }
+
+  log(`检测到上游更新,正在下载 OpenSpec tarball...`, 'info');
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cbb-os-'));
+  const tarballPath = path.join(tmpDir, 'openspec.tar.gz');
+
+  try {
+    await downloadToFile(GITHUB_TARBALL_URL, tarballPath);
+    log('正在解压...', 'info');
+    // 跨平台解压:用 zlib + 自写 tar parser。无需 shell tar,Windows 也能跑。
+    extractTarGz(tarballPath, tmpDir);
+
+    // 通过「含 src/core/templates/workflows」特征定位真仓库根。
+    // codeload 的 tarball 顶层可能是 pax_global_header / 杂项,但
+    // 真正的源码根目录固定有一个 src/ 子树。这种探测比依赖目录名约定稳。
+    let extractedDir = null;
+    for (const entry of fs.readdirSync(tmpDir)) {
+      const cand = path.join(tmpDir, entry);
+      let isDir = false;
+      try { isDir = fs.statSync(cand).isDirectory(); } catch (_) { continue; }
+      if (!isDir) continue;
+      const probe = path.join(cand, 'src', 'core', 'templates', 'workflows');
+      if (fs.existsSync(probe)) {
+        extractedDir = cand;
+        break;
+      }
+    }
+    if (!extractedDir) {
+      throw new Error('解压后未在 tarball 中定位到含 src/core/templates/workflows 的 OpenSpec 根目录');
+    }
+
+    const workflowsDir = path.join(extractedDir, 'src', 'core', 'templates', 'workflows');
+    if (!fs.existsSync(workflowsDir)) throw new Error('未找到 workflows 目录');
+
+    let cmdCount = 0;
+    let skillCount = 0;
+
+    for (const wf of WORKFLOWS) {
+      const tsFile = path.join(workflowsDir, `${wf.name}.ts`);
+      if (!fs.existsSync(tsFile)) {
+        log(`跳过 ${wf.name}: 官方源无对应文件`, 'warn');
+        continue;
+      }
+      const tsContent = fs.readFileSync(tsFile, 'utf-8');
+
+      // 命令
+      if (wf.cmd) {
+        const fnName = functionNamesForWorkflow(wf.name, 'cmd');
+        const rendered = fnName ? renderCommandFromTs(tsContent, fnName) : null;
+        if (!rendered) {
+          log(`${wf.name}.ts: 未提取到 CommandTemplate,跳过`, 'warn');
+        } else {
+          const dest = path.join(OPENSPEC_COMMANDS_DIR, `${wf.cmd}.md`);
+          assertSafeDestination(dest, `写入命令 ${wf.name}`);
+          fs.mkdirSync(path.dirname(dest), { recursive: true });
+          fs.writeFileSync(dest, rendered);
+          cmdCount++;
+        }
+      }
+
+      // 技能
+      if (wf.skill) {
+        const fnName = functionNamesForWorkflow(wf.name, 'skill');
+        const rendered = fnName ? renderSkillFromTs(tsContent, fnName) : null;
+        if (!rendered) {
+          log(`${wf.name}.ts: 未提取到 SkillTemplate,跳过`, 'warn');
+        } else {
+          const dest = path.join(OPENSPEC_SKILLS_DIR, wf.skill, 'SKILL.md');
+          assertSafeDestination(dest, `写入技能 ${wf.name}`);
+          fs.mkdirSync(path.dirname(dest), { recursive: true });
+          fs.writeFileSync(dest, rendered);
+          skillCount++;
+        }
+      }
+    }
+
+    writeVersion(versionToken);
+    log(
+      `已更新 OpenSpec 工作流: ${localToken ? localToken.slice(0, 12) : '(无)'} → ${versionToken.slice(0, 12)} ` +
+      `(${cmdCount} 个命令 + ${skillCount} 个技能)`,
+      'success'
+    );
+
+    return { version: versionToken, cmdCount, skillCount, skipped: false };
+  } catch (err) {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+    throw err;
+  }
+}
+
+// ── 完整性校验 ──────────────────────────────────────────────────
+
+/**
+ * 校验 Safe-Overwrite 区的所有文件均已部署。
+ * @returns {{valid: boolean, missing: string[]}}
+ */
+function validateDeployed() {
+  const missing = [];
+  for (const wf of WORKFLOWS) {
+    if (wf.cmd) {
+      const p = path.join(OPENSPEC_COMMANDS_DIR, `${wf.cmd}.md`);
+      if (!fs.existsSync(p)) missing.push(`commands/${wf.cmd}.md`);
+    }
+    if (wf.skill) {
+      const p = path.join(OPENSPEC_SKILLS_DIR, wf.skill, 'SKILL.md');
+      if (!fs.existsSync(p)) missing.push(`skills/${wf.skill}/SKILL.md`);
+    }
+  }
+  return { valid: missing.length === 0, missing };
+}
+
+// ── 导出 ────────────────────────────────────────────────────────
+
+module.exports = {
+  OPENSPEC_DIR,
+  OPENSPEC_COMMANDS_DIR,
+  OPENSPEC_SKILLS_DIR,
+  VERSION_FILE,
+  WORKFLOWS,
+  GITHUB_REPO,
+  GITHUB_BRANCH,
+
+  PROTECTED_PATH_PREFIXES,
+  assertSafeDestination,
+  fetchLatestOpenSpec,
+  getLocalVersion,
+  validateDeployed,
+};