@vantaloom/runtime-linux-x64 0.1.5

package/cli/src/cli.mjs

@@ -0,0 +1,878 @@
+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
+`)
+}