@jspg-ai/coding-bb 0.0.1

package/cbb/worktrees/skills/openspec-init-worktree/scripts/create-worktrees.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * openspec-init-worktree 创建 Worktree（含自愈清理）
+ *
+ * 用法：node create-worktrees.js <ws_root> '<apps_json>' <branch>
+ *
+ * 行为：
+ *   1. 自愈清理：prune + 物理目录清理
+ *   2. workspace worktree 创建（.worktrees/worktree-<branch>）
+ *   3. 各 app worktree 创建（物理嵌套在 workspace worktree 内）
+ *   4. 失败时输出回滚提示
+ *
+ * 退出码：
+ *   0 - 全部成功
+ *   1 - 参数错误
+ *   2 - workspace worktree 创建失败
+ *   3 - 部分 app worktree 创建失败
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const wsRoot = process.argv[2];
+const branch = process.argv[3];
+
+if (!wsRoot || !branch) {
+  console.error('❌ 用法：node create-worktrees.js <ws_root> <branch>');
+  process.exit(1);
+}
+
+function loadAppsFromConfig() {
+  const configPath = path.join(wsRoot, 'CONFIG.json');
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    return Array.isArray(config.apps) ? config.apps : null;
+  } catch (e) { return null; }
+}
+
+const apps = loadAppsFromConfig();
+if (!apps) {
+  console.error('❌ CONFIG.json 缺失或 apps 为空');
+  process.exit(1);
+}
+
+function run(cmd, cwd) {
+  try {
+    return { ok: true, out: execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).trim() };
+  } catch (e) {
+    return { ok: false, err: (e.stderr || e.message || String(e)).trim() };
+  }
+}
+
+// 1. 自愈清理
+console.log('=== 自愈清理 ===');
+
+// 1.1 prune 所有仓库
+const allRepos = [wsRoot, ...apps.map(a => path.join(wsRoot, '.code', a.name))];
+for (const repo of allRepos) {
+  if (fs.existsSync(repo)) {
+    run('git worktree prune', repo);
+  }
+}
+console.log('✅ 已 prune 所有仓库的 worktree 元数据');
+
+// 1.2 清理 .worktrees/ 下无元数据的物理目录
+const worktreesDir = path.join(wsRoot, '.worktrees');
+if (fs.existsSync(worktreesDir)) {
+  const validWts = run('git worktree list --porcelain', wsRoot);
+  const validPaths = new Set();
+  if (validWts.ok) {
+    validWts.out.split('\n').forEach(line => {
+      if (line.startsWith('worktree ')) {
+        validPaths.add(line.substring(9).trim());
+      }
+    });
+  }
+
+  const entries = fs.readdirSync(worktreesDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = path.join(worktreesDir, entry.name);
+    let absDir;
+    try { absDir = fs.realpathSync(dir); } catch { continue; }
+    if (!validPaths.has(absDir)) {
+      try {
+        fs.rmSync(dir, { recursive: true, force: true });
+        console.log('🧹 已清理残留目录：' + entry.name);
+      } catch (e) {
+        console.log('⏳ 残留目录仍被占用，跳过：' + entry.name);
+      }
+    }
+  }
+}
+
+// 2. workspace worktree 创建
+console.log('=== 创建 Workspace Worktree ===');
+const wtDir = path.join(wsRoot, '.worktrees', 'worktree-' + branch);
+if (fs.existsSync(wtDir)) {
+  console.log('⏭️  workspace worktree 已存在，复用：' + wtDir);
+} else {
+  const created = run('git worktree add ".worktrees/worktree-' + branch + '" "' + branch + '"', wsRoot);
+  if (!created.ok) {
+    console.error('❌ workspace worktree 创建失败：' + created.err);
+    console.error('   常见原因：分支已在其他 worktree 检出，或权限不足');
+    process.exit(2);
+  }
+  console.log('✅ workspace worktree 已创建：' + wtDir);
+}
+
+// 3. apps worktree 创建（物理嵌套）
+console.log('=== 创建 App Worktrees ===');
+const results = [];
+for (const app of apps) {
+  const appPath = path.join(wsRoot, '.code', app.name);
+  const nestedWt = path.join(wtDir, app.name);
+
+  if (fs.existsSync(nestedWt) && fs.existsSync(path.join(nestedWt, '.git'))) {
+    console.log('⏭️  ' + app.name + ': 嵌套 worktree 已存在，复用');
+    results.push({ name: app.name, status: 'reused' });
+    continue;
+  }
+
+  // 防御性兜底：父目录不存在则创建
+  fs.mkdirSync(path.dirname(nestedWt), { recursive: true });
+  const created = run('git worktree add "' + nestedWt + '" "' + branch + '"', appPath);
+  if (created.ok) {
+    console.log('✅ ' + app.name + ': 嵌套 worktree 创建成功');
+    results.push({ name: app.name, status: 'created' });
+  } else {
+    console.error('❌ ' + app.name + ': worktree 创建失败：' + created.err);
+    results.push({ name: app.name, status: 'failed', error: created.err });
+  }
+}
+
+const hasFailed = results.some(r => r.status === 'failed');
+if (hasFailed) {
+  console.error('');
+  console.error('⚠️  部分 app worktree 创建失败，需手动清理：');
+  console.error('   cd ' + wsRoot + ' && git worktree remove .worktrees/worktree-' + branch);
+  for (const r of results.filter(x => x.status === 'failed')) {
+    console.error('   git -C .code/' + r.name + ' worktree remove <worktree-path>');
+  }
+  console.error('---');
+  console.error('WORKTREE_RESULT', JSON.stringify(results));
+  process.exit(3);
+}
+
+console.log('---');
+console.log('WORKTREE_RESULT', JSON.stringify(results));
+console.log('WT_PATH', path.resolve(wtDir));
+process.exit(0);

package/cbb/worktrees/skills/openspec-init-worktree/scripts/find-workspace-root.js

@@ -0,0 +1,67 @@
+require('./silence-popup');
+/**
+ * openspec-shared 工作空间根目录定位
+ *
+ * 唯一真源：cbb/worktrees/_shared/scripts/find-workspace-root.js
+ * 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（init / extend / close / push）。
+ *
+ * 优先：git worktree list 第一行（主仓库根目录，不受 worktree 内 CONFIG.json 副本干扰）
+ * 兜底：当前目录含 CONFIG.json
+ *
+ * 退出码：
+ *   0 - 定位成功，输出 WS_ROOT 绝对路径
+ *   1 - 未找到工作空间根目录
+ *
+ * 输出格式：
+ *   第一行：人类可读报告
+ *   最后一行：纯路径（便于 AI agent 解析后用于 cd）
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+function tryExec(cmd) {
+  try {
+    return { ok: true, out: execSync(cmd, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).trim() };
+  } catch (e) {
+    return { ok: false };
+  }
+}
+
+let wsRoot = '';
+
+// 优先：git worktree list 第一行
+const worktreeList = tryExec('git worktree list');
+if (worktreeList.ok) {
+  const firstLine = worktreeList.out.split('\n')[0];
+  if (firstLine) {
+    // 格式：<path> <sha> [<branch>]
+    const candidate = firstLine.split(/\s+/)[0];
+    if (candidate && fs.existsSync(candidate)) {
+      wsRoot = candidate;
+    }
+  }
+}
+
+// 兜底：当前目录含 CONFIG.json
+if (!wsRoot) {
+  const cwd = process.cwd();
+  if (fs.existsSync(path.join(cwd, 'CONFIG.json'))) {
+    wsRoot = cwd;
+  }
+}
+
+// 校验
+if (!wsRoot || !fs.existsSync(path.join(wsRoot, 'CONFIG.json'))) {
+  console.error('❌ 未找到工作空间根目录');
+  console.error('   原因：git worktree list 失败且当前目录无 CONFIG.json');
+  console.error('   请在业务工作空间根目录（由 cbb setup 初始化、包含 CONFIG.json）下执行本技能');
+  process.exit(1);
+}
+
+console.log('✅ 工作空间根目录：' + wsRoot);
+console.log('---');
+// 最后一行输出纯路径，AI agent 可直接 cd 使用
+console.log(wsRoot);
+process.exit(0);

package/cbb/worktrees/skills/openspec-init-worktree/scripts/generate-app-options.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * 从 CONFIG.json 读取应用列表，机械生成 AskUserQuestion options
+ *
+ * 核心原则：label 由代码硬生成，绝不依赖 AI 理解或翻译
+ *   label = "【" + sideLabel + "】 - " + app.name
+ *
+ * 用法：
+ *   node generate-app-options.js                        → 生成全部应用的 options
+ *   node generate-app-options.js --filter app1,app2     → 只生成指定 app 的 options
+ *
+ * 退出码：
+ *   0 - 成功，输出 APP_OPTIONS
+ *   1 - 解析失败
+ *   2 - apps 为空
+ *
+ * 输出格式（末行为机器可解析行）：
+ *   ✅ 已生成 N 个应用选项
+ *   ---
+ *   APP_OPTIONS [{"label":"...", "name":"..."}, ...]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// === 解析命令行参数 ===
+const filterNames = [];
+const args = process.argv.slice(2);
+for (const arg of args) {
+  if (arg.startsWith('--filter=')) {
+    const raw = arg.slice('--filter='.length);
+    if (raw) {
+      filterNames.push(...raw.split(',').map(s => s.trim()).filter(Boolean));
+    }
+  }
+}
+
+// === 读取 CONFIG.json ===
+const configPath = path.join(process.cwd(), 'CONFIG.json');
+
+if (!fs.existsSync(configPath)) {
+  console.error('❌ CONFIG.json 不存在');
+  console.error('---');
+  console.error('CONFIG_MISSING');
+  process.exit(1);
+}
+
+let config;
+try {
+  config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+} catch (e) {
+  console.error('❌ CONFIG.json 解析失败：', e.message);
+  console.error('---');
+  console.error('CONFIG_INVALID');
+  process.exit(1);
+}
+
+const apps = config.apps || [];
+if (apps.length === 0) {
+  console.error('❌ CONFIG.json 中 apps 为空');
+  console.error('---');
+  console.error('CONFIG_EMPTY');
+  process.exit(2);
+}
+
+// === 过滤（如果指定了 --filter） ===
+let targetApps = apps;
+if (filterNames.length > 0) {
+  targetApps = apps.filter(app => filterNames.includes(app.name));
+  if (targetApps.length === 0) {
+    console.error('❌ --filter 指定的应用均不在 CONFIG.json 中：' + filterNames.join(', '));
+    console.error('---');
+    console.error('FILTER_NO_MATCH');
+    process.exit(2);
+  }
+}
+
+// === 机械生成 label（核心逻辑，不可修改） ===
+// 公式：label = "【" + sideLabel + "】 - " + app.name
+// app.name 逐字符原样复制，不翻译、不加工
+const options = [];
+for (const app of targetApps) {
+  const sideLabel = (app.side === 'front') ? '前端' : '后端';
+  const label = '【' + sideLabel + '】 - ' + app.name;
+  options.push({ label: label, name: app.name });
+}
+
+// === 输出 ===
+console.log('✅ 已生成 ' + options.length + ' 个应用选项（label 由脚本硬编码，绝不翻译）');
+console.log('---');
+console.log('APP_OPTIONS ' + JSON.stringify(options));
+process.exit(0);

package/cbb/worktrees/skills/openspec-init-worktree/scripts/install-ai.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * openspec-init-worktree 在 worktree 中安装 AI 配置（必要步骤）
+ *
+ * 用法：node install-ai.js <wt_path>
+ *
+ * 行为：
+ *   1. 检测 cbb 是否全局安装，未安装则自动安装
+ *   2. 直接用 npm 全局 bin 路径调用 cbb（避免 PowerShell PATH 缓存）
+ *   3. 在 worktree 内执行 cbb init --yes
+ *   4. 失败则 exit 2，阻塞 init-worktree 流程（与 push-branches.js 语义一致）
+ *
+ * 退出码：
+ *   0 - 成功
+ *   1 - 参数错误（脚本 bug 或调用错误）
+ *   2 - cbb init 执行失败（**阻塞 init-worktree**，用户必须手动恢复）
+ */
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const wtPath = process.argv[2];
+
+if (!wtPath) {
+  console.error('Usage: node install-ai.js <wt_path>');
+  process.exit(1);
+}
+
+if (!fs.existsSync(wtPath)) {
+  console.error('ERROR: worktree path not exist: ' + wtPath);
+  process.exit(1);
+}
+
+function run(cmd, cwd, env) {
+  try {
+    return { ok: true, out: execSync(cmd, { cwd: cwd || process.cwd(), encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], env: env || process.env, input: '\n' }).trim() };
+  } catch (e) {
+    return { ok: false, err: (e.stderr || e.message || String(e)).trim() };
+  }
+}
+
+// 查找 cbb 可执行文件：先 PATH，再 npm 全局 bin
+function findCbb() {
+  // 1. 直接调用 cbb --version
+  let r = run('cbb --version');
+  if (r.ok) return { cmd: 'cbb', version: r.out };
+
+  // 2. 查 npm 全局 bin 目录
+  const npmRoot = run('npm root -g');
+  if (npmRoot.ok) {
+    // Windows: <npm_root>\..\cbb.cmd (bin 在 npm_root 的父目录)
+    // Unix: <npm_root>/../bin/cbb
+    const candidates = [];
+    if (process.platform === 'win32') {
+      candidates.push(path.join(npmRoot.out, 'cbb.cmd'));
+      candidates.push(path.join(npmRoot.out, '..', 'cbb.cmd'));
+      candidates.push(path.join(npmRoot.out, '..', 'bin', 'cbb.cmd'));
+      // npm 全局 bin 通常是 %APPDATA%\npm\cbb.cmd
+      const appdata = process.env.APPDATA || process.env.USERPROFILE;
+      if (appdata) candidates.push(path.join(appdata, 'npm', 'cbb.cmd'));
+    } else {
+      candidates.push(path.join(npmRoot.out, '..', 'bin', 'cbb'));
+      candidates.push(path.join(npmRoot.out, '..', 'cbb'));
+    }
+    for (const c of candidates) {
+      if (fs.existsSync(c)) {
+        // 尝试执行
+        r = run('"' + c + '" --version');
+        if (r.ok) return { cmd: '"' + c + '"', version: r.out };
+      }
+    }
+  }
+  return null;
+}
+
+// 1. 检测/安装 cbb
+let cbbInfo = findCbb();
+if (!cbbInfo) {
+  console.log('WARN: cbb not globally installed, try auto-install...');
+  const install = run('npm install -g @jspg-ai/coding-bb');
+  if (!install.ok) {
+    console.error('ERROR: cbb auto-install failed: ' + install.err);
+    console.error('');
+    console.error('━━━ init-worktree 已中断 ━━━');
+    console.error('请手动安装 cbb 后重跑 init-worktree：');
+    console.error('  1. npm install -g @jspg-ai/coding-bb');
+    console.error('  2. cd "' + wtPath + '" && cbb init --yes');
+    console.error('  3. 在 ai-workspace 根目录重跑 init-worktree');
+    console.log('---');
+    console.log('AI_INIT_FAILED');
+    process.exit(2);
+  }
+  // 重新查找（npm install 后 PATH 可能仍未刷新）
+  cbbInfo = findCbb();
+  if (!cbbInfo) {
+    // 最后尝试直接用 npm 全局 bin
+    const npmRoot = run('npm root -g');
+    if (npmRoot.ok) {
+      const candidates = process.platform === 'win32'
+        ? [path.join(npmRoot.out, '..', 'cbb.cmd'), path.join(npmRoot.out, '..', 'bin', 'cbb.cmd')]
+        : [path.join(npmRoot.out, '..', 'bin', 'cbb')];
+      for (const c of candidates) {
+        if (fs.existsSync(c)) {
+          cbbInfo = { cmd: '"' + c + '"', version: 'located at ' + c };
+          break;
+        }
+      }
+    }
+  }
+  if (!cbbInfo) {
+    console.error('ERROR: cbb not found after install. Likely npm PATH cache issue.');
+    console.error('');
+    console.error('━━━ init-worktree 已中断 ━━━');
+    console.error('可能原因：npm 全局 bin 目录不在当前 shell 的 PATH 中。');
+    console.error('手动恢复步骤：');
+    console.error('  1. 重启终端让 PATH 生效，或手动定位 cbb：');
+    console.error('     npm root -g          # 拿到全局 node_modules 路径');
+    console.error('     <path>/../cbb.cmd # Windows / <path>/../bin/cbb  # Unix');
+    console.error('  2. cd "' + wtPath + '" && cbb init --yes');
+    console.error('  3. 在 ai-workspace 根目录重跑 init-worktree');
+    console.log('---');
+    console.log('AI_INIT_FAILED');
+    process.exit(2);
+  }
+  console.log('OK: cbb located: ' + cbbInfo.version);
+} else {
+  console.log('OK: cbb found: ' + cbbInfo.version);
+}
+
+// 2. 在 worktree 中执行 cbb init --yes
+console.log('Installing AI config in worktree: ' + wtPath);
+const initCmd = cbbInfo.cmd + ' init --yes';
+const init = run(initCmd, wtPath);
+if (init.ok) {
+  console.log('OK: AI config installed');
+  // 输出 init 的最后几行（init 通常输出大量日志）
+  const lines = init.out.split(/\r?\n/);
+  const tail = lines.slice(-5).join('\n');
+  console.log(tail);
+  console.log('---');
+  console.log('AI_INIT_OK');
+  process.exit(0);
+} else {
+  console.error('ERROR: AI config install failed: ' + init.err);
+  console.error('');
+  console.error('━━━ init-worktree 已中断 ━━━');
+  console.error('原因：cbb init 是必要步骤。AI 配置缺失将导致后续 openspec-* ');
+  console.error('     （propose/apply/verify/ff 等）技能全部不可用。');
+  console.error('');
+  console.error('━━━ 手动恢复步骤（请按顺序执行）━━━');
+  console.error('');
+  console.error('1. 验证环境');
+  console.error('   $ cbb --version');
+  console.error('   $ node --version    # 需要 >= 16.7.0');
+  console.error('');
+  console.error('2. 若 cbb 未安装，先安装');
+  console.error('   $ npm install -g @jspg-ai/coding-bb');
+  console.error('');
+  console.error('3. 进入 worktree 并初始化 AI 配置');
+  console.error('   $ cd "' + wtPath + '"');
+  console.error('   $ cbb init --yes');
+  console.error('');
+  console.error('4. 重新执行 init-worktree');
+  console.error('   在 ai-workspace 根目录重跑，会跳过已初始化的部分');
+  console.error('   （用 .cbb/.managed-by-cbb 判重）');
+  console.error('');
+  console.error('━━━ 常见失败原因对照 ━━━');
+  console.error('  • 0xc0000142 DLL 初始化失败 → 退出 Qoder 后重试，或到系统终端执行');
+  console.error('  • npm ERR! network → 检查代理：npm config get registry');
+  console.error('  • EACCES permission denied → 关闭杀毒软件或用管理员终端');
+  console.error('  • npm login 401 → token 过期，重新 npm login');
+  console.log('---');
+  console.log('AI_INIT_FAILED');
+  process.exit(2);
+}
+

package/cbb/worktrees/skills/openspec-init-worktree/scripts/parse-config.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * openspec-init-worktree 读取并校验 CONFIG.json
+ *
+ * 退出码：
+ *   0 - 成功，输出应用列表 JSON
+ *   1 - 解析失败（JSON 格式错误、文件不存在等）
+ *   2 - apps 为空数组
+ *
+ * 输出格式：
+ *   CONFIG_OK {json}
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const configPath = path.join(process.cwd(), 'CONFIG.json');
+
+if (!fs.existsSync(configPath)) {
+  console.error('❌ CONFIG.json 不存在');
+  console.error('   请先在 cbb setup 阶段创建，或手动配置');
+  console.error('---');
+  console.error('CONFIG_MISSING');
+  process.exit(1);
+}
+
+let config;
+try {
+  config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+} catch (e) {
+  console.error('❌ CONFIG.json 解析失败：', e.message);
+  console.error('   请检查 JSON 格式');
+  console.error('---');
+  console.error('CONFIG_INVALID');
+  process.exit(1);
+}
+
+const apps = config.apps || [];
+if (apps.length === 0) {
+  console.error('❌ CONFIG.json 中 apps 为空');
+  console.error('   请编辑 CONFIG.json 配置关联应用');
+  console.error('---');
+  console.error('CONFIG_EMPTY');
+  process.exit(2);
+}
+
+// 校验每个 app 必填字段
+for (const app of apps) {
+  if (!app.name) {
+    console.error('❌ 应用缺少 name 字段');
+    process.exit(1);
+  }
+  if (!app.repo) {
+    console.error('❌ 应用 ' + app.name + ' 缺少 repo 字段');
+    process.exit(1);
+  }
+  // side 缺失默认 back
+  if (!app.side) {
+    app.side = 'back';
+  }
+}
+
+console.log('✅ CONFIG.json 有效（' + apps.length + ' 个应用）');
+console.log('---');
+console.log('CONFIG_OK', JSON.stringify(apps));
+process.exit(0);

package/cbb/worktrees/skills/openspec-init-worktree/scripts/push-branches.js

@@ -0,0 +1,101 @@
+require('./silence-popup');
+/**
+ * openspec-init-worktree 推送并建立 upstream
+ *
+ * 薄壳脚本：核心 push 逻辑委托给同目录的 push-core.js（共享脚本，源仓库真源在 _shared/scripts/）。
+ * 本脚本只负责 CLI 入口编排（编排 init-worktree 关注的 workspace + .code/<app>/ 列表）。
+ *
+ * Usage: node push-branches.js <ws_root> <branch>
+ *
+ * 退出码：
+ *   0 - 全部推送成功
+ *   1 - 参数错误（CONFIG 缺失或 argv 不足）
+ *   2 - 部分/全部失败（AI agent 必须阻塞流程）
+ *
+ * 新场景（开发完成后跨 worktree 推送）请使用 openspec-push-worktrees/scripts/push-worktrees.js。
+ */
+
+const { pushSingle, classifyError, collectRemoteMetadata } = require('./push-core');
+const fs = require('fs');
+const path = require('path');
+
+function loadAppsFromConfig(wsRoot) {
+  const configPath = path.join(wsRoot, 'CONFIG.json');
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    return Array.isArray(config.apps) ? config.apps : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 编排：对 workspace + 所有 app 仓库逐个 push
+ * @param {{ wsRoot: string, branch: string, apps?: Array, execSyncImpl?: Function }} opts
+ * @returns {Array}
+ */
+function executePush(opts) {
+  const wsRoot = opts.wsRoot;
+  const branch = opts.branch;
+  const apps = opts.apps != null ? opts.apps : loadAppsFromConfig(wsRoot);
+  if (apps == null) {
+    throw new Error('CONFIG.json missing or apps empty');
+  }
+
+  const results = [];
+  // workspace
+  results.push(pushSingle(wsRoot, 'workspace', branch, { execSyncImpl: opts.execSyncImpl }));
+  // apps
+  for (const app of apps) {
+    const appPath = path.join(wsRoot, '.code', app.name);
+    results.push(pushSingle(appPath, app.name, branch, { execSyncImpl: opts.execSyncImpl }));
+  }
+  return results;
+}
+
+// 导出供单测（require 上下文不会触发 argv 检查）
+// 兼容历史：test/push-branches.test.js 仍可 require 本文件获得 classifyError/pushSingle/collectRemoteMetadata
+module.exports = { classifyError, pushSingle, collectRemoteMetadata, executePush };
+
+function main() {
+  const wsRoot = process.argv[2];
+  const branch = process.argv[3];
+  if (!wsRoot || !branch) {
+    console.error('❌ 用法：node push-branches.js <ws_root> <branch>');
+    process.exit(1);
+  }
+
+  const apps = loadAppsFromConfig(wsRoot);
+  if (apps == null) {
+    console.error('❌ CONFIG.json 缺失或 apps 为空');
+    process.exit(1);
+  }
+
+  console.log('=== 推送并建立 upstream ===');
+  console.log('当前分支: ' + branch);
+
+  const results = executePush({ wsRoot, branch, apps });
+
+  // 人类可读报告
+  for (const r of results) {
+    if (r.status === 'pushed') {
+      console.log('✅ ' + r.name + ': 已推送 ' + r.upstream);
+    } else if (r.status === 'remote-exists') {
+      console.log('⚠️  ' + r.name + ': 远程分支已存在（需用户决策）');
+    } else {
+      console.error('❌ ' + r.name + ': 推送失败 - ' + (r.message || r.error));
+    }
+  }
+
+  const hasFailure = results.some(r => r.status === 'failed' || r.status === 'remote-exists');
+
+  console.log('---');
+  console.log('PUSH_RESULT', JSON.stringify(results));
+  process.exit(hasFailure ? 2 : 0);
+}
+
+// CLI 入口（仅直接调用本脚本时执行，require 时跳过）
+if (require.main === module) {
+  main();
+}