@vantaloom/runtime-win32-x64 0.1.24 → 0.2.0

package/cli/src/cli.mjs

@@ -1,878 +1,917 @@
-import { execFileSync, spawnSync } from "node:child_process"
-import {
-  chmodSync,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs"
-import { cp, writeFile } from "node:fs/promises"
-import os from "node:os"
-import path from "node:path"
-import { fileURLToPath } from "node:url"
-
-const cliRoot = path.resolve(fileURLToPath(import.meta.url), "..", "..")
-const repoCandidate = path.resolve(cliRoot, "..", "..")
-const installedConfigPath = path.join(cliRoot, "config.json")
-const defaultReleaseTag = "runtime-latest"
-const defaultRepo = "Timefiles404/Vantaloom-next"
-const defaultNpmRegistry = "https://registry.npmjs.org"
-
-export async function main(argv) {
-  const command = argv[0] ?? "help"
-  const options = parseOptions(argv.slice(1))
-
-  switch (command) {
-    case "install":
-      if (options.package) {
-        await installFromPackage({ ...options, update: false })
-      } else if (shouldUseSourceInstall(options)) {
-        await installFromSource(options)
-      } else if (shouldUseReleaseSync(options)) {
-        await syncFromRelease(options, "install")
-      } 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 if (shouldUseReleaseSync(options)) {
-        await syncFromRelease(options, "update")
-      } 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 "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}`)
-  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}`)
-  console.log(`run: ${displayCommand(prefix)} status`)
-}
-
-async function packageRuntime(options) {
-  const sourceRoot = findSourceRoot(options.source)
-  const packageRoot = safeDirectory(
-    options.output ?? path.join(sourceRoot, "artifacts", "packages", `vantaloom-${platformId()}`)
-  )
-  const { platform: builtPlatform, version } = await buildRuntimePackage(sourceRoot, packageRoot, {
-    buildWeb: options.buildWeb,
-  })
-
-  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 buildRuntimePackage(sourceRoot, packageRoot, options) {
-  const version = gitVersion(sourceRoot)
-  const platform = platformId()
-  const buildBin = path.join(packageRoot, "bin")
-  const buildWeb = path.join(packageRoot, "web")
-
-  removeKnownPath(packageRoot, path.dirname(packageRoot))
-  mkdirSync(buildBin, { recursive: true })
-
-  buildGo(sourceRoot, buildBin, "vantaloom-api")
-  buildGo(sourceRoot, buildBin, "vantaloom-agent")
-  buildGo(sourceRoot, buildBin, "vantaloomctl")
-
-  if (options.buildWeb) {
-    runPnpm(["--filter", "vantaloom-app", "build"], { cwd: sourceRoot })
-  }
-
-  await copyStaticWeb(sourceRoot, buildWeb)
-  await copyCliDirectory(path.join(packageRoot, "cli"), sourceRoot, runtimeConfigFromSource(sourceRoot))
-  writeBuildManifest(packageRoot, version, platform)
-
-  return { platform, version }
-}
-
-async function applyPackage(packageRoot, prefix, options) {
-  assertRuntimePackage(packageRoot)
-
-  const existingConfig = readInstalledConfig(prefix)
-  const packageConfig = readJSONIfExists(path.join(packageRoot, "cli", "config.json"))
-  const mergedConfig = mergeRuntimeConfig(packageConfig, existingConfig, {
-    sourceRoot: options.sourceRoot,
-  })
-  const version = readVersion(packageRoot)
-
-  mkdirSync(prefix, { recursive: true })
-  const existingCtl = path.join(prefix, "bin", binaryName("vantaloomctl"))
-  if (existsSync(existingCtl)) {
-    spawnSync(existingCtl, ["stop", "--prefix", prefix], { stdio: "inherit" })
-  }
-
-  for (const name of ["bin", "web", "cli"]) {
-    removeKnownPath(path.join(prefix, name), prefix)
-    await cp(path.join(packageRoot, name), path.join(prefix, name), {
-      recursive: true,
-      force: true,
-      dereference: false,
-    })
-  }
-
-  await writeLauncher(prefix)
-  await writeText(path.join(prefix, "cli", "config.json"), `${JSON.stringify(mergedConfig, null, 2)}\n`)
-  await writeText(path.join(prefix, "VERSION"), `${version}\n`)
-  await cp(path.join(packageRoot, "manifest.json"), path.join(prefix, "manifest.json"), {
-    force: true,
-  })
-
-  run(path.join(prefix, "bin", binaryName("vantaloomctl")), [
-    "install",
-    "--prefix",
-    prefix,
-    "--version",
-    version,
-  ])
-
-  if (!options.noStart) {
-    run(path.join(prefix, "bin", binaryName("vantaloomctl")), [
-      "start",
-      "--prefix",
-      prefix,
-    ])
-  }
-
-  return version
-}
-
-async function syncFromNpmRegistry(options, action) {
-  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
-  const installedConfig = readInstalledConfig(prefix)
-  const runtimePackage = options.runtimePackage || installedConfig.runtimePackage || runtimePackageName(platformId())
-  const runtimeVersion = options.runtimeVersion || installedConfig.runtimeVersion || "latest"
-  const registry = normalizeRegistry(options.npmRegistry || installedConfig.npmRegistry || 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 resolveNpmPackage({ registry, name: runtimePackage, version: runtimeVersion })
-    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: registry,
-      update: action === "update",
-    })
-
-    console.log(`${action === "update" ? "updated" : "installed"} Vantaloom: ${prefix}`)
-    console.log(`version: ${version}`)
-    console.log(`source: ${runtimePackage}@${resolved.version}`)
-    console.log(`run: ${displayCommand(prefix)} status`)
-  } finally {
-    removeKnownPath(tempRoot, os.tmpdir())
-  }
-}
-
-async function syncFromRelease(options, action) {
-  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
-  const installedConfig = readInstalledConfig(prefix)
-  const sourceRoot = installedConfig.sourceRoot
-    ? tryAssertSourceRoot(installedConfig.sourceRoot)
-    : tryFindSourceRoot()
-  const sourceRemote = sourceRoot ? gitRemoteUrl(sourceRoot) : ""
-  const repo = options.repo || installedConfig.repo || inferGitHubRepo(options.remote ?? installedConfig.remote ?? sourceRemote) || defaultRepo
-  const releaseTag = options.releaseTag || installedConfig.releaseTag || defaultReleaseTag
-  const tempRoot = mkdtempSync(path.join(os.tmpdir(), "vantaloom-update-"))
-
-  try {
-    const extractRoot = path.join(tempRoot, "extract")
-    const archive = path.join(tempRoot, `vantaloom-${platformId()}.tar.gz`)
-    mkdirSync(extractRoot, { recursive: true })
-
-    await downloadReleaseAsset({
-      repo,
-      releaseTag,
-      assetName: `vantaloom-${platformId()}.tar.gz`,
-      target: archive,
-      token: options.githubToken,
-    })
-    run("tar", ["-xzf", archive, "-C", extractRoot])
-
-    const packageRoot = findExtractedPackage(extractRoot, platformId())
-    const version = await applyPackage(packageRoot, prefix, {
-      noStart: options.noStart,
-      sourceRoot: installedConfig.sourceRoot,
-      update: action === "update",
-    })
-
-    console.log(`${action === "update" ? "updated" : "installed"} Vantaloom: ${prefix}`)
-    console.log(`version: ${version}`)
-    console.log(`source: ${repo}@${releaseTag}`)
-    console.log(`run: ${displayCommand(prefix)} status`)
-  } finally {
-    removeKnownPath(tempRoot, os.tmpdir())
-  }
-}
-
-async function downloadReleaseAsset({ repo, releaseTag, assetName, target, token }) {
-  const releaseUrl = `https://api.github.com/repos/${repo}/releases/tags/${releaseTag}`
-  const headers = {
-    "User-Agent": "vantaloom-cli",
-  }
-  const githubToken = token || process.env.VANTALOOM_GITHUB_TOKEN || process.env.GITHUB_TOKEN
-  if (githubToken) {
-    headers.Authorization = `Bearer ${githubToken}`
-  }
-
-  const releaseResponse = await fetch(releaseUrl, { headers })
-  if (!releaseResponse.ok) {
-    const detail = await releaseResponse.text().catch(() => "")
-    const authHint = releaseResponse.status === 404 || releaseResponse.status === 403
-      ? " If the repository is private, set VANTALOOM_GITHUB_TOKEN to a GitHub token that can read releases."
-      : ""
-    throw new Error(`failed to inspect ${repo}@${releaseTag}: HTTP ${releaseResponse.status}.${authHint}${detail ? ` ${detail.slice(0, 200)}` : ""}`)
-  }
-
-  const release = await releaseResponse.json()
-  const asset = release.assets?.find((asset) => asset.name === assetName)
-  if (!asset) {
-    const names = release.assets?.map((asset) => asset.name).join(", ") || "none"
-    throw new Error(`missing release asset ${assetName} in ${repo}@${releaseTag}; available assets: ${names}`)
-  }
-
-  const response = await fetch(asset.url, {
-    headers: {
-      ...headers,
-      Accept: "application/octet-stream",
-    },
-  })
-  if (!response.ok) {
-    const detail = await response.text().catch(() => "")
-    const authHint = response.status === 404 || response.status === 403
-      ? " If the repository is private, set VANTALOOM_GITHUB_TOKEN to a GitHub token that can read releases."
-      : ""
-    throw new Error(`failed to download ${assetName} from ${repo}@${releaseTag}: HTTP ${response.status}.${authHint}${detail ? ` ${detail.slice(0, 200)}` : ""}`)
-  }
-
-  const buffer = Buffer.from(await response.arrayBuffer())
-  await writeFile(target, buffer)
-}
-
-async function resolveNpmPackage({ registry, name, version }) {
-  const metadataUrl = `${registry}/${encodeURIComponent(name).replace("%2F", "%2f")}`
-  const response = await fetch(metadataUrl, {
-    headers: {
-      Accept: "application/vnd.npm.install-v1+json",
-      "User-Agent": "vantaloom-cli",
-    },
-  })
-  if (!response.ok) {
-    const detail = await response.text().catch(() => "")
-    throw new Error(`failed to inspect npm package ${name}: HTTP ${response.status}${detail ? ` ${detail.slice(0, 200)}` : ""}`)
-  }
-
-  const metadata = await response.json()
-  const selectedVersion = metadata["dist-tags"]?.[version] ?? version
-  const packageVersion = metadata.versions?.[selectedVersion]
-  if (!packageVersion?.dist?.tarball) {
-    const available = Object.keys(metadata.versions ?? {}).slice(-8).join(", ") || "none"
-    throw new Error(`missing npm package ${name}@${version}; available versions: ${available}`)
-  }
-  return {
-    version: selectedVersion,
-    tarball: packageVersion.dist.tarball,
-  }
-}
-
-async function downloadNpmTarball({ tarballUrl, target, packageName, version }) {
-  const response = await fetch(tarballUrl, {
-    headers: {
-      "User-Agent": "vantaloom-cli",
-    },
-  })
-  if (!response.ok) {
-    const detail = await response.text().catch(() => "")
-    throw new Error(`failed to download ${packageName}@${version}: HTTP ${response.status}${detail ? ` ${detail.slice(0, 200)}` : ""}`)
-  }
-
-  const buffer = Buffer.from(await response.arrayBuffer())
-  await writeFile(target, buffer)
-}
-
-function shouldUseSourceInstall(options) {
-  return Boolean(options.local || options.source || options.buildWeb)
-}
-
-function shouldUseReleaseSync(options) {
-  return Boolean(options.repo || options.remote || options.releaseTag || options.githubToken)
-}
-
-function assertRuntimePackage(packageRoot) {
-  for (const name of ["bin", "web", "cli", "manifest.json"]) {
-    if (!existsSync(path.join(packageRoot, name))) {
-      throw new Error(`invalid Vantaloom package, missing ${name}: ${packageRoot}`)
-    }
-  }
-}
-
-function readVersion(packageRoot) {
-  const versionPath = path.join(packageRoot, "VERSION")
-  if (existsSync(versionPath)) {
-    return readFileSync(versionPath, "utf8").trim() || "dev"
-  }
-  const manifest = readJSONIfExists(path.join(packageRoot, "manifest.json"))
-  return manifest.version ?? "dev"
-}
-
-function readInstalledConfig(prefix) {
-  return readJSONIfExists(path.join(prefix, "cli", "config.json"))
-}
-
-function readJSONIfExists(filePath) {
-  if (!existsSync(filePath)) {
-    return {}
-  }
-  return JSON.parse(readFileSync(filePath, "utf8"))
-}
-
-function mergeRuntimeConfig(packageConfig, existingConfig, overrides) {
-  const merged = { ...packageConfig }
-  for (const key of ["sourceRoot", "remote", "repo", "releaseTag", "runtimePackage", "runtimeVersion", "npmRegistry"]) {
-    if (!merged[key] && existingConfig[key]) {
-      merged[key] = existingConfig[key]
-    }
-  }
-  if (overrides.sourceRoot) {
-    merged.sourceRoot = overrides.sourceRoot
-  }
-  if (overrides.runtimePackage) {
-    merged.runtimePackage = overrides.runtimePackage
-  }
-  if (overrides.runtimeVersion) {
-    merged.runtimeVersion = overrides.runtimeVersion
-  }
-  if (overrides.npmRegistry) {
-    merged.npmRegistry = overrides.npmRegistry
-  }
-  if (!merged.repo) {
-    merged.repo = defaultRepo
-  }
-  if (!merged.releaseTag) {
-    merged.releaseTag = defaultReleaseTag
-  }
-  if (!merged.runtimePackage) {
-    merged.runtimePackage = runtimePackageName(platformId())
-  }
-  if (!merged.runtimeVersion) {
-    merged.runtimeVersion = "latest"
-  }
-  if (!merged.npmRegistry) {
-    merged.npmRegistry = defaultNpmRegistry
-  }
-  return merged
-}
-
-function runtimeConfigFromSource(sourceRoot) {
-  const remote = gitRemoteUrl(sourceRoot)
-  const repo = inferGitHubRepo(remote) || defaultRepo
-  return {
-    ...(process.env.GITHUB_ACTIONS ? {} : { sourceRoot }),
-    ...(remote ? { remote } : {}),
-    repo,
-    releaseTag: defaultReleaseTag,
-    runtimePackage: runtimePackageName(platformId()),
-    runtimeVersion: "latest",
-    npmRegistry: defaultNpmRegistry,
-  }
-}
-
-function findExtractedPackage(extractRoot, platform) {
-  const expected = path.join(extractRoot, `vantaloom-${platform}`)
-  if (existsSync(expected)) {
-    return expected
-  }
-
-  const directories = readdirSync(extractRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => path.join(extractRoot, entry.name))
-  if (directories.length === 1) {
-    return directories[0]
-  }
-
-  throw new Error(`could not find extracted Vantaloom package in ${extractRoot}`)
-}
-
-function findExtractedNpmPackage(extractRoot) {
-  const expected = path.join(extractRoot, "package")
-  if (existsSync(expected)) {
-    return expected
-  }
-
-  const directories = readdirSync(extractRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => path.join(extractRoot, entry.name))
-  if (directories.length === 1) {
-    return directories[0]
-  }
-
-  throw new Error(`could not find extracted npm package in ${extractRoot}`)
-}
-
-function tryFindSourceRoot() {
-  try {
-    return findSourceRoot()
-  } catch {
-    return ""
-  }
-}
-
-function tryAssertSourceRoot(sourceRoot) {
-  try {
-    return assertSourceRoot(sourceRoot)
-  } catch {
-    return ""
-  }
-}
-
-function gitRemoteUrl(sourceRoot) {
-  const result = spawnSync("git", ["remote", "get-url", "origin"], {
-    cwd: sourceRoot,
-    encoding: "utf8",
-  })
-  if (result.status === 0) {
-    return result.stdout.trim()
-  }
-  return ""
-}
-
-function inferGitHubRepo(remote) {
-  if (!remote) {
-    return ""
-  }
-  const normalized = remote.replace(/\.git$/, "")
-  const httpsMatch = normalized.match(/github\.com[:/]([^/]+\/[^/]+)$/)
-  if (httpsMatch) {
-    return httpsMatch[1]
-  }
-  const sshMatch = normalized.match(/^[^:]+:([^/]+\/[^/]+)$/)
-  return sshMatch?.[1] ?? ""
-}
-
-async function copyStaticWeb(sourceRoot, buildWeb) {
-  const exportRoot = path.join(sourceRoot, "apps", "vantaloom", "out")
-  if (!existsSync(exportRoot)) {
-    throw new Error(
-      "missing Next static export output; let GitHub CI run production build, or pass --build-web for a local one-off build"
-    )
-  }
-
-  removeKnownPath(buildWeb, path.dirname(buildWeb))
-  await copyDir(exportRoot, buildWeb)
-}
-
-async function copyCliDirectory(target, sourceRoot, config) {
-  const sourceCliRoot = path.join(sourceRoot, "packages", "cli")
-  if (!existsSync(path.join(sourceCliRoot, "bin", "vantaloom.mjs"))) {
-    throw new Error(`missing source CLI package: ${sourceCliRoot}`)
-  }
-  removeKnownPath(target, path.dirname(target))
-  mkdirSync(target, { recursive: true })
-  await copyDir(sourceCliRoot, target)
-  await writeText(
-    path.join(target, "config.json"),
-    `${JSON.stringify(config, null, 2)}\n`
-  )
-}
-
-async function writeLauncher(prefix) {
-  if (process.platform === "win32") {
-    await writeText(
-      path.join(prefix, "vantaloom.cmd"),
-      `@echo off\r\nnode "%~dp0cli\\bin\\vantaloom.mjs" %*\r\n`
-    )
-  } else {
-    const launcher = `#!/usr/bin/env sh\nexec node "$(dirname "$0")/cli/bin/vantaloom.mjs" "$@"\n`
-    const launcherPath = path.join(prefix, "vantaloom")
-    await writeText(launcherPath, launcher)
-    chmodSync(launcherPath, 0o755)
-  }
-}
-
-function runCtl(command, options) {
-  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
-  const ctl = path.join(prefix, "bin", binaryName("vantaloomctl"))
-  if (!existsSync(ctl)) {
-    throw new Error(`missing installed runtime at ${prefix}; run "vantaloom install" first`)
-  }
-
-  const args = [command, "--prefix", prefix]
-  if (options.component) {
-    args.push("--component", options.component)
-  }
-  run(ctl, args)
-}
-
-function printPaths(options) {
-  const sourceRoot = findSourceRoot(options.source)
-  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
-  console.log(JSON.stringify({ sourceRoot, prefix }, null, 2))
-}
-
-function buildGo(sourceRoot, buildBin, name) {
-  run("go", [
-    "build",
-    "-o",
-    path.join(buildBin, binaryName(name)),
-    `./apps/api/cmd/${name}`,
-  ], { cwd: sourceRoot })
-}
-
-async function copyDir(source, destination, options = {}) {
-  if (!existsSync(source)) {
-    throw new Error(`missing source directory: ${source}`)
-  }
-  removeKnownPath(destination, path.dirname(destination))
-  mkdirSync(destination, { recursive: true })
-  await cp(source, destination, {
-    recursive: true,
-    force: true,
-    dereference: options.dereference ?? true,
-  })
-}
-
-function writeBuildManifest(buildRoot, version, platform) {
-  writeFileSync(path.join(buildRoot, "VERSION"), `${version}\n`)
-  writeFileSync(
-    path.join(buildRoot, "manifest.json"),
-    `${JSON.stringify(
-      {
-        name: "Vantaloom Local Runtime",
-        version,
-        platform,
-        updatedAt: new Date().toISOString(),
-        components: ["api", "agent", "web", "ctl"],
-      },
-      null,
-      2
-    )}\n`
-  )
-}
-
-function writeRuntimePackageMetadata(packageRoot, sourceRoot, platform) {
-  const version = npmPackageVersion(sourceRoot)
-  const { os: runtimeOS, cpu } = parsePlatformId(platform)
-  const name = runtimePackageName(platform)
-  writeFileSync(
-    path.join(packageRoot, "package.json"),
-    `${JSON.stringify(
-      {
-        name,
-        version,
-        private: false,
-        description: `Vantaloom local runtime for ${platform}.`,
-        type: "module",
-        os: [runtimeOS],
-        cpu: [cpu],
-        files: ["bin", "web", "cli", "manifest.json", "VERSION", "README.md"],
-        publishConfig: {
-          access: "public",
-        },
-        engines: {
-          node: ">=20",
-        },
-      },
-      null,
-      2
-    )}\n`
-  )
-  writeFileSync(
-    path.join(packageRoot, "README.md"),
-    `# ${name}\n\nPlatform runtime package for Vantaloom ${platform}. Install @vantaloom/cli instead of this package directly.\n`
-  )
-}
-
-function findSourceRoot(sourceOption) {
-  if (sourceOption) {
-    return assertSourceRoot(path.resolve(sourceOption))
-  }
-  if (process.env.VANTALOOM_SOURCE) {
-    return assertSourceRoot(path.resolve(process.env.VANTALOOM_SOURCE))
-  }
-  if (existsSync(installedConfigPath)) {
-    const config = JSON.parse(readFileSync(installedConfigPath, "utf8"))
-    if (config.sourceRoot) {
-      return assertSourceRoot(path.resolve(config.sourceRoot))
-    }
-  }
-  return assertSourceRoot(repoCandidate)
-}
-
-function npmPackageVersion(sourceRoot) {
-  const packageJSON = readJSONIfExists(path.join(sourceRoot, "packages", "cli", "package.json"))
-  return packageJSON.version ?? "0.0.0"
-}
-
-function assertSourceRoot(sourceRoot) {
-  if (!existsSync(path.join(sourceRoot, "apps", "api", "go.mod"))) {
-    throw new Error(`not a Vantaloom source root: ${sourceRoot}`)
-  }
-  return sourceRoot
-}
-
-function gitVersion(sourceRoot) {
-  const result = spawnSync("git", ["rev-parse", "--short", "HEAD"], {
-    cwd: sourceRoot,
-    encoding: "utf8",
-  })
-  if (result.status === 0) {
-    return result.stdout.trim() || "dev"
-  }
-  return "dev"
-}
-
-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 "repo":
-      case "remote":
-      case "release-tag":
-      case "github-token":
-      case "runtime-package":
-      case "runtime-version":
-      case "npm-registry":
-        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 "local":
-        options.local = true
-        break
-      default:
-        throw new Error(`unknown option --${key}`)
-    }
-  }
-  return options
-}
-
-function safeDirectory(value) {
-  const full = path.resolve(value)
-  const parsed = path.parse(full)
-  if (full === parsed.root) {
-    throw new Error(`refusing to operate on unsafe directory: ${value}`)
-  }
-  return full
-}
-
-function removeKnownPath(target, expectedParent) {
-  if (!existsSync(target)) {
-    return
-  }
-  const full = path.resolve(target)
-  const parent = path.resolve(expectedParent)
-  const prefix = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`
-  if (!full.startsWith(prefix)) {
-    throw new Error(`refusing to remove path outside expected parent: ${full}`)
-  }
-  rmSync(full, { recursive: true, force: true })
-}
-
-function run(command, args, options = {}) {
-  try {
-    execFileSync(command, args, { stdio: "inherit", ...options })
-  } catch (error) {
-    if (error && typeof error.status === "number") {
-      throw new Error(`${command} exited with ${error.status}`)
-    }
-    throw error
-  }
-}
-
-function runPnpm(args, options = {}) {
-  if (process.platform === "win32") {
-    run("cmd.exe", ["/d", "/s", "/c", "pnpm", ...args], options)
-    return
-  }
-  run("pnpm", args, options)
-}
-
-function binaryName(name) {
-  return process.platform === "win32" ? `${name}.exe` : name
-}
-
-function platformId() {
-  return `${process.platform}-${process.arch}`
-}
-
-function runtimePackageName(platform) {
-  return `@vantaloom/runtime-${platform}`
-}
-
-function parsePlatformId(platform) {
-  const parts = platform.split("-")
-  const cpu = parts.pop()
-  const runtimeOS = parts.join("-")
-  if (!runtimeOS || !cpu) {
-    throw new Error(`invalid platform id: ${platform}`)
-  }
-  return { os: runtimeOS, cpu }
-}
-
-function packageBasename(name) {
-  return name.split("/").pop() ?? name
-}
-
-function normalizeRegistry(value) {
-  return value.replace(/\/+$/, "")
-}
-
-function defaultPrefix() {
-  if (process.env.VANTALOOM_HOME) {
-    return process.env.VANTALOOM_HOME
-  }
-  if (process.platform === "win32") {
-    return "D:\\Vantaloom"
-  }
-  if (process.platform === "darwin") {
-    return path.join(os.homedir(), "Applications", "Vantaloom")
-  }
-  return path.join(os.homedir(), ".local", "vantaloom")
-}
-
-function displayCommand(prefix) {
-  if (process.platform === "win32") {
-    return path.join(prefix, "vantaloom.cmd")
-  }
-  return path.join(prefix, "vantaloom")
-}
-
-function toCamel(value) {
-  return value.replace(/-([a-z])/g, (_, char) => char.toUpperCase())
-}
-
-async function writeText(filePath, content) {
-  mkdirSync(path.dirname(filePath), { recursive: true })
-  await writeFile(filePath, content)
-}
-
-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]
-  vantaloom update   --local [--prefix <dir>] [--source <repo>] [--build-web] [--no-start]
-  vantaloom package  [--source <repo>] [--output <dir>] [--build-web] [--archive] [--npm-package]
-  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
-`)
-}
+import { execFileSync, spawnSync } from "node:child_process"
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import { cp, writeFile } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const cliRoot = path.resolve(fileURLToPath(import.meta.url), "..", "..")
+const repoCandidate = path.resolve(cliRoot, "..", "..")
+const installedConfigPath = path.join(cliRoot, "config.json")
+const defaultReleaseTag = "runtime-latest"
+const defaultRepo = "Timefiles404/Vantaloom-next"
+const defaultNpmRegistry = "https://registry.npmjs.org"
+
+export async function main(argv) {
+  const command = argv[0] ?? "help"
+  const options = parseOptions(argv.slice(1))
+
+  switch (command) {
+    case "install":
+      if (options.package) {
+        await installFromPackage({ ...options, update: false })
+      } else if (shouldUseSourceInstall(options)) {
+        await installFromSource(options)
+      } else if (shouldUseReleaseSync(options)) {
+        await syncFromRelease(options, "install")
+      } 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 if (shouldUseReleaseSync(options)) {
+        await syncFromRelease(options, "update")
+      } 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 "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}`)
+  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}`)
+  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,
+  })
+
+  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 buildRuntimePackage(sourceRoot, packageRoot, options) {
+  const version = gitVersion(sourceRoot)
+  const platform = options.target ?? platformId()
+  const buildBin = path.join(packageRoot, "bin")
+  const buildWeb = path.join(packageRoot, "web")
+
+  removeKnownPath(packageRoot, path.dirname(packageRoot))
+  mkdirSync(buildBin, { recursive: true })
+
+  buildGo(sourceRoot, buildBin, "vantaloom-api", platform)
+  buildGo(sourceRoot, buildBin, "vantaloom-agent", platform)
+  buildGo(sourceRoot, buildBin, "vantaloomctl", platform)
+  // Tray app requires CGO (systray), only buildable natively on Windows.
+  if (platform.startsWith("win32") && process.platform === "win32") {
+    try {
+      buildGo(sourceRoot, buildBin, "vantaloom-tray", platform)
+    } catch { /* optional: skip if systray build fails */ }
+  }
+
+  if (options.buildWeb) {
+    runPnpm(["--filter", "vantaloom-app", "build"], { cwd: sourceRoot })
+  }
+
+  await copyStaticWeb(sourceRoot, buildWeb)
+  await copyCliDirectory(path.join(packageRoot, "cli"), sourceRoot, runtimeConfigFromSource(sourceRoot))
+  writeBuildManifest(packageRoot, version, platform)
+
+  return { platform, version }
+}
+
+async function applyPackage(packageRoot, prefix, options) {
+  assertRuntimePackage(packageRoot)
+
+  const existingConfig = readInstalledConfig(prefix)
+  const packageConfig = readJSONIfExists(path.join(packageRoot, "cli", "config.json"))
+  const mergedConfig = mergeRuntimeConfig(packageConfig, existingConfig, {
+    sourceRoot: options.sourceRoot,
+  })
+  const version = readVersion(packageRoot)
+
+  mkdirSync(prefix, { recursive: true })
+  const existingCtl = path.join(prefix, "bin", binaryName("vantaloomctl"))
+  if (existsSync(existingCtl)) {
+    spawnSync(existingCtl, ["stop", "--prefix", prefix], { stdio: "inherit" })
+  }
+
+  for (const name of ["bin", "web", "cli"]) {
+    removeKnownPath(path.join(prefix, name), prefix)
+    await cp(path.join(packageRoot, name), path.join(prefix, name), {
+      recursive: true,
+      force: true,
+      dereference: false,
+    })
+  }
+
+  await writeLauncher(prefix)
+  await writeText(path.join(prefix, "cli", "config.json"), `${JSON.stringify(mergedConfig, null, 2)}\n`)
+  await writeText(path.join(prefix, "VERSION"), `${version}\n`)
+  await cp(path.join(packageRoot, "manifest.json"), path.join(prefix, "manifest.json"), {
+    force: true,
+  })
+
+  run(path.join(prefix, "bin", binaryName("vantaloomctl")), [
+    "install",
+    "--prefix",
+    prefix,
+    "--version",
+    version,
+  ])
+
+  if (!options.noStart) {
+    run(path.join(prefix, "bin", binaryName("vantaloomctl")), [
+      "start",
+      "--prefix",
+      prefix,
+    ])
+  }
+
+  return version
+}
+
+async function syncFromNpmRegistry(options, action) {
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  const installedConfig = readInstalledConfig(prefix)
+  const runtimePackage = options.runtimePackage || installedConfig.runtimePackage || runtimePackageName(platformId())
+  const runtimeVersion = options.runtimeVersion || installedConfig.runtimeVersion || "latest"
+  const registry = normalizeRegistry(options.npmRegistry || installedConfig.npmRegistry || 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 resolveNpmPackage({ registry, name: runtimePackage, version: runtimeVersion })
+    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: registry,
+      update: action === "update",
+    })
+
+    console.log(`${action === "update" ? "updated" : "installed"} Vantaloom: ${prefix}`)
+    console.log(`version: ${version}`)
+    console.log(`source: ${runtimePackage}@${resolved.version}`)
+    console.log(`run: ${displayCommand(prefix)} status`)
+  } finally {
+    removeKnownPath(tempRoot, os.tmpdir())
+  }
+}
+
+async function syncFromRelease(options, action) {
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  const installedConfig = readInstalledConfig(prefix)
+  const sourceRoot = installedConfig.sourceRoot
+    ? tryAssertSourceRoot(installedConfig.sourceRoot)
+    : tryFindSourceRoot()
+  const sourceRemote = sourceRoot ? gitRemoteUrl(sourceRoot) : ""
+  const repo = options.repo || installedConfig.repo || inferGitHubRepo(options.remote ?? installedConfig.remote ?? sourceRemote) || defaultRepo
+  const releaseTag = options.releaseTag || installedConfig.releaseTag || defaultReleaseTag
+  const tempRoot = mkdtempSync(path.join(os.tmpdir(), "vantaloom-update-"))
+
+  try {
+    const extractRoot = path.join(tempRoot, "extract")
+    const archive = path.join(tempRoot, `vantaloom-${platformId()}.tar.gz`)
+    mkdirSync(extractRoot, { recursive: true })
+
+    await downloadReleaseAsset({
+      repo,
+      releaseTag,
+      assetName: `vantaloom-${platformId()}.tar.gz`,
+      target: archive,
+      token: options.githubToken,
+    })
+    run("tar", ["-xzf", archive, "-C", extractRoot])
+
+    const packageRoot = findExtractedPackage(extractRoot, platformId())
+    const version = await applyPackage(packageRoot, prefix, {
+      noStart: options.noStart,
+      sourceRoot: installedConfig.sourceRoot,
+      update: action === "update",
+    })
+
+    console.log(`${action === "update" ? "updated" : "installed"} Vantaloom: ${prefix}`)
+    console.log(`version: ${version}`)
+    console.log(`source: ${repo}@${releaseTag}`)
+    console.log(`run: ${displayCommand(prefix)} status`)
+  } finally {
+    removeKnownPath(tempRoot, os.tmpdir())
+  }
+}
+
+async function downloadReleaseAsset({ repo, releaseTag, assetName, target, token }) {
+  const releaseUrl = `https://api.github.com/repos/${repo}/releases/tags/${releaseTag}`
+  const headers = {
+    "User-Agent": "vantaloom-cli",
+  }
+  const githubToken = token || process.env.VANTALOOM_GITHUB_TOKEN || process.env.GITHUB_TOKEN
+  if (githubToken) {
+    headers.Authorization = `Bearer ${githubToken}`
+  }
+
+  const releaseResponse = await fetch(releaseUrl, { headers })
+  if (!releaseResponse.ok) {
+    const detail = await releaseResponse.text().catch(() => "")
+    const authHint = releaseResponse.status === 404 || releaseResponse.status === 403
+      ? " If the repository is private, set VANTALOOM_GITHUB_TOKEN to a GitHub token that can read releases."
+      : ""
+    throw new Error(`failed to inspect ${repo}@${releaseTag}: HTTP ${releaseResponse.status}.${authHint}${detail ? ` ${detail.slice(0, 200)}` : ""}`)
+  }
+
+  const release = await releaseResponse.json()
+  const asset = release.assets?.find((asset) => asset.name === assetName)
+  if (!asset) {
+    const names = release.assets?.map((asset) => asset.name).join(", ") || "none"
+    throw new Error(`missing release asset ${assetName} in ${repo}@${releaseTag}; available assets: ${names}`)
+  }
+
+  const response = await fetch(asset.url, {
+    headers: {
+      ...headers,
+      Accept: "application/octet-stream",
+    },
+  })
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "")
+    const authHint = response.status === 404 || response.status === 403
+      ? " If the repository is private, set VANTALOOM_GITHUB_TOKEN to a GitHub token that can read releases."
+      : ""
+    throw new Error(`failed to download ${assetName} from ${repo}@${releaseTag}: HTTP ${response.status}.${authHint}${detail ? ` ${detail.slice(0, 200)}` : ""}`)
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer())
+  await writeFile(target, buffer)
+}
+
+async function resolveNpmPackage({ registry, name, version }) {
+  const metadataUrl = `${registry}/${encodeURIComponent(name).replace("%2F", "%2f")}`
+  const response = await fetch(metadataUrl, {
+    headers: {
+      Accept: "application/vnd.npm.install-v1+json",
+      "User-Agent": "vantaloom-cli",
+    },
+  })
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "")
+    throw new Error(`failed to inspect npm package ${name}: HTTP ${response.status}${detail ? ` ${detail.slice(0, 200)}` : ""}`)
+  }
+
+  const metadata = await response.json()
+  const selectedVersion = metadata["dist-tags"]?.[version] ?? version
+  const packageVersion = metadata.versions?.[selectedVersion]
+  if (!packageVersion?.dist?.tarball) {
+    const available = Object.keys(metadata.versions ?? {}).slice(-8).join(", ") || "none"
+    throw new Error(`missing npm package ${name}@${version}; available versions: ${available}`)
+  }
+  return {
+    version: selectedVersion,
+    tarball: packageVersion.dist.tarball,
+  }
+}
+
+async function downloadNpmTarball({ tarballUrl, target, packageName, version }) {
+  const response = await fetch(tarballUrl, {
+    headers: {
+      "User-Agent": "vantaloom-cli",
+    },
+  })
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "")
+    throw new Error(`failed to download ${packageName}@${version}: HTTP ${response.status}${detail ? ` ${detail.slice(0, 200)}` : ""}`)
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer())
+  await writeFile(target, buffer)
+}
+
+function shouldUseSourceInstall(options) {
+  return Boolean(options.local || options.source || options.buildWeb)
+}
+
+function shouldUseReleaseSync(options) {
+  return Boolean(options.repo || options.remote || options.releaseTag || options.githubToken)
+}
+
+function assertRuntimePackage(packageRoot) {
+  for (const name of ["bin", "web", "cli", "manifest.json"]) {
+    if (!existsSync(path.join(packageRoot, name))) {
+      throw new Error(`invalid Vantaloom package, missing ${name}: ${packageRoot}`)
+    }
+  }
+}
+
+function readVersion(packageRoot) {
+  const versionPath = path.join(packageRoot, "VERSION")
+  if (existsSync(versionPath)) {
+    return readFileSync(versionPath, "utf8").trim() || "dev"
+  }
+  const manifest = readJSONIfExists(path.join(packageRoot, "manifest.json"))
+  return manifest.version ?? "dev"
+}
+
+function readInstalledConfig(prefix) {
+  return readJSONIfExists(path.join(prefix, "cli", "config.json"))
+}
+
+function readJSONIfExists(filePath) {
+  if (!existsSync(filePath)) {
+    return {}
+  }
+  return JSON.parse(readFileSync(filePath, "utf8"))
+}
+
+function mergeRuntimeConfig(packageConfig, existingConfig, overrides) {
+  const merged = { ...packageConfig }
+  for (const key of ["sourceRoot", "remote", "repo", "releaseTag", "runtimePackage", "runtimeVersion", "npmRegistry"]) {
+    if (!merged[key] && existingConfig[key]) {
+      merged[key] = existingConfig[key]
+    }
+  }
+  if (overrides.sourceRoot) {
+    merged.sourceRoot = overrides.sourceRoot
+  }
+  if (overrides.runtimePackage) {
+    merged.runtimePackage = overrides.runtimePackage
+  }
+  if (overrides.runtimeVersion) {
+    merged.runtimeVersion = overrides.runtimeVersion
+  }
+  if (overrides.npmRegistry) {
+    merged.npmRegistry = overrides.npmRegistry
+  }
+  if (!merged.repo) {
+    merged.repo = defaultRepo
+  }
+  if (!merged.releaseTag) {
+    merged.releaseTag = defaultReleaseTag
+  }
+  if (!merged.runtimePackage) {
+    merged.runtimePackage = runtimePackageName(platformId())
+  }
+  if (!merged.runtimeVersion) {
+    merged.runtimeVersion = "latest"
+  }
+  if (!merged.npmRegistry) {
+    merged.npmRegistry = defaultNpmRegistry
+  }
+  return merged
+}
+
+function runtimeConfigFromSource(sourceRoot) {
+  const remote = gitRemoteUrl(sourceRoot)
+  const repo = inferGitHubRepo(remote) || defaultRepo
+  return {
+    ...(process.env.GITHUB_ACTIONS ? {} : { sourceRoot }),
+    ...(remote ? { remote } : {}),
+    repo,
+    releaseTag: defaultReleaseTag,
+    runtimePackage: runtimePackageName(platformId()),
+    runtimeVersion: "latest",
+    npmRegistry: defaultNpmRegistry,
+  }
+}
+
+function findExtractedPackage(extractRoot, platform) {
+  const expected = path.join(extractRoot, `vantaloom-${platform}`)
+  if (existsSync(expected)) {
+    return expected
+  }
+
+  const directories = readdirSync(extractRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(extractRoot, entry.name))
+  if (directories.length === 1) {
+    return directories[0]
+  }
+
+  throw new Error(`could not find extracted Vantaloom package in ${extractRoot}`)
+}
+
+function findExtractedNpmPackage(extractRoot) {
+  const expected = path.join(extractRoot, "package")
+  if (existsSync(expected)) {
+    return expected
+  }
+
+  const directories = readdirSync(extractRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(extractRoot, entry.name))
+  if (directories.length === 1) {
+    return directories[0]
+  }
+
+  throw new Error(`could not find extracted npm package in ${extractRoot}`)
+}
+
+function tryFindSourceRoot() {
+  try {
+    return findSourceRoot()
+  } catch {
+    return ""
+  }
+}
+
+function tryAssertSourceRoot(sourceRoot) {
+  try {
+    return assertSourceRoot(sourceRoot)
+  } catch {
+    return ""
+  }
+}
+
+function gitRemoteUrl(sourceRoot) {
+  const result = spawnSync("git", ["remote", "get-url", "origin"], {
+    cwd: sourceRoot,
+    encoding: "utf8",
+  })
+  if (result.status === 0) {
+    return result.stdout.trim()
+  }
+  return ""
+}
+
+function inferGitHubRepo(remote) {
+  if (!remote) {
+    return ""
+  }
+  const normalized = remote.replace(/\.git$/, "")
+  const httpsMatch = normalized.match(/github\.com[:/]([^/]+\/[^/]+)$/)
+  if (httpsMatch) {
+    return httpsMatch[1]
+  }
+  const sshMatch = normalized.match(/^[^:]+:([^/]+\/[^/]+)$/)
+  return sshMatch?.[1] ?? ""
+}
+
+async function copyStaticWeb(sourceRoot, buildWeb) {
+  const exportRoot = path.join(sourceRoot, "apps", "vantaloom", "out")
+  if (!existsSync(exportRoot)) {
+    throw new Error(
+      "missing Next static export output; let GitHub CI run production build, or pass --build-web for a local one-off build"
+    )
+  }
+
+  removeKnownPath(buildWeb, path.dirname(buildWeb))
+  await copyDir(exportRoot, buildWeb)
+}
+
+async function copyCliDirectory(target, sourceRoot, config) {
+  const sourceCliRoot = path.join(sourceRoot, "packages", "cli")
+  if (!existsSync(path.join(sourceCliRoot, "bin", "vantaloom.mjs"))) {
+    throw new Error(`missing source CLI package: ${sourceCliRoot}`)
+  }
+  removeKnownPath(target, path.dirname(target))
+  mkdirSync(target, { recursive: true })
+  await copyDir(sourceCliRoot, target)
+  await writeText(
+    path.join(target, "config.json"),
+    `${JSON.stringify(config, null, 2)}\n`
+  )
+}
+
+async function writeLauncher(prefix) {
+  if (process.platform === "win32") {
+    await writeText(
+      path.join(prefix, "vantaloom.cmd"),
+      `@echo off\r\nnode "%~dp0cli\\bin\\vantaloom.mjs" %*\r\n`
+    )
+  } else {
+    const launcher = `#!/usr/bin/env sh\nexec node "$(dirname "$0")/cli/bin/vantaloom.mjs" "$@"\n`
+    const launcherPath = path.join(prefix, "vantaloom")
+    await writeText(launcherPath, launcher)
+    chmodSync(launcherPath, 0o755)
+  }
+}
+
+function runCtl(command, options) {
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  const ctl = path.join(prefix, "bin", binaryName("vantaloomctl"))
+  if (!existsSync(ctl)) {
+    throw new Error(`missing installed runtime at ${prefix}; run "vantaloom install" first`)
+  }
+
+  const args = [command, "--prefix", prefix]
+  if (options.component) {
+    args.push("--component", options.component)
+  }
+  run(ctl, args)
+}
+
+function printPaths(options) {
+  const sourceRoot = findSourceRoot(options.source)
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  console.log(JSON.stringify({ sourceRoot, prefix }, null, 2))
+}
+
+function buildGo(sourceRoot, buildBin, name, targetPlatform) {
+  const goEnv = targetPlatform ? platformToGoEnv(targetPlatform) : {}
+  const isWindowsTarget = targetPlatform
+    ? targetPlatform.startsWith("win32")
+    : process.platform === "win32"
+  const ext = isWindowsTarget ? ".exe" : ""
+  const ldflags = name === "vantaloom-tray" ? "-s -w -H windowsgui" : "-s -w"
+  run("go", [
+    "build",
+    "-ldflags", ldflags,
+    "-o",
+    path.join(buildBin, `${name}${ext}`),
+    `./apps/api/cmd/${name}`,
+  ], { cwd: sourceRoot, env: { ...process.env, ...goEnv } })
+}
+
+async function copyDir(source, destination, options = {}) {
+  if (!existsSync(source)) {
+    throw new Error(`missing source directory: ${source}`)
+  }
+  removeKnownPath(destination, path.dirname(destination))
+  mkdirSync(destination, { recursive: true })
+  await cp(source, destination, {
+    recursive: true,
+    force: true,
+    dereference: options.dereference ?? true,
+  })
+}
+
+function writeBuildManifest(buildRoot, version, platform) {
+  const components = ["api", "agent", "web", "ctl"]
+  if (platform.startsWith("win32")) {
+    components.push("tray")
+  }
+  writeFileSync(path.join(buildRoot, "VERSION"), `${version}\n`)
+  writeFileSync(
+    path.join(buildRoot, "manifest.json"),
+    `${JSON.stringify(
+      {
+        name: "Vantaloom Local Runtime",
+        version,
+        platform,
+        updatedAt: new Date().toISOString(),
+        components,
+      },
+      null,
+      2
+    )}\n`
+  )
+}
+
+function writeRuntimePackageMetadata(packageRoot, sourceRoot, platform) {
+  const version = npmPackageVersion(sourceRoot)
+  const { os: runtimeOS, cpu } = parsePlatformId(platform)
+  const name = runtimePackageName(platform)
+  writeFileSync(
+    path.join(packageRoot, "package.json"),
+    `${JSON.stringify(
+      {
+        name,
+        version,
+        private: false,
+        description: `Vantaloom local runtime for ${platform}.`,
+        type: "module",
+        os: [runtimeOS],
+        cpu: [cpu],
+        files: ["bin", "web", "cli", "manifest.json", "VERSION", "README.md"],
+        publishConfig: {
+          access: "public",
+        },
+        engines: {
+          node: ">=20",
+        },
+      },
+      null,
+      2
+    )}\n`
+  )
+  writeFileSync(
+    path.join(packageRoot, "README.md"),
+    `# ${name}\n\nPlatform runtime package for Vantaloom ${platform}. Install @vantaloom/cli instead of this package directly.\n`
+  )
+}
+
+function findSourceRoot(sourceOption) {
+  if (sourceOption) {
+    return assertSourceRoot(path.resolve(sourceOption))
+  }
+  if (process.env.VANTALOOM_SOURCE) {
+    return assertSourceRoot(path.resolve(process.env.VANTALOOM_SOURCE))
+  }
+  if (existsSync(installedConfigPath)) {
+    const config = JSON.parse(readFileSync(installedConfigPath, "utf8"))
+    if (config.sourceRoot) {
+      return assertSourceRoot(path.resolve(config.sourceRoot))
+    }
+  }
+  return assertSourceRoot(repoCandidate)
+}
+
+function npmPackageVersion(sourceRoot) {
+  const packageJSON = readJSONIfExists(path.join(sourceRoot, "packages", "cli", "package.json"))
+  return packageJSON.version ?? "0.0.0"
+}
+
+function assertSourceRoot(sourceRoot) {
+  if (!existsSync(path.join(sourceRoot, "apps", "api", "go.mod"))) {
+    throw new Error(`not a Vantaloom source root: ${sourceRoot}`)
+  }
+  return sourceRoot
+}
+
+function gitVersion(sourceRoot) {
+  const result = spawnSync("git", ["rev-parse", "--short", "HEAD"], {
+    cwd: sourceRoot,
+    encoding: "utf8",
+  })
+  if (result.status === 0) {
+    return result.stdout.trim() || "dev"
+  }
+  return "dev"
+}
+
+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 "repo":
+      case "remote":
+      case "release-tag":
+      case "github-token":
+      case "runtime-package":
+      case "runtime-version":
+      case "npm-registry":
+        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
+      default:
+        throw new Error(`unknown option --${key}`)
+    }
+  }
+  return options
+}
+
+function safeDirectory(value) {
+  const full = path.resolve(value)
+  const parsed = path.parse(full)
+  if (full === parsed.root) {
+    throw new Error(`refusing to operate on unsafe directory: ${value}`)
+  }
+  return full
+}
+
+function removeKnownPath(target, expectedParent) {
+  if (!existsSync(target)) {
+    return
+  }
+  const full = path.resolve(target)
+  const parent = path.resolve(expectedParent)
+  const prefix = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`
+  if (!full.startsWith(prefix)) {
+    throw new Error(`refusing to remove path outside expected parent: ${full}`)
+  }
+  rmSync(full, { recursive: true, force: true })
+}
+
+function run(command, args, options = {}) {
+  try {
+    execFileSync(command, args, { stdio: "inherit", ...options })
+  } catch (error) {
+    if (error && typeof error.status === "number") {
+      throw new Error(`${command} exited with ${error.status}`)
+    }
+    throw error
+  }
+}
+
+function runPnpm(args, options = {}) {
+  if (process.platform === "win32") {
+    run("cmd.exe", ["/d", "/s", "/c", "pnpm", ...args], options)
+    return
+  }
+  run("pnpm", args, options)
+}
+
+function binaryName(name, targetPlatform) {
+  const isWindows = targetPlatform
+    ? targetPlatform.startsWith("win32")
+    : process.platform === "win32"
+  return isWindows ? `${name}.exe` : name
+}
+
+function platformToGoEnv(platform) {
+  const { os: runtimeOS, cpu } = parsePlatformId(platform)
+  const goosMap = { win32: "windows", linux: "linux", darwin: "darwin" }
+  const goarchMap = { x64: "amd64", arm64: "arm64" }
+  return {
+    GOOS: goosMap[runtimeOS] ?? runtimeOS,
+    GOARCH: goarchMap[cpu] ?? cpu,
+    CGO_ENABLED: "0",
+  }
+}
+
+function platformId() {
+  return `${process.platform}-${process.arch}`
+}
+
+function runtimePackageName(platform) {
+  return `@vantaloom/runtime-${platform}`
+}
+
+function parsePlatformId(platform) {
+  const parts = platform.split("-")
+  const cpu = parts.pop()
+  const runtimeOS = parts.join("-")
+  if (!runtimeOS || !cpu) {
+    throw new Error(`invalid platform id: ${platform}`)
+  }
+  return { os: runtimeOS, cpu }
+}
+
+function packageBasename(name) {
+  return name.split("/").pop() ?? name
+}
+
+function normalizeRegistry(value) {
+  return value.replace(/\/+$/, "")
+}
+
+function defaultPrefix() {
+  if (process.env.VANTALOOM_HOME) {
+    return process.env.VANTALOOM_HOME
+  }
+  if (process.platform === "win32") {
+    return "D:\\Vantaloom"
+  }
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Applications", "Vantaloom")
+  }
+  return path.join(os.homedir(), ".local", "vantaloom")
+}
+
+function displayCommand(prefix) {
+  if (process.platform === "win32") {
+    return path.join(prefix, "vantaloom.cmd")
+  }
+  return path.join(prefix, "vantaloom")
+}
+
+function toCamel(value) {
+  return value.replace(/-([a-z])/g, (_, char) => char.toUpperCase())
+}
+
+async function writeText(filePath, content) {
+  mkdirSync(path.dirname(filePath), { recursive: true })
+  await writeFile(filePath, content)
+}
+
+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]
+  vantaloom update   --local [--prefix <dir>] [--source <repo>] [--build-web] [--no-start]
+  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
+`)
+}