@jspg-ai/coding-bb 0.0.3-beta.4 → 0.0.3-beta.7

package/cbb/lib/utils/tar.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * 跨平台 .tar.gz 解压工具。
+ *
+ * 用 zlib + 手写 tar parser，避开 OS shell tar（Windows 上是 bsdtar、行为不完全一致），
+ * 与仓库「脚本语言统一 Node.js、禁止平台绑定脚本」的约定一致。
+ *
+ * 支持：
+ *   - gzip 压缩的 tar（GitHub tarball / npm registry tgz 都是这种）
+ *   - 目录项（type '5' 或名字以 '/' 结尾）
+ *   - 跳过 pax 扩展头（'g'/'x'）等元数据伪条目
+ *   - 路径穿越防护（拒绝 ../ 逃逸 destDir）
+ *
+ * 不支持（上游 tarball 均不使用，遇到时跳过而非静默损坏）：
+ *   - GNU longname/longlink（'L'/'K'）—— 超过 100 字符的路径
+ */
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+
+// 非文件、非目录的 tar 条目类型（pax 扩展头、GNU 长名等）
+const META_TYPE_FLAGS = new Set(['g', 'x', 'L', 'K', 'V', 'N']);
+
+/**
+ * 解析 tar buffer，返回条目列表（不落盘）。
+ * @param {Buffer} data - 已解压的 tar 数据
+ * @returns {Array<{name: string, size: number, typeFlag: string, dataStart: number}>}
+ */
+function listTar(data) {
+  const entries = [];
+  let off = 0;
+  while (off + 512 <= data.length) {
+    const header = data.subarray(off, off + 512);
+    off += 512;
+
+    // 连续两个 512 字节零块 = 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]（八进制 ASCII）
+    const size = parseInt(header.subarray(124, 136).toString('utf-8').trim(), 8) || 0;
+
+    // 类型标志 header[156]（'0'/NUL = 普通文件，'5' = 目录）
+    const typeFlag = String.fromCharCode(header[156]);
+
+    entries.push({ name, size, typeFlag, dataStart: off });
+    off += Math.ceil(size / 512) * 512;
+  }
+  return entries;
+}
+
+/**
+ * 解压 .tar.gz buffer 到目标目录。
+ * @param {Buffer} compressed - .tar.gz 文件内容
+ * @param {string} destDir - 解压目标根目录（不存在则创建）
+ * @returns {{files: number, dirs: number}} 落盘计数
+ */
+function extractTarGz(compressed, destDir) {
+  const data = zlib.gunzipSync(compressed);
+  const root = path.resolve(destDir);
+  let files = 0;
+  let dirs = 0;
+
+  for (const entry of listTar(data)) {
+    if (!entry.name) continue;
+    // 跳过 pax 扩展头等元数据伪条目
+    if (META_TYPE_FLAGS.has(entry.typeFlag)) continue;
+
+    const target = path.resolve(root, entry.name);
+    // 路径穿越防护：解压目标必须落在 destDir 内
+    if (target !== root && !target.startsWith(root + path.sep)) continue;
+
+    if (entry.typeFlag === '5' || entry.name.endsWith('/')) {
+      fs.mkdirSync(target, { recursive: true });
+      dirs += 1;
+    } else {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, data.subarray(entry.dataStart, entry.dataStart + entry.size));
+      files += 1;
+    }
+  }
+
+  return { files, dirs };
+}
+
+module.exports = { extractTarGz, listTar };

package/cbb/lib/utils/upstream.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * 上游内容拉取的共享工具。
+ *
+ * 维护者侧（cbbm update --upstream-*）需要访问 GitHub / npm registry。
+ * 本模块提供：
+ *   - 镜像前缀列表加载（config/upstream-mirrors.json，仓库内维护）
+ *   - 带重定向跟随的 HTTPS GET
+ *   - 「按镜像列表依次尝试」的拉取策略（首个成功即用）
+ *
+ * 镜像前缀为空字符串表示直连；列表末位通常放 "" 作为兜底。
+ */
+
+const fs = require('fs');
+const https = require('https');
+const path = require('path');
+
+const SHARED_STANDARDS_DIR = path.join(__dirname, '..', '..', '..');
+const MIRRORS_FILE = path.join(SHARED_STANDARDS_DIR, 'config', 'upstream-mirrors.json');
+
+/**
+ * 读取指定上游的镜像前缀列表。
+ * 文件缺失 / 解析失败 / 未配置该上游时返回 ['']（仅直连）。
+ * @param {string} name - 上游名（如 'superpowers'）
+ * @returns {string[]}
+ */
+function loadMirrors(name) {
+  try {
+    const data = JSON.parse(fs.readFileSync(MIRRORS_FILE, 'utf-8'));
+    const list = data[name];
+    if (Array.isArray(list) && list.length > 0) {
+      return list.map(m => String(m));
+    }
+  } catch (_) { /* 回退到直连 */ }
+  return [''];
+}
+
+/**
+ * 发起 HTTPS GET，跟随重定向（最多 8 次），返回响应体 Buffer。
+ * @param {string} url
+ * @param {number} [redirectCount]
+ * @returns {Promise<Buffer>}
+ */
+function httpsGetBuffer(url, redirectCount = 0) {
+  if (redirectCount > 8) return Promise.reject(new Error('Too many redirects'));
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { 'User-Agent': 'cbb-cli' } }, res => {
+      if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location) {
+        res.resume();
+        return httpsGetBuffer(res.headers.location, redirectCount + 1).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode}: ${url}`));
+      }
+      const chunks = [];
+      res.on('data', c => chunks.push(c));
+      res.on('end', () => resolve(Buffer.concat(chunks)));
+      res.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+/**
+ * 按镜像列表依次尝试拉取，首个成功即返回。
+ * @param {string[]} mirrors - 镜像前缀列表（'' = 直连）
+ * @param {(prefix: string) => string} buildUrl - 由前缀构造完整 URL
+ * @returns {Promise<{buffer: Buffer, mirror: string, url: string}>}
+ */
+async function fetchWithMirrors(mirrors, buildUrl) {
+  const errors = [];
+  for (const mirror of mirrors) {
+    const url = buildUrl(mirror);
+    try {
+      const buffer = await httpsGetBuffer(url);
+      return { buffer, mirror, url };
+    } catch (err) {
+      errors.push(`${mirror || '(直连)'}: ${err.message}`);
+    }
+  }
+  throw new Error(`所有镜像均失败:\n  ${errors.join('\n  ')}`);
+}
+
+module.exports = {
+  MIRRORS_FILE,
+  loadMirrors,
+  httpsGetBuffer,
+  fetchWithMirrors,
+};

package/cbb/worktrees/commands/worktree-close.md

@@ -1,6 +1,6 @@
 ---
 name: "CBB: Worktree Close"
-description: 关闭/清理由 init-worktree 创建的多仓库联动 worktree 工作空间，移除 worktree 并按用户选择处理特性分支
+description: 关闭/清理由 worktree-init 创建的多仓库联动 worktree 工作空间，移除 worktree 并按用户选择处理特性分支
 category: Workflow
 tags: [worktree, cleanup, worktree, git-worktree]
 ---

package/config/upstream-mirrors.json

@@ -0,0 +1,12 @@
+{
+  "_comment": "维护者拉取上游内容时的镜像前缀列表，按顺序尝试，首个成功即用。空字符串 \"\" 表示直连。",
+  "superpowers": [
+    "https://gh-proxy.com/",
+    "https://ghfast.top/",
+    ""
+  ],
+  "openspec": [
+    "https://registry.npmmirror.com",
+    "https://registry.npmjs.org"
+  ]
+}

package/config/workspace-agents.sample.md

@@ -1,39 +1,41 @@
-# 业务空间使用说明（AI Agent 导航）
-
-本目录是由 `@jspg-ai/coding-bb` 初始化的**多仓库联动开发业务空间**。
-进入本目录工作时，请先按本文件理解目录职责与协作约定，再动手。
-
-## 核心约定
-
-1. **本目录不做需求开发**。本目录（业务空间主分支）只负责组织与调度；所有需求开发都在 `.worktrees/worktree-<需求名>/` 隔离目录内进行。
-2. **AI 配置安装在空间根**：编码规范、OpenSpec 命令、worktree 管理技能都装在本目录（`cbb setup` / `cbb update` 安装）；worktree 内**不安装** AI 配置，AI 会话始终以空间根为基础。
-3. **接到新需求先建 worktree**：在本目录执行 `/cbb:worktree-init <需求名>`（opencode 写法：`/cbb-worktree-init`）。它会为 `workspace-config.json` 中的全量关联应用同步创建同名 worktree。
-4. **开发命令在本会话执行，写操作指向 worktree**：需求提案 / 实现 / 验证 / 归档（`/opsx:propose` → `/opsx:apply` → `/opsx:verify` → `/opsx:archive`）在空间根会话执行；但所有产生写操作的命令（git commit / openspec / 构建 / 测试 / 文件修改）必须以 `.worktrees/worktree-<需求名>/`（或其应用子目录）为工作目录（显式 `cd` 或绝对路径）；**禁止在空间根（主分支）执行写操作**。
-5. **关联应用增减只改配置**：编辑 `workspace-config.json` 的 `apps` 数组（`name` / `repo` / `side` / `desc`），然后用同一需求名重跑 worktree 初始化即幂等补齐；不要手工 `git clone` 应用仓库。
-6. **不要绕过 worktree 直接修改 `.codespace/` 或本目录的代码**。`.codespace/` 是工具维护的基准代码，不是开发区。
-
-## 目录结构与职责
-
-| 路径 | 职责 | 维护方式 |
-|------|----------|----------|
-| `workspace-config.json` | 关联应用清单，所有应用联动的唯一数据源 | 人工编辑 |
-| `.codespace/` | 各关联应用的基准代码（每个应用一个子目录） | `cbb setup` 与 worktree 流程自动 clone / fetch；**勿手动编辑**；已 gitignore，不提交 |
-| `.worktrees/` | 需求隔离开发区（每个需求一个 `worktree-<需求名>/` 目录） | worktree 命令自动创建 / 清理；不提交（首次执行 worktree 流程时自动加入 .gitignore） |
-| `openspec/` | OpenSpec 工作流配置（`config.yaml` + `schemas/`） | 由 cbb 安装；需求变更产物（`openspec/changes/` 等）在**需求工作树内**生成，随需求分支提交 |
-| `.claude/` `.qoder/` `.opencode/` | AI 工具适配目录：编码规范规则、OpenSpec 命令、worktree 管理命令 | 由 cbb 按 setup 时选择的工具安装；已 gitignore，不提交，勿手动改 |
-| `.cbb/` | cbb 安装清单 + worktree 运行时（`.cbb/skills/`：流程文档与脚本，各工具命令共用） | 由 cbb 管理；**勿手动编辑** |
-
-## 典型流程
-
-```
-本目录：/cbb:worktree-init <需求名>
-  → 继续在当前会话开发：写操作命令以 .worktrees/worktree-<需求名>/ 为工作目录
-    （/opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive）
-  → /cbb:worktree-push 推送 → 合并后 /cbb:worktree-close 关闭
-```
-
-> 命令写法因 AI 工具而异：Claude Code / Qoder 为 `/cbb:worktree-init`，opencode 为 `/cbb-worktree-init`；`/opsx:*` 同理（opencode 为 `/opsx-*`）。
-
----
-
-本文件由 `@jspg-ai/coding-bb` 生成（仅缺失时写入，之后不会覆盖或删除，可自由增补团队约定）。
+# 业务空间使用说明（AI Agent 导航）
+
+本目录是由 `@jspg-ai/coding-bb` 初始化的**多仓库联动开发业务空间**。
+进入本目录工作时，请先按本文件理解目录职责与协作约定，再动手。
+
+## 核心约定
+
+1. **本目录不做需求开发**。本目录（业务空间主分支）只负责组织与调度；需求开发的**写操作**都在 `.worktrees/worktree-<需求名>/` 隔离目录内进行，**AI 会话仍停在空间根**（worktree 内不装 AI 配置）。
+2. **AI 配置安装在空间根**：编码规范、OpenSpec 命令、worktree 管理技能都装在本目录（`cbb setup` / `cbb update` 安装）；worktree 内**不安装** AI 配置，AI 会话始终以空间根为基础。
+3. **接到新需求先建 worktree**：在本目录执行 `/cbb:worktree-init <需求名>`（opencode 写法：`/cbb-worktree-init`）。它会为 `workspace-config.json` 中的全量关联应用同步创建同名 worktree。
+4. **开发命令在本会话执行，写操作指向 worktree**：需求提案 / 实现 / 验证 / 归档（`/opsx:propose` → `/opsx:apply` → `/opsx:verify` → `/opsx:archive`）在空间根会话执行；但所有产生写操作的命令（git commit / openspec / 构建 / 测试 / 文件修改）必须以 `.worktrees/worktree-<需求名>/`（或其应用子目录）为工作目录（显式 `cd` 或绝对路径）；**禁止在空间根（主分支）执行写操作**。
+5. **关联应用增减只改配置**：编辑 `workspace-config.json` 的 `apps` 数组（`name` / `repo` / `side` / `desc`），然后用同一需求名重跑 worktree 初始化即幂等补齐；不要手工 `git clone` 应用仓库。
+6. **不要绕过 worktree 直接修改 `.codespace/` 或本目录的代码**。`.codespace/` 是工具维护的基准代码，不是开发区。
+
+## 目录结构与职责
+
+| 路径 | 职责 | 维护方式 |
+|------|----------|----------|
+| `workspace-config.json` | 关联应用清单，所有应用联动的唯一数据源 | 人工编辑 |
+| `.codespace/` | 各关联应用的基准代码（每个应用一个子目录） | `cbb setup` 与 worktree 流程自动 clone / fetch；**勿手动编辑**；已 gitignore，不提交 |
+| `.worktrees/` | 需求隔离开发区（每个需求一个 `worktree-<需求名>/` 目录） | worktree 命令自动创建 / 清理；不提交（首次执行 worktree 流程时自动加入 .gitignore） |
+| `openspec/` | OpenSpec 工作流配置（`config.yaml` + `schemas/`） | 由 cbb 安装；需求变更产物（`openspec/changes/` 等）在**需求工作树内**生成，随需求分支提交 |
+| `.claude/` `.qoder/` `.opencode/` `.codebuddy/` `.trae/` | AI 工具适配目录：编码规范规则、OpenSpec 命令、worktree 管理命令 | 由 cbb 按 setup 时选择的工具安装；已 gitignore，不提交，勿手动改 |
+| `.cbb/` | cbb 安装清单 + worktree 运行时（`.cbb/skills/`：流程文档与脚本，各工具命令共用） | 由 cbb 管理；**勿手动编辑** |
+
+## 典型流程
+
+```
+本目录：/cbb:worktree-init <需求名>
+  → 继续在当前会话开发：写操作命令以 .worktrees/worktree-<需求名>/ 为工作目录
+    （/opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive）
+  → /cbb:worktree-push 推送 → 合并后 /cbb:worktree-close 关闭
+```
+
+> 命令写法因 AI 工具而异：Claude Code / Qoder / WorkBuddy / Trae 为 `/cbb:worktree-init`、`/opsx:propose`；opencode 因「文件名即命令名」且 Windows 文件名不允许 `:`，扁平化为 `/cbb-worktree-init`、`/opsx-propose`。
+
+---
+
+本文件由 `@jspg-ai/coding-bb` 生成（仅缺失时写入，之后不会覆盖或删除，可自由增补团队约定）。
+
+> ⓘ 本文件仅供导航；目录纪律以 cbb 安装的编码规范规则（`cbb-ai-behavior.md` 第 8 条）为准，该规则随 `cbb update` 更新。

package/openspec/.version

@@ -1,6 +1,5 @@
 {
-  "sha": "9d4e5974e5c0d9a09b9c6c1e1eb0975e80ec4461",
-  "branch": "main",
+  "version": "1.13.1",
   "repo": "Fission-AI/OpenSpec",
-  "updatedAt": "2026-09-12T00:00:00.000Z"
+  "renderedAt": "2026-09-19T13:22:53.815Z"
 }