@astrale-os/sdk 0.1.6 → 0.1.8

package/src/cli/run.ts

@@ -0,0 +1,710 @@
+/**
+ * The `astrale-domain` CLI — dev | build | deploy | publish.
+ *
+ * Thin by design: it reads `astrale.config.ts`, resolves `envs[<env>] → params`
+ * via the adapter, loads the env's secrets file, then drives `adapter.watch`
+ * (dev) or `adapter.deploy` (build+ship). It prints the resulting URL and the
+ * exact `astrale domain install <url> --direct` line. It boots no kernel and knows
+ * nothing provider-specific — that all lives in the adapter.
+ *
+ * The diagnostic spec (`.astrale/spec.json`) is written AFTER watch/deploy
+ * returns, at the live URL: the install graph (and therefore `schemaHash`)
+ * embeds `binding.remoteUrl`s derived from the serving URL, so a spec built at
+ * a guessed URL would carry a hash that never matches the worker's `/meta`.
+ * Only `astrale-domain build` (no URL exists yet) uses an explicit placeholder
+ * and says so.
+ *
+ *   astrale-domain dev               # = deploy dev --watch
+ *   astrale-domain prod              # = deploy prod
+ *   astrale-domain deploy <env>      # any env key
+ *   astrale-domain build             # rebuild spec only (placeholder URL)
+ *   astrale-domain publish [env]     # register the deployed URL in the admin catalog (NO deploy)
+ *
+ * `publish` registers a domain's ALREADY-deployed URL in the admin catalog by
+ * SHELLING OUT to the operator CLI (`astrale domain publish --origin --name
+ * --public-url`); it does NOT deploy — run `prod` / `deploy <env>` first, or use
+ * `deploy --publish` to deploy AND register in one step. Standalone publish
+ * defaults the registered address to `https://<origin>` (what every fleet domain
+ * serves at); pass `--public-url` for workers.dev / split-host deploys. Auth
+ * lives entirely in the operator CLI — this build tool never touches
+ * credentials. Requires `astrale` on PATH (the same CLI the deploy footer
+ * already points you at for `domain install`).
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync, watch as watchFs } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { basename, dirname, isAbsolute, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import type { DeployResult, DomainAdapter, DomainInfo, WatchHandle } from '../config/adapter'
+import type { DeployConfig } from '../config/deploy'
+
+import { loadDotenvFile } from './dotenv'
+import { buildProjectSpec } from './spec'
+
+const CONFIG_NAMES = ['astrale.config.ts', 'astrale.config.js', 'astrale.config.mjs']
+
+type ParsedArgs = {
+  command: 'dev' | 'build' | 'deploy' | 'publish'
+  env: string
+  watch: boolean
+  /** `--port <n>` (dev only) — overrides the env's local dev port. */
+  port?: number
+  /** `--host <url>` (dev only) — public URL of a tunnel/proxy front: binds 0.0.0.0 + pins WORKER_URL. */
+  host?: string
+  /** `--publish` tail-flag on deploy/prod: ALSO register the freshly-deployed URL (deploy + register). */
+  publish?: boolean
+  /** `--name <slug>` — registry name to publish under (default: the origin's first label, e.g. `ai-gateway`). */
+  name?: string
+  /** `--install-by-default` — mark the published domain for install on every new instance. */
+  installByDefault?: boolean
+  /** `--public-url <url>` — (publish only) the address the catalog points at (default: `https://<origin>`). */
+  publicUrl?: string
+}
+
+export async function run(argv: readonly string[]): Promise<number> {
+  // `--help` anywhere prints usage — previously `prod --help` IGNORED the
+  // flag and started a real deploy (observed in an external test run).
+  if (argv.includes('--help') || argv.includes('-h')) {
+    printUsage()
+    return 0
+  }
+  let parsed: ParsedArgs
+  try {
+    parsed = parseArgs(argv)
+  } catch (err) {
+    printUsage((err as Error).message)
+    return 2
+  }
+
+  // The CLI imports the project's TypeScript modules (astrale.config.ts, the ★
+  // files) directly — that requires a TS-native runtime. Fail with the remedy
+  // instead of a cryptic ERR_UNKNOWN_FILE_EXTENSION deep in `import()`.
+  if (!process.versions.bun) {
+    error(
+      'astrale-domain requires Bun (it imports your astrale.config.ts directly). ' +
+        'Install it from https://bun.sh, then re-run.',
+    )
+    return 1
+  }
+
+  const projectDir = process.cwd()
+  const configPath = findConfig(projectDir)
+  if (!configPath) {
+    error(`No astrale.config.ts found in ${projectDir}. Run this from a domain project root.`)
+    return 1
+  }
+
+  let def: DeployConfig
+  try {
+    def = await loadConfig(configPath)
+  } catch (err) {
+    // Adapter-swap papercut: editing the `adapter:` call without the import
+    // (or vice versa) surfaces as a bare ReferenceError. Name the real fix.
+    const m = err instanceof Error ? /^(\w+) is not defined/.exec(err.message) : null
+    if (m) {
+      error(
+        `astrale.config.ts references \`${m[1]}\` but never imports it.\n` +
+          `  If you swapped adapters (cloudflare ⇄ astrale), update BOTH lines:\n` +
+          `    import { ${m[1]} } from '@astrale-os/adapter-cloudflare'\n` +
+          `    adapter: ${m[1]}({ ... })`,
+      )
+      return 1
+    }
+    throw err
+  }
+  const specPath = join(projectDir, '.astrale', 'spec.json')
+
+  if (parsed.command === 'build') {
+    // Spec-only: no adapter params, no secrets, no deploy → no real URL.
+    // Build at an explicit placeholder and say so: the schemaHash of this
+    // spec will NOT match a live worker's /meta (the install graph embeds
+    // URL-derived bindings).
+    const placeholderUrl = `https://${def.origin}`
+    try {
+      await writeSpec({ projectDir, specPath, def, url: placeholderUrl })
+    } catch (err) {
+      error(`Spec build failed: ${(err as Error).message}`)
+      return 1
+    }
+    info(`Built spec → ${rel(projectDir, specPath)}  (origin: ${def.origin})`)
+    info(
+      `note: built at placeholder ${placeholderUrl} — its schemaHash differs from a deployed worker.`,
+    )
+    return 0
+  }
+
+  if (parsed.command === 'publish') {
+    // Register the already-deployed URL in the admin catalog — NO deploy. The
+    // public address defaults to `https://<origin>` (the canonical custom-domain
+    // prod URL — what every fleet domain serves at); `--public-url` overrides it
+    // for workers.dev / split-host deploys. No adapter, secrets, or params: this
+    // only points the registry at an address the author already deployed.
+    const pkg = readPackageMeta(projectDir)
+    const name = parsed.name ?? def.origin.split('.')[0] ?? def.origin
+    const url = parsed.publicUrl ?? `https://${def.origin}`
+    info(`registering ${def.origin} → ${url} in the admin catalog (no deploy)`)
+    return await publishToAdmin({
+      origin: def.origin,
+      name,
+      url,
+      ...(pkg.description ? { description: pkg.description } : {}),
+      ...(parsed.installByDefault ? { installByDefault: true } : {}),
+    })
+  }
+
+  const adapter = def.adapter as DomainAdapter<unknown>
+  // CLI param overrides — applied over the env's params here AND re-applied by
+  // the config hot-regen path, which re-resolves `adapter.params` from the
+  // fresh config (without them, the first config edit would silently drop the
+  // flags — e.g. lose the `--host`-pinned WORKER_URL and drift the iss).
+  const paramOverrides: Record<string, unknown> = {}
+  // CLI port override beats the env's configured port (both adapters read
+  // `params.port` in watch).
+  if (parsed.command === 'dev' && parsed.port !== undefined) paramOverrides.port = parsed.port
+  // `--host <public-url>`: off-localhost dev (sandbox preview, tunnel). The
+  // adapter binds 0.0.0.0 and pins WORKER_URL so the worker's per-request-Host
+  // identity doesn't drift to the proxy's internal hostname.
+  if (parsed.command === 'dev' && parsed.host !== undefined) paramOverrides.host = parsed.host
+  const params = { ...(adapter.params(parsed.env) as Record<string, unknown>), ...paramOverrides }
+
+  const domain = toDomainInfo(def)
+
+  // The client SPA is a DECLARED binding (`defineDomain({ client })`), not a
+  // folder we sniff for: its presence + source dir come from the definition.
+  const clientDir = def.client ? join(projectDir, def.client.dir) : undefined
+  const secrets = loadSecrets(adapter, params, projectDir)
+
+  if (parsed.command === 'dev' || (parsed.command === 'deploy' && parsed.watch)) {
+    return runWatch({
+      adapter,
+      params,
+      paramOverrides,
+      projectDir,
+      specPath,
+      clientDir,
+      secrets,
+      domain,
+      env: parsed.env,
+      def,
+      configPath,
+    })
+  }
+
+  // deploy (no watch)
+  const result = await adapter.deploy(params, {
+    projectDir,
+    specPath,
+    secrets,
+    ...(clientDir ? { clientDir } : {}),
+    domain,
+    env: parsed.env,
+  })
+  await writeSpecBestEffort({ projectDir, specPath, def, url: result.url })
+  printDeployed(result, def)
+
+  if (parsed.publish) {
+    const pkg = readPackageMeta(projectDir)
+    // The registry `name` is a short catalog slug, distinct from the FQDN-like
+    // `origin` AND from the npm package name (`@scope/…` for a published domain —
+    // illegal as a catalog slug). Default to the origin's first label (the fleet
+    // convention, e.g. `ai-gateway`); `--name` overrides.
+    const name = parsed.name ?? def.origin.split('.')[0] ?? def.origin
+    return await publishToAdmin({
+      origin: def.origin,
+      name,
+      url: result.url,
+      ...(pkg.description ? { description: pkg.description } : {}),
+      ...(parsed.installByDefault ? { installByDefault: true } : {}),
+    })
+  }
+  return 0
+}
+
+/**
+ * Register the just-deployed URL in the admin catalog by shelling out to the
+ * operator CLI (`astrale domain publish`). Deliberately a subprocess, not a
+ * library call: all credential/admin-target resolution lives in `@astrale-os/
+ * astrale` and we don't want it (or a kernel client) pulled into this build
+ * tool — we only own the fresh URL. A missing `astrale` is reported with the
+ * exact line to run by hand, so a deploy that already succeeded isn't a dead end.
+ */
+async function publishToAdmin(args: {
+  origin: string
+  name: string
+  url: string
+  description?: string
+  installByDefault?: boolean
+}): Promise<number> {
+  // `--public-url`, not `--url`: the operator CLI reserves `--url` for kernel
+  // targeting, so the domain's public address rides its own flag.
+  const cliArgs = [
+    'domain',
+    'publish',
+    '--origin',
+    args.origin,
+    '--name',
+    args.name,
+    '--public-url',
+    args.url,
+  ]
+  if (args.description) cliArgs.push('--description', args.description)
+  if (args.installByDefault) cliArgs.push('--install-by-default')
+
+  info(`publishing to the admin catalog → astrale ${cliArgs.join(' ')}`)
+  return await new Promise<number>((resolveCode) => {
+    const child = spawn('astrale', cliArgs, { stdio: 'inherit' })
+    child.on('error', (err) => {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        error(
+          `\`astrale\` CLI not found on PATH. The deploy succeeded — publish it by hand:\n` +
+            `      astrale ${cliArgs.join(' ')}`,
+        )
+      } else {
+        error(`failed to run \`astrale domain publish\`: ${err.message}`)
+      }
+      resolveCode(1)
+    })
+    child.on('exit', (code) => resolveCode(code ?? 1))
+  })
+}
+
+/** Best-effort read of the project's package.json `name`/`description` (publish defaults). */
+function readPackageMeta(projectDir: string): { name?: string; description?: string } {
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8')) as {
+      name?: string
+      description?: string
+    }
+    return { name: pkg.name, description: pkg.description }
+  } catch {
+    return {}
+  }
+}
+
+async function runWatch(args: {
+  adapter: DomainAdapter<unknown>
+  params: unknown
+  paramOverrides: Record<string, unknown>
+  projectDir: string
+  specPath: string
+  clientDir?: string
+  secrets: Record<string, string>
+  domain: DomainInfo
+  env: string
+  def: DeployConfig
+  configPath: string
+}): Promise<number> {
+  const { adapter, params, projectDir, specPath, clientDir, secrets, domain, env, def } = args
+  let reloads = 0
+  const onReload = () => {
+    reloads += 1
+    info(`↻ reloaded (#${reloads}) — same URL, no reinstall needed for handler edits`)
+  }
+  const handle: WatchHandle = await adapter.watch(params, {
+    projectDir,
+    specPath,
+    ...(clientDir ? { clientDir } : {}),
+    secrets,
+    domain,
+    env,
+    onReload,
+  })
+  await writeSpecBestEffort({ projectDir, specPath, def, url: handle.url })
+  printDevReady(handle.url, domain)
+
+  const stopConfigWatch = watchConfigForRegen({
+    configPath: args.configPath,
+    initial: def,
+    env,
+    paramOverrides: args.paramOverrides,
+    projectDir,
+    specPath,
+    ...(clientDir ? { clientDir } : {}),
+    url: handle.url,
+    onReload,
+  })
+
+  await new Promise<void>((resolveStop) => {
+    const stop = () => {
+      stopConfigWatch()
+      void handle.stop().finally(resolveStop)
+    }
+    process.on('SIGINT', stop)
+    process.on('SIGTERM', stop)
+  })
+  return 0
+}
+
+/**
+ * Watch `astrale.config.ts` while `dev` runs: on change, re-import the config
+ * (cache-busted), re-resolve env params + secrets, and re-run the adapter's
+ * codegen via `adapter.regenerate` — the running dev server (e.g. `wrangler
+ * dev`, which watches its generated config + entry) reloads them itself, so a
+ * config edit lands without restarting the CLI.
+ *
+ * Watches the config's DIRECTORY, not the file: editors save via atomic
+ * rename, which silently kills an inode-bound watch.
+ *
+ * Deliberate limits, surfaced to the user instead of half-applied:
+ *  • origin / adapter changes re-key the worker's identity → restart;
+ *  • a mid-edit broken config (syntax error, bad env) warns and keeps the
+ *    previous generation running;
+ *  • modules the config IMPORTS (e.g. the schema) stay module-cached — only
+ *    the config file itself is re-evaluated, which covers everything
+ *    `defineDomain` owns (vars, requires, postInstall, wrangler overlay…).
+ */
+export function watchConfigForRegen(args: {
+  configPath: string
+  initial: DeployConfig
+  env: string
+  /** CLI flag overrides (dev --port / --host) — re-applied on every regen. */
+  paramOverrides: Record<string, unknown>
+  projectDir: string
+  specPath: string
+  clientDir?: string
+  url: string
+  onReload: () => void
+}): () => void {
+  let running = false
+  let pending = false
+  let stopped = false
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  async function regen(): Promise<void> {
+    if (stopped) return
+    if (running) {
+      pending = true
+      return
+    }
+    running = true
+    try {
+      const def = await loadConfig(args.configPath, { fresh: true })
+      if (def.origin !== args.initial.origin || def.adapter.name !== args.initial.adapter.name) {
+        warn(
+          `astrale.config.ts: \`origin\` or adapter changed — that re-keys the worker's ` +
+            `identity; restart \`astrale-domain dev\` to apply.`,
+        )
+        return
+      }
+      const adapter = def.adapter as DomainAdapter<unknown>
+      if (!adapter.regenerate) {
+        warn(
+          `astrale.config.ts changed, but the "${adapter.name}" adapter has no \`regenerate\` — ` +
+            `restart \`astrale-domain dev\` to apply.`,
+        )
+        return
+      }
+      const params = {
+        ...(adapter.params(args.env) as Record<string, unknown>),
+        ...args.paramOverrides,
+      }
+      const domain = toDomainInfo(def)
+      await adapter.regenerate(params, {
+        projectDir: args.projectDir,
+        specPath: args.specPath,
+        ...(args.clientDir ? { clientDir: args.clientDir } : {}),
+        secrets: loadSecrets(adapter, params, args.projectDir),
+        domain,
+        env: args.env,
+        onReload: args.onReload,
+      })
+      await writeSpecBestEffort({
+        projectDir: args.projectDir,
+        specPath: args.specPath,
+        def,
+        url: args.url,
+      })
+      info(
+        `↻ astrale.config.ts changed — codegen regenerated, the dev server reloads it ` +
+          `(a port / workerName / remote change still needs a restart)`,
+      )
+    } catch (err) {
+      warn(
+        `astrale.config.ts changed but reloading it failed (previous config stays live): ` +
+          `${(err as Error).message}`,
+      )
+    } finally {
+      running = false
+      if (pending && !stopped) {
+        pending = false
+        void regen()
+      }
+    }
+  }
+
+  const configFile = basename(args.configPath)
+  const watcher = watchFs(dirname(args.configPath), (_event, file) => {
+    if (file && file !== configFile) return
+    clearTimeout(timer)
+    // Debounce: editors fire several fs events per save (write + rename).
+    timer = setTimeout(() => void regen(), 200)
+  })
+
+  return () => {
+    stopped = true
+    clearTimeout(timer)
+    watcher.close()
+  }
+}
+
+// ── spec ─────────────────────────────────────────────────────────────────
+
+async function writeSpec(args: {
+  projectDir: string
+  specPath: string
+  def: DeployConfig
+  url: string
+}): Promise<void> {
+  const { wire, schemaHash } = await buildProjectSpec(args.def, args.url)
+  await mkdir(dirname(args.specPath), { recursive: true })
+  await writeFile(args.specPath, JSON.stringify({ ...wire, schemaHash }, null, 2))
+}
+
+/**
+ * Diagnostic-spec write for dev/deploy: best-effort — the worker builds the
+ * live install bundle itself, so a malformed project still runs/deploys; we
+ * warn and continue.
+ */
+async function writeSpecBestEffort(args: {
+  projectDir: string
+  specPath: string
+  def: DeployConfig
+  url: string
+}): Promise<void> {
+  try {
+    await writeSpec(args)
+  } catch (err) {
+    const msg = (err as Error).message
+    warn(`(non-fatal) skipped the local diagnostic spec — the worker builds the real one: ${msg}`)
+    if (msg.includes('MISSING_DEF')) {
+      warn(
+        `  MISSING_DEF here usually means TWO copies of @astrale-os/kernel-core are loaded ` +
+          `(linked dev deps). Try \`pnpm dedupe\`; the deploy itself is unaffected.`,
+      )
+    }
+  }
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function loadSecrets(
+  adapter: DomainAdapter<unknown>,
+  params: unknown,
+  projectDir: string,
+): Record<string, string> {
+  const file = adapter.secretsFile?.(params)
+  if (!file) return {}
+  const abs = isAbsolute(file) ? file : join(projectDir, file)
+  return loadDotenvFile(abs)
+}
+
+function findConfig(dir: string): string | undefined {
+  for (const name of CONFIG_NAMES) {
+    const candidate = join(dir, name)
+    if (existsSync(candidate)) return candidate
+  }
+  return undefined
+}
+
+function toDomainInfo(def: DeployConfig): DomainInfo {
+  return {
+    origin: def.origin,
+    requires: def.requires,
+    ...(def.postInstall ? { postInstall: def.postInstall } : {}),
+    // Presence comes from the definition the author wired — never a folder probe.
+    hasViews: def.views !== undefined,
+    hasFunctions: def.functions !== undefined,
+    hasClient: def.client !== undefined,
+    hasDeps: def.deps !== undefined,
+  }
+}
+
+async function loadConfig(path: string, opts?: { fresh: boolean }): Promise<DeployConfig> {
+  // Re-importing an EDITED file: Bun's ESM registry is keyed by path and never
+  // re-reads the source — a `?reload=N` query re-EVALUATES but serves the
+  // CACHED (stale) source. Bun unifies that registry with `require.cache`, so
+  // deleting the entry forces a fresh read on the next import (the CLI is
+  // Bun-gated, see `run()`). Modules the config itself imports stay cached —
+  // the documented hot-regen limit.
+  if (opts?.fresh) delete createRequire(import.meta.url).cache[path]
+  const mod = (await import(pathToFileURL(path).href)) as { default?: unknown }
+  const def = mod.default
+  if (!def || typeof def !== 'object' || !('adapter' in def) || !('origin' in def)) {
+    throw new Error(
+      `${path} must \`export default deploy(domain, adapter)\` from '@astrale-os/sdk' ` +
+        `(where \`domain\` is a \`defineDomain({ ... })\` from your domain.ts).`,
+    )
+  }
+  return def as DeployConfig
+}
+
+/** Require a plausible public URL for `--host`; default the scheme to https. */
+function normalizeHost(raw: string | undefined): string {
+  if (!raw || raw.startsWith('-')) throw new Error(`--host needs a public URL, got "${raw ?? ''}"`)
+  const url = /^https?:\/\//.test(raw) ? raw : `https://${raw}`
+  try {
+    return new URL(url).origin
+  } catch {
+    throw new Error(`--host needs a valid URL, got "${raw}"`)
+  }
+}
+
+export function parseArgs(argv: readonly string[]): ParsedArgs {
+  const [cmd, ...rest] = argv
+  const watch = rest.includes('--watch')
+  // Tail-flag (deploy/prod/publish): register the deployed URL in the admin
+  // catalog after a successful deploy. The `publish` command implies it.
+  const publish = rest.includes('--publish')
+  const installByDefault = rest.includes('--install-by-default')
+  // `--port <n>` / `--port=<n>`: consume the flag AND its value so neither
+  // leaks into the positionals (a bare `8788` would be read as the env name).
+  let port: number | undefined
+  let host: string | undefined
+  let name: string | undefined
+  let publicUrl: string | undefined
+  const cleaned: string[] = []
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!
+    if (a === '--port') {
+      const v = rest[++i]
+      port = Number(v)
+      if (!Number.isInteger(port) || port <= 0)
+        throw new Error(`--port needs a port number, got "${v}"`)
+    } else if (a.startsWith('--port=')) {
+      port = Number(a.slice('--port='.length))
+      if (!Number.isInteger(port) || port <= 0)
+        throw new Error(`--port needs a port number, got "${a}"`)
+    } else if (a === '--host') {
+      host = normalizeHost(rest[++i])
+    } else if (a.startsWith('--host=')) {
+      host = normalizeHost(a.slice('--host='.length))
+    } else if (a === '--name') {
+      name = rest[++i]
+      if (!name) throw new Error('--name needs a value (the registry slug to publish under)')
+    } else if (a.startsWith('--name=')) {
+      name = a.slice('--name='.length)
+    } else if (a === '--public-url') {
+      publicUrl = rest[++i]
+      if (!publicUrl)
+        throw new Error('--public-url needs a value (the address the catalog points at)')
+    } else if (a.startsWith('--public-url=')) {
+      publicUrl = a.slice('--public-url='.length)
+    } else {
+      cleaned.push(a)
+    }
+  }
+  const positionals = cleaned.filter((a) => !a.startsWith('-'))
+
+  // Publish-related fields shared by deploy/prod/publish (publish itself is
+  // gated per-command: opt-in via `--publish`, always-on for `publish`).
+  const pub = {
+    ...(name !== undefined ? { name } : {}),
+    ...(installByDefault ? { installByDefault } : {}),
+  }
+
+  switch (cmd) {
+    case 'dev':
+      return {
+        command: 'dev',
+        env: positionals[0] ?? 'dev',
+        watch: true,
+        ...(port !== undefined ? { port } : {}),
+        ...(host !== undefined ? { host } : {}),
+      }
+    case 'prod':
+      return { command: 'deploy', env: 'prod', watch, ...(publish ? { publish } : {}), ...pub }
+    case 'deploy': {
+      const env = positionals[0]
+      if (!env) throw new Error('`deploy` requires an env key, e.g. `deploy prod`.')
+      return { command: 'deploy', env, watch, ...(publish ? { publish } : {}), ...pub }
+    }
+    case 'publish':
+      // Register the ALREADY-deployed URL in the admin catalog — NO deploy.
+      // (Use `deploy [env] --publish` to deploy AND register in one step.) The
+      // public address defaults to `https://<origin>`; `--public-url` overrides.
+      return {
+        command: 'publish',
+        env: positionals[0] ?? 'prod',
+        watch: false,
+        ...pub,
+        ...(publicUrl !== undefined ? { publicUrl } : {}),
+      }
+    case 'build':
+      // Spec-only — no env resolution happens on this path.
+      return { command: 'build', env: 'dev', watch: false }
+    default:
+      throw new Error(cmd ? `Unknown command "${cmd}".` : 'Missing command.')
+  }
+}
+
+function rel(from: string, to: string): string {
+  return to.startsWith(from) ? `.${to.slice(from.length)}` : to
+}
+
+// ── output ───────────────────────────────────────────────────────────────
+
+const GREEN = '\x1b[32m'
+const DIM = '\x1b[2m'
+const BOLD = '\x1b[1m'
+const YELLOW = '\x1b[33m'
+const RED = '\x1b[31m'
+const RESET = '\x1b[0m'
+
+function info(msg: string): void {
+  process.stdout.write(`${DIM}›${RESET} ${msg}\n`)
+}
+function warn(msg: string): void {
+  process.stderr.write(`${YELLOW}!${RESET} ${msg}\n`)
+}
+function error(msg: string): void {
+  process.stderr.write(`${RED}✗${RESET} ${msg}\n`)
+}
+
+function printDevReady(url: string, domain: DomainInfo): void {
+  process.stdout.write(
+    `\n${GREEN}✓${RESET} ${BOLD}${domain.origin}${RESET} running (dev, hot-reload)\n` +
+      `  ${BOLD}URL${RESET}  ${GREEN}${url}${RESET}\n` +
+      `  ${DIM}install on an instance:${RESET}\n` +
+      `      ${BOLD}astrale domain install ${url} --direct${RESET}\n` +
+      `  ${DIM}edit a handler → reloads at the same URL. edit the schema → reinstall.${RESET}\n\n`,
+  )
+}
+
+function printDeployed(result: DeployResult, def: DeployConfig): void {
+  // Adapters that already completed the install (managed deploys) supply
+  // their own next-steps; the default hint would tell the user to redo it.
+  const footer =
+    result.nextSteps !== undefined
+      ? result.nextSteps === ''
+        ? ''
+        : `${result.nextSteps}\n`
+      : `  ${DIM}install on an instance:${RESET}\n` +
+        `      ${BOLD}astrale domain install ${result.url} --direct${RESET}\n`
+  process.stdout.write(
+    `\n${GREEN}✓${RESET} ${BOLD}${def.origin}${RESET} deployed\n` +
+      `  ${BOLD}URL${RESET}  ${GREEN}${result.url}${RESET}\n` +
+      footer +
+      `\n`,
+  )
+}
+
+function printUsage(msg?: string): void {
+  if (msg) error(msg)
+  process.stderr.write(
+    `\nUsage:\n` +
+      `  astrale-domain dev               # deploy dev --watch (hot-reload, prints URL)\n` +
+      `  astrale-domain prod              # deploy prod\n` +
+      `  astrale-domain deploy <env>      # deploy any env key (--watch optional)\n` +
+      `  astrale-domain publish [env]     # register the already-deployed URL in the admin catalog (NO deploy)\n` +
+      `  astrale-domain build             # rebuild the diagnostic spec only\n` +
+      `\nFlags:\n` +
+      `  --publish                        # on deploy/prod: ALSO register the deployed URL (deploy + register)\n` +
+      `  --name <slug>                    # registry name to publish under (default: the origin's first label)\n` +
+      `  --public-url <url>               # (publish) address the catalog points at (default: https://<origin>)\n` +
+      `  --install-by-default             # mark the published domain for install on every new instance\n` +
+      `\n  publish shells out to \`astrale domain publish\` (needs \`astrale\` on PATH).\n\n`,
+  )
+}