@house365/comate 0.2.7 → 0.2.9

package/README.md

@@ -41,6 +41,15 @@ skills 装到用户级（`~/.agents/skills`），装一次所有项目共用；`
 
 装完输入 `/comate` 开始使用，`comate doctor` 可自检。
 
+## 更新
+
+```bash
+npm install -g @house365/comate@latest
+cd your-project && comate init
+```
+
+两步都要跑：`npm` 只换 CLI 本身，skills 是 `comate init` 铺到 `~/.agents/skills` 的，npm 不管。这里的 `@latest` 不能省——本地已装时，不带 tag 的 `npm install -g` 可能认为已满足而不去 registry 取新版。
+
 ## 用法
 
 输入 `/comate` 自动探测当前阶段并分派,或直接调用某个阶段 skill。状态记录在每个 change 的 `openspec/changes/<name>/.comate.yaml` 中,支持上下文压缩后断点恢复。

package/bin/init-run.mjs

@@ -3,8 +3,10 @@ import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
+import { findBash } from './doctor.mjs';
 import {
   NPM_TIMEOUT_MS,
+  capture,
   SKILLS_TIMEOUT_MS,
   npmInvocation,
   openSpecState,
@@ -55,6 +57,19 @@ export async function init(pkgRoot) {
     return 1;
   }
 
+  // comate's skills are bash scripts needing associative arrays (bash 4+), and
+  // macOS ships 3.2. Fail here rather than installing everything and letting the
+  // first /comate call die inside a sourced library.
+  const bash = bashVersion();
+  if (bash !== null && bash < 4) {
+    console.error(
+      `\ncomate 的脚本需要 bash >= 4，当前 ${bash === 0 ? '未知版本' : `bash ${bash}.x`}。\n` +
+        'macOS 自带 bash 3.2（授权原因），装一个新的：\n\n  brew install bash\n\n' +
+        '装好后重跑 comate init。',
+    );
+    return 3;
+  }
+
   const stopSpinner = startSpinner('Initializing…');
 
   // 1. OpenSpec CLI — a PATH command, so always global.
@@ -236,6 +251,22 @@ export function banner(version, { ci = isCI() } = {}) {
   ].join('\n');
 }
 
+// Major version of the bash that comate's scripts will actually run under, or
+// null when there is no bash at all — that is doctor's diagnosis to deliver, not
+// a reason to block the install. Windows resolves through findBash so a Git Bash
+// install is not mistaken for the WSL launcher.
+// Parsed from --version rather than `-c 'echo $BASH_VERSINFO'`: capture() runs
+// through a shell on Windows, which swallows the variable before bash sees it.
+export function bashVersion(probe = (bin) => capture(bin, ['--version'])) {
+  const bin = process.platform === 'win32' ? findBash() : 'bash';
+  if (!bin) return null;
+  const out = probe(bin);
+  if (out === null) return null;
+  // "GNU bash, version 5.2.26(1)-release ..." / macOS: "... version 3.2.57(1)"
+  const major = out.match(/version (\d+)\./)?.[1];
+  return major === undefined ? 0 : Number(major);
+}
+
 // Every major CI sets CI=true; GITHUB_ACTIONS covers the Actions runner even in
 // the odd config that doesn't.
 function isCI() {

package/bin/init.mjs

@@ -98,12 +98,16 @@ function run({ command, args, shell }, timeout, { quiet = false } = {}) {
   return { ok: true };
 }
 
-function capture(command, args) {
+// shell defaults to off: passing args with shell:true is deprecated in Node 24
+// and is an injection surface, since the args are concatenated rather than
+// escaped. Callers that genuinely need cmd.exe resolution (a bare `openspec`
+// that only exists as openspec.cmd) opt in explicitly.
+function capture(command, args, { shell = false } = {}) {
   const { status, stdout: out } = spawnSync(command, args, {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],
     timeout: 15_000,
-    shell: process.platform === 'win32',
+    ...(shell ? { shell: true } : {}),
   });
   return status === 0 ? out.trim() : null;
 }
@@ -138,7 +142,9 @@ function skillsInvocation(pkgRoot, args) {
 }
 
 function openSpecState() {
-  const version = capture('openspec', ['--version']);
+  // shell:true on Windows: npm installs this as openspec.cmd, which cannot be
+  // spawned directly. bashVersion needs no shell — it has a real executable path.
+  const version = capture('openspec', ['--version'], { shell: process.platform === 'win32' });
   if (version === null) return { status: 'missing' };
   return { status: atLeast(version, MIN_OPENSPEC) ? 'ready' : 'outdated', version };
 }

package/docs/COMATE_MANUAL.md

@@ -64,6 +64,13 @@ comate 是一个规约驱动、AI 辅助的开发编排器。它将 **OpenSpec**
 
 ## 2. 安装与前置条件
 
+```bash
+npm install -g @house365/comate
+cd your-project && comate init
+```
+
+`init` 会装好下面 2.2–2.4 的全部内容。本节余下部分用于排查：init 报某项失败时，对照确认要装什么、怎么自查。
+
 ### 2.1 运行环境
 
 | 依赖 | 要求 | 检查方式 |
@@ -79,7 +86,9 @@ comate 是一个规约驱动、AI 辅助的开发编排器。它将 **OpenSpec**
 
 ```bash
 npm install -g @fission-ai/openspec@latest
-cd <project-root> && openspec init
+# --tools 必填：openspec 靠探测已有 agent 配置目录决定写哪些 tool 文件，
+# 干净项目里探测不到会直接报 No tools detected 退出
+cd <project-root> && openspec init . --tools none
 openspec list --json  # 验证安装
 ```
 
@@ -89,7 +98,7 @@ comate 使用以下 OpenSpec 能力（以技能形式调用）：`openspec-explo
 
 处理技术设计/规划/执行/收尾。comate 的 design、build 和 verify 阶段依赖它。
 
-Superpowers 是一个技能集。按你的平台约定安装。确认以下技能可加载：
+`comate init` 已用 `skills add obra/superpowers -g` 装到用户级。手动补装同理。确认以下技能可加载：
 
 - `superpowers:brainstorming`
 - `superpowers:writing-plans`
@@ -102,7 +111,9 @@ Superpowers 是一个技能集。按你的平台约定安装。确认以下技
 
 ### 2.4 comate 本身
 
-分发方式 = 将完整的 comate 技能目录复制到你的平台技能目录。本项目（Claude Code 插件）使用扁平布局：
+comate 以 npm 包分发（`npm install -g @house365/comate`），`comate init` 通过 skills CLI 装到用户级 `~/.agents/skills`，一次装完所有项目共用，支持 Claude Code、Codex、Cursor 等 70+ agent。
+
+采用扁平布局——每个 phase 是顶层技能目录，而非 `comate/<phase>/` 嵌套。部分 agent（含 Claude Code）只发现顶层目录，扁平是共同可用的最小公倍数：
 
 ```
 skills/
@@ -183,8 +194,8 @@ skills/
 
 | 场景 | 处理方式 |
 |----------|----------|
-| `openspec list --json` 失败 | 检查 openspec 安装，提示 `openspec init` |
-| 子技能不可用 | 停止流程，提示安装/启用该技能 |
+| `openspec list --json` 失败 | 检查 openspec 安装，提示 `openspec init . --tools none` |
+| 子技能不可用 | 停止流程，提示运行 `comate init` 补装 |
 | `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `state set` 修复后继续 |
 | 构建/测试失败 | 回到 build 阶段修复，不要进入 verify |
 | 变更目录结构不完整 | 按 comate-open 产出物要求补全缺失文件 |
@@ -542,8 +553,8 @@ bash comate/scripts/comate.sh status       # 所有活动变更状态
 | Guard 持续报告 isolation/build_mode 未设置 | 断点恢复时未填写 | 返回 build 阶段完成设置 |
 | 验证失败后无法推进 | verify_result: fail | 用户先选择修复方案，智能体执行 `state transition <name> verify-fail` 后返回 build |
 | 变更目录结构不完整 | 流程中断 | 按 comate-open 产出物要求补全 |
-| `openspec list --json` 失败 | openspec 未安装或未初始化 | 运行 `openspec init` |
-| 子技能不可用 | Superpowers 未安装 | 按平台文档安装 |
+| `openspec list --json` 失败 | openspec 未安装或未初始化 | 运行 `comate init`，或 `openspec init . --tools none` |
+| 子技能不可用 | Superpowers 未安装 | 运行 `comate init` 补装 |
 | bash 版本过低 | bash < 4（无关联数组） | Windows：Git Bash/WSL；macOS：`brew install bash` |
 | .sh 文件包含 CRLF | git 配置问题 | 仓库有 `.gitattributes` 强制 `eol=lf`；如已损坏，使用 `dos2unix` |
 | 脏工作树无法推进 | 未遵循 dirty-worktree 协议 | 按协议归属，暂停并询问用户 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "comate —— OpenSpec + Superpowers 规约驱动的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",

package/skills/comate/SKILL.md

@@ -75,7 +75,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 
 | 场景 | 处理 |
 |------|------|
-| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `openspec init` |
+| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `comate init` |
 | 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
 | `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `bash "$COMATE" state set` 修正后继续 |
 | 构建/测试失败 | 回 build 阶段修复，不进入 verify |

package/skills/comate/reference/prerequisites.md

@@ -2,9 +2,9 @@
 
 规范路径：`comate/reference/prerequisites.md`
 
-comate 不附带安装器：OpenSpec 与 Superpowers 需要**手动安装**，comate 本身的分发方式就是「复制 `comate/` 文件夹」。本清单说明需要装什么、怎么自查、怎么补。
+`comate init` 会自动装好 OpenSpec CLI、Superpowers 和 comate 自身，正常情况下不需要手动执行本清单。清单保留下来用于排查：init 报某项失败时，对照这里确认要装什么、怎么自查、怎么补。
 
-> 一键自查：运行 `bash comate/scripts/comate.sh doctor`。它会检查下列大部分项目并给出可执行提示。
+> 一键自查：`comate doctor`（或直接 `bash comate/scripts/comate.sh doctor`）。它会检查下列大部分项目并给出可执行提示。
 
 ## 1. 运行环境
 
@@ -25,10 +25,10 @@ comate 不附带安装器：OpenSpec 与 Superpowers 需要**手动安装**，co
 npm install -g @fission-ai/openspec@latest
 ```
 
-初始化（在项目根目录）：
+初始化（在项目根目录）。`comate init` 已经做过这一步，手动补做时需要 `--tools`：openspec 靠探测已有的 agent 配置目录决定写哪些 tool 文件，干净项目里探测不到会直接报 `No tools detected` 退出。
 
 ```bash
-openspec init
+openspec init . --tools none
 ```
 
 自查：
@@ -44,7 +44,7 @@ comate 用到的 OpenSpec 能力（以 skill 形式调用）：`openspec-explore
 
 负责技术设计 / 计划 / 执行 / 收尾。comate 的 design / build / verify 阶段依赖它。
 
-Superpowers 是一组 skill，按你所用平台的约定安装到 skills 目录（如 `.claude/skills/`、`.cursor/skills/`、`~/.config/skills/` 等）。安装后确认下列 skill 可加载：
+`comate init` 已用 `skills add obra/superpowers -g` 装到用户级。手动补装同理。安装后确认下列 skill 可加载：
 
 - `superpowers:brainstorming`
 - `superpowers:writing-plans`
@@ -58,7 +58,9 @@ Superpowers 是一组 skill，按你所用平台的约定安装到 skills 目录
 
 ## 4. comate 自身
 
-分发 = 复制 comate 的全部 skill 目录到目标平台的 skills 目录。本项目（Claude Code 插件）采用**平铺布局**，因为 Claude Code 只发现顶层 skill 目录：
+comate 以 npm 包分发（`npm install -g @house365/comate`），`comate init` 通过 skills CLI 装到用户级 `~/.agents/skills`，一次装完所有项目共用，支持 Claude Code、Codex、Cursor 等 70+ agent。
+
+采用**平铺布局**——每个 phase 是顶层 skill 目录，而非 `comate/<phase>/` 嵌套。部分 agent（含 Claude Code）只发现顶层目录，平铺是共同可用的最小公倍数：
 
 ```
 skills/

package/skills/comate/scripts/comate.sh

@@ -25,6 +25,24 @@
 
 set -euo pipefail
 
+# Must come before sourcing the lib. comate-lib.sh declares associative arrays
+# at load time, which bash 3.2 (what macOS ships as /bin/bash) parses as an
+# ordinary array assignment — the subscript is then evaluated as arithmetic and
+# `set -u` aborts with "schema_version: unbound variable". doctor has its own
+# bash>=4 check, but it never got to run: the source above it already died.
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+  cat >&2 <<EOF
+comate needs bash >= 4 (associative arrays), found ${BASH_VERSION:-unknown}.
+
+macOS ships bash 3.2 for licensing reasons. Install a current one:
+  brew install bash
+
+Then re-run through it, e.g.:
+  $(command -v brew >/dev/null 2>&1 && echo "\$(brew --prefix)/bin/bash" || echo /opt/homebrew/bin/bash) $0 $*
+EOF
+  exit 3
+fi
+
 SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")" && pwd)"
 # shellcheck source=comate-lib.sh
 . "$SCRIPT_DIR/comate-lib.sh"