cannwork-rehearsal 0.4.1 → 0.5.0

package/README.md

@@ -1,141 +1,142 @@
-# cannwork-cli
-
-A terminal launcher for AI coding agents (starting with [opencode](https://opencode.ai)), built with [OpenTUI](https://github.com/msmps/opentui) and React, running on [Bun](https://bun.sh/).
-
-## Requirements
-
-- [Bun](https://bun.sh/) **1.3.0** or later — to run from source and to build
-- Node.js 18+ — only to launch the tiny `cannwork` shim when installed from npm; the packaged executable embeds its own runtime and does not need Bun
-
-## Install
-
-Trial-period name (currently available — the official scoped name is not published yet):
-
-```bash
-npm install -g cannwork-rehearsal
-# or run without installing
-npx cannwork-rehearsal
-```
-
-Official name (to be published later): `@zhoufangchaojs/cannwork`, same usage once available.
-
-The npm package ships standalone executables per platform. Supported platforms:
-
-| Platform | Suffix |
-| --- | --- |
-| Windows x64 | `win32-x64` |
-| Linux x64 (glibc) | `linux-x64` |
-| Linux arm64 (glibc) | `linux-arm64` |
-| macOS x64 | `darwin-x64` |
-| macOS arm64 | `darwin-arm64` |
-
-The installed platform package is `<package-name>-<suffix>` (currently `cannwork-rehearsal-<suffix>`, later `@zhoufangchaojs/cannwork-<suffix>`).
-
-Notes:
-
-- Do not install with `--omit=optional`: the matching platform package is an optional dependency.
-- Linux binaries link glibc; Alpine/musl is not covered yet — `OPENTUI_LIBC`/musl builds are not published.
-- The macOS binaries are not codesigned/notarized. If Gatekeeper blocks the binary, clear the quarantine flag:
-  ```bash
-  xattr -d com.apple.quarantine "$(npm root -g)/cannwork-rehearsal-darwin-arm64/bin/cannwork"
-  ```
-- `cannwork-rehearsal` is the **trial-period release name**: it is published and installable on purpose so real users can try it while the official `@zhoufangchaojs/cannwork` name is not released yet. It will be retired (unpublished/deprecated) once the official name is published.
-
-### Automatic update check
-
-When you run `cannwork` in an interactive terminal, the launcher asks the npm registry whether a newer version exists. If one does, it prompts before the TUI starts:
-
-- `[1] 更新` — runs `npm install -g <package>@latest` in place, then asks you to run `cannwork` again
-- `[2] 跳过` — skips this time only; the same version will be offered again next launch
-- `[3] 跳过此版本` — remembers this version and stops prompting for it (a newer version still prompts)
-
-The check is skipped entirely for `cannwork -v` / `cannwork --version`, on non-interactive terminals (stdin or stdout not a TTY), or when `CANNWORK_NO_UPDATE_CHECK=1` is set. Network failures never block startup — the launcher simply continues with the installed version.
-
-## Getting Started (from source)
-
-Install dependencies:
-
-```bash
-bun install
-```
-
-Start the app in watch mode:
-
-```bash
-bun dev
-```
-
-## Credentials and login
-
-- The access token stays in process memory only and is never written to `~/.cannwork-tui/cannwork.json`.
-- The refresh token is encrypted with AES-256-GCM using a key derived from a stable machine fingerprint, then stored as `refreshTokenEnc`; `refreshTokenSavedAt` records when it was written and is metadata only.
-- **Breaking upgrade:** on first launch after upgrading from a version that stored plaintext tokens, the legacy `accessToken`, `refreshToken` and `accessTokenExpiresAt` fields are deleted and you must log in again with `/login` or `/gitcode-token`.
-- If the machine fingerprint changes (host identity or OS user), the stored refresh token can no longer be decrypted and you need to log in again.
-- Multi-instance refreshes are serialized through a SQLite lease lock (`token_refresh_lock`). If the local database is unavailable, the launcher falls back to best-effort refreshes.
-
-## Scripts
-
-| Script | Description |
-| --- | --- |
-| `bun dev` | Run the app with auto-reload on file changes |
-| `bun run typecheck` | Type-check the source with `tsc --noEmit` |
-| `bun run test` | Run the test suite |
-| `bun run build` | Build a JS bundle (requires Bun on the target machine) |
-| `bun run build:exe` | Build a standalone executable for the current platform |
-| `bun run build:publish` | Cross-compile all 5 platforms and assemble `dist/publish/<pkg>/` |
-| `bun run release` | Check → build → publish all packages (sub-packages first) |
-
-Build artifacts are written to `dist/`.
-
-`build:publish` prepares any missing target-platform native packages (`@opentui/core-*`) automatically by fetching them from npm into `node_modules`, so the build machine needs network access on first run. Pass `--manifests-only` to assemble manifests without compiling.
-
-## Maintainer release runbook
-
-Releases are published **manually by the maintainer** to <https://registry.npmjs.org/> in two phases: an unscoped **trial release** that is kept live for real users, then (later) the official scoped release, after which the trial name is retired. AI assistants and other automation must not run a real release — they may only read release files, run checks/tests/builds, and use `--dry-run`.
-
-### Phase 1 — unscoped trial release (kept live)
-
-1. Set `name` to `cannwork-rehearsal` and `version` to the intended version in the root `package.json` (single source of truth). The script never bumps the version or creates git tags for you.
-2. `npm login` (any account with publish rights).
-3. Optional preview: `bun run release --dry-run`. It prints the release plan (package names, version, package count, sub-packages-before-main order), runs typecheck + tests, cross-compiles, and verifies the packed artifacts **without uploading or asking for confirmation**.
-4. Real release: run `bun run release` in an **interactive terminal**. After checks, build, and artifact verification it prints the same plan and asks `确认发布 <name>@<version>…`; only `y` / `yes` continues. Any other input (including an empty line) cancels with exit code 0 and uploads nothing.
-5. The script publishes the 5 platform packages first, then the main package, and finally queries the registry for every package. It succeeds only when all 6 target versions are `live`. If any package is still staged (`0.0.0-stage`) or the query fails, the command exits non-zero, names the package, and tells you to wait for npm to promote it (or approve it on npmjs.com) before smoke-testing.
-6. Smoke-test in a clean directory: `npx cannwork-rehearsal`. On success the script writes `dist/.rehearsal-ok`, which unlocks phase 2.
-7. **Keep it live**: do not unpublish. During the trial, ship updates by repeating steps 3–6 with a bumped version.
-
-### Phase 2 — official scoped release (deferred), then retire the trial name
-
-8. Set `name` to `@zhoufangchaojs/cannwork`, then run `bun run release` in an interactive terminal and confirm. The script refuses to publish a scoped name until the trial-release marker exists, and it performs the same registry check afterwards.
-9. Verify: `npm view @zhoufangchaojs/cannwork version`, smoke-test `npx @zhoufangchaojs/cannwork`, then tag the release yourself (tagging is intentionally outside the script):
-   ```bash
-   git tag <version>
-   ```
-10. Retire the trial packages: `npm unpublish` all 6 (`cannwork-rehearsal` and `cannwork-rehearsal-*`) within the 72-hour window, otherwise `npm deprecate` them as trial packages. If the active credential is a `Granular access token` that bypasses 2FA, unpublish is rejected with 403 — delete the packages on npmjs.com instead, or run `npm login --auth-type=web` first.
-
-### Release script options
-
-- `--dry-run` — plan, check, build, and pack without uploading or confirming.
-- `--yes` — skip the interactive confirmation. Only for rehearsals or explicitly authorized automation; a real release without a TTY is rejected unless this flag is present.
-- `--no-build` / `--skip-checks` — reuse existing artifacts / skip typecheck and tests (use with care).
-- `--root <dir>` — run against another checkout.
-
-Rollback: `npm unpublish` the affected version within the allowed window; afterwards `npm deprecate` and publish a fixed version.
-
-## Project Structure
-
-```
-├── bin/
-│   ├── cannwork.js     # Node-compatible launcher shipped in the npm main package
-│   └── update-check.js # Pre-launch version check, prompt and global install
-├── scripts/        # cross-platform build and publish tooling
-├── src/
-│   └── index.tsx   # App entry, renders the TUI with @opentui/react
-├── openspec/       # OpenSpec change management workspace
-├── dist/           # Build output
-├── package.json
-└── tsconfig.json
-```
-
-## Notes
-
-This project was created using `bun create tui`. [create-tui](https://github.com/msmps/create-tui) is the easiest way to get started with OpenTUI.
+# cannwork-cli
+
+A terminal launcher for AI coding agents (starting with [opencode](https://opencode.ai)), built with [OpenTUI](https://github.com/msmps/opentui) and React, running on [Bun](https://bun.sh/).
+
+## Requirements
+
+- [Bun](https://bun.sh/) **1.3.0** or later — to run from source and to build
+- Node.js 18+ — only to launch the tiny `cannbot` shim when installed from npm; the packaged executable embeds its own runtime and does not need Bun
+
+## Install
+
+Trial-period name (currently available — the official scoped name is not published yet):
+
+```bash
+npm install -g cannwork-rehearsal
+# or run without installing
+npx cannwork-rehearsal
+```
+
+Official name (to be published later): `@zhoufangchaojs/cannwork`, same usage once available.
+
+The npm package ships standalone executables per platform. Supported platforms:
+
+| Platform | Suffix |
+| --- | --- |
+| Windows x64 | `win32-x64` |
+| Linux x64 (glibc) | `linux-x64` |
+| Linux arm64 (glibc) | `linux-arm64` |
+| macOS x64 | `darwin-x64` |
+| macOS arm64 | `darwin-arm64` |
+
+The installed platform package is `<package-name>-<suffix>` (currently `cannwork-rehearsal-<suffix>`, later `@zhoufangchaojs/cannwork-<suffix>`).
+
+Notes:
+
+- The installed command is `cannbot` (the launcher is `bin/cannbot.js`). The former `cannwork` command is no longer installed; uninstall any previous global install and remove the old `cannwork` shim if your shell still resolves it.
+- Do not install with `--omit=optional`: the matching platform package is an optional dependency.
+- Linux binaries link glibc; Alpine/musl is not covered yet — `OPENTUI_LIBC`/musl builds are not published.
+- The macOS binaries are not codesigned/notarized. If Gatekeeper blocks the binary, clear the quarantine flag:
+  ```bash
+  xattr -d com.apple.quarantine "$(npm root -g)/cannwork-rehearsal-darwin-arm64/bin/cannwork"
+  ```
+- `cannwork-rehearsal` is the **trial-period release name**: it is published and installable on purpose so real users can try it while the official `@zhoufangchaojs/cannwork` name is not released yet. It will be retired (unpublished/deprecated) once the official name is published.
+
+### Automatic update check
+
+When you run `cannbot` in an interactive terminal, the launcher asks the npm registry whether a newer version exists. If one does, it prompts before the TUI starts:
+
+- `[1] 更新` — runs `npm install -g <package>@latest` in place, then asks you to run `cannbot` again
+- `[2] 跳过` — skips this time only; the same version will be offered again next launch
+- `[3] 跳过此版本` — remembers this version and stops prompting for it (a newer version still prompts)
+
+The check is skipped entirely for `cannbot -v` / `cannbot --version`, on non-interactive terminals (stdin or stdout not a TTY), or when `CANNWORK_NO_UPDATE_CHECK=1` is set. Network failures never block startup — the launcher simply continues with the installed version.
+
+## Getting Started (from source)
+
+Install dependencies:
+
+```bash
+bun install
+```
+
+Start the app in watch mode:
+
+```bash
+bun dev
+```
+
+## Credentials and login
+
+- The access token stays in process memory only and is never written to `~/.cannwork-tui/cannwork.json`.
+- The refresh token is encrypted with AES-256-GCM using a key derived from a stable machine fingerprint, then stored as `refreshTokenEnc`; `refreshTokenSavedAt` records when it was written and is metadata only.
+- **Breaking upgrade:** on first launch after upgrading from a version that stored plaintext tokens, the legacy `accessToken`, `refreshToken` and `accessTokenExpiresAt` fields are deleted and you must log in again with `/login` or `/gitcode-token`.
+- If the machine fingerprint changes (host identity or OS user), the stored refresh token can no longer be decrypted and you need to log in again.
+- Multi-instance refreshes are serialized through a SQLite lease lock (`token_refresh_lock`). If the local database is unavailable, the launcher falls back to best-effort refreshes.
+
+## Scripts
+
+| Script | Description |
+| --- | --- |
+| `bun dev` | Run the app with auto-reload on file changes |
+| `bun run typecheck` | Type-check the source with `tsc --noEmit` |
+| `bun run test` | Run the test suite |
+| `bun run build` | Build a JS bundle (requires Bun on the target machine) |
+| `bun run build:exe` | Build a standalone executable for the current platform |
+| `bun run build:publish` | Cross-compile all 5 platforms and assemble `dist/publish/<pkg>/` |
+| `bun run release` | Check → build → publish all packages (sub-packages first) |
+
+Build artifacts are written to `dist/`.
+
+`build:publish` prepares any missing target-platform native packages (`@opentui/core-*`) automatically by fetching them from npm into `node_modules`, so the build machine needs network access on first run. Pass `--manifests-only` to assemble manifests without compiling.
+
+## Maintainer release runbook
+
+Releases are published **manually by the maintainer** to <https://registry.npmjs.org/> in two phases: an unscoped **trial release** that is kept live for real users, then (later) the official scoped release, after which the trial name is retired. AI assistants and other automation must not run a real release — they may only read release files, run checks/tests/builds, and use `--dry-run`.
+
+### Phase 1 — unscoped trial release (kept live)
+
+1. Set `name` to `cannwork-rehearsal` and `version` to the intended version in the root `package.json` (single source of truth). The script never bumps the version or creates git tags for you.
+2. `npm login` (any account with publish rights).
+3. Optional preview: `bun run release --dry-run`. It prints the release plan (package names, version, package count, sub-packages-before-main order), runs typecheck + tests, cross-compiles, and verifies the packed artifacts **without uploading or asking for confirmation**.
+4. Real release: run `bun run release` in an **interactive terminal**. After checks, build, and artifact verification it prints the same plan and asks `确认发布 <name>@<version>…`; only `y` / `yes` continues. Any other input (including an empty line) cancels with exit code 0 and uploads nothing.
+5. The script publishes the 5 platform packages first, then the main package, and finally queries the registry for every package. It succeeds only when all 6 target versions are `live`. If any package is still staged (`0.0.0-stage`) or the query fails, the command exits non-zero, names the package, and tells you to wait for npm to promote it (or approve it on npmjs.com) before smoke-testing.
+6. Smoke-test in a clean directory: `npx cannwork-rehearsal`. On success the script writes `dist/.rehearsal-ok`, which unlocks phase 2.
+7. **Keep it live**: do not unpublish. During the trial, ship updates by repeating steps 3–6 with a bumped version.
+
+### Phase 2 — official scoped release (deferred), then retire the trial name
+
+8. Set `name` to `@zhoufangchaojs/cannwork`, then run `bun run release` in an interactive terminal and confirm. The script refuses to publish a scoped name until the trial-release marker exists, and it performs the same registry check afterwards.
+9. Verify: `npm view @zhoufangchaojs/cannwork version`, smoke-test `npx @zhoufangchaojs/cannwork`, then tag the release yourself (tagging is intentionally outside the script):
+   ```bash
+   git tag <version>
+   ```
+10. Retire the trial packages: `npm unpublish` all 6 (`cannwork-rehearsal` and `cannwork-rehearsal-*`) within the 72-hour window, otherwise `npm deprecate` them as trial packages. If the active credential is a `Granular access token` that bypasses 2FA, unpublish is rejected with 403 — delete the packages on npmjs.com instead, or run `npm login --auth-type=web` first.
+
+### Release script options
+
+- `--dry-run` — plan, check, build, and pack without uploading or confirming.
+- `--yes` — skip the interactive confirmation. Only for rehearsals or explicitly authorized automation; a real release without a TTY is rejected unless this flag is present.
+- `--no-build` / `--skip-checks` — reuse existing artifacts / skip typecheck and tests (use with care).
+- `--root <dir>` — run against another checkout.
+
+Rollback: `npm unpublish` the affected version within the allowed window; afterwards `npm deprecate` and publish a fixed version.
+
+## Project Structure
+
+```
+├── bin/
+│   ├── cannbot.js      # Node-compatible launcher shipped in the npm main package (`cannbot` command)
+│   └── update-check.js # Pre-launch version check, prompt and global install
+├── scripts/        # cross-platform build and publish tooling
+├── src/
+│   └── index.tsx   # App entry, renders the TUI with @opentui/react
+├── openspec/       # OpenSpec change management workspace
+├── dist/           # Build output
+├── package.json
+└── tsconfig.json
+```
+
+## Notes
+
+This project was created using `bun create tui`. [create-tui](https://github.com/msmps/create-tui) is the easiest way to get started with OpenTUI.

package/bin/{cannwork.js → cannbot.js}

@@ -1,191 +1,191 @@
-#!/usr/bin/env node
-import { createRequire } from "node:module";
-import { spawn } from "node:child_process";
-import { accessSync, chmodSync, constants, realpathSync } from "node:fs";
-import { resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import {
-  askUpdateChoice,
-  checkForUpdate,
-  DISABLE_UPDATE_CHECK_ENV,
-  formatUpdateNotice,
-  manualInstallCommand,
-  readSkippedVersion,
-  runGlobalInstall,
-  writeSkippedVersion,
-} from "./update-check.js";
-
-export const SUPPORTED_TARGETS = Object.freeze([
-  "win32-x64",
-  "linux-x64",
-  "linux-arm64",
-  "darwin-x64",
-  "darwin-arm64",
-]);
-
-export function subPackageName(mainName, os, arch) {
-  if (typeof mainName !== "string" || mainName.length === 0) return null;
-  if (!SUPPORTED_TARGETS.includes(`${os}-${arch}`)) return null;
-  const suffix = `-${os}-${arch}`;
-  if (mainName.startsWith("@")) {
-    const slash = mainName.indexOf("/");
-    if (slash <= 1 || slash === mainName.length - 1) return null;
-    return `${mainName}${suffix}`;
-  }
-  return `${mainName}${suffix}`;
-}
-
-export function binarySubpath(os) {
-  return os === "win32" ? "bin/cannwork.exe" : "bin/cannwork";
-}
-
-export function missingPackageMessage(mainName, os, arch) {
-  const pkg = subPackageName(mainName, os, arch) ?? `${mainName}-${os}-${arch}`;
-  return [
-    `${mainName}: 缺少当前平台 (${os}-${arch}) 的运行时包 ${pkg}。`,
-    "",
-    "  可能原因：安装时使用了 --omit=optional，或该平台尚未提供预编译产物。",
-    `  受支持平台：${SUPPORTED_TARGETS.join(", ")}`,
-    "",
-    "  修复：重新完整安装（保留可选依赖），例如",
-    `    npm install -g ${mainName}`,
-    "",
-  ].join("\n");
-}
-
-export function resolveBinaryPath(mainName, os, arch, requireFn) {
-  const subPackage = subPackageName(mainName, os, arch);
-  if (subPackage === null) return null;
-  try {
-    return requireFn.resolve(`${subPackage}/${binarySubpath(os)}`);
-  } catch {
-    return null;
-  }
-}
-
-function ensureExecutable(binaryPath, os) {
-  if (os === "win32") return;
-  try {
-    accessSync(binaryPath, constants.X_OK);
-  } catch {
-    try {
-      chmodSync(binaryPath, 0o755);
-    } catch {
-      return;
-    }
-  }
-}
-
-export function spawnBinary(binaryPath, args) {
-  return new Promise((resolveCode) => {
-    let child;
-    try {
-      child = spawn(binaryPath, args, { stdio: "inherit", windowsHide: false });
-    } catch {
-      resolveCode(1);
-      return;
-    }
-    child.on("error", () => resolveCode(1));
-    child.on("exit", (code) => {
-      resolveCode(typeof code === "number" ? code : 1);
-    });
-  });
-}
-
-export async function run(argv = process.argv.slice(2), options = {}) {
-  const { platform: os, arch } = process;
-  const stdin = options.stdin ?? process.stdin;
-  const stdout = options.stdout ?? process.stdout;
-  const stderr = options.stderr ?? process.stderr;
-  const env = options.env ?? process.env;
-
-  const requireFromHere = createRequire(import.meta.url);
-  let manifest;
-  try {
-    manifest = requireFromHere("../package.json");
-  } catch {
-    stderr.write("cannwork: 无法读取自身包清单，安装可能已损坏。\n");
-    return 1;
-  }
-  const mainName = manifest.name;
-
-  if (argv.includes("-v") || argv.includes("--version")) {
-    stdout.write(`${manifest.version}\n`);
-    return 0;
-  }
-
-  const interactive = stdin.isTTY === true && stdout.isTTY === true;
-  if (!options.skipUpdateCheck && interactive && env[DISABLE_UPDATE_CHECK_ENV] !== "1") {
-    try {
-      const result = await checkForUpdate({
-        name: mainName,
-        localVersion: manifest.version,
-        manifest,
-        fetchImpl: options.fetchImpl,
-        timeoutMs: options.timeoutMs,
-      });
-      if (result.updateAvailable) {
-        const stateDir = options.stateDir;
-        if (readSkippedVersion(stateDir) !== result.latestVersion) {
-          const notice = formatUpdateNotice({
-            name: mainName,
-            current: manifest.version,
-            latest: result.latestVersion,
-          });
-          const ask = options.askChoice ?? askUpdateChoice;
-          const choice = await ask({ notice, stdin, stdout });
-          if (choice === "update") {
-            const install = options.installGlobal ?? runGlobalInstall;
-            if (install(mainName)) {
-              stdout.write(`\n已更新到 ${result.latestVersion}，请重新执行 cannwork。\n`);
-              return 0;
-            }
-            stderr.write(`\n更新失败。请手动执行：${manualInstallCommand(mainName)}\n\n`);
-          } else if (choice === "skip-version") {
-            writeSkippedVersion(result.latestVersion, stateDir);
-          }
-        }
-      }
-    } catch {
-      // 升级检查是可选增强：任何异常都静默放行，绝不阻断启动
-    }
-  }
-
-  const resolveBinary = options.resolveBinary ?? resolveBinaryPath;
-  const binaryPath = resolveBinary(mainName, os, arch, requireFromHere);
-  if (binaryPath === null) {
-    stderr.write(missingPackageMessage(mainName, os, arch));
-    return 1;
-  }
-
-  ensureExecutable(binaryPath, os);
-  const spawnChild = options.spawnBinary ?? spawnBinary;
-  return await spawnChild(binaryPath, argv);
-}
-
-export const ENTRYPOINT_UNDETERMINED_MESSAGE =
-  "cannwork: 无法确认启动器入口，已跳过执行。\n";
-
-export function entrypointStatus(metaUrl, argv1) {
-  if (typeof argv1 !== "string" || argv1.length === 0) return "not-entrypoint";
-  try {
-    const selfPath = realpathSync(fileURLToPath(metaUrl));
-    const argvPath = realpathSync(resolve(argv1));
-    return selfPath === argvPath ? "entrypoint" : "not-entrypoint";
-  } catch {
-    return "undetermined";
-  }
-}
-
-export function isEntrypoint(metaUrl, argv1) {
-  return entrypointStatus(metaUrl, argv1) === "entrypoint";
-}
-
-const entryStatus = entrypointStatus(import.meta.url, process.argv[1]);
-if (entryStatus === "entrypoint") {
-  run().then((code) => {
-    process.exit(code);
-  });
-} else if (entryStatus === "undetermined") {
-  process.stderr.write(ENTRYPOINT_UNDETERMINED_MESSAGE);
-}
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
+import { accessSync, chmodSync, constants, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  askUpdateChoice,
+  checkForUpdate,
+  DISABLE_UPDATE_CHECK_ENV,
+  formatUpdateNotice,
+  manualInstallCommand,
+  readSkippedVersion,
+  runGlobalInstall,
+  writeSkippedVersion,
+} from "./update-check.js";
+
+export const SUPPORTED_TARGETS = Object.freeze([
+  "win32-x64",
+  "linux-x64",
+  "linux-arm64",
+  "darwin-x64",
+  "darwin-arm64",
+]);
+
+export function subPackageName(mainName, os, arch) {
+  if (typeof mainName !== "string" || mainName.length === 0) return null;
+  if (!SUPPORTED_TARGETS.includes(`${os}-${arch}`)) return null;
+  const suffix = `-${os}-${arch}`;
+  if (mainName.startsWith("@")) {
+    const slash = mainName.indexOf("/");
+    if (slash <= 1 || slash === mainName.length - 1) return null;
+    return `${mainName}${suffix}`;
+  }
+  return `${mainName}${suffix}`;
+}
+
+export function binarySubpath(os) {
+  return os === "win32" ? "bin/cannwork.exe" : "bin/cannwork";
+}
+
+export function missingPackageMessage(mainName, os, arch) {
+  const pkg = subPackageName(mainName, os, arch) ?? `${mainName}-${os}-${arch}`;
+  return [
+    `${mainName}: 缺少当前平台 (${os}-${arch}) 的运行时包 ${pkg}。`,
+    "",
+    "  可能原因：安装时使用了 --omit=optional，或该平台尚未提供预编译产物。",
+    `  受支持平台：${SUPPORTED_TARGETS.join(", ")}`,
+    "",
+    "  修复：重新完整安装（保留可选依赖），例如",
+    `    npm install -g ${mainName}`,
+    "",
+  ].join("\n");
+}
+
+export function resolveBinaryPath(mainName, os, arch, requireFn) {
+  const subPackage = subPackageName(mainName, os, arch);
+  if (subPackage === null) return null;
+  try {
+    return requireFn.resolve(`${subPackage}/${binarySubpath(os)}`);
+  } catch {
+    return null;
+  }
+}
+
+function ensureExecutable(binaryPath, os) {
+  if (os === "win32") return;
+  try {
+    accessSync(binaryPath, constants.X_OK);
+  } catch {
+    try {
+      chmodSync(binaryPath, 0o755);
+    } catch {
+      return;
+    }
+  }
+}
+
+export function spawnBinary(binaryPath, args) {
+  return new Promise((resolveCode) => {
+    let child;
+    try {
+      child = spawn(binaryPath, args, { stdio: "inherit", windowsHide: false });
+    } catch {
+      resolveCode(1);
+      return;
+    }
+    child.on("error", () => resolveCode(1));
+    child.on("exit", (code) => {
+      resolveCode(typeof code === "number" ? code : 1);
+    });
+  });
+}
+
+export async function run(argv = process.argv.slice(2), options = {}) {
+  const { platform: os, arch } = process;
+  const stdin = options.stdin ?? process.stdin;
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const env = options.env ?? process.env;
+
+  const requireFromHere = createRequire(import.meta.url);
+  let manifest;
+  try {
+    manifest = requireFromHere("../package.json");
+  } catch {
+    stderr.write("cannwork: 无法读取自身包清单，安装可能已损坏。\n");
+    return 1;
+  }
+  const mainName = manifest.name;
+
+  if (argv.includes("-v") || argv.includes("--version")) {
+    stdout.write(`${manifest.version}\n`);
+    return 0;
+  }
+
+  const interactive = stdin.isTTY === true && stdout.isTTY === true;
+  if (!options.skipUpdateCheck && interactive && env[DISABLE_UPDATE_CHECK_ENV] !== "1") {
+    try {
+      const result = await checkForUpdate({
+        name: mainName,
+        localVersion: manifest.version,
+        manifest,
+        fetchImpl: options.fetchImpl,
+        timeoutMs: options.timeoutMs,
+      });
+      if (result.updateAvailable) {
+        const stateDir = options.stateDir;
+        if (readSkippedVersion(stateDir) !== result.latestVersion) {
+          const notice = formatUpdateNotice({
+            name: mainName,
+            current: manifest.version,
+            latest: result.latestVersion,
+          });
+          const ask = options.askChoice ?? askUpdateChoice;
+          const choice = await ask({ notice, stdin, stdout });
+          if (choice === "update") {
+            const install = options.installGlobal ?? runGlobalInstall;
+            if (install(mainName)) {
+              stdout.write(`\n已更新到 ${result.latestVersion}，请重新执行 cannbot。\n`);
+              return 0;
+            }
+            stderr.write(`\n更新失败。请手动执行：${manualInstallCommand(mainName)}\n\n`);
+          } else if (choice === "skip-version") {
+            writeSkippedVersion(result.latestVersion, stateDir);
+          }
+        }
+      }
+    } catch {
+      // 升级检查是可选增强：任何异常都静默放行，绝不阻断启动
+    }
+  }
+
+  const resolveBinary = options.resolveBinary ?? resolveBinaryPath;
+  const binaryPath = resolveBinary(mainName, os, arch, requireFromHere);
+  if (binaryPath === null) {
+    stderr.write(missingPackageMessage(mainName, os, arch));
+    return 1;
+  }
+
+  ensureExecutable(binaryPath, os);
+  const spawnChild = options.spawnBinary ?? spawnBinary;
+  return await spawnChild(binaryPath, argv);
+}
+
+export const ENTRYPOINT_UNDETERMINED_MESSAGE =
+  "cannwork: 无法确认启动器入口，已跳过执行。\n";
+
+export function entrypointStatus(metaUrl, argv1) {
+  if (typeof argv1 !== "string" || argv1.length === 0) return "not-entrypoint";
+  try {
+    const selfPath = realpathSync(fileURLToPath(metaUrl));
+    const argvPath = realpathSync(resolve(argv1));
+    return selfPath === argvPath ? "entrypoint" : "not-entrypoint";
+  } catch {
+    return "undetermined";
+  }
+}
+
+export function isEntrypoint(metaUrl, argv1) {
+  return entrypointStatus(metaUrl, argv1) === "entrypoint";
+}
+
+const entryStatus = entrypointStatus(import.meta.url, process.argv[1]);
+if (entryStatus === "entrypoint") {
+  run().then((code) => {
+    process.exit(code);
+  });
+} else if (entryStatus === "undetermined") {
+  process.stderr.write(ENTRYPOINT_UNDETERMINED_MESSAGE);
+}

package/bin/update-check.js

@@ -1,206 +1,206 @@
-import { spawnSync } from "node:child_process";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-export const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
-export const UPDATE_CHECK_TIMEOUT_MS = 1500;
-export const DISABLE_UPDATE_CHECK_ENV = "CANNWORK_NO_UPDATE_CHECK";
-export const SKIP_FILE_NAME = "upgrade.json";
-
-const VERSION_PATTERN = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u;
-
-export function parseVersion(raw) {
-  if (typeof raw !== "string") return null;
-  const match = VERSION_PATTERN.exec(raw.trim());
-  if (match === null) return null;
-  return {
-    major: Number(match[1]),
-    minor: Number(match[2]),
-    patch: Number(match[3]),
-    prerelease: match[4] ?? null,
-  };
-}
-
-function comparePrerelease(left, right) {
-  const leftIds = left.split(".");
-  const rightIds = right.split(".");
-  const length = Math.min(leftIds.length, rightIds.length);
-  for (let index = 0; index < length; index += 1) {
-    const leftId = leftIds[index] ?? "";
-    const rightId = rightIds[index] ?? "";
-    const leftNumeric = /^\d+$/u.test(leftId);
-    const rightNumeric = /^\d+$/u.test(rightId);
-    if (leftNumeric && rightNumeric) {
-      const diff = Number(leftId) - Number(rightId);
-      if (diff !== 0) return diff > 0 ? 1 : -1;
-      continue;
-    }
-    if (leftNumeric) return -1;
-    if (rightNumeric) return 1;
-    if (leftId !== rightId) return leftId < rightId ? -1 : 1;
-  }
-  if (leftIds.length === rightIds.length) return 0;
-  return leftIds.length < rightIds.length ? -1 : 1;
-}
-
-export function compareVersions(left, right) {
-  const a = parseVersion(left);
-  const b = parseVersion(right);
-  if (a === null || b === null) return null;
-  for (const key of ["major", "minor", "patch"]) {
-    if (a[key] !== b[key]) return a[key] > b[key] ? 1 : -1;
-  }
-  if (a.prerelease === null && b.prerelease === null) return 0;
-  if (a.prerelease === null) return 1;
-  if (b.prerelease === null) return -1;
-  return comparePrerelease(a.prerelease, b.prerelease);
-}
-
-export function isUpdateAvailable(localVersion, latestVersion) {
-  return compareVersions(latestVersion, localVersion) === 1;
-}
-
-export function resolveRegistry(manifest) {
-  const configured = manifest?.publishConfig?.registry;
-  return typeof configured === "string" && configured.trim().length > 0
-    ? configured.trim()
-    : DEFAULT_REGISTRY;
-}
-
-export function encodePackageName(name) {
-  return encodeURI(name).replace(/\//gu, "%2F");
-}
-
-export function packageLatestUrl(name, registry = DEFAULT_REGISTRY) {
-  const base =
-    typeof registry === "string" && registry.trim().length > 0 ? registry.trim() : DEFAULT_REGISTRY;
-  const withSlash = base.endsWith("/") ? base : `${base}/`;
-  return `${withSlash}${encodePackageName(name)}/latest`;
-}
-
-export async function fetchLatestVersion(name, options = {}) {
-  const {
-    registry = DEFAULT_REGISTRY,
-    timeoutMs = UPDATE_CHECK_TIMEOUT_MS,
-    fetchImpl = globalThis.fetch,
-  } = options;
-  if (typeof fetchImpl !== "function" || typeof name !== "string" || name.length === 0) {
-    return null;
-  }
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), Math.max(1, Number(timeoutMs) || 1));
-  try {
-    const response = await fetchImpl(packageLatestUrl(name, registry), {
-      headers: { Accept: "application/json" },
-      signal: controller.signal,
-    });
-    if (response === null || typeof response !== "object" || response.ok !== true) return null;
-    const body = await response.json();
-    const version = body?.version;
-    return typeof version === "string" && version.trim().length > 0 ? version.trim() : null;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-export async function checkForUpdate(options = {}) {
-  const {
-    name,
-    localVersion,
-    manifest,
-    fetchImpl,
-    timeoutMs = UPDATE_CHECK_TIMEOUT_MS,
-  } = options;
-  const latestVersion = await fetchLatestVersion(name, {
-    registry: resolveRegistry(manifest),
-    timeoutMs,
-    fetchImpl,
-  });
-  return {
-    latestVersion,
-    updateAvailable: latestVersion !== null && isUpdateAvailable(localVersion, latestVersion),
-  };
-}
-
-export function upgradeStateDir() {
-  return join(homedir(), ".cannwork-tui");
-}
-
-export function upgradeStatePath(dir = upgradeStateDir()) {
-  return join(dir, SKIP_FILE_NAME);
-}
-
-export function readSkippedVersion(dir = upgradeStateDir()) {
-  try {
-    const parsed = JSON.parse(readFileSync(upgradeStatePath(dir), "utf8"));
-    const value = parsed?.skippedVersion;
-    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
-  } catch {
-    return null;
-  }
-}
-
-export function writeSkippedVersion(version, dir = upgradeStateDir()) {
-  if (typeof version !== "string" || version.trim().length === 0) return false;
-  try {
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(
-      upgradeStatePath(dir),
-      `${JSON.stringify({ skippedVersion: version.trim() }, null, 2)}\n`,
-      "utf8",
-    );
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export function parseUpdateChoice(raw) {
-  const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
-  if (value === "1" || value === "u" || value === "y") return "update";
-  if (value === "3" || value === "v") return "skip-version";
-  return "skip";
-}
-
-export function formatUpdateNotice({ name, current, latest }) {
-  return [
-    `发现 cannwork 新版本：${current} -> ${latest}`,
-    `  [1] 更新（执行 npm install -g ${name}@latest）`,
-    "  [2] 跳过（仅本次）",
-    "  [3] 跳过此版本（不再提示该版本）",
-  ].join("\n");
-}
-
-export async function askUpdateChoice({ notice, stdin = process.stdin, stdout = process.stdout }) {
-  const readline = await import("node:readline/promises");
-  const rl = readline.createInterface({ input: stdin, output: stdout });
-  try {
-    const answer = await rl.question(`${notice}\n请选择 [1/2/3]: `);
-    return parseUpdateChoice(answer);
-  } catch {
-    return "skip";
-  } finally {
-    rl.close();
-  }
-}
-
-export function manualInstallCommand(name) {
-  return `npm install -g ${name}@latest`;
-}
-
-export function runGlobalInstall(name, options = {}) {
-  const { spawnImpl = spawnSync, platform = process.platform } = options;
-  if (typeof name !== "string" || name.trim().length === 0) return false;
-  try {
-    const result = spawnImpl("npm", ["install", "-g", `${name.trim()}@latest`], {
-      stdio: "inherit",
-      shell: platform === "win32",
-    });
-    return result?.status === 0;
-  } catch {
-    return false;
-  }
-}
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+export const UPDATE_CHECK_TIMEOUT_MS = 1500;
+export const DISABLE_UPDATE_CHECK_ENV = "CANNWORK_NO_UPDATE_CHECK";
+export const SKIP_FILE_NAME = "upgrade.json";
+
+const VERSION_PATTERN = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u;
+
+export function parseVersion(raw) {
+  if (typeof raw !== "string") return null;
+  const match = VERSION_PATTERN.exec(raw.trim());
+  if (match === null) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ?? null,
+  };
+}
+
+function comparePrerelease(left, right) {
+  const leftIds = left.split(".");
+  const rightIds = right.split(".");
+  const length = Math.min(leftIds.length, rightIds.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftId = leftIds[index] ?? "";
+    const rightId = rightIds[index] ?? "";
+    const leftNumeric = /^\d+$/u.test(leftId);
+    const rightNumeric = /^\d+$/u.test(rightId);
+    if (leftNumeric && rightNumeric) {
+      const diff = Number(leftId) - Number(rightId);
+      if (diff !== 0) return diff > 0 ? 1 : -1;
+      continue;
+    }
+    if (leftNumeric) return -1;
+    if (rightNumeric) return 1;
+    if (leftId !== rightId) return leftId < rightId ? -1 : 1;
+  }
+  if (leftIds.length === rightIds.length) return 0;
+  return leftIds.length < rightIds.length ? -1 : 1;
+}
+
+export function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  if (a === null || b === null) return null;
+  for (const key of ["major", "minor", "patch"]) {
+    if (a[key] !== b[key]) return a[key] > b[key] ? 1 : -1;
+  }
+  if (a.prerelease === null && b.prerelease === null) return 0;
+  if (a.prerelease === null) return 1;
+  if (b.prerelease === null) return -1;
+  return comparePrerelease(a.prerelease, b.prerelease);
+}
+
+export function isUpdateAvailable(localVersion, latestVersion) {
+  return compareVersions(latestVersion, localVersion) === 1;
+}
+
+export function resolveRegistry(manifest) {
+  const configured = manifest?.publishConfig?.registry;
+  return typeof configured === "string" && configured.trim().length > 0
+    ? configured.trim()
+    : DEFAULT_REGISTRY;
+}
+
+export function encodePackageName(name) {
+  return encodeURI(name).replace(/\//gu, "%2F");
+}
+
+export function packageLatestUrl(name, registry = DEFAULT_REGISTRY) {
+  const base =
+    typeof registry === "string" && registry.trim().length > 0 ? registry.trim() : DEFAULT_REGISTRY;
+  const withSlash = base.endsWith("/") ? base : `${base}/`;
+  return `${withSlash}${encodePackageName(name)}/latest`;
+}
+
+export async function fetchLatestVersion(name, options = {}) {
+  const {
+    registry = DEFAULT_REGISTRY,
+    timeoutMs = UPDATE_CHECK_TIMEOUT_MS,
+    fetchImpl = globalThis.fetch,
+  } = options;
+  if (typeof fetchImpl !== "function" || typeof name !== "string" || name.length === 0) {
+    return null;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(1, Number(timeoutMs) || 1));
+  try {
+    const response = await fetchImpl(packageLatestUrl(name, registry), {
+      headers: { Accept: "application/json" },
+      signal: controller.signal,
+    });
+    if (response === null || typeof response !== "object" || response.ok !== true) return null;
+    const body = await response.json();
+    const version = body?.version;
+    return typeof version === "string" && version.trim().length > 0 ? version.trim() : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function checkForUpdate(options = {}) {
+  const {
+    name,
+    localVersion,
+    manifest,
+    fetchImpl,
+    timeoutMs = UPDATE_CHECK_TIMEOUT_MS,
+  } = options;
+  const latestVersion = await fetchLatestVersion(name, {
+    registry: resolveRegistry(manifest),
+    timeoutMs,
+    fetchImpl,
+  });
+  return {
+    latestVersion,
+    updateAvailable: latestVersion !== null && isUpdateAvailable(localVersion, latestVersion),
+  };
+}
+
+export function upgradeStateDir() {
+  return join(homedir(), ".cannwork-tui");
+}
+
+export function upgradeStatePath(dir = upgradeStateDir()) {
+  return join(dir, SKIP_FILE_NAME);
+}
+
+export function readSkippedVersion(dir = upgradeStateDir()) {
+  try {
+    const parsed = JSON.parse(readFileSync(upgradeStatePath(dir), "utf8"));
+    const value = parsed?.skippedVersion;
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeSkippedVersion(version, dir = upgradeStateDir()) {
+  if (typeof version !== "string" || version.trim().length === 0) return false;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      upgradeStatePath(dir),
+      `${JSON.stringify({ skippedVersion: version.trim() }, null, 2)}\n`,
+      "utf8",
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function parseUpdateChoice(raw) {
+  const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+  if (value === "1" || value === "u" || value === "y") return "update";
+  if (value === "3" || value === "v") return "skip-version";
+  return "skip";
+}
+
+export function formatUpdateNotice({ name, current, latest }) {
+  return [
+    `发现 cannwork 新版本：${current} -> ${latest}`,
+    `  [1] 更新（执行 npm install -g ${name}@latest）`,
+    "  [2] 跳过（仅本次）",
+    "  [3] 跳过此版本（不再提示该版本）",
+  ].join("\n");
+}
+
+export async function askUpdateChoice({ notice, stdin = process.stdin, stdout = process.stdout }) {
+  const readline = await import("node:readline/promises");
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question(`${notice}\n请选择 [1/2/3]: `);
+    return parseUpdateChoice(answer);
+  } catch {
+    return "skip";
+  } finally {
+    rl.close();
+  }
+}
+
+export function manualInstallCommand(name) {
+  return `npm install -g ${name}@latest`;
+}
+
+export function runGlobalInstall(name, options = {}) {
+  const { spawnImpl = spawnSync, platform = process.platform } = options;
+  if (typeof name !== "string" || name.trim().length === 0) return false;
+  try {
+    const result = spawnImpl("npm", ["install", "-g", `${name.trim()}@latest`], {
+      stdio: "inherit",
+      shell: platform === "win32",
+    });
+    return result?.status === 0;
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "cannwork-rehearsal",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "bin": {
-    "cannwork": "bin/cannwork.js"
+    "cannbot": "bin/cannbot.js"
   },
   "files": [
     "bin",
     "README.md"
   ],
   "optionalDependencies": {
-    "cannwork-rehearsal-win32-x64": "0.4.1",
-    "cannwork-rehearsal-linux-x64": "0.4.1",
-    "cannwork-rehearsal-linux-arm64": "0.4.1",
-    "cannwork-rehearsal-darwin-x64": "0.4.1",
-    "cannwork-rehearsal-darwin-arm64": "0.4.1"
+    "cannwork-rehearsal-win32-x64": "0.5.0",
+    "cannwork-rehearsal-linux-x64": "0.5.0",
+    "cannwork-rehearsal-linux-arm64": "0.5.0",
+    "cannwork-rehearsal-darwin-x64": "0.5.0",
+    "cannwork-rehearsal-darwin-arm64": "0.5.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",