@jspg-ai/coding-bb 0.0.1

package/cbb/lib/utils/checkbox.js

@@ -0,0 +1,383 @@
+'use strict';
+
+/**
+ * inquirer 风格 checkbox 多选 UI。
+ *
+ * 键盘交互（TTY 模式）：
+ *   ↑ / ↓  或  j / k  — 移动光标
+ *   Space              — 切换当前项
+ *   a                  — 全选 / 全不选（已全选时再按全不选）
+ *   i                  — 反选所有项
+ *   Enter              — 确认（必须 ≥1 项已选）
+ *   Ctrl+C             — 取消并退出进程
+ *
+ * 降级路径（非 TTY，例如 CI / 管道）：
+ *   输出列表后用 readline 接收按编号输入，多选用逗号分隔。
+ *
+ * 跨平台：
+ *   - Windows 10 1607+ / Windows 11 原生支持 ANSI 与 raw mode
+ *   - 颜色由 process.stdout.isTTY 与 NO_COLOR 环境变量联合控制
+ */
+
+const readline = require('readline');
+
+// ── ANSI 控制序列 ─────────────────────────────────────────
+
+const ESC = '\x1b';
+const CLEAR_LINE = `${ESC}[2K`;            // 擦除整行
+const CURSOR_UP = (n) => `${ESC}[${n}A`;    // 光标上移 n 行
+const CLEAR_TO_END = `${ESC}[J`;            // 擦除从光标到屏幕底部
+const HIDE_CURSOR = `${ESC}[?25l`;
+const SHOW_CURSOR = `${ESC}[?25h`;
+
+const { COLOR, COLOR_ENABLED, c } = require('./output');
+
+// ── 纯函数：选中状态操作（独立可测）────────────────────
+
+/** 切换某项选中状态，返回新 Set（不可变） */
+function toggle(selected, idx) {
+  const next = new Set(selected);
+  if (next.has(idx)) next.delete(idx);
+  else next.add(idx);
+  return next;
+}
+
+/** 全选 / 全不选（已全选时再按则全不选） */
+function toggleAll(selected, total) {
+  if (total <= 0) return new Set();
+  if (selected.size === total) return new Set();
+  return new Set(Array.from({ length: total }, (_, i) => i));
+}
+
+/** 反选所有 */
+function invert(selected, total) {
+  const next = new Set();
+  for (let i = 0; i < total; i++) {
+    if (!selected.has(i)) next.add(i);
+  }
+  return next;
+}
+
+/**
+ * 解析非 TTY 模式下逗号 / 空格分隔的编号输入。
+ * @returns {Set<number>} 选中的索引（0-based），输入为空返回空 Set
+ */
+function parseBulkInput(input, total) {
+  if (typeof input !== 'string' || !input.trim()) return new Set();
+  const indices = input.split(/[,，\s]+/)
+    .map(s => parseInt(s, 10) - 1)
+    .filter(i => Number.isInteger(i) && i >= 0 && i < total);
+  return new Set(indices);
+}
+
+// ── 渲染：把状态转成行数组（独立可测）────────────────────
+
+/**
+ * @param {object} state
+ * @param {Array<{label:string, hint?:string}>} state.items
+ * @param {number} state.cursor
+ * @param {Set<number>} state.selected
+ * @param {string} [state.header]
+ * @param {string} [state.footer]
+ * @param {string} [state.emptyMsg]
+ * @returns {string[]} 行数组
+ */
+function renderLines(state) {
+  const { items, cursor, selected, header, footer, emptyMsg } = state;
+  const lines = [];
+
+  if (header) {
+    lines.push(c('bold', header));
+    lines.push(c('gray', '─'.repeat(48)));
+  }
+
+  if (items.length === 0) {
+    lines.push(c('gray', emptyMsg || '（无可选项）'));
+  } else {
+    items.forEach((item, i) => {
+      const isCursor = i === cursor;
+      const isSelected = selected.has(i);
+      const cursorMark = isCursor ? c('cyan', '❯') : ' ';
+      const checkMark = isSelected ? c('green', '☑') : c('gray', '☐');
+      const raw = `  ${cursorMark} ${checkMark} ${item.label}`;
+      // 当前行整体加粗 + 反转视频：浅色终端也能识别
+      const line = isCursor && COLOR_ENABLED
+        ? `${COLOR.bold}${COLOR.reverse}${raw}${COLOR.reset}`
+        : (isCursor ? c('bold', raw) : raw);
+      lines.push(line);
+      if (item.hint) {
+        lines.push(c('gray', '        ' + item.hint));
+      }
+    });
+  }
+
+  if (footer) {
+    lines.push('');
+    lines.push(c('gray', footer));
+  }
+
+  return lines;
+}
+
+// ── TTY 模式：键盘交互主循环 ─────────────────────────────
+
+const DEFAULT_FOOTER = '↑↓ 移动 · 空格 切换 · a 全选 · i 反选 · 回车 确认 · Ctrl+C 取消';
+
+/**
+ * 探测 raw mode 是否真的可用。
+ *
+ * 返回 false 的场景（需要降级到 fallback）：
+ *  - process.stdin 不是 TTY（如 CI / 管道）
+ *  - setRawMode(true) 抛错
+ *  - setRawMode(true) 调用后 stdin.isRaw 不是 true（例如 Git Bash MINGW64 通过
+ *    winpty 启动时：setRawMode 不报错但 isRaw 可能为 false，或实际键盘事件无法
+ *    传递给 Node.js 的 keypress 监听器）
+ *
+ * 探测完后还原原始 raw mode 状态，避免影响后续读取。
+ */
+function canEnableRawMode(stdin) {
+  if (!stdin.isTTY) return false;
+  const wasRaw = stdin.isRaw === true;
+  try {
+    stdin.setRawMode(true);
+    const ok = stdin.isRaw === true;
+    if (wasRaw !== ok) {
+      try { stdin.setRawMode(wasRaw); } catch (_) { /* ignore */ }
+    }
+    return ok;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {Array<{label:string, hint?:string}>} options.items
+ * @param {string} [options.header]
+ * @param {string} [options.footer]
+ * @param {Set<number>} [options.preSelected] 预选项索引
+ * @returns {Promise<Set<number>>} 选中的索引集合
+ */
+function promptCheckboxTty({ items, header, footer, preSelected }) {
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+
+    // 探测：raw mode 不可用则立即降级，避免在 MINGW64 等环境下静默退出
+    if (!canEnableRawMode(stdin)) {
+      return promptCheckboxFallback({ items, header, footer, preSelected })
+        .then(resolve, reject);
+    }
+
+    const state = {
+      items,
+      cursor: 0,
+      selected: new Set(preSelected || []),
+      header,
+      footer: footer || DEFAULT_FOOTER,
+      emptyMsg: '（无可选项）',
+    };
+
+    let lastLineCount = 0;
+    let finished = false;
+
+    function rerender() {
+      if (lastLineCount > 0) {
+        stdout.write(CURSOR_UP(lastLineCount));
+        stdout.write(CLEAR_TO_END);
+      }
+      const lines = renderLines(state);
+      stdout.write(lines.join('\n') + '\n');
+      lastLineCount = lines.length;
+    }
+
+    function showWarning(text) {
+      // 在 UI 下方追加一行警告，下次 rerender 会被清除
+      stdout.write('\n' + c('yellow', `  ${text}`) + '\n');
+      lastLineCount += 2;
+    }
+
+    function finish(result, error) {
+      if (finished) return;
+      finished = true;
+      stdin.removeListener('keypress', onKeypress);
+      stdin.removeListener('end', onStdinEnd);
+      stdin.removeListener('close', onStdinEnd);
+      if (stdin.isRaw) {
+        try { stdin.setRawMode(false); } catch (_) { /* ignore */ }
+      }
+      // 恢复 paused 状态：避免 stdin 保持 flowing 导致 Node.js 事件循环
+      // 不退出（表现为进程运行完毕但光标停留在 shell 输入位置）
+      if (typeof stdin.pause === 'function') {
+        try { stdin.pause(); } catch (_) { /* ignore */ }
+      }
+      stdout.write(SHOW_CURSOR);
+      // 清理 UI：上移光标到 UI 开始位置后清除
+      if (lastLineCount > 0) {
+        stdout.write(CURSOR_UP(lastLineCount));
+        stdout.write(CLEAR_TO_END);
+      }
+      if (error) reject(error);
+      else resolve(result);
+    }
+
+    /**
+     * stdin 意外关闭降级处理。
+     *
+     * Git Bash MINGW64 通过 winpty 启动子进程时，raw mode 启用后 stdin 可能被
+     * 父进程立即关闭（表现为进程静默退出，UI 残留）。此时不能留白屏，降级到
+     * fallback 路径，用 preSelected 默认值确认，同时输出可见提示。
+     */
+    function onStdinEnd() {
+      if (finished) return;
+      stdin.removeListener('keypress', onKeypress);
+      stdin.removeListener('end', onStdinEnd);
+      stdin.removeListener('close', onStdinEnd);
+      if (stdin.isRaw) {
+        try { stdin.setRawMode(false); } catch (_) { /* ignore */ }
+      }
+      if (typeof stdin.pause === 'function') {
+        try { stdin.pause(); } catch (_) { /* ignore */ }
+      }
+      stdout.write(SHOW_CURSOR);
+      if (lastLineCount > 0) {
+        stdout.write(CURSOR_UP(lastLineCount));
+        stdout.write(CLEAR_TO_END);
+      }
+      stdout.write(c('yellow', '\n  ⚠ stdin 已关闭，自动使用默认选择\n\n'));
+      promptCheckboxFallback({ items, header, footer, preSelected })
+        .then(resolve, reject);
+    }
+
+    function onKeypress(str, key) {
+      if (!key || finished) return;
+
+      // Ctrl+C 退出
+      if (key.ctrl && key.name === 'c') {
+        finish(new Set(), new Error('USER_CANCELLED'));
+        return;
+      }
+
+      switch (key.name) {
+        case 'up':
+        case 'k':
+          state.cursor = (state.cursor - 1 + items.length) % items.length;
+          rerender();
+          break;
+        case 'down':
+        case 'j':
+          state.cursor = (state.cursor + 1) % items.length;
+          rerender();
+          break;
+        case 'space':
+          state.selected = toggle(state.selected, state.cursor);
+          rerender();
+          break;
+        case 'a':
+          state.selected = toggleAll(state.selected, items.length);
+          rerender();
+          break;
+        case 'i':
+          state.selected = invert(state.selected, items.length);
+          rerender();
+          break;
+        case 'return':
+        case 'enter':
+          if (state.selected.size === 0) {
+            showWarning('⚠ 请至少选择 1 项');
+          } else {
+            finish(state.selected);
+          }
+          break;
+        default:
+          // 忽略其他按键
+          break;
+      }
+    }
+
+    // 启用 raw mode + 注册事件监听
+    // （探测阶段已通过 canEnableRawMode，这里理论上不会抛错；保留 try 防御）
+    try { stdin.setRawMode(true); } catch (_) { /* ignore */ }
+    readline.emitKeypressEvents(stdin);
+    stdin.on('keypress', onKeypress);
+    stdin.on('end', onStdinEnd);
+    stdin.on('close', onStdinEnd);
+    // 确保 stdin flowing：某些环境下 setRawMode 不会自动 resume
+    if (typeof stdin.resume === 'function') stdin.resume();
+
+    // 隐藏光标 + 首次渲染
+    stdout.write(HIDE_CURSOR);
+    rerender();
+  });
+}
+
+// ── 非 TTY 降级路径 ──────────────────────────────────────
+
+function promptCheckboxFallback({ items, header, footer, preSelected }) {
+  return new Promise((resolve) => {
+    const state = {
+      items,
+      cursor: 0,
+      selected: new Set(preSelected || []),
+      header,
+      footer,
+      emptyMsg: '（无可选项）',
+    };
+
+    // 输出列表（无光标、无高亮，逐项标号）
+    console.log(c('bold', header) || '');
+    console.log(c('gray', '─'.repeat(48)));
+    items.forEach((item, i) => {
+      console.log(`  ${c('cyan', String(i + 1) + '.')} ${item.label}`);
+      if (item.hint) console.log(c('gray', '        ' + item.hint));
+    });
+    console.log('');
+    if (footer) console.log(c('gray', footer));
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(`请输入编号（多选用逗号分隔）: `, (answer) => {
+      rl.close();
+      const selected = parseBulkInput(answer, items.length);
+      resolve(selected);
+    });
+  });
+}
+
+// ── 主入口 ──────────────────────────────────────────────
+
+/**
+ * 弹出 checkbox 列表，收集用户选择。
+ * @param {object} options
+ * @param {Array<{label:string, hint?:string}>} options.items
+ * @param {string} [options.header]   顶部标题（建议已含图标）
+ * @param {string} [options.footer]   底部操作提示；不传则使用默认模板
+ * @param {Set<number>|number[]} [options.preSelected] 预选项索引
+ * @returns {Promise<Set<number>>} 选中的索引集合（0-based，按原始顺序）
+ */
+function promptCheckbox(options) {
+  const isTty = process.stdin.isTTY && process.stdout.isTTY;
+  const prompt = isTty ? promptCheckboxTty : promptCheckboxFallback;
+
+  // 兼容 number[] 形式的 preSelected
+  const normalized = { ...options };
+  if (Array.isArray(options.preSelected)) {
+    normalized.preSelected = new Set(options.preSelected);
+  }
+
+  return prompt(normalized);
+}
+
+module.exports = {
+  promptCheckbox,
+  // 暴露纯函数供单测与复用
+  toggle,
+  toggleAll,
+  invert,
+  parseBulkInput,
+  renderLines,
+  canEnableRawMode,
+};

package/cbb/lib/utils/gitignore.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * .gitignore 管理的纯函数工具（无副作用，便于单测；由 init.js 的 I/O 层调用）。
+ *
+ * 安装时：若 .gitignore 已含某目录（认可带/不带尾斜杠两种形式），则不重复添加；
+ *         否则新增无尾斜杠形式（.claude / .qoder，更通用）。.cbb/ 维持带斜杠。
+ * 卸载时：移除本包曾写入的所有形式（新旧版本均覆盖）。
+ *
+ * 注意：.gitignore 条目无 _managedBy 之类的标记，卸载按"形式匹配"移除，
+ * 若用户恰好写了相同行也会被一并移除（与本包历史行为一致）。
+ */
+
+// 各目录：add = 写入形式；accept = 视为"已存在 / 需卸载移除"的可接受形式（含尾斜杠变体）。
+// .claude / .qoder 写无尾斜杠形式，但检测/卸载时同时认可带斜杠变体，避免重复添加、覆盖旧版本。
+const GITIGNORE_RULES = [
+  { add: '.claude', accept: ['.claude', '.claude/'] },
+  { add: '.qoder', accept: ['.qoder', '.qoder/'] },
+  { add: '.cbb/', accept: ['.cbb/'] },
+  { add: '.code/', accept: ['.code/', '.code'] },
+];
+
+/** 将 .gitignore 文本拆为行数组。 */
+function toLines(content) {
+  return (content || '').split(/\r?\n/);
+}
+
+/**
+ * 给定 .gitignore 内容，返回需要新增的条目。
+ * 已含任一可接受形式（带/不带尾斜杠）的目录会被跳过；全部已存在时返回空数组。
+ * 返回的是写入形式（.claude / .qoder 无尾斜杠，.cbb/ 带尾斜杠）。
+ */
+function entriesToAdd(content) {
+  const lines = toLines(content).map(l => l.trim());
+  return GITIGNORE_RULES
+    .filter(r => !r.accept.some(a => lines.includes(a)))
+    .map(r => r.add);
+}
+
+/**
+ * 给定 .gitignore 行数组，返回移除本包所有形式后的行数组（用于卸载）。
+ * 同时移除带/不带尾斜杠的形式，覆盖新旧版本写入的条目。
+ */
+function filterManaged(lines) {
+  const removable = new Set(GITIGNORE_RULES.flatMap(r => r.accept));
+  return (lines || []).filter(l => !removable.has(l.trim()));
+}
+
+/**
+ * 将待新增条目追加到现有 .gitignore 内容，返回新内容字符串。
+ * 有内容时用一个空行分隔，使新增条目另起一行开始；空内容直接写（不产生前导空行）。
+ * 幂等：已含全部条目时调用方应先经 entriesToAdd 判定（返回空数组则不调用）。
+ */
+function appendEntries(content, entries) {
+  const block = entries.join('\n');
+  if ((content || '').trim() === '') {
+    return block + '\n';
+  }
+  // 去掉末尾换行后：一个换行结束末行，再一个换行形成空行，然后是新增条目
+  const base = content.replace(/\n+$/, '');
+  return base + '\n\n' + block + '\n';
+}
+
+module.exports = {
+  GITIGNORE_RULES,
+  entriesToAdd,
+  filterManaged,
+  appendEntries,
+};

package/cbb/lib/utils/output.js

@@ -0,0 +1,64 @@
+// ── 颜色与输出辅助（公共模块）──────────────────────────────
+// 合并自 lib/install/init.js、lib/utils/checkbox.js、lib/superpowers/index.js
+
+const COLOR = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  reverse: '\x1b[7m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+};
+
+/** 是否启用颜色：仅 TTY 且未设置 NO_COLOR 时启用 */
+const COLOR_ENABLED = process.stdout.isTTY === true && !process.env.NO_COLOR;
+
+function c(color, text) {
+  if (!COLOR_ENABLED) return text;
+  return `${COLOR[color]}${text}${COLOR.reset}`;
+}
+
+// ── 工具函数 ──────────────────────────────────────────────
+
+// 各类型的图标 + 颜色：icon 是前缀文字（2 字符对齐），color 是着色 key。
+// 新增类型不会破坏旧调用；不识别的 type 退化为 info。
+const LOG_STYLES = {
+  info:    { icon: '  ', color: null },
+  success: { icon: '✓', color: 'green' },
+  error:   { icon: '✗', color: 'red' },
+  warn:    { icon: '!', color: 'yellow' },
+  dim:     { icon: '  ', color: 'gray' },
+  accent:  { icon: '  ', color: 'cyan' },
+};
+
+function log(msg, type = 'info') {
+  const s = LOG_STYLES[type] || LOG_STYLES.info;
+  const text = `${s.icon} ${msg}`;
+  console.log(s.color ? c(s.color, text) : text);
+}
+
+/** 输出一行分节标题（带图标 + 颜色），紧跟一行灰色分隔线 */
+function section(icon, title) {
+  console.log('');
+  console.log(c('bold', `${icon}  ${title}`));
+  console.log(c('gray', '─'.repeat(48)));
+}
+
+/** 以"label + value"两列对齐的方式输出一条字段记录 */
+function field(label, value, valueColor) {
+  console.log(`  ${c('gray', (label + ':').padEnd(8, ' '))} ${valueColor ? c(valueColor, value) : value}`);
+}
+
+module.exports = {
+  COLOR,
+  COLOR_ENABLED,
+  c,
+  LOG_STYLES,
+  log,
+  section,
+  field,
+};

package/cbb/lib/utils/settings.js

@@ -0,0 +1,119 @@
+/**
+ * settings.json 读写工具
+ *
+ * 负责向 Qoder / Claude 的 settings.json 安全地写入 / 移除版本检查 hook，
+ * 通过 UserPromptSubmit 事件在用户发消息时自动检查本规范是否有新版本。
+ * 脚本内做会话级去重，每会话只提示一次。
+ *
+ * 所有本包写入的 hook 条目都带 `_managedBy: "cbb"` 标记，便于卸载时精确移除，
+ * 不影响用户自有的 hooks 配置。
+ *
+ * removeLegacyHooks 负责清理旧版本曾写入、现已弃用的 SessionStart hook：
+ * 当前仅安装 UserPromptSubmit，但升级自旧版本的用户 settings.json 中可能仍残留
+ * SessionStart 条目，升级 / 卸载时需主动移除，否则会永久残留。
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MANAGED_BY = 'cbb';
+
+// 旧版本曾写入、现已弃用的 hook 事件。升级 / 卸载时需清理这些事件下本包标记的条目。
+const LEGACY_HOOK_EVENTS = ['SessionStart'];
+
+/** 返回 hook 要执行的命令（绝对路径调用本包的 check-update.js） */
+function getCheckUpdateCommand() {
+  const scriptPath = path.join(__dirname, 'check-update.js');
+  return `node "${scriptPath}"`;
+}
+
+function readSettings(settingsPath) {
+  if (!fs.existsSync(settingsPath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(settingsPath, 'utf-8')) || {};
+  } catch (_) {
+    return {};
+  }
+}
+
+function writeSettings(settingsPath, data) {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2) + '\n');
+}
+
+/** 移除某事件下本包标记的条目，返回过滤后的数组 */
+function stripManaged(arr) {
+  return (Array.isArray(arr) ? arr : []).filter(
+    entry => !(entry && entry._managedBy === MANAGED_BY)
+  );
+}
+
+/**
+ * 向 settings.json 写入本包的版本检查 hook。
+ * @param {string} settingsPath settings.json 路径
+ * @param {string} command 要执行的命令
+ * @param {string[]} events 要写入的事件名数组，如 ['UserPromptSubmit']
+ * 已存在本包标记的条目会先移除再添加（保证命令为最新路径），不重复。
+ */
+function addHooks(settingsPath, command, events) {
+  const settings = readSettings(settingsPath);
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+
+  events.forEach(event => {
+    settings.hooks[event] = stripManaged(settings.hooks[event]);
+    const entry = { _managedBy: MANAGED_BY, hooks: [{ type: 'command', command }] };
+    settings.hooks[event].push(entry);
+  });
+
+  writeSettings(settingsPath, settings);
+  return true;
+}
+
+/**
+ * 移除本包写入的版本检查 hook，保留用户其它配置。
+ * 清理变空的事件数组 / hooks。
+ * @param {string} settingsPath settings.json 路径
+ * @param {string[]} events 要清理的事件名数组
+ * 返回 true 表示有改动。
+ */
+function removeHooks(settingsPath, events) {
+  if (!fs.existsSync(settingsPath)) return false;
+  const settings = readSettings(settingsPath);
+  if (!settings.hooks || typeof settings.hooks !== 'object') return false;
+
+  let changed = false;
+  events.forEach(event => {
+    if (!Array.isArray(settings.hooks[event])) return;
+    const before = settings.hooks[event].length;
+    settings.hooks[event] = stripManaged(settings.hooks[event]);
+    if (settings.hooks[event].length !== before) changed = true;
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  });
+
+  if (!changed) return false;
+
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+  // 文件变成空对象则删除，否则写回
+  if (Object.keys(settings).length === 0) {
+    fs.unlinkSync(settingsPath);
+  } else {
+    writeSettings(settingsPath, settings);
+  }
+  return true;
+}
+
+/**
+ * 清理遗留事件下本包标记的 hook 条目（旧版本写入的 SessionStart 等）。
+ * 复用 removeHooks 的清理逻辑；返回 true 表示有改动。
+ */
+function removeLegacyHooks(settingsPath) {
+  return removeHooks(settingsPath, LEGACY_HOOK_EVENTS);
+}
+
+module.exports = {
+  getCheckUpdateCommand,
+  addHooks,
+  removeHooks,
+  removeLegacyHooks,
+};