@house365/comate 0.10.2 → 1.0.2-next.0

package/bin/cli.mjs

@@ -1,191 +1,198 @@
 #!/usr/bin/env node
-// comate CLI. Two jobs:
-//   init  — install comate + its prerequisites (OpenSpec CLI, Superpowers)
-//   *     — everything else is forwarded to the `skills` CLI, which already
-//           handles agent detection, symlinking, update/remove for 70+ agents.
-import { fileURLToPath } from 'node:url';
-import { dirname } from 'node:path';
-import { readFileSync } from 'node:fs';
-import { get } from 'node:https';
-
-import { run, skillsInvocation, SKILLS_TIMEOUT_MS, atLeast } from './init.mjs';
-
-// Check npm registry for the latest version and notify if an update is available.
-async function checkForUpdates(currentVersion) {
-  // Escape hatch: skip the network round-trip entirely. Keeps `--version`
-  // deterministic and offline-safe in tests and CI.
-  if (process.env.COMATE_NO_UPDATE_CHECK) return;
-  return new Promise((resolve) => {
-    const req = get('https://registry.npmjs.org/@house365/comate/latest', { timeout: 3000 }, (res) => {
-      if (res.statusCode !== 200) {
-        resolve();
-        return;
-      }
-      let data = '';
-      res.on('data', (chunk) => { data += chunk; });
-      res.on('end', () => {
-        try {
-          const pkg = JSON.parse(data);
-          const latestVersion = pkg.version;
-          // Notify only when the registry is strictly newer. A plain `!==` also
-          // fired when local was ahead of the registry (e.g. mid-release, before
-          // publish lands), printing a bogus "update available" for an older
-          // version and polluting `--version` stdout.
-          if (latestVersion && atLeast(latestVersion, currentVersion) && latestVersion !== currentVersion) {
-            console.log('');
-            console.log(`\x1b[33m🔔 有新版本可用：${latestVersion} (当前版本：${currentVersion})\x1b[0m`);
-            console.log(`\x1b[36m更新命令：npm install -g @house365/comate@latest\x1b[0m`);
-            console.log('');
-          }
-        } catch {
-          // Ignore parse errors
-        }
-        resolve();
-      });
-    });
-    req.on('error', () => resolve());
-    req.on('timeout', () => {
-      req.destroy();
-      resolve();
-    });
-  });
-}
-
-// comate 自身的子命令（在下方被先取处理，不会透传给 skills CLI）。
-const COMATE_COMMANDS = ['init', 'doctor', 'update', 'usage', 'cleanup'];
-
-// 允许透传给 skills CLI 的子命令（含别名）。留在这里的都是 skills CLI 真实存在
-// 的命令，未列入的一律视为未知命令并命中 --help。init/update 已被 comate 先取，
-// 故不在此列。
-const SKILLS_PASSTHROUGH = new Set([
-  'add', 'a',
-  'use',
-  'remove', 'rm',
-  'list', 'ls',
-  'find',
-  'upgrade',
-  'experimental_install',
-  'experimental_sync',
-]);
-
-// Flags accepted on a bare `comate [flags]` invocation — these forward to the
-// implicit `skills add`. Anything else starting with `-` is a typo (e.g.
-// `--vasdasd`) and must hit help instead of silently installing everything.
-// --version/-v and --help/-h are intercepted earlier, so they need not be here.
-const ADD_FLAGS = new Set([
-  '-g', '--global',
-  '-a', '--agent',
-  '-s', '--skill',
-  '-l', '--list',
-  '-y', '--yes',
-  '--copy',
-  '--metadata',
-  '--subagent',
-  '--all',
-  '--full-depth',
-]);
-
-const HELP_TEXT = `comate — SDD (规约驱动开发) 的 AI 开发编排器
-
-用法:
-  comate                安装/更新本包全部 comate skill 到当前 agent
-  comate init           安装 comate 和依赖到用户级，并在当前项目创建 openspec/
-  comate doctor         健康检查
-  comate update         更新 comate 到最新版本
-  comate usage          查看本项目 token 用量（--global 看全部；参数透传给 ccusage）
-  comate cleanup        清理重复的 superpowers 安装（当 plugin 版本已存在时）
-  comate --help, -h     显示本帮助
-  comate --version, -v  显示版本号
-
-管理 skill（透传给 skills CLI）:
-  comate add <包>       添加 skill 包
-  comate remove [名]    移除已装 skill（别名 rm）
-  comate list           列出已装 skill（别名 ls）
-  comate find [关键词]  搜索 skill
-
-装好后在 agent 中输入 /comate 开始使用。`;
-
-function printHelp(stream = console.log) {
-  stream(HELP_TEXT);
-}
-
-const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const args = process.argv.slice(2);
-const packageVersion = JSON.parse(readFileSync(`${pkgRoot}/package.json`, 'utf8')).version;
-
-if (args[0] === '--version' || args[0] === '-v') {
-  console.log(packageVersion);
-  // Await the check: without it, process.exit(0) fires synchronously and the
-  // process dies before the registry request resolves, so the update notice
-  // never prints. The check has its own 3s timeout, so a dead network stalls
-  // this by at most 3s.
-  await checkForUpdates(packageVersion).catch(() => {
-    // Silently ignore network errors
-  });
-  process.exit(0);
-}
-
-if (args[0] === 'init') {
-  const { init } = await import('./init-run.mjs');
-  process.exit(await init(pkgRoot));
-}
-
-if (args[0] === 'doctor') {
-  const { doctor } = await import('./doctor.mjs');
-  process.exit(doctor(args.slice(1)));
-}
-
-if (args[0] === 'update') {
-  const { update } = await import('./update.mjs');
-  process.exit(await update(packageVersion));
-}
-
-if (args[0] === 'usage') {
-  const { usage } = await import('./usage.mjs');
-  process.exit(await usage(args.slice(1), { pkgRoot }));
-}
-
-if (args[0] === 'cleanup') {
-  const { cleanup } = await import('./cleanup-duplicate-superpowers.mjs');
-  process.exit(cleanup());
-}
-
-if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
-  printHelp();
-  process.exit(0);
-}
-
-// A leading token that is neither a flag, a comate command, nor a known skills
-// passthrough command is an unknown command. Print help to stderr and exit 1 so
-// typos surface as usage guidance instead of an opaque skills CLI error.
-if (args.length && !args[0].startsWith('-')) {
-  const cmd = args[0];
-  if (!COMATE_COMMANDS.includes(cmd) && !SKILLS_PASSTHROUGH.has(cmd)) {
-    console.error(`comate: 未知命令 '${cmd}'\n`);
-    printHelp(console.error);
-    process.exit(1);
-  }
-} else if (args[0]?.startsWith('-')) {
-  // Bare-flags mode: every arg is forwarded to the implicit `skills add`. Any
-  // dash-prefixed arg that isn't a known install flag is a typo (e.g.
-  // --vasdasd). Without this it fell through and silently installed everything.
-  // Flag values (e.g. `-a claude-code`) don't start with `-`, so they're safe.
-  const bad = args.find((a) => a.startsWith('-') && !ADD_FLAGS.has(a));
-  if (bad) {
-    console.error(`comate: 未知选项 '${bad}'\n`);
-    printHelp(console.error);
-    process.exit(1);
-  }
-}
-
-// No args, or only flags (-g, --list, …) = install every comate skill from this
-// package, forwarding the flags. A leading passthrough subcommand goes straight
-// through, so add/remove/list all still work.
-const argv =
-  args.length && !args[0].startsWith('-') ? args : ['add', pkgRoot, '--skill', '*', ...args];
-
-const result = run(skillsInvocation(pkgRoot, argv), SKILLS_TIMEOUT_MS);
-if (!result.ok) {
-  console.error(`comate: skills CLI 执行失败 — ${result.reason}`);
-  process.exit(1);
-}
+// comate CLI. Three jobs:
+//   init            — install the comate skill and lay down the comate/ scaffold
+//   status / doctor / import-specs
+//                   — forwarded to the installed skill's scripts/comate.mjs, so
+//                     the CLI never carries a second copy of the state machine
+//   *               — everything else is forwarded to the `skills` CLI, which
+//                     handles agent detection, symlinking, update/remove.
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { get } from 'node:https';
+
+import { run, skillsInvocation, SKILLS_TIMEOUT_MS, atLeast } from './init.mjs';
+
+// Check npm registry for the latest version and notify if an update is available.
+async function checkForUpdates(currentVersion) {
+  // Escape hatch: skip the network round-trip entirely. Keeps `--version`
+  // deterministic and offline-safe in tests and CI.
+  if (process.env.COMATE_NO_UPDATE_CHECK) return;
+  return new Promise((resolve) => {
+    const req = get('https://registry.npmjs.org/@house365/comate/latest', { timeout: 3000 }, (res) => {
+      if (res.statusCode !== 200) {
+        resolve();
+        return;
+      }
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          const pkg = JSON.parse(data);
+          const latestVersion = pkg.version;
+          // Notify only when the registry is strictly newer. A plain `!==` also
+          // fired when local was ahead of the registry (e.g. mid-release, before
+          // publish lands), printing a bogus "update available" for an older
+          // version and polluting `--version` stdout.
+          if (latestVersion && atLeast(latestVersion, currentVersion) && latestVersion !== currentVersion) {
+            console.log('');
+            console.log(`\x1b[33m🔔 有新版本可用：${latestVersion} (当前版本：${currentVersion})\x1b[0m`);
+            console.log(`\x1b[36m更新命令：npm install -g @house365/comate@latest\x1b[0m`);
+            console.log('');
+          }
+        } catch {
+          // Ignore parse errors
+        }
+        resolve();
+      });
+    });
+    req.on('error', () => resolve());
+    req.on('timeout', () => {
+      req.destroy();
+      resolve();
+    });
+  });
+}
+
+// comate 自身的子命令（在下方被先取处理，不会透传给 skills CLI）。
+const COMATE_COMMANDS = ['init', 'doctor', 'status', 'import-specs', 'update', 'usage'];
+
+// 允许透传给 skills CLI 的子命令（含别名）。留在这里的都是 skills CLI 真实存在
+// 的命令，未列入的一律视为未知命令并命中 --help。init/update 已被 comate 先取，
+// 故不在此列。
+const SKILLS_PASSTHROUGH = new Set([
+  'add', 'a',
+  'use',
+  'remove', 'rm',
+  'list', 'ls',
+  'find',
+  'upgrade',
+  'experimental_install',
+  'experimental_sync',
+]);
+
+// Flags accepted on a bare `comate [flags]` invocation — these forward to the
+// implicit `skills add`. Anything else starting with `-` is a typo (e.g.
+// `--vasdasd`) and must hit help instead of silently installing everything.
+// --version/-v and --help/-h are intercepted earlier, so they need not be here.
+const ADD_FLAGS = new Set([
+  '-g', '--global',
+  '-a', '--agent',
+  '-s', '--skill',
+  '-l', '--list',
+  '-y', '--yes',
+  '--copy',
+  '--metadata',
+  '--subagent',
+  '--all',
+  '--full-depth',
+]);
+
+const HELP_TEXT = `comate — SDD (规约驱动开发) 的 AI 开发编排器
+
+用法:
+  comate                安装/更新本包全部 comate skill 到当前 agent
+  comate init           安装 comate skill 到用户级，并在当前项目创建 comate/
+  comate init --migrate [--dry-run]
+                        把 0.x 的 docs/knowledge-base、docs/architecture 移到 comate/
+  comate import-specs [--dry-run]
+                        把 openspec/specs 主规格导入 comate/comate/specs
+  comate status [名]    查看当前项目的 change 与下一步
+  comate doctor         健康检查
+  comate update         更新 comate 到最新版本
+  comate usage          查看本项目 token 用量（--global 看全部；参数透传给 ccusage）
+  comate --help, -h     显示本帮助
+  comate --version, -v  显示版本号
+
+管理 skill（透传给 skills CLI）:
+  comate add <包>       添加 skill 包
+  comate remove [名]    移除已装 skill（别名 rm）
+  comate list           列出已装 skill（别名 ls）
+  comate find [关键词]  搜索 skill
+
+装好后在 agent 中输入 /comate 开始使用。`;
+
+function printHelp(stream = console.log) {
+  stream(HELP_TEXT);
+}
+
+const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const args = process.argv.slice(2);
+const packageVersion = JSON.parse(readFileSync(`${pkgRoot}/package.json`, 'utf8')).version;
+
+if (args[0] === '--version' || args[0] === '-v') {
+  console.log(packageVersion);
+  // Await the check: without it, process.exit(0) fires synchronously and the
+  // process dies before the registry request resolves, so the update notice
+  // never prints. The check has its own 3s timeout, so a dead network stalls
+  // this by at most 3s.
+  await checkForUpdates(packageVersion).catch(() => {
+    // Silently ignore network errors
+  });
+  process.exit(0);
+}
+
+if (args[0] === 'init') {
+  const { init } = await import('./init-run.mjs');
+  process.exit(await init(pkgRoot, args.slice(1)));
+}
+
+if (args[0] === 'doctor') {
+  const { doctor } = await import('./doctor.mjs');
+  process.exit(doctor(args.slice(1)));
+}
+
+if (args[0] === 'status' || args[0] === 'import-specs') {
+  const { forward } = await import('./doctor.mjs');
+  process.exit(forward(args[0], args.slice(1)));
+}
+
+if (args[0] === 'update') {
+  const { update } = await import('./update.mjs');
+  process.exit(await update(packageVersion));
+}
+
+if (args[0] === 'usage') {
+  const { usage } = await import('./usage.mjs');
+  process.exit(await usage(args.slice(1), { pkgRoot }));
+}
+
+if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+  printHelp();
+  process.exit(0);
+}
+
+// A leading token that is neither a flag, a comate command, nor a known skills
+// passthrough command is an unknown command. Print help to stderr and exit 1 so
+// typos surface as usage guidance instead of an opaque skills CLI error.
+if (args.length && !args[0].startsWith('-')) {
+  const cmd = args[0];
+  if (!COMATE_COMMANDS.includes(cmd) && !SKILLS_PASSTHROUGH.has(cmd)) {
+    console.error(`comate: 未知命令 '${cmd}'\n`);
+    printHelp(console.error);
+    process.exit(1);
+  }
+} else if (args[0]?.startsWith('-')) {
+  // Bare-flags mode: every arg is forwarded to the implicit `skills add`. Any
+  // dash-prefixed arg that isn't a known install flag is a typo (e.g.
+  // --vasdasd). Without this it fell through and silently installed everything.
+  // Flag values (e.g. `-a claude-code`) don't start with `-`, so they're safe.
+  const bad = args.find((a) => a.startsWith('-') && !ADD_FLAGS.has(a));
+  if (bad) {
+    console.error(`comate: 未知选项 '${bad}'\n`);
+    printHelp(console.error);
+    process.exit(1);
+  }
+}
+
+// No args, or only flags (-g, --list, …) = install every comate skill from this
+// package, forwarding the flags. A leading passthrough subcommand goes straight
+// through, so add/remove/list all still work.
+const argv =
+  args.length && !args[0].startsWith('-') ? args : ['add', pkgRoot, '--skill', '*', ...args];
+
+const result = run(skillsInvocation(pkgRoot, argv), SKILLS_TIMEOUT_MS);
+if (!result.ok) {
+  console.error(`comate: skills CLI 执行失败 — ${result.reason}`);
+  process.exit(1);
+}

package/bin/doctor.mjs

@@ -1,11 +1,11 @@
-// `comate doctor` — run the installed comate.sh health check.
+// `comate doctor` — run the installed comate.mjs 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.
+// comate.mjs already implements every check. This only locates the installed
+// copy (the one the agent would load) so the user doesn't need the path.
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { delimiter, dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { atLeast, capture, npmInvocation } from './init.mjs';
@@ -21,60 +21,48 @@ function skillRoots() {
 
 export function findComateScript(roots = skillRoots()) {
   for (const root of roots) {
-    const script = join(root, 'comate', 'scripts', 'comate.sh');
+    const script = join(root, 'comate', 'scripts', 'comate.mjs');
     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;
-}
+// Installed copy first (the one the agent loads); the package's own copy only
+// when nothing is installed yet, so `comate status` still works right after npm i.
+const scriptOrBundled = () => findComateScript() ?? [join(defaultPkgRoot(), 'skills', 'comate', 'scripts', 'comate.mjs')].find(existsSync) ?? null;
 
-export function doctor(argv) {
-  const script = findComateScript();
+// `comate status` / `comate import-specs`: run the same state machine the agent uses.
+export function forward(command, argv) {
+  const script = scriptOrBundled();
   if (!script) {
-    console.error('找不到已安装的 comate。先运行: comate init');
+    console.error('找不到 comate 脚本。先运行: comate init');
+    return 1;
+  }
+  const { status, error } = spawnSync(process.execPath, [script, command, ...argv], { stdio: 'inherit' });
+  if (error) {
+    console.error(`无法执行 ${script}：${error.message}`);
     return 1;
   }
+  return status ?? 1;
+}
 
-  const bash = findBash();
-  if (!bash) {
-    console.error('找不到 bash — comate 的脚本需要 bash。请安装 Git for Windows。');
+export function doctor(argv) {
+  const script = scriptOrBundled();
+  if (!script) {
+    console.error('找不到已安装的 comate。先运行: comate init');
     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',
-  });
+  // Same node that runs this CLI — no shell, no bash, works the same on Windows.
+  const { status, error } = spawnSync(process.execPath, [script, 'doctor', ...argv], { stdio: 'inherit' });
   if (error) {
-    console.error(`无法执行 bash (${bash}) — comate 的脚本需要 bash。${error.message}`);
+    console.error(`无法执行 ${script}：${error.message}`);
     return 1;
   }
 
-  // ccusage is a node dependency (for `comate usage`), not a bash-side tool, so
-  // it lives here rather than in comate.sh's doctor. A miss is a warning, never
-  // a failure: usage falls back to `npx ccusage@latest`, so it still works.
+  // ccusage is a dependency of the npm CLI (for `comate usage`), not of the
+  // skill script, so it is checked here. A miss is a warning, never a
+  // failure: usage falls back to `npx ccusage@latest`, so it still works.
   reportCcusage();
 
   // Version check is the only place a user learns a newer comate exists: the