@house365/comate 0.9.19 → 0.9.22

package/bin/cli.mjs

@@ -8,10 +8,13 @@ import { dirname } from 'node:path';
 import { readFileSync } from 'node:fs';
 import { get } from 'node:https';
 
-import { run, skillsInvocation, SKILLS_TIMEOUT_MS } from './init.mjs';
+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) {
@@ -24,7 +27,11 @@ async function checkForUpdates(currentVersion) {
         try {
           const pkg = JSON.parse(data);
           const latestVersion = pkg.version;
-          if (latestVersion && latestVersion !== currentVersion) {
+          // 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`);
@@ -44,14 +51,57 @@ async function checkForUpdates(currentVersion) {
   });
 }
 
+// comate 自身的子命令（在下方被先取处理，不会透传给 skills CLI）。
+const COMATE_COMMANDS = ['init', 'doctor', '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',
+]);
+
+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 --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);
-  // Check for updates in the background, non-blocking
-  checkForUpdates(packageVersion).catch(() => {
+  // 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);
@@ -77,22 +127,26 @@ if (args[0] === 'usage') {
   process.exit(await usage(args.slice(1), { pkgRoot }));
 }
 
-if (args[0] === '--help' || args[0] === '-h') {
-  console.log(`comate — SDD (规约驱动开发) 的 AI 开发编排器
-
-用法:
-  comate init      安装 comate 和依赖到用户级，并在当前项目创建 openspec/
-  comate doctor    健康检查
-  comate update    更新 comate 到最新版本
-  comate usage     查看本项目 token 用量（--global 看全部；参数透传给 ccusage）
-
-装好后在 agent 中输入 /comate 开始使用。`);
+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);
+  }
+}
+
 // No args, or only flags (-g, --list, …) = install every comate skill from this
-// package, forwarding the flags. A leading subcommand passes straight through,
-// so remove/list/update all still work.
+// 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];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.9.19",
+  "version": "0.9.22",
   "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",