@house365/comate 0.1.3 → 0.2.0

package/README.md

@@ -25,39 +25,21 @@ open → design → build → verify → archive
 ## 安装
 
 ```bash
-cd <你的项目目录>
-npx @house365/comate init     # 装到 ./.agents/skills/
+npm install -g @house365/comate
 ```
 
-装到用户全局，所有项目可用（此时在哪个目录执行都一样）：
+到项目目录初始化：
 
 ```bash
-npx @house365/comate init -g  # 装到 ~/.agents/skills/
+cd your-project
+comate init
 ```
 
-`init` 会一并装齐两个依赖（OpenSpec CLI、Superpowers），已装的自动跳过，可重复执行。
+`init` 会装好 comate 及其依赖（OpenSpec CLI、Superpowers），并创建 `openspec/` 项目结构。支持 Claude Code、Codex、Cursor 等 70+ agent。可重复执行，已装的自动跳过。
 
-项目安装的目标目录就是**你执行命令时所在的目录**。init 会先打印完整路径，并在目录看起来不像项目（没有 `.git`、`package.json` 等标志）或就是你的主目录时中止，避免装错地方——确实要装在当前目录就加 `--force`。
+skills 装到用户级（`~/.agents/skills`），装一次所有项目共用；`openspec/` 是项目自己的规约，建在当前目录，所以 `init` 需要在项目目录下运行。
 
-只装 comate 本身、不碰依赖：
-
-```bash
-npx @house365/comate          # 装到当前项目 ./.agents/skills/
-npx @house365/comate -g       # 装到用户全局
-npx @house365/comate --list   # 只看有哪些 skill，不安装
-```
-
-需要同时创建 `openspec/` 项目结构时加 `--openspec-init`。
-
-支持 Claude Code、Codex、Cursor 等 70+ agent（底层复用 [`skills`](https://www.npmjs.com/package/skills) CLI，自动探测当前 agent）。
-
-装完跑一次健康检查：
-
-```bash
-bash .agents/skills/comate/scripts/comate.sh doctor
-```
-
-依赖详情见 [docs/COMATE_MANUAL.md](docs/COMATE_MANUAL.md) 第 2 节。
+装完输入 `/comate` 开始使用，`comate doctor` 可自检。
 
 ## 用法
 

package/bin/cli.mjs

@@ -13,24 +13,22 @@ const args = process.argv.slice(2);
 
 if (args[0] === 'init') {
   const { init } = await import('./init-run.mjs');
-  process.exit(await init(pkgRoot, args.slice(1)));
+  process.exit(await init(pkgRoot));
+}
+
+if (args[0] === 'doctor') {
+  const { doctor } = await import('./doctor.mjs');
+  process.exit(doctor(args.slice(1)));
 }
 
 if (args[0] === '--help' || args[0] === '-h') {
   console.log(`comate — OpenSpec + Superpowers 规约驱动的开发编排器
 
 用法:
-  comate-skills init [-g] [--openspec-init] [--force]
-      安装 comate 及依赖 (OpenSpec CLI、Superpowers)。已装的自动跳过，可重复执行。
-      项目安装装到当前目录，执行前会打印完整路径并确认这像个项目目录。
-        -g, --global      安装到用户全局目录 (默认: 当前项目)
-        --openspec-init   同时运行 openspec init 创建项目结构
-        -f, --force       跳过目录检查，就装在当前目录
-
-  comate-skills [add|list|remove|update ...]
-      直接透传给 skills CLI。不带子命令时安装本包全部 skill。
+  comate init      安装 comate 和依赖到用户级，并在当前项目创建 openspec/
+  comate doctor    健康检查
 
-安装后在 agent 中输入 /comate 开始使用。`);
+装好后在 agent 中输入 /comate 开始使用。`);
   process.exit(0);
 }
 

package/bin/doctor.mjs

@@ -0,0 +1,71 @@
+// `comate doctor` — run the installed comate.sh health check.
+//
+// ponytail: comate.sh already implements every check. This only locates the
+// installed copy so the user doesn't have to remember the path.
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
+
+// Where the skills CLI puts things. `init` installs user-level, but a project
+// copy shadows it for the agent, so check cwd first and report on the same one
+// the agent would load.
+function skillRoots() {
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+  const dirs = ['.agents/skills', '.claude/skills', '.cursor/skills', '.codex/skills'];
+  return [...dirs.map((d) => join(process.cwd(), d)), ...dirs.map((d) => join(home, d))];
+}
+
+export function findComateScript(roots = skillRoots()) {
+  for (const root of roots) {
+    const script = join(root, 'comate', 'scripts', 'comate.sh');
+    if (existsSync(script)) return script;
+  }
+  return null;
+}
+
+// On Windows, bare `bash` usually resolves to System32\bash.exe — the WSL
+// launcher, which cannot open `D:\...` paths (it eats the backslashes and
+// reports "No such file or directory"). Find Git's bash instead, next to the
+// git.exe already on PATH, then the standard install dirs.
+export function findBash(env = process.env, exists = existsSync) {
+  if (process.platform !== 'win32') return 'bash';
+
+  const gitDirs = (env.PATH ?? env.Path ?? '').split(delimiter).filter(Boolean);
+  const candidates = [
+    // <git>/cmd/git.exe or <git>/mingw64/bin/git.exe -> <git>/bin/bash.exe
+    ...gitDirs.flatMap((d) =>
+      exists(join(d, 'git.exe')) ? [resolve(d, '..', 'bin', 'bash.exe'), resolve(d, '..', '..', 'bin', 'bash.exe')] : [],
+    ),
+    join(env.ProgramFiles ?? 'C:\\Program Files', 'Git', 'bin', 'bash.exe'),
+    join(env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Git', 'bin', 'bash.exe'),
+    join(env.LOCALAPPDATA ?? '', 'Programs', 'Git', 'bin', 'bash.exe'),
+  ];
+  return candidates.find(exists) ?? null;
+}
+
+export function doctor(argv) {
+  const script = findComateScript();
+  if (!script) {
+    console.error('找不到已安装的 comate。先运行: comate init');
+    return 1;
+  }
+
+  const bash = findBash();
+  if (!bash) {
+    console.error('找不到 bash — comate 的脚本需要 bash。请安装 Git for Windows。');
+    return 1;
+  }
+
+  // comate.sh resolves sibling skills relative to the skills root, so run it
+  // from there rather than from wherever the user happens to be.
+  const skillsRoot = join(script, '..', '..', '..');
+  const { status, error } = spawnSync(bash, [script, 'doctor', ...argv], {
+    cwd: skillsRoot,
+    stdio: 'inherit',
+  });
+  if (error) {
+    console.error(`无法执行 bash (${bash}) — comate 的脚本需要 bash。${error.message}`);
+    return 1;
+  }
+  return status ?? 1;
+}

package/bin/init-run.mjs

@@ -1,4 +1,4 @@
-// The `init` flow: pick a scope, then install what's missing.
+// The `init` flow: install whatever the current project is missing.
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
@@ -13,16 +13,12 @@ import {
   superpowersInstalled,
 } from './init.mjs';
 
-// Same convention as the bare `comate-skills` command: no flag means project,
-// -g means global. No prompt — the flag already says it.
-export function resolveScope(argv) {
-  return argv.includes('-g') || argv.includes('--global') ? 'global' : 'project';
-}
-
-// A project install lands in cwd, and `npx` runs wherever the user happens to
-// be — so cwd is a guess, not a decision. Report it, and refuse the two cases
-// that are almost certainly a mistake: the home directory (that's what -g is
-// for) and a directory with no project marker at all.
+// `comate init` — no flags. Skills go user-level (~/.agents/skills), matching how
+// the CLI itself is installed (npm i -g): one copy, every project sees it.
+//
+// openspec/ is still per-project — it holds the project's own specs — so cwd
+// must be a project. Refuse the two cases that are almost certainly a mistake:
+// the home directory, and a directory with no project marker at all.
 const PROJECT_MARKERS = [
   '.git',
   'package.json',
@@ -44,44 +40,25 @@ export function inspectTarget(dir, home) {
   return marker ? { kind: 'project', marker } : { kind: 'bare' };
 }
 
-export async function init(pkgRoot, argv) {
-  const scope = resolveScope(argv);
-  const withOpenSpecInit = argv.includes('--openspec-init');
-  const force = argv.includes('-f') || argv.includes('--force');
+export async function init(pkgRoot) {
   const results = [];
-
   const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
-  if (scope === 'global') {
-    console.log(`\n安装范围: 全局 -> ${join(home, '.agents', 'skills')}\n`);
-  } else {
-    const cwd = process.cwd();
-    const target = inspectTarget(cwd, home);
-    console.log(`\n安装范围: 项目 -> ${join(cwd, '.agents', 'skills')}`);
-
-    if (target.kind === 'home' && !force) {
-      console.error(`
-这是你的用户主目录。装到这里通常不是你想要的——想让所有项目都能用，请加 -g：
-
-  comate-skills init -g
-
-确实要装在这里，加 --force。`);
-      return 1;
-    }
-    if (target.kind === 'bare' && !force) {
-      console.error(`
-当前目录看不出是个项目（没有 .git / package.json / pyproject.toml 等标志）。
-comate 会把 skill 装进上面这个路径，先确认这是你要的目录：
-
-  cd <你的项目目录> && npx @house365/comate init   # 换个目录
-  npx @house365/comate init -g                     # 装到全局，所有项目可用
-  npx @house365/comate init --force                # 就装在这里`);
-      return 1;
-    }
-    if (target.kind === 'project') console.log(`检测到项目标志: ${target.marker}`);
-    console.log('');
+  const cwd = process.cwd();
+
+  const target = inspectTarget(cwd, home);
+  if (target.kind !== 'project') {
+    console.error(
+      target.kind === 'home'
+        ? '\n这是主目录，请在项目目录下运行 comate init。'
+        : '\n当前目录不像项目（无 .git / package.json 等），请在项目目录下运行 comate init。',
+    );
+    return 1;
   }
 
-  // 1. OpenSpec CLI — a PATH command, so global regardless of skill scope.
+  console.log(`\nskills 装到 ${join(home, '.agents', 'skills')}（用户级，所有项目共用）`);
+  console.log(`openspec/ 建在 ${cwd}\n`);
+
+  // 1. OpenSpec CLI — a PATH command, so always global.
   const os = openSpecState();
   if (os.status === 'ready') {
     results.push(['OpenSpec CLI', 'skipped', `已安装 ${os.version}`]);
@@ -100,13 +77,13 @@ comate 会把 skill 装进上面这个路径，先确认这是你要的目录：
     }
   }
 
-  // 2. Superpowers — the skills CLI detects the agent itself.
-  if (superpowersInstalled(scope)) {
+  // 2. Superpowers — the skills CLI detects the agent itself. A pre-existing
+  // project-level copy also counts: reinstalling globally would just shadow it.
+  if (superpowersInstalled('global') || superpowersInstalled('project')) {
     results.push(['Superpowers', 'skipped', '已安装']);
   } else {
-    console.log('\n→ 安装 Superpowers (skills add obra/superpowers)');
-    const args = ['add', 'obra/superpowers', '-y', ...(scope === 'global' ? ['-g'] : [])];
-    const r = run(skillsInvocation(pkgRoot, args), SKILLS_TIMEOUT_MS);
+    console.log('\n→ 安装 Superpowers (skills add obra/superpowers -g)');
+    const r = run(skillsInvocation(pkgRoot, ['add', 'obra/superpowers', '-g', '-y']), SKILLS_TIMEOUT_MS);
     // It clones from GitHub, so a bare exit code hides the usual cause: no
     // network. Say so rather than leaving the user with "exit code 1".
     const note = r.ok
@@ -117,41 +94,39 @@ comate 会把 skill 装进上面这个路径，先确认这是你要的目录：
 
   // 3. comate itself.
   console.log('\n→ 安装 comate skills');
-  const comateArgs = ['add', pkgRoot, '--skill', '*', '-y', ...(scope === 'global' ? ['-g'] : [])];
+  const comateArgs = ['add', pkgRoot, '--skill', '*', '-g', '-y'];
   const r = run(skillsInvocation(pkgRoot, comateArgs), SKILLS_TIMEOUT_MS);
   results.push(['comate', r.ok ? 'installed' : 'failed', r.ok ? '' : r.reason]);
 
-  // 4. openspec init — opt-in: it writes openspec/ into the user's project and
-  // edits agent config files, a bigger side effect than the installs above.
-  if (withOpenSpecInit) {
-    console.log('\n→ 初始化 OpenSpec 项目结构 (openspec init)');
-    const r2 = run({ command: 'openspec', args: ['init', '.'], shell: process.platform === 'win32' }, NPM_TIMEOUT_MS);
-    results.push(['openspec init', r2.ok ? 'installed' : 'failed', r2.ok ? '' : r2.reason]);
-  } else if (!existsSync('openspec')) {
-    results.push(['openspec init', 'skipped', '未初始化项目结构，需要时加 --openspec-init']);
+  // 4. openspec/ project structure. Not optional: comate's open and archive
+  // phases read it, so an install without it cannot actually run. An existing
+  // one is left alone, which covers projects that already keep it elsewhere.
+  if (existsSync('openspec')) {
+    results.push(['openspec 结构', 'skipped', '已存在']);
+  } else {
+    console.log('\n→ 初始化 openspec/ 项目结构');
+    const r2 = run(
+      { command: 'openspec', args: ['init', '.'], shell: process.platform === 'win32' },
+      NPM_TIMEOUT_MS,
+    );
+    results.push(['openspec 结构', r2.ok ? 'installed' : 'failed', r2.ok ? '' : r2.reason]);
   }
 
-  return report(results, scope);
+  return report(results);
 }
 
-function report(results, scope) {
+function report(results) {
   const mark = { installed: '✓', skipped: '·', failed: '✗' };
-  console.log('\n' + '─'.repeat(58));
+  console.log('');
   for (const [name, status, note] of results) {
-    console.log(`  ${mark[status]} ${name.padEnd(16)} ${status.padEnd(10)} ${note}`);
+    console.log(`  ${mark[status]} ${name.padEnd(14)}${note}`);
   }
-  console.log('─'.repeat(58));
 
   const failed = results.filter(([, s]) => s === 'failed');
   if (failed.length > 0) {
-    console.error(`\n${failed.length} 项失败。修复后可重跑 comate-skills init（已安装的会自动跳过）。`);
+    console.error(`\n${failed.length} 项失败，修好后重跑 comate init。`);
     return 1;
   }
-  // Absolute path: the user should not have to work out which directory this
-  // landed in, which is the whole problem with a cwd-relative install.
-  const root = scope === 'global' ? (process.env.HOME ?? process.env.USERPROFILE ?? '~') : process.cwd();
-  const doctorPath = join(root, '.agents', 'skills', 'comate', 'scripts', 'comate.sh');
-  console.log(`\n完成。健康检查: bash "${doctorPath}" doctor`);
-  console.log('在 agent 中输入 /comate 开始使用。');
+  console.log('\n完成。在 agent 中输入 /comate 开始使用，或跑 comate doctor 自检。');
   return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "comate —— OpenSpec + Superpowers 规约驱动的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",
@@ -9,6 +9,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "bin": {
+    "comate": "bin/cli.mjs",
     "comate-skills": "bin/cli.mjs"
   },
   "files": [