omnicrawl-cli 0.1.71 → 0.2.1

package/README.md

@@ -1,75 +1,59 @@
-# omnicrawl-cli
-
-OmniCrawl 启动器：按 `platform-arch` 选包node_modules的内核二进制，把 stdio 转交给它。
-它不做协议转换——宿主直接与内核进程对话（协议见 `rust/docs/protocol-v1.md`）。
-
-## 分发形态
-
-| npm 包 | 内容 |
-| --- | --- |
-| `omnicrawl-cli` | JS 启动器（`bin/omnicrawl.mjs`） |
-| `@omnicrawl/cli-linux-x64` | 内核二进制（Linux x64，musl 静态） |
-| `@omnicrawl/cli-linux-arm-musl` | 内核二进制（Linux armv7，musl 静态，嵌入式目标） |
-| `@omnicrawl/cli-linux-arm64-musl` | 内核二进制（Linux arm64，嵌入式目标） |
-| `@omnicrawl/cli-win32-x64` | 内核二进制（Windows x64） |
-
-**平台分包、`os`/`cpu` 与平台依赖只出现在发布产物里**（`dist/npm/`）。仓库内的 `packages/cli*/package.json`
-刻意不带 `os`/`cpu`、也不声明平台分包依赖：npm 安装时会校验工作区成员的 `os`/`cpu`，带上就直接
-`notsup` 失败。发布产物由 `scripts/prepare.mjs` 生成。
-
-## 本地开发
-
-```bash
-cargo build --release -p omnicrawl-cli      # 产物：rust/target/release/omnicrawl[.exe]
-node packages/cli/scripts/prepare.mjs       # 暂存发布产物（缺的平台只警告）
-npm test -w omnicrawl-cli                  # e2e：真二进制 + 协议 v1
-OMNICRAWL_BINARY=/path/to/omnicrawl node packages/cli/bin/omnicrawl.mjs --version
-```
-
-工作区里 `@omnicrawl/cli-*` 都是 workspace 成员，启动器靠 `createRequire` 解析到它们；
-`OMNICRAWL_BINARY` 是直接指定二进制的逃生口（e2e 用的就是它）。e2e 需要 `rust/target/release`
-里有产物，否则跳过并打印构建命令。
-
-## 发布
-
-手动发布前先 `npm login`（CI 走 Trusted Publishing，无需登录与 token）。
-
-1. 交叉编译各平台（Linux 走 musl 静态，嵌入式目标优先）：
-
-   ```bash
-   cargo build --release -p omnicrawl-cli --target x86_64-pc-windows-msvc
-   cargo build --release -p omnicrawl-cli --target x86_64-unknown-linux-musl
-   cargo build --release -p omnicrawl-cli --target aarch64-unknown-linux-musl
-   cargo build --release -p omnicrawl-cli --target armv7-unknown-linux-musleabihf
-   ```
-
-   非 Linux 宿主没有 musl 链接器，Linux 目标改用 `cargo zigbuild`（需 `zig` 与
-   `rustup target add <triple>`）：
-
-   ```bash
-   cargo zigbuild --release -p omnicrawl-cli --target armv7-unknown-linux-musleabihf
-   ```
-
-2. 门槛检查（缺任何平台会失败并列出缺失平台）：
-
-   ```bash
-   node packages/cli/scripts/prepare.mjs --require-all
-   ```
-
-3. 按顺序发布暂存产物：平台包在前，启动器在后（启动器的 `optionalDependencies` 是精确版本，顺序反了会装不到）：
-
-   ```bash
-   npm publish dist/npm/cli-linux-x64
-   npm publish dist/npm/cli-linux-arm-musl
-   npm publish dist/npm/cli-linux-arm64-musl
-   npm publish dist/npm/cli-win32-x64
-   npm publish dist/npm/cli
-   ```
-
-   脚本跑完会把这几行命令直接打出来。
-
-4. 版本reproducibility：平台分包与启动器同版本；平台包只装二进制，升级它们就是换内核。
-
-## 发布前自检
-
-`cargo test --workspace`、`npm test --workspaces`，以及 `prepare --require-all` 门槛。
+# omnicrawl-cli
+
+OmniCrawl 启动器：按 `platform-arch` 选平台分包，默认启动**完整宿主**（工作台 / `api` / 插件 CLI）；
+`kernel` 子命令把 stdio 交给内核二进制（协议调试与 e2e）。
+
+## 分发形态
+
+| npm 包 | 内容 |
+| --- | --- |
+| `omnicrawl-cli` | JS 启动器（`bin/omnicrawl.mjs`） |
+| `@omnicrawl/cli-win32-x64` | 内核二进制 + 宿主载荷（Windows x64） |
+| `@omnicrawl/cli-linux-x64` | 内核二进制 + 宿主载荷（Linux x64，内核为 musl 静态） |
+| `@omnicrawl/cli-linux-arm64-musl` | 内核二进制 + 宿主载荷（Linux arm64） |
+| `@omnicrawl/cli-win32-ia32` | 仅内核（32 位 Windows 缺运行期轮子） |
+| `@omnicrawl/cli-linux-arm-musl` | 仅内核（armv7 嵌入式目标） |
+
+宿主载荷是 PyInstaller one-dir 产物（`host/`）：CPython 运行时、依赖、代码与资源都在里面，
+用户机器不需要 Python 或 pip。没有宿主载荷的平台由启动器退回内核直连，并打印这一边界。
+
+**平台分包、`os`/`cpu` 与平台依赖只出现在发布产物里**（`dist/npm/`）。仓库内的 `packages/cli*/package.json`
+刻意不带 `os`/`cpu`、也不声明平台分包依赖：npm 安装时会校验工作区成员的 `os`/`cpu`，带上就直接
+`notsup` 失败。发布产物由 `scripts/prepare.mjs` 生成。
+
+## 命令面
+
+```
+omnicrawl                 启动工作台（TUI）
+omnicrawl api             启动本地 HTTP 服务（无头/服务器场景）
+omnicrawl plugin ...      插件管理
+omnicrawl kernel ...      直连内核进程（协议调试）
+omnicrawl --version       打印启动器、平台包、宿主与内核版本
+```
+
+无交互式终端时宿主会直接给出改用 `api` 的提示并以 2 退出，不会停在协议等待状态。
+
+## 本地开发
+
+```bash
+cargo build --release -p omnicrawl-cli        # 产物：rust/target/release/omnicrawl[.exe]
+node packages/cli/scripts/build-host.mjs      # 宿主载荷：dist/host/<platform>/payload
+node packages/cli/scripts/prepare.mjs         # 暂存发布产物（缺的平台只警告）
+node packages/cli/scripts/host-smoke.mjs      # 宿主冒烟：无终端提示 + 退出码
+node packages/cli/scripts/install-smoke.mjs   # 安装冒烟：干净前缀里真装真跑
+npm test -w omnicrawl-cli                     # e2e：真二进制 + 协议 v1
+```
+
+宿主载荷只能与构建机同架构（里面有 CPython 与原生扩展），交叉构建不成立：
+其它平台由 CI 在各自 runner 上构建（见 `.github/workflows/publish-npm.yml`）。
+
+两个逃生口：`OMNICRAWL_HOST` 直接指定宿主、`OMNICRAWL_BINARY` 直接指定内核（此时启动器是纯透传）。
+
+## 发布
+
+1. 升 `packages/cli/package.json` 版本（平台包与启动器同版本）。
+2. 推 `npm-v<版本>` tag（CI 会校验 tag 与包版本一致）或手动触发 workflow：
+   矩阵各平台构建内核（+ 宿主）→ 宿主冒烟 → 暂存并上传产物；
+   发布任务下载全部产物 → 暂存启动器 → 安装冒烟 → 平台包在前、启动器在后依次发布。
+
+发布前自检：`cargo test --workspace`、`npm test --workspaces`、`prepare.mjs --require-all --require-host`。

package/bin/omnicrawl.mjs

@@ -1,9 +1,12 @@
-#!/usr/bin/env node
-// OmniCrawl 启动器：按 platform/arch 选出内核二进制并转交 stdio。
+#!/usr/bin/env node
+// OmniCrawl 启动器：按 platform/arch 选出平台分包，默认启动完整宿主（工作台 / api / plugin 指令），
+// `kernel` 子命令把 stdio 交给内核二进制（协议调试与 e2e）。
 //
-// 它不做任何协议转换——宿主直接与内核进程对话，启动器只是平台分包的解析器。
+// 两个逃生口（开发与协议测试用）：
+//   OMNICRAWL_HOST=<可执行文件>   直接指定宿主，跳过平台分包
+//   OMNICRAWL_BINARY=<可执行文件> 直接指定内核；此时启动器退化为纯透传，便于协议测试
 import { spawn } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { chmodSync, existsSync, readFileSync, statSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
 import process from 'node:process'
@@ -16,44 +19,142 @@ const PLATFORM_PACKAGES = {
   'win32-ia32': '@omnicrawl/cli-win32-ia32',
 }
 
-function resolveBinary() {
-  // 开发与测试用的逃生口：跳过分包直接指定二进制。
-  if (process.env.OMNICRAWL_BINARY) return process.env.OMNICRAWL_BINARY
+const IS_WINDOWS = process.platform === 'win32'
+const HOST_FILE = IS_WINDOWS ? 'omnicrawl-host.exe' : 'omnicrawl-host'
+const KERNEL_FILE = IS_WINDOWS ? 'omnicrawl.exe' : 'omnicrawl'
+const KERNEL_COMMAND = 'kernel'
 
+const launcherVersion = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version
+
+function fail(message) {
+  console.error(message)
+  process.exit(1)
+}
+
+/** 解析平台分包根目录；拿不到分包时抛出可直接展示的错误。 */
+function resolvePlatform() {
   const key = `${process.platform}-${process.arch}`
   const packageName = PLATFORM_PACKAGES[key]
   if (!packageName) {
     throw new Error(`不支持的平台 ${key}；已支持：${Object.keys(PLATFORM_PACKAGES).join('、')}`)
   }
-
   const require = createRequire(import.meta.url)
-  const packageRoot = dirname(require.resolve(`${packageName}/package.json`))
-  const binary = join(packageRoot, 'bin', process.platform === 'win32' ? 'omnicrawl.exe' : 'omnicrawl')
-  if (!existsSync(binary)) {
-    throw new Error(`平台分包 ${packageName} 里没有二进制：${binary}\n请重装该包，或用 OMNICRAWL_BINARY 指定。`)
+  return { packageName, root: dirname(require.resolve(`${packageName}/package.json`)) }
+}
+
+/** 目标可执行文件：宿主优先，内核兜底；两个环境变量各自覆盖。 */
+function resolveTargets() {
+  if (process.env.OMNICRAWL_HOST) {
+    return { host: process.env.OMNICRAWL_HOST, kernel: process.env.OMNICRAWL_BINARY ?? null, passthrough: false }
+  }
+  if (process.env.OMNICRAWL_BINARY) {
+    return { host: null, kernel: process.env.OMNICRAWL_BINARY, passthrough: true }
+  }
+  const { packageName, root } = resolvePlatform()
+  return {
+    host: join(root, 'host', HOST_FILE),
+    kernel: join(root, 'bin', KERNEL_FILE),
+    packageName,
+    root,
+    passthrough: false,
   }
-  return binary
 }
 
-let binary
-try {
-  binary = resolveBinary()
-} catch (error) {
-  console.error(`omnicrawl：${error.message}`)
-  process.exit(1)
+function readPayloadMeta(root) {
+  if (!root) return null
+  try {
+    return JSON.parse(readFileSync(join(root, 'version.json'), 'utf8'))
+  } catch {
+    return null
+  }
 }
 
-const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' })
+function printVersion(targets) {
+  const meta = readPayloadMeta(targets.root)
+  const lines = [`omnicrawl ${launcherVersion}`]
+  lines.push(
+    targets.packageName
+      ? `${targets.packageName} ${meta?.version ?? '未知'}（${process.platform}-${process.arch} 平台包）`
+      : `omnicrawl-cli ${launcherVersion}（启动器）`,
+  )
+  if (meta?.hostVersion) lines.push(`omnicrawl-agent ${meta.hostVersion}（宿主）`)
+  if (meta?.kernelVersion) lines.push(`omnicrawl ${meta.kernelVersion}（内核）`)
+  console.log(lines.join('\n'))
+}
 
-child.on('error', (error) => {
-  console.error(`omnicrawl：无法启动 ${binary}：${error.message}`)
-  process.exit(1)
-})
+function printHelp() {
+  console.log(
+    `用法：omnicrawl [选项] [指令]\n\n\
+  无参数        启动工作台（TUI）\n\
+  api           启动本地 HTTP 服务（无头/服务器场景）\n\
+  plugin ...    插件管理\n\
+  kernel ...    直连内核进程（协议调试）\n\n\
+  --resume <会话 ID>   启动时恢复指定会话\n\
+  --version, -V        打印启动器、平台包、宿主与内核版本\n\
+  --help, -h           打印本说明`,
+  )
+}
 
-child.on('exit', (code, signal) => {
-  if (signal) {
-    console.error(`omnicrawl：内核被信号 ${signal} 终止`)
+/** npm 打包会把未在 bin 里声明的文件权限位归一化成 0644，POSIX 下按需补回可执行位。 */
+function ensureExecutable(path) {
+  if (IS_WINDOWS) return
+  try {
+    const mode = statSync(path).mode
+    if ((mode & 0o111) === 0) chmodSync(path, mode | 0o755)
+  } catch {
+    // 权限改不动（只读文件系统等）时交给 spawn 的错误说明原因。
+  }
+}
+
+/** 把 stdio 交给目标可执行文件，并把它的退出码/信号作为本次退出状态。 */
+function run(executable, args) {
+  if (!executable || !existsSync(executable)) {
+    fail(`omnicrawl：找不到可执行文件 ${executable ?? '(未解析到)'}。请重装对应的平台包。`)
+  }
+  ensureExecutable(executable)
+  const child = spawn(executable, args, { stdio: 'inherit' })
+
+  child.on('error', (error) => {
+    console.error(`omnicrawl：无法启动 ${executable}：${error.message}`)
     process.exit(1)
+  })
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      console.error(`omnicrawl：${executable} 被信号 ${signal} 终止`)
+      process.exit(1)
+    }
+    process.exit(code ?? 0)
+  })
+}
+
+function main() {
+  let targets
+  try {
+    targets = resolveTargets()
+  } catch (error) {
+    fail(`omnicrawl：${error.message}`)
   }
-  process.exit(code ?? 0)
-})
+
+  const args = process.argv.slice(2)
+
+  // 内核透传模式（OMNICRAWL_BINARY）：启动器不介入 stdio 上的协议帧。
+  if (targets.passthrough) return run(targets.kernel, args)
+
+  if (args[0] === KERNEL_COMMAND) return run(targets.kernel, args.slice(1))
+  if (args.includes('--version') || args.includes('-V')) return printVersion(targets)
+  if (args.includes('--help') || args.includes('-h')) return printHelp()
+
+  if (targets.host && existsSync(targets.host)) return run(targets.host, args)
+
+  // 嵌入式目标（armv7 等）没有宿主载荷：退回内核直连，并说明这一平台的边界。
+  console.error(
+    `omnicrawl：平台包 ${targets.packageName ?? '(未指定)'} 没有宿主载荷，退回内核直连；` +
+      '该平台只支持协议模式（用 omnicrawl kernel 显式进入）。',
+  )
+  return run(targets.kernel, args)
+}
+
+main()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "omnicrawl-cli",
-  "version": "0.1.71",
-  "description": "OmniCrawl 启动器：按平台选择内核二进制并转交 stdio",
+  "version": "0.2.1",
+  "description": "OmniCrawl 启动器：按平台启动完整宿主（工作台 / api / 插件）",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cccchiban/omnicrawl.git",
@@ -20,14 +20,15 @@
   },
   "scripts": {
     "test": "node --test",
+    "build:host": "node scripts/build-host.mjs",
     "prepare:binaries": "node scripts/prepare.mjs"
   },
   "license": "MIT",
   "optionalDependencies": {
-    "@omnicrawl/cli-win32-x64": "0.1.71",
-    "@omnicrawl/cli-win32-ia32": "0.1.71",
-    "@omnicrawl/cli-linux-x64": "0.1.71",
-    "@omnicrawl/cli-linux-arm-musl": "0.1.71",
-    "@omnicrawl/cli-linux-arm64-musl": "0.1.71"
+    "@omnicrawl/cli-win32-x64": "0.2.1",
+    "@omnicrawl/cli-win32-ia32": "0.2.1",
+    "@omnicrawl/cli-linux-x64": "0.2.1",
+    "@omnicrawl/cli-linux-arm-musl": "0.2.1",
+    "@omnicrawl/cli-linux-arm64-musl": "0.2.1"
   }
 }