@jspg-ai/coding-bb 0.0.1

package/cbb/worktrees/skills/openspec-extend-worktree/scripts/create-branches-and-worktrees.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * openspec-extend-worktree 分支创建 + 嵌套 worktree
+ */
+const { execSync } = require('child_process');
+const { pushSingle } = require('./push-core');
+const fs = require('fs');
+const path = require('path');
+
+const wsRoot = process.argv[2];
+const branch = process.argv[3];
+const appsNames = process.argv[4];
+
+if (!wsRoot || !branch || !appsNames) {
+  console.error('Usage: node create-branches-and-worktrees.js <ws_root> <branch> <app1,app2,...>');
+  process.exit(1);
+}
+
+function loadSelectedApps() {
+  const configPath = path.join(wsRoot, 'CONFIG.json');
+  if (!fs.existsSync(configPath)) return null;
+  let config;
+  try { config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch (e) { return null; }
+  const allApps = Array.isArray(config.apps) ? config.apps : [];
+  const namesSet = new Set(appsNames.split(',').map(s => s.trim()).filter(Boolean));
+  return allApps.filter(a => namesSet.has(a.name));
+}
+
+const apps = loadSelectedApps();
+if (!apps || apps.length === 0) {
+  console.error('Apps not found in CONFIG.json: ' + appsNames);
+  process.exit(1);
+}
+
+function tryExec(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() };
+  }
+}
+
+function detectMainBranch(cwd) {
+  const remote = tryExec('git remote', cwd);
+  if (!remote.ok || !remote.out) return 'main';
+  const r = remote.out.split(/\r?\n/)[0];
+  const symbolic = tryExec('git symbolic-ref "refs/remotes/' + r + '/HEAD"', cwd);
+  if (symbolic.ok && symbolic.out) {
+    return symbolic.out.replace('refs/remotes/' + r + '/', '');
+  }
+  return 'main';
+}
+
+const results = [];
+
+function processApp(app) {
+  const appPath = path.join(wsRoot, '.code', app.name);
+  const nestedWt = path.join(wsRoot, '.worktrees', 'worktree-' + branch, app.name);
+
+  // 1: branch check
+  const branchCheck = tryExec('git branch --list "' + branch + '"', appPath);
+  let branchCreated = false;
+  if (branchCheck.ok && branchCheck.out) {
+    console.log('Skip ' + app.name + ': branch exists, reuse');
+  } else {
+    const remote = tryExec('git remote', appPath);
+    if (!remote.ok || !remote.out) {
+      console.error('FAIL ' + app.name + ': no remote');
+      results.push({ name: app.name, status: 'failed', step: 'branch', error: 'no remote' });
+      return;
+    }
+    const r = remote.out.split(/\r?\n/)[0];
+    const main = detectMainBranch(appPath);
+    const create = tryExec('git branch "' + branch + '" "' + r + '/' + main + '"', appPath);
+    if (create.ok) {
+      console.log('OK ' + app.name + ': branch ' + branch + ' created (from ' + r + '/' + main + ')');
+      branchCreated = true;
+    } else {
+      console.error('FAIL ' + app.name + ': branch create failed');
+      results.push({ name: app.name, status: 'failed', step: 'branch', error: create.err });
+      return;
+    }
+  }
+
+  // 2: nested worktree check
+  if (fs.existsSync(nestedWt) && fs.existsSync(path.join(nestedWt, '.git'))) {
+    console.log('Skip ' + app.name + ': nested worktree exists, reuse');
+    results.push({ name: app.name, status: 'reused' });
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(nestedWt), { recursive: true });
+  const wtCreate = tryExec('git worktree add "' + nestedWt + '" "' + branch + '"', appPath);
+  if (wtCreate.ok) {
+    console.log('OK ' + app.name + ': nested worktree created');
+    results.push({ name: app.name, status: branchCreated ? 'created' : 'branch-reused-wt-created' });
+  } else {
+    console.error('FAIL ' + app.name + ': worktree create failed');
+    results.push({ name: app.name, status: 'failed', step: 'worktree', error: wtCreate.err });
+  }
+}
+
+for (const app of apps) {
+  processApp(app);
+}
+
+// 3: 推送本次新建的分支并建立 upstream（仅 status='created'，避免对 init-worktree 已推过的复用分支重复 push）
+const newlyCreated = results.filter(r => r.status === 'created');
+if (newlyCreated.length > 0) {
+  console.log('=== 推送新分支建立 upstream ===');
+  for (const r of newlyCreated) {
+    const app = apps.find(a => a.name === r.name);
+    if (!app) continue;
+    const appPath = path.join(wsRoot, '.code', app.name);
+    const pushResult = pushSingle(appPath, app.name, branch);
+    if (pushResult.status === 'pushed') {
+      console.log('OK ' + app.name + ': pushed ' + pushResult.upstream);
+    } else if (pushResult.status === 'remote-exists') {
+      console.log('WARN ' + app.name + ': remote branch already exists (需要用户决策)');
+    } else {
+      console.error('FAIL ' + app.name + ': push failed - ' + (pushResult.message || pushResult.error));
+    }
+    // 覆盖原 result，附加 push 状态
+    const idx = results.findIndex(x => x.name === r.name);
+    if (idx >= 0) {
+      results[idx] = Object.assign({}, results[idx], { push_status: pushResult.status, push_error: pushResult.error, push_upstream: pushResult.upstream });
+    }
+  }
+}
+
+const hasFailed = results.some(r => r.status === 'failed' || r.push_status === 'failed' || r.push_status === 'remote-exists');
+console.log('---');
+console.log('BRANCH_WT_RESULT', JSON.stringify(results));
+process.exit(hasFailed ? 2 : 0);

package/cbb/worktrees/skills/openspec-extend-worktree/scripts/find-target-worktree.js

@@ -0,0 +1,96 @@
+require('./silence-popup');
+/**
+ * openspec-shared 目标需求名识别
+ *
+ * 唯一真源：cbb/worktrees/_shared/scripts/find-target-worktree.js
+ * 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（extend / close / push）。
+ *
+ * 用法：node find-target-worktree.js <ws_root>
+ *
+ * 优先级：
+ *   1. cwd 在 .worktrees/worktree-xxx/ 内 → 自动从路径反推
+ *   2. .worktrees/ 下只有一个 worktree → 自动选用
+ *   3. 多个 worktree → 按 mtime 倒序，第一个为推荐
+ *
+ * 输出：
+ *   末行输出需求名（用于 AI agent 解析）
+ *   多个时按 [1] xxx ⭐ / [2] yyy 列出
+ *
+ * 退出码：
+ *   0 - 唯一识别（自动或唯一）
+ *   1 - 多个 worktree，需用户输入
+ *   2 - 无 worktree
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const wsRoot = process.argv[2];
+
+if (!wsRoot) {
+  console.error('❌ 用法：node find-target-worktree.js <ws_root>');
+  process.exit(1);
+}
+
+// 优先级 1：cwd 反推
+const cwd = process.cwd();
+const cwdMatch = cwd.match(/\.worktrees[\\\/]worktree-([^\\\/]+)/);
+if (cwdMatch) {
+  const branch = cwdMatch[1];
+  console.log('✅ 从 cwd 反推需求名：' + branch);
+  console.log('---');
+  console.log(branch);
+  process.exit(0);
+}
+
+const worktreesDir = path.join(wsRoot, '.worktrees');
+if (!fs.existsSync(worktreesDir)) {
+  console.error('❌ .worktrees 目录不存在：' + worktreesDir);
+  console.error('   请先执行 openspec-init-worktree 创建 worktree');
+  console.log('---');
+  console.log('NO_WORKTREE');
+  process.exit(2);
+}
+
+// 列出所有 worktree-xxx 目录
+const entries = fs.readdirSync(worktreesDir, { withFileTypes: true })
+  .filter(e => e.isDirectory() && e.name.startsWith('worktree-'))
+  .map(e => ({
+    name: e.name.substring('worktree-'.length),
+    fullName: e.name,
+    path: path.join(worktreesDir, e.name),
+    mtime: fs.statSync(path.join(worktreesDir, e.name)).mtime.getTime(),
+  }));
+
+if (entries.length === 0) {
+  console.error('❌ 未找到任何 worktree');
+  console.error('   请先执行 openspec-init-worktree 创建 worktree');
+  console.log('---');
+  console.log('NO_WORKTREE');
+  process.exit(2);
+}
+
+// 优先级 2：唯一
+if (entries.length === 1) {
+  console.log('✅ 自动选用唯一 worktree：' + entries[0].name);
+  console.log('---');
+  console.log(entries[0].name);
+  process.exit(0);
+}
+
+// 优先级 3：多个 → 按 mtime 倒序
+entries.sort((a, b) => b.mtime - a.mtime);
+
+console.log('⚠️  检测到 ' + entries.length + ' 个 worktree（按最近修改排序）：');
+entries.forEach((e, i) => {
+  if (i === 0) {
+    console.log('  [' + (i + 1) + '] ' + e.name + '  ⭐ (推荐：最近修改)');
+  } else {
+    console.log('  [' + (i + 1) + '] ' + e.name);
+  }
+});
+console.log('请在对话中输入序号(1/2/3)或完整分支名：');
+console.log('---');
+console.log('MULTIPLE_WORKTREEES');
+process.exit(1);

package/cbb/worktrees/skills/openspec-extend-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-extend-worktree/scripts/install-ai.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * openspec-extend-worktree 确保 workspace worktree 已装 AI 配置（必要步骤）
+ *
+ * 用法：node install-ai.js <ws_root> <branch>
+ *
+ * 行为：
+ *   - 仅对 workspace worktree 跑 cbb init --yes（开发约束不在 Java 应用 worktree 中）
+ *   - 用 .cbb/.managed-by-cbb 判重，已 init 过的 workspace 跳过
+ *   - 失败则 exit 2，阻塞 extend-worktree 流程（与 init-worktree 一致）
+ *
+ * 退出码：
+ *   0 - 成功 / 跳过
+ *   1 - 参数错误
+ *   2 - cbb init 执行失败（**阻塞 extend-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 install-ai.js <ws_root> <branch>');
+  process.exit(1);
+}
+
+const wtRoot = path.join(wsRoot, '.worktrees', 'worktree-' + branch);
+
+if (!fs.existsSync(wtRoot)) {
+  console.error('❌ workspace worktree 不存在：' + wtRoot);
+  console.error('   → 请先确保 init-worktree 已创建 workspace worktree');
+  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() };
+  }
+}
+
+// 判重：init-worktree 已经 init 过的 workspace，跳过
+const marker = path.join(wtRoot, '.cbb', '.managed-by-cbb');
+if (fs.existsSync(marker)) {
+  console.log('⏭️  workspace worktree AI 配置已存在（.cbb/.managed-by-cbb），跳过');
+  console.log('---');
+  console.log('AI_INIT_OK');
+  process.exit(0);
+}
+
+// 查找 cbb 可执行文件
+function findCbb() {
+  let r = run('cbb --version');
+  if (r.ok) return { cmd: 'cbb', version: r.out };
+
+  const npmRoot = run('npm root -g');
+  if (npmRoot.ok) {
+    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'));
+      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('━━━ extend-worktree 已中断 ━━━');
+    console.error('请手动安装 cbb 后重跑 extend-worktree：');
+    console.error('  1. npm install -g @jspg-ai/coding-bb');
+    console.error('  2. cd "' + wtRoot + '" && cbb init --yes');
+    console.error('  3. 重跑 extend-worktree');
+    console.log('---');
+    console.log('AI_INIT_FAILED');
+    process.exit(2);
+  }
+  cbbInfo = findCbb();
+  if (!cbbInfo) {
+    console.error('ERROR: cbb not found after install. Likely npm PATH cache issue.');
+    console.error('');
+    console.error('━━━ extend-worktree 已中断 ━━━');
+    console.error('手动恢复：cd "' + wtRoot + '" && cbb init --yes');
+    console.error('然后重跑 extend-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. 在 workspace worktree 中执行 cbb init --yes
+console.log('Installing AI config in workspace worktree: ' + wtRoot);
+const initCmd = cbbInfo.cmd + ' init --yes';
+const init = run(initCmd, wtRoot);
+if (init.ok) {
+  console.log('✅ workspace worktree AI 配置安装完成');
+  console.log('---');
+  console.log('AI_INIT_OK');
+  process.exit(0);
+} else {
+  console.error('ERROR: AI config install failed: ' + init.err);
+  console.error('');
+  console.error('━━━ extend-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. 进入 workspace worktree 并初始化');
+  console.error('   $ cd "' + wtRoot + '"');
+  console.error('   $ cbb init --yes');
+  console.error('');
+  console.error('4. 重新执行 extend-worktree');
+  console.error('   （脚本会用 .cbb/.managed-by-cbb 判重自动跳过已恢复部分）');
+  console.log('---');
+  console.log('AI_INIT_FAILED');
+  process.exit(2);
+}

package/cbb/worktrees/skills/openspec-extend-worktree/scripts/list-available-apps.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+require('./silence-popup');
+/**
+ * openspec-extend-worktree 计算"未关联"应用清单
+ *
+ * 用法：node list-available-apps.js <ws_root> <branch>
+ *
+ * 从 CONFIG.json 读取全部应用，减去目标 worktree 中已存在的应用子目录。
+ *
+ * 输出末行：LIST_RESULT { available: [...], already: [...] }
+ *
+ * 退出码：
+ *   0 - 有可用应用
+ *   1 - 参数错误
+ *   2 - 所有应用都已关联（无新增项）
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const wsRoot = process.argv[2];
+const branch = process.argv[3];
+
+if (!wsRoot || !branch) {
+  console.error('❌ 用法：node list-available-apps.js <ws_root> <branch>');
+  process.exit(1);
+}
+
+const configPath = path.join(wsRoot, 'CONFIG.json');
+if (!fs.existsSync(configPath)) {
+  console.error('❌ CONFIG.json 不存在：' + configPath);
+  process.exit(1);
+}
+
+let config;
+try {
+  config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+} catch (e) {
+  console.error('❌ CONFIG.json 解析失败：' + e.message);
+  process.exit(1);
+}
+
+const apps = config.apps || [];
+const wtDir = path.join(wsRoot, '.worktrees', 'worktree-' + branch);
+if (!fs.existsSync(wtDir)) {
+  console.error('❌ 目标 worktree 不存在：' + wtDir);
+  console.error('   请先执行 openspec-init-worktree 创建该需求的工作空间');
+  process.exit(1);
+}
+
+const available = [];
+const already = [];
+
+for (const app of apps) {
+  const wtSub = path.join(wtDir, app.name);
+  if (fs.existsSync(wtSub) && fs.existsSync(path.join(wtSub, '.git'))) {
+    already.push(app);
+  } else {
+    available.push(app);
+  }
+}
+
+console.log('=== 已关联应用（跳过） ===');
+if (already.length === 0) {
+  console.log('  （无）');
+} else {
+  already.forEach(a => {
+    console.log('  [' + (a.side || 'back') + '] ' + a.name);
+  });
+}
+console.log('');
+console.log('=== 可补加应用 ===');
+if (available.length === 0) {
+  console.log('  （无）');
+} else {
+  available.forEach(a => {
+    console.log('  [' + (a.side || 'back') + '] ' + a.name);
+  });
+}
+
+console.log('---');
+const result = {
+  available: available.map(a => a.name),
+  already: already.map(a => a.name),
+  availableDetails: available,
+};
+console.log('LIST_RESULT', JSON.stringify(result));
+process.exit(available.length === 0 ? 2 : 0);

package/cbb/worktrees/skills/openspec-extend-worktree/scripts/push-core.js

@@ -0,0 +1,136 @@
+require('./silence-popup');
+/**
+ * openspec-shared 推送核心模块
+ *
+ * 唯一真源：cbb/worktrees/_shared/scripts/push-core.js
+ * 由 scripts/sync-shared.js 展开到各 skill 的 scripts/ 下（init-worktree / extend-worktree / push-worktrees）。
+ *
+ * 公开 API：
+ *   - tryExec(cmd, cwd, execImpl)             包装 execSync，统一返回 {ok, out|err}
+ *   - escapeBranch(name)                      分支名 shell 转义（防命令注入）
+ *   - classifyError(stderr)                   将 stderr 归类为 8 种错误码之一
+ *   - pushSingle(repoPath, repoName, branch)  推送单个仓库并建立 upstream
+ *   - collectRemoteMetadata(repoPath, branch, remote)  采集远程 commit 元信息
+ *
+ * 错误码契约（classifyError 输出）：
+ *   - ssh-auth-failed        Permission denied (publickey)
+ *   - https-auth-failed      Authentication failed
+ *   - network-unreachable    Could not resolve host / hung up / connection refused
+ *   - branch-protected       protected branch / deny updating
+ *   - remote-exists          already exists
+ *   - no-remote              (pushSingle 内部判定)
+ *   - non-fast-forward       non-fast-forward
+ *   - unknown                兜底
+ */
+
+const { execSync: realExecSync } = require('child_process');
+
+const PUSH_TIMEOUT_MS = 60000;
+
+function tryExec(cmd, cwd, execImpl) {
+  const execSync = (execImpl || realExecSync);
+  try {
+    return {
+      ok: true,
+      out: execSync(cmd, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: PUSH_TIMEOUT_MS }).toString().trim(),
+    };
+  } catch (e) {
+    const stderr = (e.stderr ? e.stderr.toString() : e.message || String(e)).trim();
+    return { ok: false, err: stderr };
+  }
+}
+
+function escapeBranch(name) {
+  return '"' + String(name).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+
+function classifyError(stderr) {
+  const s = (stderr || '').toLowerCase();
+  if (s.includes('permission denied (publickey)')) return 'ssh-auth-failed';
+  if (s.includes('authentication failed')) return 'https-auth-failed';
+  if (s.includes('could not resolve host') || s.includes('hung up') || s.includes('connection refused')) {
+    return 'network-unreachable';
+  }
+  if (s.includes('protected branch') || s.includes('deny updating')) return 'branch-protected';
+  if (s.includes('already exists')) return 'remote-exists';
+  if (s.includes('non-fast-forward')) return 'non-fast-forward';
+  return 'unknown';
+}
+
+/**
+ * 采集远程分支的元信息（hash/author/date/message + 本地 hash）
+ * 任意子命令失败时返回 null（不抛错）
+ * @param {string} repoPath
+ * @param {string} branch
+ * @param {string} remote
+ * @param {{ execSyncImpl?: Function }} [opts]
+ * @returns {{ remote: {hash, author, date, message}, local: {hash} } | null}
+ */
+function collectRemoteMetadata(repoPath, branch, remote, opts) {
+  const execImpl = opts && opts.execSyncImpl;
+  try {
+    const remoteHash = tryExec('git rev-parse ' + escapeBranch(remote + '/' + branch), repoPath, execImpl);
+    if (!remoteHash.ok || !remoteHash.out) return null;
+
+    const remoteLog = tryExec('git log -1 --format="%an <%ae> | %ad | %s" ' + escapeBranch(remote + '/' + branch), repoPath, execImpl);
+    const localHash = tryExec('git rev-parse ' + escapeBranch(branch), repoPath, execImpl);
+    if (!remoteLog.ok || !localHash.ok || !localHash.out) return null;
+
+    // 解析 "author <email> | date | message"
+    const parts = remoteLog.out.split(' | ');
+    const author = parts[0] || '';
+    const date = parts[1] || '';
+    const message = parts.slice(2).join(' | ') || '';
+
+    return {
+      remote: {
+        hash: remoteHash.out,
+        author,
+        date,
+        message,
+      },
+      local: {
+        hash: localHash.out,
+      },
+    };
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 推送单个仓库的分支并建立 upstream
+ * @param {string} repoPath
+ * @param {string} repoName
+ * @param {string} branch
+ * @param {{ execSyncImpl?: Function }} [opts]
+ * @returns {{ name: string, status: string, upstream?: string, error?: string, message?: string, metadata?: object }}
+ */
+function pushSingle(repoPath, repoName, branch, opts) {
+  const execImpl = opts && opts.execSyncImpl;
+  const remote = tryExec('git remote', repoPath, execImpl);
+  if (!remote.ok || !remote.out) {
+    return { name: repoName, status: 'failed', error: 'no-remote', message: '无远程配置' };
+  }
+  const r = remote.out.split(/\r?\n/)[0];
+  const branchEsc = escapeBranch(branch);
+  const remoteEsc = '"' + String(r).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+  const pushResult = tryExec('git push -u ' + remoteEsc + ' ' + branchEsc, repoPath, execImpl);
+  if (pushResult.ok) {
+    return { name: repoName, status: 'pushed', upstream: r + '/' + branch };
+  }
+  const errCode = classifyError(pushResult.err);
+  if (errCode === 'remote-exists') {
+    const metadata = collectRemoteMetadata(repoPath, branch, r, opts);
+    return {
+      name: repoName,
+      status: 'remote-exists',
+      error: errCode,
+      message: '远程分支已存在，需用户决策',
+      metadata,
+    };
+  }
+  return { name: repoName, status: 'failed', error: errCode, message: pushResult.err.split(/\r?\n/)[0] };
+}
+
+module.exports = { tryExec, escapeBranch, classifyError, pushSingle, collectRemoteMetadata };