@astrale-os/cli 0.4.0-alpha.13

package/src/lib/login-flow.ts

@@ -0,0 +1,164 @@
+import { upsertIdpIdentity } from './identity'
+import {
+  decodeTokenClaims,
+  exchangeAuthorizationCode,
+  identityNameFromClaims,
+  issuerFromToken,
+  normalizeTokenResponse,
+  pollDeviceToken,
+  readIdpConfigOrBuiltin,
+  readIdpStore,
+  requestClientCredentials,
+  requestDeviceAuthorization,
+  saveIdpSession,
+  subjectFromToken,
+  tokenAudienceMatches,
+  tokenExpiresAt,
+  withCachedToken,
+  workosClientIdFromEnv,
+  type IdpSession,
+  type TokenResponse,
+} from './idp'
+import { log } from './log'
+
+/**
+ * The IdP login flow, lifted out of the `auth login` command so it can be
+ * driven from anywhere (the command renders the result; `astrale setup` runs it
+ * as one hand-held step). The side effects — saving the session cache and
+ * upserting the IdP-backed identity — live here so every caller gets identical
+ * behavior; presentation (the device URL is logged here; success lines are the
+ * caller's) does not.
+ */
+export type LoginFlowOpts = {
+  idp?: string
+  name?: string
+  scope?: string
+  audience?: string
+  clientId?: string
+  clientSecretEnv?: string
+  clientCredentials?: boolean
+  code?: string
+  redirectUri?: string
+  codeVerifier?: string
+  /** Switch the default identity to the one we just logged in (default true). */
+  use?: boolean
+}
+
+export type LoginResult = {
+  session: IdpSession
+  identityName: string
+  idpName: string
+}
+
+/**
+ * Authenticate against an IdP and persist the result. Throws on any failure
+ * (no session is written) — notably BEFORE saving when an explicit `--audience`
+ * does not match the minted access token, so a wrong-audience login never
+ * leaves a half-written cache.
+ */
+export async function loginViaIdp(opts: LoginFlowOpts): Promise<LoginResult> {
+  const idpName = await resolveIdpName(opts.idp)
+  const idp = await readIdpConfigOrBuiltin(idpName, { clientId: opts.clientId, persist: true })
+  const scope = opts.scope ?? idp.client.scope ?? 'openid profile email offline_access'
+
+  const token = normalizeTokenResponse(await obtainToken(idp, opts, scope))
+  if (!token.access_token) throw new Error('IdP response did not include access_token')
+  if (opts.audience && !tokenAudienceMatches(token.access_token, opts.audience)) {
+    throw new Error(
+      `IdP response access_token was not minted for requested audience ${opts.audience}`,
+    )
+  }
+
+  const claims = decodeTokenClaims(token.id_token ?? token.access_token)
+  const subject = subjectFromToken(token, opts.clientId ?? idp.client.client_id ?? idpName)
+  const issuer = issuerFromToken(token, idp.metadata.issuer)
+  const identityName = opts.name ?? identityNameFromClaims(claims, idpName)
+  const session: IdpSession = {
+    identity: identityName,
+    idp: idpName,
+    issuer,
+    subject,
+    audience: opts.audience,
+    access_token: token.access_token,
+    id_token: token.id_token,
+    refresh_token: token.refresh_token,
+    token_type: token.token_type,
+    scope: token.scope ?? scope,
+    expires_at: tokenExpiresAt(token),
+    tokens: withCachedToken(undefined, token.access_token, tokenExpiresAt(token)),
+    claims: claims ? (claims as Record<string, unknown>) : undefined,
+    updatedAt: new Date().toISOString(),
+  }
+
+  await saveIdpSession(session)
+  await upsertIdpIdentity(identityName, {
+    subject,
+    idp: idpName,
+    issuer,
+    audience: opts.audience,
+    claims: session.claims,
+    use: opts.use,
+  })
+
+  return { session, identityName, idpName }
+}
+
+/** Resolve which IdP to use: explicit name, the sole configured one, or WorkOS. */
+export async function resolveIdpName(name: string | undefined): Promise<string> {
+  if (name) return name
+  const store = await readIdpStore()
+  const names = Object.keys(store.idps)
+  if (names.length === 1) return names[0]
+  if (names.length === 0 && workosClientIdFromEnv()) return 'workos'
+  if (names.length === 0)
+    throw new Error('No IdPs configured. Run: astrale idp add <name> --issuer <url>')
+  throw new Error(`Multiple IdPs configured. Choose one with --idp: ${names.join(', ')}`)
+}
+
+async function obtainToken(
+  idp: Awaited<ReturnType<typeof readIdpConfigOrBuiltin>>,
+  opts: LoginFlowOpts,
+  scope: string,
+): Promise<TokenResponse> {
+  if (opts.clientCredentials) {
+    return requestClientCredentials({
+      idp,
+      clientId: opts.clientId,
+      clientSecretEnv: opts.clientSecretEnv,
+      scope,
+      audience: opts.audience,
+    })
+  }
+
+  if (opts.code) {
+    if (!opts.redirectUri) throw new Error('--redirect-uri is required with --code')
+    return exchangeAuthorizationCode({
+      idp,
+      code: opts.code,
+      redirectUri: opts.redirectUri,
+      codeVerifier: opts.codeVerifier,
+      clientId: opts.clientId,
+      clientSecretEnv: opts.clientSecretEnv,
+    })
+  }
+
+  const device = await requestDeviceAuthorization({
+    idp,
+    clientId: opts.clientId,
+    scope,
+    audience: opts.audience,
+  })
+  if (device.verification_uri_complete) log.info(`Open: ${device.verification_uri_complete}`)
+  else if (device.verification_uri) log.info(`Open: ${device.verification_uri}`)
+  if (device.user_code) log.info(`Code: ${device.user_code}`)
+  if (device.message) log.dim(`  ${device.message}`)
+
+  return pollDeviceToken({
+    idp,
+    deviceCode: device.device_code,
+    clientId: opts.clientId,
+    clientSecretEnv: opts.clientSecretEnv,
+    intervalSec: device.interval,
+    expiresInSec: device.expires_in,
+  })
+}

package/src/lib/meta.ts

@@ -0,0 +1,86 @@
+/**
+ * Issuer reachability helpers — OIDC discovery + JWKS.
+ *
+ * Kernels don't expose `/meta`. They expose OIDC discovery at
+ * `/.well-known/openid-configuration` (standard, returns `issuer` and
+ * `jwks_uri`) and JWKS at `/.well-known/jwks.json`. These helpers probe
+ * both to verify the issuer is alive and publishes at least one key.
+ *
+ * Domain workers may expose `/meta` for deployment drift detection; that is
+ * outside this connect-only CLI surface.
+ */
+
+import { IssuerUnreachableError } from '../errors'
+
+export type DiscoveryDocument = {
+  /** OIDC issuer URL. */
+  issuer: string
+  /** JWKS URI (defaults to `<issuer>/.well-known/jwks.json`). */
+  jwksUri: string
+}
+
+export async function fetchDiscovery(
+  url: string,
+  timeoutMs = 5_000,
+  fetchImpl: typeof fetch = globalThis.fetch,
+): Promise<DiscoveryDocument> {
+  const discoveryUrl = url.replace(/\/+$/, '') + '/.well-known/openid-configuration'
+  try {
+    const r = await fetchImpl(discoveryUrl, { signal: AbortSignal.timeout(timeoutMs) })
+    if (!r.ok) throw new Error(`HTTP ${r.status}`)
+    const body = (await r.json()) as { issuer?: string; jwks_uri?: string }
+    if (!body.issuer) throw new Error('discovery missing "issuer"')
+    const issuer = body.issuer
+    const jwksUri = body.jwks_uri ?? `${issuer.replace(/\/+$/, '')}/.well-known/jwks.json`
+    return { issuer, jwksUri }
+  } catch (e) {
+    throw new IssuerUnreachableError(discoveryUrl, (e as Error).message)
+  }
+}
+
+export async function fetchJwks(
+  jwksUri: string,
+  timeoutMs = 5_000,
+  fetchImpl: typeof fetch = globalThis.fetch,
+): Promise<{ keys: Array<{ kid?: string }> }> {
+  try {
+    const r = await fetchImpl(jwksUri, { signal: AbortSignal.timeout(timeoutMs) })
+    if (!r.ok) throw new Error(`HTTP ${r.status}`)
+    return (await r.json()) as { keys: Array<{ kid?: string }> }
+  } catch (e) {
+    throw new IssuerUnreachableError(jwksUri, (e as Error).message)
+  }
+}
+
+/**
+ * Discover the WorkOS organization an instance host pins
+ */
+export async function fetchOrgHint(url: string, timeoutMs = 5_000): Promise<string | undefined> {
+  try {
+    const origin = new URL(url).origin
+    const r = await fetch(`${origin}/auth/org`, { signal: AbortSignal.timeout(timeoutMs) })
+    if (!r.ok) return undefined
+    const body = (await r.json()) as { organizationId?: unknown }
+    return typeof body.organizationId === 'string' ? body.organizationId : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Verify the issuer at `url` publishes OIDC discovery and a non-empty JWKS.
+ * `issuerOverride` forces a specific expected issuer when discovery URL and
+ * declared issuer differ.
+ */
+export async function checkIssuerReachability(
+  url: string,
+  issuerOverride?: string,
+  fetchImpl?: typeof fetch,
+): Promise<{ issuer: string; keys: Array<{ kid?: string }> }> {
+  const discovery = await fetchDiscovery(url, 5_000, fetchImpl)
+  const issuer = issuerOverride ?? discovery.issuer
+  const jwks = await fetchJwks(discovery.jwksUri, 5_000, fetchImpl)
+  if (jwks.keys.length === 0)
+    throw new IssuerUnreachableError(discovery.jwksUri, 'no keys published')
+  return { issuer, keys: jwks.keys }
+}

package/src/lib/output.ts

@@ -0,0 +1,222 @@
+import chalk from 'chalk'
+import { stringify as yamlStringify } from 'yaml'
+
+import { renderTable, type Column } from './table'
+
+export type { Column } from './table'
+
+export type OutputOpts = {
+  raw?: boolean
+  json?: boolean
+  format?: 'yaml' | 'json'
+}
+
+export type RawOutputOpts = Pick<OutputOpts, 'raw' | 'json'>
+
+export const RAW_OUTPUT_OPTIONS = [
+  { flags: '--json', description: 'Always-valid JSON (for jq)' },
+  { flags: '--raw', description: 'Unwrapped: bare scalar / raw bytes / JSON for objects' },
+] as const
+
+/**
+ * Is the consumer a machine (emit structured data, not a pretty view)?
+ * True for `--json`, `--raw`, or any non-TTY stdout (pipe, redirect, CI, agent).
+ */
+export function isMachine(opts?: RawOutputOpts): boolean {
+  return !!(opts?.raw || opts?.json) || !(process.stdout.isTTY ?? false)
+}
+
+/**
+ * `--raw` = the *unwrapped* value (bare scalar, raw bytes). The raw-vs-json
+ * distinction only manifests for scalars and binary; objects/arrays fall back
+ * to JSON under either flag.
+ */
+export function isUnwrapped(opts?: RawOutputOpts): boolean {
+  return !!opts?.raw
+}
+
+/**
+ * Write structured data to stdout in the appropriate format.
+ *
+ * Precedence:
+ * - `--raw` / `--json` → plain JSON, no colors (machine-readable)
+ * - explicit `--format yaml|json` → honor regardless of TTY, colors only on TTY
+ * - default on TTY → highlighted YAML
+ * - default on non-TTY → plain JSON
+ *
+ * Void-returning syscalls surface as `undefined` here; `JSON.stringify(undefined)`
+ * itself returns `undefined`, which would print the bare string `undefined` and
+ * break any caller doing `JSON.parse(stdout)`. Normalize to `null` (parseable
+ * JSON, valid YAML) at the entry so every formatter branch is consistent.
+ */
+export function output(data: unknown, opts: OutputOpts): void {
+  if (data === undefined) data = null
+
+  if (opts.raw || opts.json) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n')
+    return
+  }
+
+  const isTTY = process.stdout.isTTY ?? false
+
+  if (opts.format === 'json') {
+    const rendered = isTTY ? highlightJson(data) : JSON.stringify(data, null, 2)
+    process.stdout.write(rendered + '\n')
+    return
+  }
+
+  if (opts.format === 'yaml') {
+    const rendered = isTTY
+      ? highlightYaml(data)
+      : yamlStringify(data, { indent: 2, lineWidth: 120 }).trimEnd()
+    process.stdout.write(rendered + '\n')
+    return
+  }
+
+  // Default: TTY → highlighted YAML, non-TTY → plain JSON
+  if (isTTY) {
+    process.stdout.write(highlightYaml(data) + '\n')
+  } else {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n')
+  }
+}
+
+// ── YAML ───────────────────────────────────────────────────
+
+function highlightYaml(data: unknown): string {
+  const raw = yamlStringify(data, { indent: 2, lineWidth: 120 })
+  return raw
+    .replace(
+      /^(\s*-?\s*)([\w.-]+)(:)\s*(.*)/gm,
+      (_, indent: string, key: string, colon: string, value: string) =>
+        `${indent}${chalk.cyan(key)}${colon} ${colorYamlValue(value)}`,
+    )
+    .trimEnd()
+}
+
+function colorYamlValue(value: string): string {
+  if (value === 'null' || value === '~') return chalk.dim('null')
+  if (value === 'true' || value === 'false') return chalk.magenta(value)
+  if (/^-?\d+(\.\d+)?$/.test(value)) return chalk.yellow(value)
+  return chalk.green(value)
+}
+
+// ── JSON ───────────────────────────────────────────────────
+
+function highlightJson(data: unknown): string {
+  const json = JSON.stringify(data, null, 2)
+  return json
+    .replace(/"([^"]+)"(?=\s*:)/g, (_, key: string) => chalk.cyan(`"${key}"`))
+    .replace(/: "([^"]*)"(?=[,\n\r\]}])/g, (_, val: string) => `: ${chalk.green(`"${val}"`)}`)
+    .replace(/: (-?\d+\.?\d*(?:e[+-]?\d+)?)\b/gi, (_, num: string) => `: ${chalk.yellow(num)}`)
+    .replace(/: (true|false)\b/g, (_, bool: string) => `: ${chalk.magenta(bool)}`)
+    .replace(/: (null)\b/g, () => `: ${chalk.dim('null')}`)
+}
+
+// ── present: shape-aware rendering ──────────────────────────
+
+export type PresentOpts = OutputOpts & { denoise?: boolean }
+
+/** One display row per item plus the columns and (optional) `-q` paths. */
+export type ListProjection = {
+  columns: Column[]
+  rows: Array<Record<string, string>>
+  paths?: string[]
+}
+
+export type ListOpts = OutputOpts & {
+  quiet?: boolean
+  count?: boolean
+  long?: boolean
+}
+
+const NOISE_KEYS = new Set(['schema', 'icon', 'code', 'inputSchema', 'outputSchema'])
+
+/**
+ * Strip heavy, low-signal keys (serialized schema blobs, SVG icons, code) at any
+ * depth — so machine output is the kernel's data minus the noise, never a wall.
+ */
+export function denoise(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(denoise)
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(value)) {
+      if (NOISE_KEYS.has(k)) continue
+      out[k] = v && typeof v === 'object' ? denoise(v) : v
+    }
+    return out
+  }
+  return value
+}
+
+function isBareScalar(v: unknown): v is string | number | boolean {
+  return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'
+}
+
+/**
+ * Present a single kernel value, shape- and audience-aware.
+ *
+ * - scalar → `--raw` bare (no quotes, for `X=$(…)`) · `--json`/pipe JSON · TTY bare
+ * - object → YAML on a TTY, JSON for machines (delegates to {@link output})
+ * - array  → YAML/JSON fallback (use {@link presentList} for a table)
+ *
+ * `null`/`undefined` normalize to `null` (via `output`) so `JSON.parse(stdout)`
+ * never breaks.
+ */
+export function present(value: unknown, opts: PresentOpts = {}): void {
+  const data = opts.denoise ? denoise(value) : value
+
+  if (isBareScalar(data)) {
+    if (opts.raw) {
+      process.stdout.write(String(data) + '\n')
+      return
+    }
+    if (!opts.json && (process.stdout.isTTY ?? false)) {
+      process.stdout.write(String(data) + '\n')
+      return
+    }
+    // `--json` or non-TTY machine → JSON (quoted string / bare number).
+  }
+
+  output(data, opts)
+}
+
+/**
+ * Present an array of objects.
+ *
+ * - `--count`     → just the number
+ * - `-q/--quiet`  → one path per line (unix-pipeable)
+ * - machine       → denoised JSON of the raw items (`-l` keeps full items)
+ * - TTY           → an aligned table + a dim count footer
+ *
+ * Projection (columns/rows/paths) is for the human table and `-q` only; the
+ * machine surface stays the kernel's own item fields.
+ */
+export function presentList<T>(
+  items: T[],
+  opts: ListOpts,
+  project: (items: T[]) => ListProjection,
+): void {
+  if (opts.count) {
+    process.stdout.write(String(items.length) + '\n')
+    return
+  }
+
+  if (opts.quiet) {
+    const proj = project(items)
+    const paths = proj.paths ?? proj.rows.map((r) => r[proj.columns[0]?.key ?? ''] ?? '')
+    for (const p of paths) process.stdout.write(p + '\n')
+    return
+  }
+
+  if (isMachine(opts) || opts.format) {
+    output(opts.long ? items : denoise(items), opts)
+    return
+  }
+
+  const proj = project(items)
+  const table = renderTable(proj.rows, { columns: proj.columns })
+  const footer =
+    items.length > 0 ? chalk.dim(`\n  ${items.length} item${items.length === 1 ? '' : 's'}`) : ''
+  process.stdout.write(table + footer + '\n')
+}

package/src/lib/panel.ts

@@ -0,0 +1,61 @@
+import chalk from 'chalk'
+
+// ESC[…m — built without a control char in the source so no lint disable is needed.
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g')
+
+/** Printable width of a string, ignoring ANSI color codes. */
+function visibleWidth(s: string): number {
+  return s.replace(ANSI, '').length
+}
+
+const BOX = { tl: '╭', tr: '╮', bl: '╰', br: '╯', h: '─', v: '│' } as const
+
+export type PanelOpts = {
+  /** Colorize the box border (default: cyan). */
+  borderColor?: (s: string) => string
+  /** Horizontal padding inside the box (default: 3). */
+  padX?: number
+  /** Left margin in spaces for the whole box (default: 2). */
+  margin?: number
+}
+
+/**
+ * Draw a rounded box around pre-styled lines. Widths are computed on *visible*
+ * length so embedded ANSI (bold/color/underline) never breaks alignment. The
+ * lines are passed in already colored — `panel` only frames them.
+ */
+export function panel(lines: string[], opts: PanelOpts = {}): string {
+  const padX = opts.padX ?? 3
+  const margin = ' '.repeat(opts.margin ?? 2)
+  const border = opts.borderColor ?? chalk.cyan
+  const inner = Math.max(0, ...lines.map(visibleWidth))
+  const span = inner + padX * 2
+
+  const top = margin + border(BOX.tl + BOX.h.repeat(span) + BOX.tr)
+  const bottom = margin + border(BOX.bl + BOX.h.repeat(span) + BOX.br)
+  const body = lines.map((line) => {
+    const fill = ' '.repeat(inner - visibleWidth(line))
+    return (
+      margin + border(BOX.v) + ' '.repeat(padX) + line + fill + ' '.repeat(padX) + border(BOX.v)
+    )
+  })
+  return [top, ...body, bottom].join('\n')
+}
+
+/**
+ * The provisioned-instance hero: a bright, click-inviting panel that puts the
+ * fresh instance URL front and center. Rendered only in interactive (human)
+ * mode — machine output carries the URL in its JSON instead.
+ */
+export function renderInstanceHero(slug: string, url: string): string {
+  return panel(
+    [
+      `${chalk.green('✦')}  ${chalk.bold('Your instance is live')}`,
+      '',
+      `   ${chalk.bold.cyan.underline(url)}`,
+      '',
+      chalk.dim(`   ${slug} · ⌘-click the link or paste it into your browser`),
+    ],
+    { borderColor: chalk.cyan },
+  )
+}

package/src/lib/paths.ts

@@ -0,0 +1,11 @@
+import { paths } from './env'
+
+export const ASTRALE_HOME = paths.home
+export const KEYS_DIR = paths.keys
+export const DATA_DIR = paths.data
+export const CONFIG_PATH = paths.config
+export const INSTALL_PATH = paths.install
+export const IDENTITIES_PATH = paths.identities
+export const INSTANCES_PATH = paths.instances
+export const IDPS_PATH = paths.idps
+export const IDP_SESSIONS_DIR = paths.idpSessionsDir

package/src/lib/port.ts

@@ -0,0 +1,41 @@
+import net from 'node:net'
+
+/**
+ * Loopback port helpers for launching local servers (e.g. `astrale studio`).
+ *
+ * We probe by ACTUALLY trying to bind, not by connecting — a connect-probe to
+ * 127.0.0.1 is racy and can falsely pass on a half-open socket. Whatever port
+ * the OS lets us bind is, by definition, free for us right now. We bind on the
+ * loopback interface specifically (matching the studio's 127.0.0.1 bind) with
+ * `exclusive: true` so the probe never "succeeds" on a port another process
+ * holds via SO_REUSEADDR/REUSEPORT.
+ */
+const LOOPBACK = '127.0.0.1'
+
+/** Resolves true if [port] can be bound on loopback right now, false otherwise. */
+export function portFree(port: number, host = LOOPBACK): Promise<boolean> {
+  return new Promise((resolve) => {
+    const srv = net.createServer()
+    srv.once('error', () => resolve(false))
+    srv.once('listening', () => srv.close(() => resolve(true)))
+    srv.listen({ port, host, exclusive: true })
+  })
+}
+
+/**
+ * First free port in [start, start + span) on loopback, or null if the whole
+ * window is taken. We deliberately scan a small band in the IANA Registered
+ * range (well below the OS ephemeral range, which starts at 49152 on
+ * macOS/BSD and 32768 on Linux) so a probe can't collide with a short-lived
+ * outbound socket the OS hands out a microsecond later.
+ */
+export async function findFreePort(
+  start: number,
+  span = 20,
+  host = LOOPBACK,
+): Promise<number | null> {
+  for (let p = start; p < start + span; p++) {
+    if (await portFree(p, host)) return p
+  }
+  return null
+}

package/src/lib/proc.ts

@@ -0,0 +1,82 @@
+import { spawn, type ChildProcess, type StdioOptions } from 'node:child_process'
+
+export type RunResult = {
+  /** Exit code, or -1 when the process was killed by a signal. */
+  code: number
+  stdout: string
+  stderr: string
+}
+
+/**
+ * Spawn a child process and capture stdout/stderr as UTF-8 text.
+ *
+ * Uses `node:child_process` rather than `Bun.spawn` so the exact same code runs
+ * under both the Bun-compiled standalone binary (Linux/macOS) and the Node/npm
+ * build (Windows and any Node user). The promise rejects only when the process
+ * fails to spawn (e.g. ENOENT); a non-zero exit resolves with that `code` so
+ * callers can branch on it.
+ */
+export function run(
+  file: string,
+  args: string[] = [],
+  opts: { cwd?: string } = {},
+): Promise<RunResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(file, args, { cwd: opts.cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    let stdout = ''
+    let stderr = ''
+    child.stdout?.setEncoding('utf8')
+    child.stderr?.setEncoding('utf8')
+    child.stdout?.on('data', (chunk: string) => {
+      stdout += chunk
+    })
+    child.stderr?.on('data', (chunk: string) => {
+      stderr += chunk
+    })
+    child.on('error', reject)
+    child.on('close', (code) => resolve({ code: code ?? -1, stdout, stderr }))
+  })
+}
+
+/**
+ * Spawn a child process with inherited stdio so its output streams live to the
+ * user's terminal. Used for hand-held installs (npm / npx) where progress
+ * matters and the output is for the human, not for parsing. Resolves with the
+ * exit code; rejects only when the process fails to spawn (e.g. ENOENT).
+ */
+export function runInherit(
+  file: string,
+  args: string[] = [],
+  opts: { cwd?: string } = {},
+): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(file, args, { cwd: opts.cwd, stdio: 'inherit' })
+    child.on('error', reject)
+    child.on('close', (code) => resolve(code ?? -1))
+  })
+}
+
+/**
+ * Spawn a LONG-LIVED child and return the handle immediately so the caller can
+ * supervise it (wait for exit, forward signals, tear down siblings). Unlike
+ * run()/runInherit() — which resolve only once the child closes — this is for
+ * servers the command keeps attached to (e.g. `astrale studio`'s Bun server and
+ * Vite dev process). Same node:child_process basis (cross-runtime) and bare
+ * PATH-name lookup convention. Default stdio streams stdout/stderr live but
+ * ignores stdin, so two supervised children never contend for the TTY.
+ */
+export function spawnHandle(
+  file: string,
+  args: string[] = [],
+  opts: { cwd?: string; env?: NodeJS.ProcessEnv; stdio?: StdioOptions; detached?: boolean } = {},
+): ChildProcess {
+  return spawn(file, args, {
+    cwd: opts.cwd,
+    env: opts.env,
+    // `detached` makes the child its own process-group leader so the caller can
+    // tear down the whole tree (the child AND its grandchildren) with a single
+    // group signal — `process.kill(-child.pid, …)`.
+    detached: opts.detached,
+    stdio: opts.stdio ?? ['ignore', 'inherit', 'inherit'],
+  })
+}