@vantaloom/cli 0.15.35 → 0.15.37

package/src/cli.mjs

@@ -1,495 +1,528 @@
-import {
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-} from "node:fs"
-import os from "node:os"
-import path from "node:path"
-import {
-  cliRoot,
-  defaultNpmRegistry,
-  fallbackNpmRegistries,
-} from "./lib/constants.mjs"
-import {
-  platformId,
-  runtimePackageName,
-  safeDirectory,
-  defaultPrefix,
-  displayCommand,
-  readJSONIfExists,
-  normalizeRegistry,
-  packageBasename,
-  toCamel,
-  removeKnownPath,
-  run,
-} from "./lib/platform.mjs"
-import {
-  applyPackage,
-  findSourceRoot,
-  tryFindSourceRoot,
-  tryAssertSourceRoot,
-  readInstalledConfig,
-  writeRuntimePackageMetadata,
-  ensureInPath,
-} from "./lib/install.mjs"
-import { buildRuntimePackage } from "./lib/package.mjs"
-import {
-  resolveNpmPackageWithFallback,
-  downloadNpmTarball,
-  findExtractedNpmPackage,
-} from "./lib/registry.mjs"
-import {
-  runCtl,
-  uninstallRuntime,
-} from "./lib/lifecycle.mjs"
-import {
-  runLogin,
-  runLogout,
-  localApiBase,
-} from "./lib/auth.mjs"
-
-// Inherit strict-ssl=false from npm/npx config, or respect NODE_TLS_REJECT_UNAUTHORIZED.
-// When npm runs us via npx with strict-ssl disabled, it sets npm_config_strict_ssl="false".
-// Also check user .npmrc for strict-ssl=false (common in China behind proxies).
-function shouldDisableTLS() {
-  if (process.env.NODE_TLS_REJECT_UNAUTHORIZED === "0") return true
-  if (process.env.npm_config_strict_ssl === "false") return true
-  if (process.env.npm_config_strict_ssl === "") return true
-  try {
-    const npmrcPath = path.join(os.homedir(), ".npmrc")
-    if (existsSync(npmrcPath)) {
-      const content = readFileSync(npmrcPath, "utf8")
-      if (/^\s*strict-ssl\s*=\s*false/m.test(content)) return true
-    }
-  } catch {}
-  return false
-}
-if (shouldDisableTLS()) {
-  process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"
-}
-
-const cliVersion = readJSONIfExists(path.join(cliRoot, "package.json")).version ?? "unknown"
-
-export async function main(argv) {
-  const command = argv[0] ?? "help"
-  const options = parseOptions(argv.slice(1))
-
-  // --no-strict-ssl flag disables TLS certificate verification for fetch calls
-  if (options.noStrictSsl) {
-    process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"
-  }
-
-  if (command === "install" || command === "update") {
-    console.log(`vantaloom-cli v${cliVersion} (${platformId()})`)
-  }
-
-  switch (command) {
-    case "install":
-      if (options.package) {
-        await installFromPackage({ ...options, update: false })
-      } else if (shouldUseSourceInstall(options)) {
-        await installFromSource(options)
-      } else {
-        await syncFromNpmRegistry(options, "install")
-      }
-      return
-    case "update":
-      if (options.package) {
-        await installFromPackage({ ...options, update: true })
-      } else if (shouldUseSourceInstall(options)) {
-        await installFromSource({ ...options, update: true })
-      } else {
-        await syncFromNpmRegistry(options, "update")
-      }
-      return
-    case "package":
-      await packageRuntime(options)
-      return
-    case "platform":
-      console.log(platformId())
-      return
-    case "start":
-    case "stop":
-    case "restart":
-    case "status":
-    case "ports":
-      runCtl(command, options)
-      return
-    case "path":
-      printPaths(options)
-      return
-    case "uninstall":
-      await uninstallRuntime(options)
-      return
-    case "login":
-      await runLogin(options)
-      return
-    case "logout":
-      await runLogout(options)
-      return
-    case "bootstrap":
-      await runBootstrap(options)
-      return
-    case "help":
-    case "-h":
-    case "--help":
-      printHelp()
-      return
-    default:
-      throw new Error(`unknown command "${command}"`)
-  }
-}
-
-async function installFromSource(options) {
-  const sourceRoot = findSourceRoot(options.source)
-  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
-  const buildRoot = path.join(sourceRoot, "artifacts", "local-install", platformId())
-
-  const { version } = await buildRuntimePackage(sourceRoot, buildRoot, {
-    buildWeb: options.buildWeb,
-  })
-
-  await applyPackage(buildRoot, prefix, {
-    noStart: options.noStart,
-    sourceRoot,
-    update: options.update,
-  })
-
-  console.log(`${options.update ? "updated" : "installed"} Vantaloom: ${prefix}`)
-  console.log(`version: ${version}`)
-  ensureInPath(prefix)
-  console.log(`run: ${displayCommand(prefix)} status`)
-}
-
-async function installFromPackage(options) {
-  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
-  const packageRoot = safeDirectory(options.package)
-  const version = await applyPackage(packageRoot, prefix, {
-    noStart: options.noStart,
-    update: options.update,
-  })
-
-  console.log(`${options.update ? "updated" : "installed"} Vantaloom: ${prefix}`)
-  console.log(`version: ${version}`)
-  ensureInPath(prefix)
-  console.log(`run: ${displayCommand(prefix)} status`)
-}
-
-async function packageRuntime(options) {
-  const sourceRoot = findSourceRoot(options.source)
-  const targetPlatform = options.target ?? platformId()
-  const packageRoot = safeDirectory(
-    options.output ?? path.join(sourceRoot, "artifacts", "packages", `vantaloom-${targetPlatform}`)
-  )
-  const { platform: builtPlatform, version } = await buildRuntimePackage(sourceRoot, packageRoot, {
-    buildWeb: options.buildWeb,
-    target: targetPlatform,
-    npmPackage: options.npmPackage,
-  })
-
-  if (options.npmPackage) {
-    writeRuntimePackageMetadata(packageRoot, sourceRoot, builtPlatform)
-  }
-
-  if (options.archive) {
-    const archivePath = `${packageRoot}.tar.gz`
-    removeKnownPath(archivePath, path.dirname(archivePath))
-    run("tar", [
-      "-czf",
-      archivePath,
-      "-C",
-      path.dirname(packageRoot),
-      path.basename(packageRoot),
-    ])
-    console.log(`archive: ${archivePath}`)
-  }
-
-  console.log(`packaged Vantaloom: ${packageRoot}`)
-  console.log(`platform: ${builtPlatform}`)
-  console.log(`version: ${version}`)
-}
-
-async function syncFromNpmRegistry(options, action) {
-  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
-  const installedConfig = readInstalledConfig(prefix)
-  // Always derive runtimePackage from current platform — never trust stale config
-  // from a different platform (e.g. win32 config baked into a darwin package).
-  // Only explicit --runtime-package flag can override.
-  const runtimePackage = options.runtimePackage || runtimePackageName(platformId())
-  const runtimeVersion = options.runtimeVersion || installedConfig.runtimeVersion || "latest"
-  const explicitRegistry = options.npmRegistry || installedConfig.npmRegistry
-  // Resolve against npmjs.org — the registry the runtime packages are published
-  // to. Ambient mirror config (npm_config_registry / .npmrc) is deliberately NOT
-  // adopted: mirrors lag on dist-tags (npmmirror still served "latest" = 0.6.12
-  // months after 0.15.x shipped), and trusting one turns an update into a silent
-  // rollback. Mirrors stay in the fallback chain for unreachable-network cases.
-  const registry = normalizeRegistry(explicitRegistry || defaultNpmRegistry)
-  const tempRoot = mkdtempSync(path.join(os.tmpdir(), "vantaloom-npm-"))
-
-  try {
-    const extractRoot = path.join(tempRoot, "extract")
-    const archive = path.join(tempRoot, `${packageBasename(runtimePackage)}-${runtimeVersion}.tgz`)
-    mkdirSync(extractRoot, { recursive: true })
-
-    const resolved = await resolveNpmPackageWithFallback({
-      registries: explicitRegistry ? [registry] : [registry, ...fallbackNpmRegistries.map(normalizeRegistry)],
-      name: runtimePackage,
-      version: runtimeVersion,
-    })
-    assertNotDowngrade({ prefix, resolved, runtimePackage, options, action })
-    await downloadNpmTarball({
-      tarballUrl: resolved.tarball,
-      target: archive,
-      packageName: runtimePackage,
-      version: resolved.version,
-    })
-    run("tar", ["-xzf", archive, "-C", extractRoot])
-
-    const packageRoot = findExtractedNpmPackage(extractRoot)
-    const version = await applyPackage(packageRoot, prefix, {
-      noStart: options.noStart,
-      runtimePackage,
-      runtimeVersion: options.runtimeVersion ? resolved.version : "latest",
-      npmRegistry: resolved.registry,
-      update: action === "update",
-    })
-
-    console.log(`${action === "update" ? "updated" : "installed"} Vantaloom: ${prefix}`)
-    console.log(`version: ${version}`)
-    console.log(`source: ${runtimePackage}@${resolved.version}`)
-    console.log(`registry: ${resolved.registry}`)
-    ensureInPath(prefix)
-    console.log(`run: ${displayCommand(prefix)} status`)
-  } finally {
-    removeKnownPath(tempRoot, os.tmpdir())
-  }
-}
-
-// A registry mirror can answer "latest" with a version far older than the one
-// already installed (npmmirror did exactly that: 0.6.12 long after 0.15.x
-// shipped), turning an update into a silent rollback. Refuse it unless the
-// caller asked for that exact version or opted in explicitly.
-function assertNotDowngrade({ prefix, resolved, runtimePackage, options, action }) {
-  if (action !== "update" || options.runtimeVersion || options.allowDowngrade) {
-    return
-  }
-  const installed = readRuntimeVersion(prefix)
-  if (!isOlderVersion(resolved.version, installed)) {
-    return
-  }
-  throw new Error(
-    `${resolved.registry} offers ${runtimePackage}@${resolved.version}, older than the installed ${installed}.\n` +
-    `  A mirror whose dist-tags lag behind npmjs.org is the usual cause.\n` +
-    `  Retry with --npm-registry https://registry.npmjs.org/, or pass --allow-downgrade to install it anyway.`
-  )
-}
-
-// Installed runtime version ("" when absent/unreadable — never block on it).
-function readRuntimeVersion(prefix) {
-  try {
-    return readFileSync(path.join(prefix, "VERSION"), "utf8").trim()
-  } catch {
-    return ""
-  }
-}
-
-// candidate < installed on the X.Y.Z triple (a -/+ suffix on patch is ignored).
-// Non-semver on either side → false: never block a locally built or unversioned
-// install from being replaced.
-function isOlderVersion(candidate, installed) {
-  const parse = (value) => {
-    const parts = String(value).split(".")
-    if (parts.length < 3) {
-      return null
-    }
-    const triple = [parts[0], parts[1], parts.slice(2).join(".").split(/[-+]/)[0]].map(Number)
-    return triple.every(Number.isInteger) ? triple : null
-  }
-  const found = parse(candidate)
-  const current = parse(installed)
-  if (!found || !current) {
-    return false
-  }
-  for (let index = 0; index < 3; index += 1) {
-    if (found[index] !== current[index]) {
-      return found[index] < current[index]
-    }
-  }
-  return false
-}
-
-function shouldUseSourceInstall(options) {
-  return Boolean(options.local || options.source || options.buildWeb)
-}
-
-function printPaths(options) {
-  const sourceRoot = findSourceRoot(options.source)
-  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
-  console.log(JSON.stringify({ sourceRoot, prefix }, null, 2))
-}
-
-function parseOptions(args) {
-  const options = {}
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index]
-    if (!arg.startsWith("--")) {
-      throw new Error(`unexpected argument "${arg}"`)
-    }
-    const [key, inlineValue] = arg.slice(2).split("=", 2)
-    switch (key) {
-      case "prefix":
-      case "source":
-      case "component":
-      case "package":
-      case "output":
-      case "runtime-package":
-      case "runtime-version":
-      case "npm-registry":
-      case "hub":
-      case "email":
-      case "password":
-        options[toCamel(key)] = inlineValue ?? args[++index]
-        if (!options[toCamel(key)]) {
-          throw new Error(`missing value for --${key}`)
-        }
-        break
-      case "build-web":
-        options.buildWeb = true
-        break
-      case "no-start":
-        options.noStart = true
-        break
-      case "archive":
-        options.archive = true
-        break
-      case "npm-package":
-        options.npmPackage = true
-        break
-      case "target":
-        options.target = inlineValue ?? args[++index]
-        if (!options.target) {
-          throw new Error("missing value for --target")
-        }
-        break
-      case "local":
-        options.local = true
-        break
-      case "skip-autostart":
-        options.skipAutostart = true
-        break
-      case "no-strict-ssl":
-        options.noStrictSsl = true
-        break
-      case "allow-downgrade":
-        options.allowDowngrade = true
-        break
-      default:
-        throw new Error(`unknown option --${key}`)
-    }
-  }
-  return options
-}
-
-function printHelp() {
-  console.log(`Vantaloom CLI
-
-Usage:
-  vantaloom install   [--prefix <dir>] [--runtime-version <version>] [--npm-registry <url>] [--package <dir>] [--no-start]
-  vantaloom install   --local [--prefix <dir>] [--source <repo>] [--build-web] [--no-start]
-  vantaloom update    [--prefix <dir>] [--runtime-version <version>] [--npm-registry <url>] [--no-start] [--allow-downgrade]
-  vantaloom update    --local [--prefix <dir>] [--source <repo>] [--build-web] [--no-start]
-  vantaloom uninstall [--prefix <dir>]
-  vantaloom package   [--source <repo>] [--output <dir>] [--build-web] [--archive] [--npm-package] [--target <platform>]
-  vantaloom start     [--prefix <dir>] [--component all|api|agent|web]
-  vantaloom stop      [--prefix <dir>] [--component all|api|agent|web]
-  vantaloom restart   [--prefix <dir>] [--component all|api|agent|web]
-  vantaloom status    [--prefix <dir>]
-  vantaloom ports     [--prefix <dir>]
-  vantaloom path      [--prefix <dir>] [--source <repo>]
-  vantaloom platform
-  vantaloom login     [--hub <url>] [--email <email>] [--password <pw>] [--prefix <dir>]
-  vantaloom logout    [--prefix <dir>]
-  vantaloom bootstrap [--hub <url>] --email <email> --password <pw> [--prefix <dir>] [--runtime-version <ver>] [--npm-registry <url>]
-
-Hub login (for machines with no web access):
-  "vantaloom login" authenticates to the Hub from the terminal and joins this
-  machine to your workgroup — no browser needed. Email/password may be passed as
-  flags (for scripts) or entered interactively. The local runtime must be running
-  (run "vantaloom start" first).
-
-Unattended bootstrap (one command for fresh hosts):
-  "vantaloom bootstrap" installs the runtime from npm, starts it, waits for it
-  to be ready, then logs in to the Hub — all in one step. Designed for ssh/scp
-  deployment scripts and cloud-init. Requires --email/--password (or env
-  VANTALOOM_HUB_EMAIL/VANTALOOM_HUB_PASSWORD) and --hub (or env
-  VANTALOOM_HUB_URL). The runtime auto-starts and reconnects on reboot.
-`)
-}
-
-// runBootstrap = install runtime (from npm) + wait ready + login Hub，一条命令完成无人值守部署。
-// 面向 ssh/scp 远程部署脚本和 cloud-init 场景；用户在远程主机 npm i -g @vantaloom/cli 后
-// 跑这条命令即可把机器加入 workgroup，无需进 UI。
-async function runBootstrap(options) {
-  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
-  const hubUrl = options.hub || process.env.VANTALOOM_HUB_URL || process.env.NEXT_PUBLIC_HUB_URL
-  const email = options.email || process.env.VANTALOOM_HUB_EMAIL
-  const password = options.password || process.env.VANTALOOM_HUB_PASSWORD
-
-  if (!hubUrl) {
-    throw new Error("bootstrap 需要 --hub <url>（或设置 VANTALOOM_HUB_URL 环境变量）")
-  }
-  if (!email || !password) {
-    throw new Error("bootstrap 需要 --email 和 --password（或设置 VANTALOOM_HUB_EMAIL/VANTALOOM_HUB_PASSWORD 环境变量）")
-  }
-
-  // 1. 安装 runtime（从 npm 拉取，自动 start）
-  console.log(`vantaloom-cli v${cliVersion} (${platformId()})`)
-  console.log(`\n▸ 安装 runtime（从 npm）`)
-  const installOpts = { ...options, prefix }
-  // bootstrap 不允许 --no-start，runtime 必须起来才能 login
-  delete installOpts.noStart
-  await syncFromNpmRegistry(installOpts, "install")
-
-  // 2. 等待 runtime 就绪（轮询 /v1/hub/status）
-  const localApi = localApiBase(prefix)
-  console.log(`\n▸ 等待 runtime 就绪（${localApi}）`)
-  let ready = false
-  for (let i = 0; i < 30; i++) {
-    await sleep(2000)
-    try {
-      const res = await fetch(`${localApi}/v1/hub/status`)
-      if (res.ok) {
-        ready = true
-        console.log(`  ✓ runtime 就绪（第 ${i + 1} 次探测）`)
-        break
-      }
-    } catch {}
-    if (i % 5 === 0) {
-      console.log(`  等待中...（第 ${i + 1} 次）`)
-    }
-  }
-  if (!ready) {
-    throw new Error(`runtime 60s 内未就绪（${localApi} 不可达）。请手动检查 "vantaloom status" 后重试 "vantaloom login"。`)
-  }
-
-  // 3. 登录 Hub + 注册机器 + 连接
-  console.log(`\n▸ 登录 Hub 并连接`)
-  await runLogin({
-    hub: hubUrl,
-    email,
-    password,
-    prefix,
-  })
-
-  console.log(`\n════════════════════════════════════════`)
-  console.log(`  无人值守部署完成！`)
-  console.log(`  安装目录: ${prefix}`)
-  console.log(`  Hub: ${hubUrl}`)
-  console.log(`  runtime 已启动并会在重启后自动恢复。`)
-  console.log(`════════════════════════════════════════`)
-}
-
-function sleep(ms) {
-  return new Promise(resolve => setTimeout(resolve, ms))
-}
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+} from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import {
+  cliRoot,
+  defaultNpmRegistry,
+  fallbackNpmRegistries,
+} from "./lib/constants.mjs"
+import {
+  platformId,
+  runtimePackageName,
+  safeDirectory,
+  defaultPrefix,
+  displayCommand,
+  readJSONIfExists,
+  normalizeRegistry,
+  packageBasename,
+  toCamel,
+  removeKnownPath,
+  run,
+} from "./lib/platform.mjs"
+import {
+  applyPackage,
+  findSourceRoot,
+  tryFindSourceRoot,
+  tryAssertSourceRoot,
+  readInstalledConfig,
+  writeRuntimePackageMetadata,
+  ensureInPath,
+} from "./lib/install.mjs"
+import { buildRuntimePackage } from "./lib/package.mjs"
+import {
+  resolveNpmPackageWithFallback,
+  downloadNpmTarball,
+  findExtractedNpmPackage,
+} from "./lib/registry.mjs"
+import {
+  runCtl,
+  uninstallRuntime,
+} from "./lib/lifecycle.mjs"
+import {
+  runLogin,
+  runLogout,
+  localApiBase,
+} from "./lib/auth.mjs"
+import { runMcp, mcpHint } from "./lib/mcp.mjs"
+
+// Inherit strict-ssl=false from npm/npx config, or respect NODE_TLS_REJECT_UNAUTHORIZED.
+// When npm runs us via npx with strict-ssl disabled, it sets npm_config_strict_ssl="false".
+// Also check user .npmrc for strict-ssl=false (common in China behind proxies).
+function shouldDisableTLS() {
+  if (process.env.NODE_TLS_REJECT_UNAUTHORIZED === "0") return true
+  if (process.env.npm_config_strict_ssl === "false") return true
+  if (process.env.npm_config_strict_ssl === "") return true
+  try {
+    const npmrcPath = path.join(os.homedir(), ".npmrc")
+    if (existsSync(npmrcPath)) {
+      const content = readFileSync(npmrcPath, "utf8")
+      if (/^\s*strict-ssl\s*=\s*false/m.test(content)) return true
+    }
+  } catch {}
+  return false
+}
+if (shouldDisableTLS()) {
+  process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"
+}
+
+const cliVersion = readJSONIfExists(path.join(cliRoot, "package.json")).version ?? "unknown"
+
+export async function main(argv) {
+  const command = argv[0] ?? "help"
+  // "mcp" 带子命令（status/path/print/install）；其余命令的参数全是 --flag。
+  let rest = argv.slice(1)
+  let subcommand
+  if (command === "mcp" && rest[0] && !rest[0].startsWith("--")) {
+    subcommand = rest[0]
+    rest = rest.slice(1)
+  }
+  const options = parseOptions(rest)
+
+  // --no-strict-ssl flag disables TLS certificate verification for fetch calls
+  if (options.noStrictSsl) {
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"
+  }
+
+  if (command === "install" || command === "update") {
+    console.log(`vantaloom-cli v${cliVersion} (${platformId()})`)
+  }
+
+  switch (command) {
+    case "install":
+      if (options.package) {
+        await installFromPackage({ ...options, update: false })
+      } else if (shouldUseSourceInstall(options)) {
+        await installFromSource(options)
+      } else {
+        await syncFromNpmRegistry(options, "install")
+      }
+      return
+    case "update":
+      if (options.package) {
+        await installFromPackage({ ...options, update: true })
+      } else if (shouldUseSourceInstall(options)) {
+        await installFromSource({ ...options, update: true })
+      } else {
+        await syncFromNpmRegistry(options, "update")
+      }
+      return
+    case "package":
+      await packageRuntime(options)
+      return
+    case "platform":
+      console.log(platformId())
+      return
+    case "start":
+    case "stop":
+    case "restart":
+    case "status":
+    case "ports":
+      runCtl(command, options)
+      return
+    case "path":
+      printPaths(options)
+      return
+    case "uninstall":
+      await uninstallRuntime(options)
+      return
+    case "login":
+      await runLogin(options)
+      return
+    case "logout":
+      await runLogout(options)
+      return
+    case "bootstrap":
+      await runBootstrap(options)
+      return
+    case "mcp":
+      await runMcp(subcommand, options)
+      return
+    case "help":
+    case "-h":
+    case "--help":
+      printHelp()
+      return
+    default:
+      throw new Error(`unknown command "${command}"`)
+  }
+}
+
+async function installFromSource(options) {
+  const sourceRoot = findSourceRoot(options.source)
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  const buildRoot = path.join(sourceRoot, "artifacts", "local-install", platformId())
+
+  const { version } = await buildRuntimePackage(sourceRoot, buildRoot, {
+    buildWeb: options.buildWeb,
+  })
+
+  await applyPackage(buildRoot, prefix, {
+    noStart: options.noStart,
+    sourceRoot,
+    update: options.update,
+  })
+
+  console.log(`${options.update ? "updated" : "installed"} Vantaloom: ${prefix}`)
+  console.log(mcpHint(prefix))
+  console.log(`version: ${version}`)
+  ensureInPath(prefix)
+  console.log(`run: ${displayCommand(prefix)} status`)
+}
+
+async function installFromPackage(options) {
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  const packageRoot = safeDirectory(options.package)
+  const version = await applyPackage(packageRoot, prefix, {
+    noStart: options.noStart,
+    update: options.update,
+  })
+
+  console.log(`${options.update ? "updated" : "installed"} Vantaloom: ${prefix}`)
+  console.log(mcpHint(prefix))
+  console.log(`version: ${version}`)
+  ensureInPath(prefix)
+  console.log(`run: ${displayCommand(prefix)} status`)
+}
+
+async function packageRuntime(options) {
+  const sourceRoot = findSourceRoot(options.source)
+  const targetPlatform = options.target ?? platformId()
+  const packageRoot = safeDirectory(
+    options.output ?? path.join(sourceRoot, "artifacts", "packages", `vantaloom-${targetPlatform}`)
+  )
+  const { platform: builtPlatform, version } = await buildRuntimePackage(sourceRoot, packageRoot, {
+    buildWeb: options.buildWeb,
+    target: targetPlatform,
+    npmPackage: options.npmPackage,
+  })
+
+  if (options.npmPackage) {
+    writeRuntimePackageMetadata(packageRoot, sourceRoot, builtPlatform)
+  }
+
+  if (options.archive) {
+    const archivePath = `${packageRoot}.tar.gz`
+    removeKnownPath(archivePath, path.dirname(archivePath))
+    run("tar", [
+      "-czf",
+      archivePath,
+      "-C",
+      path.dirname(packageRoot),
+      path.basename(packageRoot),
+    ])
+    console.log(`archive: ${archivePath}`)
+  }
+
+  console.log(`packaged Vantaloom: ${packageRoot}`)
+  console.log(`platform: ${builtPlatform}`)
+  console.log(`version: ${version}`)
+}
+
+async function syncFromNpmRegistry(options, action) {
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  const installedConfig = readInstalledConfig(prefix)
+  // Always derive runtimePackage from current platform — never trust stale config
+  // from a different platform (e.g. win32 config baked into a darwin package).
+  // Only explicit --runtime-package flag can override.
+  const runtimePackage = options.runtimePackage || runtimePackageName(platformId())
+  const runtimeVersion = options.runtimeVersion || installedConfig.runtimeVersion || "latest"
+  const explicitRegistry = options.npmRegistry || installedConfig.npmRegistry
+  // Resolve against npmjs.org — the registry the runtime packages are published
+  // to. Ambient mirror config (npm_config_registry / .npmrc) is deliberately NOT
+  // adopted: mirrors lag on dist-tags (npmmirror still served "latest" = 0.6.12
+  // months after 0.15.x shipped), and trusting one turns an update into a silent
+  // rollback. Mirrors stay in the fallback chain for unreachable-network cases.
+  const registry = normalizeRegistry(explicitRegistry || defaultNpmRegistry)
+  const tempRoot = mkdtempSync(path.join(os.tmpdir(), "vantaloom-npm-"))
+
+  try {
+    const extractRoot = path.join(tempRoot, "extract")
+    const archive = path.join(tempRoot, `${packageBasename(runtimePackage)}-${runtimeVersion}.tgz`)
+    mkdirSync(extractRoot, { recursive: true })
+
+    const resolved = await resolveNpmPackageWithFallback({
+      registries: explicitRegistry ? [registry] : [registry, ...fallbackNpmRegistries.map(normalizeRegistry)],
+      name: runtimePackage,
+      version: runtimeVersion,
+    })
+    assertNotDowngrade({ prefix, resolved, runtimePackage, options, action })
+    await downloadNpmTarball({
+      tarballUrl: resolved.tarball,
+      target: archive,
+      packageName: runtimePackage,
+      version: resolved.version,
+    })
+    run("tar", ["-xzf", archive, "-C", extractRoot])
+
+    const packageRoot = findExtractedNpmPackage(extractRoot)
+    const version = await applyPackage(packageRoot, prefix, {
+      noStart: options.noStart,
+      runtimePackage,
+      runtimeVersion: options.runtimeVersion ? resolved.version : "latest",
+      npmRegistry: resolved.registry,
+      update: action === "update",
+    })
+
+    console.log(`${action === "update" ? "updated" : "installed"} Vantaloom: ${prefix}`)
+    console.log(mcpHint(prefix))
+    console.log(`version: ${version}`)
+    console.log(`source: ${runtimePackage}@${resolved.version}`)
+    console.log(`registry: ${resolved.registry}`)
+    ensureInPath(prefix)
+    console.log(`run: ${displayCommand(prefix)} status`)
+  } finally {
+    removeKnownPath(tempRoot, os.tmpdir())
+  }
+}
+
+// A registry mirror can answer "latest" with a version far older than the one
+// already installed (npmmirror did exactly that: 0.6.12 long after 0.15.x
+// shipped), turning an update into a silent rollback. Refuse it unless the
+// caller asked for that exact version or opted in explicitly.
+function assertNotDowngrade({ prefix, resolved, runtimePackage, options, action }) {
+  if (action !== "update" || options.runtimeVersion || options.allowDowngrade) {
+    return
+  }
+  const installed = readRuntimeVersion(prefix)
+  if (!isOlderVersion(resolved.version, installed)) {
+    return
+  }
+  throw new Error(
+    `${resolved.registry} offers ${runtimePackage}@${resolved.version}, older than the installed ${installed}.\n` +
+    `  A mirror whose dist-tags lag behind npmjs.org is the usual cause.\n` +
+    `  Retry with --npm-registry https://registry.npmjs.org/, or pass --allow-downgrade to install it anyway.`
+  )
+}
+
+// Installed runtime version ("" when absent/unreadable — never block on it).
+function readRuntimeVersion(prefix) {
+  try {
+    return readFileSync(path.join(prefix, "VERSION"), "utf8").trim()
+  } catch {
+    return ""
+  }
+}
+
+// candidate < installed on the X.Y.Z triple (a -/+ suffix on patch is ignored).
+// Non-semver on either side → false: never block a locally built or unversioned
+// install from being replaced.
+function isOlderVersion(candidate, installed) {
+  const parse = (value) => {
+    const parts = String(value).split(".")
+    if (parts.length < 3) {
+      return null
+    }
+    const triple = [parts[0], parts[1], parts.slice(2).join(".").split(/[-+]/)[0]].map(Number)
+    return triple.every(Number.isInteger) ? triple : null
+  }
+  const found = parse(candidate)
+  const current = parse(installed)
+  if (!found || !current) {
+    return false
+  }
+  for (let index = 0; index < 3; index += 1) {
+    if (found[index] !== current[index]) {
+      return found[index] < current[index]
+    }
+  }
+  return false
+}
+
+function shouldUseSourceInstall(options) {
+  return Boolean(options.local || options.source || options.buildWeb)
+}
+
+function printPaths(options) {
+  const sourceRoot = findSourceRoot(options.source)
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  console.log(JSON.stringify({ sourceRoot, prefix }, null, 2))
+}
+
+function parseOptions(args) {
+  const options = {}
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (!arg.startsWith("--")) {
+      throw new Error(`unexpected argument "${arg}"`)
+    }
+    const [key, inlineValue] = arg.slice(2).split("=", 2)
+    switch (key) {
+      case "prefix":
+      case "source":
+      case "component":
+      case "package":
+      case "output":
+      case "runtime-package":
+      case "runtime-version":
+      case "npm-registry":
+      case "hub":
+      case "email":
+      case "password":
+      case "client":
+      case "api":
+        options[toCamel(key)] = inlineValue ?? args[++index]
+        if (!options[toCamel(key)]) {
+          throw new Error(`missing value for --${key}`)
+        }
+        break
+      case "build-web":
+        options.buildWeb = true
+        break
+      case "no-start":
+        options.noStart = true
+        break
+      case "archive":
+        options.archive = true
+        break
+      case "npm-package":
+        options.npmPackage = true
+        break
+      case "target":
+        options.target = inlineValue ?? args[++index]
+        if (!options.target) {
+          throw new Error("missing value for --target")
+        }
+        break
+      case "local":
+        options.local = true
+        break
+      case "skip-autostart":
+        options.skipAutostart = true
+        break
+      case "no-strict-ssl":
+        options.noStrictSsl = true
+        break
+      case "allow-downgrade":
+        options.allowDowngrade = true
+        break
+      case "force":
+        options.force = true
+        break
+      case "no-skill":
+        options.skill = false
+        break
+      default:
+        throw new Error(`unknown option --${key}`)
+    }
+  }
+  return options
+}
+
+function printHelp() {
+  console.log(`Vantaloom CLI
+
+Usage:
+  vantaloom install   [--prefix <dir>] [--runtime-version <version>] [--npm-registry <url>] [--package <dir>] [--no-start]
+  vantaloom install   --local [--prefix <dir>] [--source <repo>] [--build-web] [--no-start]
+  vantaloom update    [--prefix <dir>] [--runtime-version <version>] [--npm-registry <url>] [--no-start] [--allow-downgrade]
+  vantaloom update    --local [--prefix <dir>] [--source <repo>] [--build-web] [--no-start]
+  vantaloom uninstall [--prefix <dir>]
+  vantaloom package   [--source <repo>] [--output <dir>] [--build-web] [--archive] [--npm-package] [--target <platform>]
+  vantaloom start     [--prefix <dir>] [--component all|api|agent|web]
+  vantaloom stop      [--prefix <dir>] [--component all|api|agent|web]
+  vantaloom restart   [--prefix <dir>] [--component all|api|agent|web]
+  vantaloom status    [--prefix <dir>]
+  vantaloom ports     [--prefix <dir>]
+  vantaloom path      [--prefix <dir>] [--source <repo>]
+  vantaloom platform
+  vantaloom login     [--hub <url>] [--email <email>] [--password <pw>] [--prefix <dir>]
+  vantaloom logout    [--prefix <dir>]
+  vantaloom bootstrap [--hub <url>] --email <email> --password <pw> [--prefix <dir>] [--runtime-version <ver>] [--npm-registry <url>]
+  vantaloom mcp       [status|path|print|install] [--client claude|cursor|codex|all] [--api <url>] [--force] [--no-skill] [--prefix <dir>]
+
+Let another agent drive this machine (MCP bridge):
+  "vantaloom mcp install" registers the bundled MCP server (<prefix>/bin/vantaloom-mcp)
+  with Claude Code / Cursor / Codex and installs the vantaloom-fleet skill, so an
+  external agent can list your machines, run commands, open terminals and move
+  files across the mesh — a keyless SSH replacement. "vantaloom mcp" alone prints
+  the binary path and per-client registration status; "print" emits the config
+  snippets if you would rather paste them yourself. The MCP server is launched by
+  the agent client (independent of the Vantaloom runtime lifecycle) but needs the
+  local runtime to be running.
+
+Hub login (for machines with no web access):
+  "vantaloom login" authenticates to the Hub from the terminal and joins this
+  machine to your workgroup — no browser needed. Email/password may be passed as
+  flags (for scripts) or entered interactively. The local runtime must be running
+  (run "vantaloom start" first).
+
+Unattended bootstrap (one command for fresh hosts):
+  "vantaloom bootstrap" installs the runtime from npm, starts it, waits for it
+  to be ready, then logs in to the Hub — all in one step. Designed for ssh/scp
+  deployment scripts and cloud-init. Requires --email/--password (or env
+  VANTALOOM_HUB_EMAIL/VANTALOOM_HUB_PASSWORD) and --hub (or env
+  VANTALOOM_HUB_URL). The runtime auto-starts and reconnects on reboot.
+`)
+}
+
+// runBootstrap = install runtime (from npm) + wait ready + login Hub，一条命令完成无人值守部署。
+// 面向 ssh/scp 远程部署脚本和 cloud-init 场景；用户在远程主机 npm i -g @vantaloom/cli 后
+// 跑这条命令即可把机器加入 workgroup，无需进 UI。
+async function runBootstrap(options) {
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  const hubUrl = options.hub || process.env.VANTALOOM_HUB_URL || process.env.NEXT_PUBLIC_HUB_URL
+  const email = options.email || process.env.VANTALOOM_HUB_EMAIL
+  const password = options.password || process.env.VANTALOOM_HUB_PASSWORD
+
+  if (!hubUrl) {
+    throw new Error("bootstrap 需要 --hub <url>（或设置 VANTALOOM_HUB_URL 环境变量）")
+  }
+  if (!email || !password) {
+    throw new Error("bootstrap 需要 --email 和 --password（或设置 VANTALOOM_HUB_EMAIL/VANTALOOM_HUB_PASSWORD 环境变量）")
+  }
+
+  // 1. 安装 runtime（从 npm 拉取，自动 start）
+  console.log(`vantaloom-cli v${cliVersion} (${platformId()})`)
+  console.log(`\n▸ 安装 runtime（从 npm）`)
+  const installOpts = { ...options, prefix }
+  // bootstrap 不允许 --no-start，runtime 必须起来才能 login
+  delete installOpts.noStart
+  await syncFromNpmRegistry(installOpts, "install")
+
+  // 2. 等待 runtime 就绪（轮询 /v1/hub/status）
+  const localApi = localApiBase(prefix)
+  console.log(`\n▸ 等待 runtime 就绪（${localApi}）`)
+  let ready = false
+  for (let i = 0; i < 30; i++) {
+    await sleep(2000)
+    try {
+      const res = await fetch(`${localApi}/v1/hub/status`)
+      if (res.ok) {
+        ready = true
+        console.log(`  ✓ runtime 就绪（第 ${i + 1} 次探测）`)
+        break
+      }
+    } catch {}
+    if (i % 5 === 0) {
+      console.log(`  等待中...（第 ${i + 1} 次）`)
+    }
+  }
+  if (!ready) {
+    throw new Error(`runtime 60s 内未就绪（${localApi} 不可达）。请手动检查 "vantaloom status" 后重试 "vantaloom login"。`)
+  }
+
+  // 3. 登录 Hub + 注册机器 + 连接
+  console.log(`\n▸ 登录 Hub 并连接`)
+  await runLogin({
+    hub: hubUrl,
+    email,
+    password,
+    prefix,
+  })
+
+  console.log(`\n════════════════════════════════════════`)
+  console.log(`  无人值守部署完成！`)
+  console.log(`  安装目录: ${prefix}`)
+  console.log(`  Hub: ${hubUrl}`)
+  console.log(`  runtime 已启动并会在重启后自动恢复。`)
+  console.log(`════════════════════════════════════════`)
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}