@house365/comate 0.10.2 → 1.0.2-next.0

package/bin/init-run.mjs

@@ -1,368 +1,310 @@
-// The `init` flow: install whatever the current project is missing.
-import { spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { createInterface } from 'node:readline';
-
-import { findBash } from './doctor.mjs';
-import {
-  NPM_TIMEOUT_MS,
-  capture,
-  SKILLS_TIMEOUT_MS,
-  npmInvocation,
-  openSpecState,
-  pruneDeprecatedSkills,
-  run,
-  scaffoldDocs,
-  skillsInvocation,
-  superpowersInstalled,
-  userSkillsRoot,
-} from './init.mjs';
-
-// `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',
-  'pyproject.toml',
-  'Cargo.toml',
-  'go.mod',
-  'pom.xml',
-  'build.gradle',
-  'composer.json',
-  'Gemfile',
-  'openspec',
-  '.agents',
-];
-
-export function inspectTarget(dir, home) {
-  const normalise = (p) => resolve(p).replace(/[\\/]+$/, '').toLowerCase();
-  if (home && normalise(dir) === normalise(home)) return { kind: 'home' };
-  const marker = PROJECT_MARKERS.find((m) => existsSync(join(dir, m)));
-  return marker ? { kind: 'project', marker } : { kind: 'bare' };
-}
-
-export async function init(pkgRoot) {
-  const results = [];
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
-  const cwd = process.cwd();
-
-  const target = inspectTarget(cwd, home);
-  if (target.kind !== 'project') {
-    // Home directory is always refused
-    if (target.kind === 'home') {
-      console.error('\n这是主目录，请在项目目录下运行 comate init。');
-      return 1;
-    }
-
-    // Bare directory: ask user if they want to create a project here
-    console.log('\n当前目录不像项目（无 .git / package.json 等）。');
-    const confirmed = await askConfirm('要在这里初始化新项目吗？');
-    if (!confirmed) {
-      console.log('已取消。');
-      return 1;
-    }
-  }
-
-  // comate's scripts intentionally support macOS's system Bash 3.2. Fail only
-  // when Bash is older than the syntax the state machine supports.
-  const bash = bashVersion();
-  if (bash !== null && bash < 3) {
-    console.error(
-      `\ncomate 的脚本需要 bash >= 3.2，当前 ${bash === 0 ? '未知版本' : `bash ${bash}.x`}。\n` +
-        '请安装 Bash 3.2 或更高版本后重跑 comate init。',
-    );
-    return 3;
-  }
-
-  const stopSpinner = startSpinner('Initializing…');
-
-  // 1. OpenSpec CLI — a PATH command, so always global.
-  const os = openSpecState();
-  if (os.status === 'ready') {
-    results.push(['OpenSpec CLI', 'skipped', `已安装 ${os.version}`]);
-  } else {
-    const r = run(
-      npmInvocation(['install', '-g', '@fission-ai/openspec@latest']),
-      NPM_TIMEOUT_MS,
-      { quiet: true },
-    );
-    if (!r.ok) {
-      // An outdated-but-usable CLI is better than a hard failure.
-      const usable = os.status === 'outdated';
-      const note = usable ? `升级失败，沿用 ${os.version}` : r.reason;
-      results.push(['OpenSpec CLI', usable ? 'skipped' : 'failed', note, usable ? '' : r.output]);
-    } else if (openSpecState().status === 'missing') {
-      results.push(['OpenSpec CLI', 'failed', 'npm 安装完成但 PATH 中仍找不到 openspec，请重启终端']);
-    } else {
-      results.push(['OpenSpec CLI', 'installed', '']);
-    }
-  }
-
-  // 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 {
-    const r = run(
-      skillsInvocation(pkgRoot, ['add', 'obra/superpowers', '-g', '-y']),
-      SKILLS_TIMEOUT_MS,
-      { quiet: true },
-    );
-    // 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
-      ? ''
-      : `${r.reason} — 需要访问 github.com，检查网络/代理后重试`;
-    results.push(['Superpowers', r.ok ? 'installed' : 'failed', note, r.output]);
-  }
-
-  // 3. comate itself. The skills CLI reports per-agent failures without ever
-  // setting a non-zero exit code, and we swallow its output — so a zero status
-  // is not evidence the skill landed. Check the file.
-  const comateArgs = ['add', pkgRoot, '--skill', '*', '-g', '-y'];
-  const r = run(skillsInvocation(pkgRoot, comateArgs), SKILLS_TIMEOUT_MS, { quiet: true });
-  const landed = existsSync(join(home, '.agents', 'skills', 'comate', 'SKILL.md'));
-  if (r.ok && !landed) {
-    results.push(['comate', 'failed', `未装到 ${join(home, '.agents', 'skills')}`]);
-  } else {
-    results.push(['comate', r.ok ? 'installed' : 'failed', r.ok ? '' : r.reason, r.output]);
-  }
-
-  // Prune comate skill dirs renamed/dropped in past releases. `skills add` above
-  // only adds/overwrites, so /comate-hotfix etc. would otherwise linger as dead
-  // slash commands. The postinstall hook does this too, but --ignore-scripts
-  // users never run it — init is their only path, so it must clean up here.
-  const pruned = pruneDeprecatedSkills(userSkillsRoot(home));
-  if (pruned.length) results.push(['清理废弃 skill', 'installed', pruned.join('、')]);
-
-  // 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 {
-    // --tools is not optional in practice: openspec derives the tool list by
-    // sniffing existing agent config dirs, so a fresh project (no .claude etc.)
-    // aborts with "No tools detected and no --tools flag provided". comate's
-    // skills are agent-agnostic and only openspec/ itself matters here, so ask
-    // for none rather than guessing which agents the user wants wired up.
-    const r2 = run(
-      {
-        command: 'openspec',
-        args: ['init', '.', '--tools', 'none'],
-        shell: process.platform === 'win32',
-      },
-      NPM_TIMEOUT_MS,
-      { quiet: true },
-    );
-    results.push(['openspec/', r2.ok ? 'installed' : 'failed', r2.ok ? '' : r2.reason, r2.output]);
-  }
-
-  // 5. docs/ knowledge-base scaffold. /comate-gate reads PRDs from
-  // docs/knowledge-base/requirements/ (comate_kb_root is hardcoded there), so a
-  // fresh project has nowhere to put a PRD. Idempotent — existing files are left
-  // alone, only missing pieces are filled in, so re-running never clobbers a
-  // project's real docs. A failure here is non-fatal to the rest of the install.
-  const sc = scaffoldDocs(pkgRoot);
-  if (!sc.ok) {
-    results.push(['docs/', 'failed', sc.reason]);
-  } else if (sc.created === 0) {
-    results.push(['docs/', 'skipped', '已存在']);
-  } else {
-    const note = sc.skipped > 0 ? `新建 ${sc.created} 个文件,保留 ${sc.skipped} 个已有` : '';
-    results.push(['docs/', 'installed', note]);
-  }
-
-  stopSpinner();
-  return report(results);
-}
-
-// A yes/no prompt. Defaults to "no" so a piped/non-interactive run (CI, an
-// unattended npx) never silently scaffolds a project into whatever directory it
-// happened to land in — those callers should point at a real project instead.
-// [y/N]: empty input, EOF (Ctrl-D / closed stdin), or anything but y/yes = no.
-export function askConfirm(question, { input = process.stdin, output = process.stdout } = {}) {
-  if (!input.isTTY) return Promise.resolve(false);
-  const rl = createInterface({ input, output });
-  return new Promise((done) => {
-    rl.question(`${question} [y/N] `, (answer) => {
-      rl.close();
-      done(/^\s*y(es)?\s*$/i.test(answer));
-    });
-  });
-}
-
-// The spinner runs in its own process because every step above is a synchronous
-// spawnSync — an interval on this thread would never fire. In a pipe \r does not
-// overwrite, so animating there would leave every frame on screen; print one
-// static line instead.
-function startSpinner(label) {
-  if (!process.stdout.isTTY) {
-    console.log(`\n${label}`);
-    return () => {};
-  }
-
-  const child = spawn(process.execPath, [join(import.meta.dirname, 'spinner.mjs'), label], {
-    stdio: ['ignore', 'inherit', 'ignore'],
-  });
-  let stopped = false;
-  return () => {
-    if (stopped) return;
-    stopped = true;
-    child.kill();
-    // The parent erases the line, not the child: on Windows SIGTERM is not a
-    // real signal — Node terminates the process outright, so a handler in the
-    // child never runs and its last frame would sit under the logo.
-    process.stdout.write(`\r${' '.repeat(label.length + 6)}\r`);
-  };
-}
-
-// Success is one screen: the wordmark and where things landed. The per-item
-// breakdown only earns its space when something failed, and then it carries the
-// reason — a bare "失败" would leave the user with nowhere to go.
-function report(results) {
-  const failed = results.filter(([, s]) => s === 'failed');
-  if (failed.length > 0) {
-    console.error('\n安装失败\n');
-    for (const [name, status, note, output] of results) {
-      const mark = { installed: '✓', skipped: '·', failed: '✗' }[status];
-      console.error(`  ${mark} ${name.padEnd(14)}${note}`);
-      // The child's own output, indented under the item it belongs to, so a
-      // knock-on failure doesn't look like a second unrelated problem.
-      if (status === 'failed' && output) {
-        for (const line of output.split('\n')) console.error(`      ${line.trim()}`);
-      }
-    }
-    console.error('\n修好后重跑 comate init。');
-    return 1;
-  }
-
-  console.log(banner(pkgVersion()));
-  console.log('  Type /comate in your agent to start, or run comate doctor\n');
-  return 0;
-}
-
-// ponytail: read package.json rather than hardcoding — npm version bumps the
-// file, and a stale literal in the banner is worse than no version at all.
-export function pkgVersion(root = resolve(import.meta.dirname, '..')) {
-  try {
-    return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
-  } catch {
-    return '';
-  }
-}
-
-// Only CI gates the wordmark. Two earlier guards were both wrong and are worth
-// naming so they don't come back:
-//
-//   isTTY — npm's Windows global install resolves `comate` to a comate.ps1
-//   shim, and PowerShell calling node through a .ps1 wrapper takes over stdout,
-//   so isTTY is false in a real terminal — exactly where the logo belongs.
-//
-//   chcp — reports the codepage the child process inherited, which the shim
-//   does not propagate (65001 outside, 936 inside). It also answers the wrong
-//   question: writing to a real Windows console goes through WriteConsoleW,
-//   which converts to UTF-16 and bypasses the codepage entirely.
-export function banner(version, { ci = isCI() } = {}) {
-  const tag = `comate${version ? ` v${version}` : ''}`;
-  const plain = `\n  ${tag} - AI coding almost there!\n`;
-  if (ci) return plain;
-
-  const art = [
-    ' ██████╗ ██████╗ ███╗   ███╗ █████╗ ████████╗███████╗',
-    '██╔════╝██╔═══██╗████╗ ████║██╔══██╗╚══██╔══╝██╔════╝',
-    '██║     ██║   ██║██╔████╔██║███████║   ██║   █████╗  ',
-    '██║     ██║   ██║██║╚██╔╝██║██╔══██║   ██║   ██╔══╝  ',
-    '╚██████╗╚██████╔╝██║ ╚═╝ ██║██║  ██║   ██║   ███████╗',
-    ' ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝',
-  ];
-  // Trailing padding keeps the source rows aligned; strip it so a colour run
-  // doesn't sit behind spaces the terminal may highlight on select.
-  const trim = (line) => line.replace(/\s+$/, '');
-  // Centred under the art, not under the terminal: the wordmark is fixed-width,
-  // so centring against art[0] holds at any window size. Computed rather than
-  // hardcoded because the version string changes length on every release.
-  const tagline = `${tag} - AI coding almost there!`;
-  const indent = ' '.repeat(2 + Math.max(0, Math.round((art[0].length - tagline.length) / 2)));
-  if (process.env.NO_COLOR) {
-    return ['', ...art.map((l) => `  ${trim(l)}`), '', `${indent}${tagline}`, ''].join('\n');
-  }
-
-  // 24-bit SGR. Truecolor is not universal, but the two terminals that matter
-  // here (Windows Terminal, VS Code) both support it, and one that doesn't
-  // degrades to its nearest palette entry rather than breaking.
-  const sgr = ([r, g, b]) => `\x1B[38;2;${r};${g};${b}m`;
-  const RESET = '\x1B[0m';
-
-  // Polished chrome under a cyan→magenta rim light: [face, edge] per row. The
-  // ramp shifts hue rather than dropping brightness — every row stays high
-  // luminance, which is what keeps it reading as lit metal instead of fading
-  // out. An earlier darkening ramp went muddy across the bottom half.
-  const ramp = [
-    [[255, 255, 255], [150, 240, 255]],
-    [[214, 248, 255], [ 56, 214, 255]],
-    [[168, 214, 255], [ 92, 148, 255]],
-    [[186, 160, 255], [148, 100, 255]],
-    [[233, 150, 255], [200,  76, 255]],
-    [[255, 150, 224], [255,  72, 178]],
-  ];
-
-  // Blocks are the lit face, box-drawing pieces are the bevelled edge. Two
-  // shades per row is the whole trick: it gives every glyph a rim, which is
-  // what separates brushed metal from a flat decal.
-  const emboss = (line, [face, edge]) => {
-    let out = '';
-    let cur = null;
-    for (const ch of line) {
-      const want = ch === ' ' ? null : ch === '█' ? face : edge;
-      if (want !== cur) {
-        out += want ? sgr(want) : RESET;
-        cur = want;
-      }
-      out += ch;
-    }
-    return out + RESET;
-  };
-
-  // The tagline picks up the ramp instead of going dim grey: the name in the
-  // white highlight so it stays the thing you read first, the strapline in the
-  // magenta rim so the line closes the gradient the art opened. Dropping \x1B[2m
-  // matters — dim on a saturated colour is what made this read as washed out.
-  const nameLit = `${sgr(ramp[0][0])}${tag}${RESET}`;
-  const strap = `${sgr(ramp[5][1])} - AI coding almost there!${RESET}`;
-
-  return [
-    '',
-    ...art.map((line, i) => `  ${emboss(trim(line), ramp[i])}`),
-    '',
-    `${indent}${nameLit}${strap}`,
-    '',
-  ].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() {
-  return Boolean(process.env.CI || process.env.GITHUB_ACTIONS);
-}
+// The `init` flow: install whatever the current project is missing.
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+
+import {
+  LAYOUT_MOVES,
+  SKILLS_TIMEOUT_MS,
+  capture,
+  migrateLayout,
+  pruneDeprecatedSkills,
+  run,
+  scaffoldComate,
+  skillsInvocation,
+  userSkillsRoot,
+} from './init.mjs';
+
+// `comate init [--migrate [--dry-run]]`. Skills go user-level (~/.agents/skills),
+// matching how the CLI itself is installed (npm i -g): one copy, every project
+// sees it.
+//
+// comate/ is per-project — it holds the project's own specs and changes — 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',
+  'pyproject.toml',
+  'Cargo.toml',
+  'go.mod',
+  'pom.xml',
+  'build.gradle',
+  'composer.json',
+  'Gemfile',
+  'openspec',
+  '.agents',
+];
+
+export function inspectTarget(dir, home) {
+  const normalise = (p) => resolve(p).replace(/[\\/]+$/, '').toLowerCase();
+  if (home && normalise(dir) === normalise(home)) return { kind: 'home' };
+  const marker = PROJECT_MARKERS.find((m) => existsSync(join(dir, m)));
+  return marker ? { kind: 'project', marker } : { kind: 'bare' };
+}
+
+export async function init(pkgRoot, argv = []) {
+  const results = [];
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+  const cwd = process.cwd();
+
+  const target = inspectTarget(cwd, home);
+  if (target.kind !== 'project') {
+    // Home directory is always refused
+    if (target.kind === 'home') {
+      console.error('\n这是主目录，请在项目目录下运行 comate init。');
+      return 1;
+    }
+
+    // Bare directory: ask user if they want to create a project here
+    console.log('\n当前目录不像项目（无 .git / package.json 等）。');
+    const confirmed = await askConfirm('要在这里初始化新项目吗？');
+    if (!confirmed) {
+      console.log('已取消。');
+      return 1;
+    }
+  }
+
+  // --migrate: move 0.x docs/knowledge-base and docs/architecture into comate/.
+  // --dry-run lists the moves and stops; a conflict stops before moving anything.
+  if (argv.includes('--migrate')) {
+    const dryRun = argv.includes('--dry-run');
+    const { moves, ok } = migrateLayout(cwd, { dryRun });
+    if (!moves.length) console.log('\n没有需要迁移的目录（docs/knowledge-base、docs/architecture 都不存在）。');
+    for (const m of moves) {
+      const mark = { move: '→', moved: '✓', conflict: '✗' }[m.status];
+      console.log(`  ${mark} ${m.from}  →  ${m.to}${m.status === 'conflict' ? '（目标已存在，未移动）' : ''}`);
+    }
+    if (!ok) {
+      console.error('\n目标目录已存在，没有移动任何文件。手动合并后重跑 comate init --migrate。');
+      return 1;
+    }
+    if (dryRun) {
+      console.log('\n以上为预览（--dry-run）。确认后运行 comate init --migrate 执行（使用 git mv 保留历史）。');
+      return 0;
+    }
+  }
+
+  const stopSpinner = startSpinner('Initializing…');
+
+  // 1. git — comate 1.0 keeps candidates, archives and finish steps in git.
+  const gitVersion = capture('git', ['--version']);
+  if (gitVersion === null) {
+    results.push(['git', 'failed', '找不到 git：comate 1.0 需要 git']);
+  } else if (spawnSync('git', ['rev-parse', '--git-dir'], { cwd, stdio: 'ignore' }).status !== 0) {
+    results.push(['git', 'warn', '当前目录还不是 git 仓库：先 git init 并做一次初始提交，再用 /comate']);
+  } else {
+    results.push(['git', 'skipped', gitVersion]);
+  }
+
+  // 2. comate itself. The skills CLI reports per-agent failures without ever
+  // setting a non-zero exit code, and we swallow its output — so a zero status
+  // is not evidence the skill landed. Check the file.
+  const comateArgs = ['add', pkgRoot, '--skill', '*', '-g', '-y'];
+  const r = run(skillsInvocation(pkgRoot, comateArgs), SKILLS_TIMEOUT_MS, { quiet: true });
+  const landed = existsSync(join(home, '.agents', 'skills', 'comate', 'SKILL.md'));
+  if (r.ok && !landed) {
+    results.push(['comate', 'failed', `未装到 ${join(home, '.agents', 'skills')}`]);
+  } else {
+    results.push(['comate', r.ok ? 'installed' : 'failed', r.ok ? '' : r.reason, r.output]);
+  }
+
+  // Prune comate skill dirs renamed/dropped in past releases. `skills add` above
+  // only adds/overwrites, so /comate-spec etc. would otherwise linger as dead
+  // slash commands. The postinstall hook does this too, but --ignore-scripts
+  // users never run it — init is their only path, so it must clean up here.
+  const pruned = pruneDeprecatedSkills(userSkillsRoot(home));
+  if (pruned.length) results.push(['清理废弃 skill', 'installed', pruned.join('、')]);
+
+  // 3. comate/ project scaffold: config.json, knowledge-base (PRD template),
+  // architecture placeholder. Idempotent — existing files are left alone.
+  const sc = scaffoldComate(pkgRoot);
+  if (!sc.ok) {
+    results.push(['comate/', 'failed', sc.reason]);
+  } else if (sc.created === 0) {
+    results.push(['comate/', 'skipped', '已存在']);
+  } else {
+    const note = sc.skipped > 0 ? `新建 ${sc.created} 个文件,保留 ${sc.skipped} 个已有` : '';
+    results.push(['comate/', 'installed', note]);
+  }
+  if (!argv.includes('--migrate') && LAYOUT_MOVES.some(([from]) => existsSync(join(cwd, from)))) {
+    results.push(['docs/', 'warn', '发现 0.x 的 docs/knowledge-base 或 docs/architecture：comate init --migrate --dry-run 查看迁移清单']);
+  }
+  if (existsSync(join(cwd, 'openspec', 'specs'))) {
+    results.push(['openspec/', 'warn', '发现 0.x 主规格：comate import-specs --dry-run 查看迁移清单']);
+  }
+
+  stopSpinner();
+  return report(results);
+}
+
+// A yes/no prompt. Defaults to "no" so a piped/non-interactive run (CI, an
+// unattended npx) never silently scaffolds a project into whatever directory it
+// happened to land in — those callers should point at a real project instead.
+// [y/N]: empty input, EOF (Ctrl-D / closed stdin), or anything but y/yes = no.
+export function askConfirm(question, { input = process.stdin, output = process.stdout } = {}) {
+  if (!input.isTTY) return Promise.resolve(false);
+  const rl = createInterface({ input, output });
+  return new Promise((done) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close();
+      done(/^\s*y(es)?\s*$/i.test(answer));
+    });
+  });
+}
+
+// The spinner runs in its own process because every step above is a synchronous
+// spawnSync — an interval on this thread would never fire. In a pipe \r does not
+// overwrite, so animating there would leave every frame on screen; print one
+// static line instead.
+function startSpinner(label) {
+  if (!process.stdout.isTTY) {
+    console.log(`\n${label}`);
+    return () => {};
+  }
+
+  const child = spawn(process.execPath, [join(import.meta.dirname, 'spinner.mjs'), label], {
+    stdio: ['ignore', 'inherit', 'ignore'],
+  });
+  let stopped = false;
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    child.kill();
+    // The parent erases the line, not the child: on Windows SIGTERM is not a
+    // real signal — Node terminates the process outright, so a handler in the
+    // child never runs and its last frame would sit under the logo.
+    process.stdout.write(`\r${' '.repeat(label.length + 6)}\r`);
+  };
+}
+
+// Success is one screen: the wordmark and where things landed. The per-item
+// breakdown only earns its space when something failed, and then it carries the
+// reason — a bare "失败" would leave the user with nowhere to go.
+function report(results) {
+  const failed = results.filter(([, s]) => s === 'failed');
+  if (failed.length > 0) {
+    console.error('\n安装失败\n');
+    for (const [name, status, note, output] of results) {
+      const mark = { installed: '✓', skipped: '·', warn: '⚠', failed: '✗' }[status];
+      console.error(`  ${mark} ${name.padEnd(14)}${note}`);
+      // The child's own output, indented under the item it belongs to, so a
+      // knock-on failure doesn't look like a second unrelated problem.
+      if (status === 'failed' && output) {
+        for (const line of output.split('\n')) console.error(`      ${line.trim()}`);
+      }
+    }
+    console.error('\n修好后重跑 comate init。');
+    return 1;
+  }
+
+  console.log(banner(pkgVersion()));
+  for (const [name, , note] of results.filter(([, s]) => s === 'warn')) console.log(`  ⚠ ${name.padEnd(12)}${note}`);
+  console.log('  在 agent 中输入 /comate 开始；配置检查命令：comate/comate/config.json\n');
+  return 0;
+}
+
+// ponytail: read package.json rather than hardcoding — npm version bumps the
+// file, and a stale literal in the banner is worse than no version at all.
+export function pkgVersion(root = resolve(import.meta.dirname, '..')) {
+  try {
+    return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+  } catch {
+    return '';
+  }
+}
+
+// Only CI gates the wordmark. Two earlier guards were both wrong and are worth
+// naming so they don't come back:
+//
+//   isTTY — npm's Windows global install resolves `comate` to a comate.ps1
+//   shim, and PowerShell calling node through a .ps1 wrapper takes over stdout,
+//   so isTTY is false in a real terminal — exactly where the logo belongs.
+//
+//   chcp — reports the codepage the child process inherited, which the shim
+//   does not propagate (65001 outside, 936 inside). It also answers the wrong
+//   question: writing to a real Windows console goes through WriteConsoleW,
+//   which converts to UTF-16 and bypasses the codepage entirely.
+export function banner(version, { ci = isCI() } = {}) {
+  const tag = `comate${version ? ` v${version}` : ''}`;
+  const plain = `\n  ${tag} - AI coding almost there!\n`;
+  if (ci) return plain;
+
+  const art = [
+    ' ██████╗ ██████╗ ███╗   ███╗ █████╗ ████████╗███████╗',
+    '██╔════╝██╔═══██╗████╗ ████║██╔══██╗╚══██╔══╝██╔════╝',
+    '██║     ██║   ██║██╔████╔██║███████║   ██║   █████╗  ',
+    '██║     ██║   ██║██║╚██╔╝██║██╔══██║   ██║   ██╔══╝  ',
+    '╚██████╗╚██████╔╝██║ ╚═╝ ██║██║  ██║   ██║   ███████╗',
+    ' ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝',
+  ];
+  // Trailing padding keeps the source rows aligned; strip it so a colour run
+  // doesn't sit behind spaces the terminal may highlight on select.
+  const trim = (line) => line.replace(/\s+$/, '');
+  // Centred under the art, not under the terminal: the wordmark is fixed-width,
+  // so centring against art[0] holds at any window size. Computed rather than
+  // hardcoded because the version string changes length on every release.
+  const tagline = `${tag} - AI coding almost there!`;
+  const indent = ' '.repeat(2 + Math.max(0, Math.round((art[0].length - tagline.length) / 2)));
+  if (process.env.NO_COLOR) {
+    return ['', ...art.map((l) => `  ${trim(l)}`), '', `${indent}${tagline}`, ''].join('\n');
+  }
+
+  // 24-bit SGR. Truecolor is not universal, but the two terminals that matter
+  // here (Windows Terminal, VS Code) both support it, and one that doesn't
+  // degrades to its nearest palette entry rather than breaking.
+  const sgr = ([r, g, b]) => `\x1B[38;2;${r};${g};${b}m`;
+  const RESET = '\x1B[0m';
+
+  // Polished chrome under a cyan→magenta rim light: [face, edge] per row. The
+  // ramp shifts hue rather than dropping brightness — every row stays high
+  // luminance, which is what keeps it reading as lit metal instead of fading
+  // out. An earlier darkening ramp went muddy across the bottom half.
+  const ramp = [
+    [[255, 255, 255], [150, 240, 255]],
+    [[214, 248, 255], [ 56, 214, 255]],
+    [[168, 214, 255], [ 92, 148, 255]],
+    [[186, 160, 255], [148, 100, 255]],
+    [[233, 150, 255], [200,  76, 255]],
+    [[255, 150, 224], [255,  72, 178]],
+  ];
+
+  // Blocks are the lit face, box-drawing pieces are the bevelled edge. Two
+  // shades per row is the whole trick: it gives every glyph a rim, which is
+  // what separates brushed metal from a flat decal.
+  const emboss = (line, [face, edge]) => {
+    let out = '';
+    let cur = null;
+    for (const ch of line) {
+      const want = ch === ' ' ? null : ch === '█' ? face : edge;
+      if (want !== cur) {
+        out += want ? sgr(want) : RESET;
+        cur = want;
+      }
+      out += ch;
+    }
+    return out + RESET;
+  };
+
+  // The tagline picks up the ramp instead of going dim grey: the name in the
+  // white highlight so it stays the thing you read first, the strapline in the
+  // magenta rim so the line closes the gradient the art opened. Dropping \x1B[2m
+  // matters — dim on a saturated colour is what made this read as washed out.
+  const nameLit = `${sgr(ramp[0][0])}${tag}${RESET}`;
+  const strap = `${sgr(ramp[5][1])} - AI coding almost there!${RESET}`;
+
+  return [
+    '',
+    ...art.map((line, i) => `  ${emboss(trim(line), ramp[i])}`),
+    '',
+    `${indent}${nameLit}${strap}`,
+    '',
+  ].join('\n');
+}
+
+// Every major CI sets CI=true; GITHUB_ACTIONS covers the Actions runner even in
+// the odd config that doesn't.
+function isCI() {
+  return Boolean(process.env.CI || process.env.GITHUB_ACTIONS);
+}