@astrale-os/cli 0.5.0-alpha.0 → 0.6.0-alpha.0

package/src/lib/instance-target.ts

@@ -172,6 +172,11 @@ export function adminTargetToInstance(target: ResolvedAdminTarget): ResolvedInst
 export function isManagedInstanceNotFound(error: unknown): boolean {
   if (!(error instanceof Error)) return false
   if (error.name === 'NotFoundError') return true
+  // The admin kernel reports a missing instance node as InternalKernelError
+  // with a NOT_FOUND-prefixed message. In this lookup that's an instance
+  // miss (config problem), not a kernel fault — map it so callers get the
+  // typed INSTANCE_NOT_FOUND with remediation instead of a raw kernel error.
+  if (error.name === 'InternalKernelError' && /^NOT_FOUND\b/.test(error.message)) return true
   const data = (error as Error & { data?: unknown }).data
   return (
     error.name === 'KernelError' &&

package/src/lib/instance.ts

@@ -113,6 +113,17 @@ export function sanitizeStore(store: InstanceStore): { store: InstanceStore; cha
 
 let instancesMemo: InstanceStore | null = null
 
+/**
+ * Drop the in-process bookmark cache so the next `readInstances` re-reads disk.
+ *
+ * A long-lived host (e.g. `@astrale-os/connect-host`) would otherwise serve a
+ * stale bookmark list after the user runs `astrale instance bookmark`. The CLI
+ * itself is one-shot, so this is a no-op for command usage.
+ */
+export function resetInstancesMemo(): void {
+  instancesMemo = null
+}
+
 export async function readInstances(
   _config?: AstraleConfig,
   opts: { persist?: boolean } = {},

package/src/lib/log.ts

@@ -3,6 +3,7 @@ import ora, { type Ora } from 'ora'
 
 import { AstraleError, NotImplementedError } from '../errors'
 import { formatElapsed } from './format'
+import { isMachine, type RawOutputOpts } from './output'
 
 export const log = {
   info: (msg: string) => console.log(chalk.blue('ℹ'), msg),
@@ -13,12 +14,21 @@ export const log = {
   dim: (msg: string) => console.log(chalk.dim(msg)),
 }
 
-/** Report an error with hint (when present) and exit. */
-export function fatal(e: unknown): never {
+/** Report an error with hint (when present) and exit. Commands that carry
+ *  RawOutputOpts should pass them so machine consumers (--json/--raw/piped)
+ *  get one structured JSON line on stderr instead of the pretty ✖ view. */
+export function fatal(e: unknown, opts?: RawOutputOpts): never {
   // Ctrl-C at an interactive (@inquirer/prompts) prompt — exit quietly with the
   // SIGINT convention, not a red error line.
   if (e instanceof Error && e.name === 'ExitPromptError') process.exit(130)
   const msg = e instanceof Error ? e.message : String(e)
+  if (opts && isMachine(opts)) {
+    const error = e instanceof AstraleError ? e.code : e instanceof Error ? e.name : 'Error'
+    const payload: Record<string, unknown> = { error, message: msg }
+    if (e instanceof AstraleError && e.hint) payload.hint = e.hint
+    process.stderr.write(JSON.stringify(payload) + '\n')
+    process.exit(1)
+  }
   log.error(msg)
   if (e instanceof AstraleError && e.hint) log.dim(`  hint: ${e.hint}`)
   process.exit(1)

package/src/lib/login-flow.ts

@@ -29,6 +29,27 @@ import { log } from './log'
  * behavior; presentation (the device URL is logged here; success lines are the
  * caller's) does not.
  */
+/**
+ * Interactive device-flow progress. Emitted once, when the device authorization
+ * has been requested and the user must approve it in a browser. The caller
+ * decides how to present it (the CLI logs it; the desktop opens the URL and
+ * pushes it to the renderer). Structurally identical to connect-host's wire
+ * `AuthVerificationEvent`, but declared here so the CLI carries no dependency on
+ * connect-host (which depends on the CLI, not the reverse).
+ */
+export type DeviceVerification = {
+  /** The base verification URL (fallback to the complete one when absent). */
+  verificationUri: string
+  /** Pre-filled verification URL (opens straight to the approval page). */
+  verificationUriComplete?: string
+  /** The short user code to confirm — a reassurance fallback when the URL is pre-filled. */
+  userCode?: string
+  /** Seconds until the device code expires. */
+  expiresIn?: number
+  /** Human-readable instruction from the IdP. */
+  message?: string
+}
+
 export type LoginFlowOpts = {
   idp?: string
   name?: string
@@ -42,6 +63,12 @@ export type LoginFlowOpts = {
   codeVerifier?: string
   /** Switch the default identity to the one we just logged in (default true). */
   use?: boolean
+  /**
+   * When set, receives the device-flow verification details and REPLACES the
+   * default `log.info` presentation (a headless/GUI caller drives the UI). The
+   * `auth login` command passes nothing, so its terminal output is unchanged.
+   */
+  onVerification?: (e: DeviceVerification) => void
 }
 
 export type LoginResult = {
@@ -148,10 +175,20 @@ async function obtainToken(
     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}`)
+  if (opts.onVerification) {
+    opts.onVerification({
+      verificationUri: device.verification_uri ?? device.verification_uri_complete ?? '',
+      verificationUriComplete: device.verification_uri_complete,
+      userCode: device.user_code,
+      expiresIn: device.expires_in,
+      message: device.message,
+    })
+  } else {
+    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,

package/src/lib/provision-instance.ts

@@ -5,7 +5,7 @@ import type { AdminTargetCommandOpts } from './admin-target'
 
 import { AuthError } from '../errors'
 import { withAdminKernelClient } from '../kernel/client'
-import { ADMIN_INSTANCE } from './admin-instance'
+import { adminInstanceMethod } from './admin-instance'
 import { readIdentities, type IdentityStore } from './identity'
 import { setActive, upsertManagedBookmark } from './instance'
 import { withSpinner } from './log'
@@ -74,7 +74,7 @@ export async function provisionInstance(
         const created = await withAdminKernelClient(
           createOpts,
           async (ctx) =>
-            (await ctx.client.call(`${ADMIN_INSTANCE}/alphaCreate`, {
+            (await ctx.client.call(adminInstanceMethod('alphaCreate'), {
               slug,
               ...(hostId ? { host_id: hostId } : {}),
             })) as { url: string; organizationId?: string },

package/src/lib/view/open-intent.ts

@@ -0,0 +1,97 @@
+import type { IntentMessage, MountedWindow, ResolvedView, Shell } from '@astrale-os/shell'
+
+export interface OpenIntentHost {
+  current(): MountedWindow | null
+  setCurrent(window: MountedWindow): void
+  mount(view: ResolvedView, nodeId: string): Promise<MountedWindow>
+  opened(view: ResolvedView, nodeId: string): void
+  failed(error: unknown): void
+  reply(message: IntentMessage<'open'>, windowId: string): void
+  reject(message: IntentMessage<'open'>, error: unknown): void
+}
+
+/** Register the root host's serialized node-to-View navigation handler. */
+export function installOpenIntentHandler(shell: Shell, host: OpenIntentHost): () => void {
+  let queue = Promise.resolve()
+  return shell.onIntent('open', (message) => {
+    const run = queue.then(() => handleOpenIntent(shell, host, message))
+    queue = run.catch(() => {})
+    return run
+  })
+}
+
+export async function handleOpenIntent(
+  shell: Pick<Shell, 'views'>,
+  host: OpenIntentHost,
+  message: IntentMessage<'open'>,
+): Promise<void> {
+  const { nodeId, viewId } = message.envelope.payload
+  try {
+    const selected = selectResolvedView(await shell.views.resolve(nodeId), viewId)
+    const previous = host.current()
+    const next = await host.mount(selected, nodeId)
+
+    host.setCurrent(next)
+    host.opened(selected, nodeId)
+    // A correlated requester is normally `previous`; answer while its channel
+    // still exists, then retire the old mount.
+    host.reply(message, next.windowId)
+
+    if (previous && previous.windowId !== next.windowId) {
+      try {
+        const closed = await previous.close({ force: true })
+        if (closed.kind === 'refused') {
+          host.failed(new Error(closed.reason ?? `Window ${previous.windowId} refused to close`))
+        }
+      } catch (error) {
+        host.failed(error)
+      }
+    }
+  } catch (error) {
+    host.reject(message, error)
+    host.failed(error)
+  }
+}
+
+export function selectResolvedView(
+  views: readonly ResolvedView[],
+  viewId: string | undefined,
+): ResolvedView {
+  const selected = viewId ? views.find((view) => view.id === viewId) : views[0]
+  if (selected) return selected
+  throw new Error(
+    viewId ? `View ${viewId} does not resolve for this node` : 'No view resolves for this node',
+  )
+}
+
+/** Mount a shell view with bounded handshake retries and a plain fallback. */
+export async function mountWithHandshakeFallback<T>(opts: {
+  handshake: 'shell' | 'none'
+  attempts: number
+  mount(handshake: 'shell' | 'none'): Promise<T>
+  cleanupFailedAttempt(): void
+}): Promise<{ mounted: T; handshake: 'shell' | 'none' }> {
+  if (opts.handshake === 'none') {
+    try {
+      return { mounted: await opts.mount('none'), handshake: 'none' }
+    } catch (error) {
+      opts.cleanupFailedAttempt()
+      throw error
+    }
+  }
+  let lastError: unknown
+  for (let attempt = 0; attempt < opts.attempts; attempt++) {
+    try {
+      return { mounted: await opts.mount('shell'), handshake: 'shell' }
+    } catch (error) {
+      lastError = error
+      opts.cleanupFailedAttempt()
+    }
+  }
+  try {
+    return { mounted: await opts.mount('none'), handshake: 'none' }
+  } catch (error) {
+    opts.cleanupFailedAttempt()
+    throw error ?? lastError
+  }
+}

package/src/lib/view/resolve.ts

@@ -0,0 +1,104 @@
+import type { ClientContext } from '../../kernel'
+
+import { AstraleError } from '../../errors'
+
+/**
+ * View + target resolution for `astrale view`. Both spec shapes funnel through
+ * the kernel's `View:resolve` syscall: a ViewPath resolves to the view node
+ * itself (its class implements UI), a target path lists the views attached to
+ * it via `view_for`.
+ */
+
+const VIEW_RESOLVE_PATH = '/:kernel.astrale.ai:class.View:resolve'
+const VIEW_PATH_RE = /^\/:[^\s/:@]+:view\.[a-z][a-z0-9-]*$/
+
+export type ViewSpec = { kind: 'view' | 'target'; path: string }
+
+export function parseViewSpec(spec: string): ViewSpec {
+  if (VIEW_PATH_RE.test(spec)) return { kind: 'view', path: spec }
+  if (spec.startsWith('/') || spec.startsWith('@')) return { kind: 'target', path: spec }
+  throw new AstraleError(
+    'INVALID_ARGUMENT',
+    `"${spec}" is neither a ViewPath (/:origin:view.slug) nor a node path (/… or @id)`,
+  )
+}
+
+/** Wire shape of one `View:resolve` entry. */
+export type ViewCandidate = {
+  id: string
+  path: string
+  url: string
+  name?: string
+  handshake?: 'shell' | 'none'
+  origin: 'self' | 'class'
+}
+
+export async function resolveViewCandidates(
+  ctx: ClientContext,
+  nodePath: string,
+): Promise<ViewCandidate[]> {
+  const result = await ctx.client.call(VIEW_RESOLVE_PATH, { node: nodePath })
+  if (!Array.isArray(result)) {
+    throw new AstraleError('UNEXPECTED_RESULT', `View:resolve returned a non-array for ${nodePath}`)
+  }
+  return result as ViewCandidate[]
+}
+
+/** The slug tail of a candidate: `view.dashboard` → `dashboard`. */
+export function candidateSlug(candidate: ViewCandidate): string {
+  const fromPath = candidate.path?.split('/').pop() ?? ''
+  return candidate.name ?? fromPath
+}
+
+export function pickCandidate(
+  candidates: ViewCandidate[],
+  nodePath: string,
+  slug?: string,
+): ViewCandidate | 'ambiguous' {
+  if (slug) {
+    const match = candidates.find((c) => candidateSlug(c) === slug || c.path.endsWith(`/${slug}`))
+    if (!match) {
+      throw new AstraleError(
+        'VIEW_NOT_FOUND',
+        `No view "${slug}" on ${nodePath} — available: ${candidates.map(candidateSlug).join(', ') || '(none)'}`,
+      )
+    }
+    return match
+  }
+  if (candidates.length === 0) {
+    throw new AstraleError('VIEW_NOT_FOUND', `No views resolve on ${nodePath}`)
+  }
+  if (candidates.length === 1) return candidates[0]
+  return 'ambiguous'
+}
+
+/**
+ * Apply a `--view-url` override: an origin-only value swaps the origin and
+ * keeps the resolved path, a value with a path replaces the URL wholesale.
+ */
+export function applyViewUrlOverride(resolvedUrl: string, override: string): string {
+  const parsed = parseUrl(override)
+  if (parsed.pathname !== '/') return parsed.toString()
+  const original = parseUrl(resolvedUrl)
+  return new URL(original.pathname + original.search + original.hash, parsed.origin).toString()
+}
+
+/**
+ * The kernel addresses locally-served workers as `host.docker.internal`
+ * (reachable from its container); the host browser reaches the same worker on
+ * loopback. Rewrite so the iframe loads without an /etc/hosts entry.
+ */
+export function rewriteLocalViewUrl(url: string): string {
+  const parsed = parseUrl(url)
+  if (parsed.hostname !== 'host.docker.internal') return url
+  parsed.hostname = '127.0.0.1'
+  return parsed.toString()
+}
+
+function parseUrl(raw: string): URL {
+  try {
+    return new URL(raw)
+  } catch {
+    throw new AstraleError('INVALID_URL', `Not a valid URL: ${raw}`)
+  }
+}

package/src/lib/view/server.ts

@@ -0,0 +1,294 @@
+import type { ReadableStream as WebReadableStream } from 'node:stream/web'
+
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
+import { dirname, join } from 'node:path'
+import { Readable } from 'node:stream'
+
+import type { ViewServeConfig } from './session'
+
+import { withKernelClient } from '../../kernel'
+import { fetchWithCaFile } from '../../kernel/ca-fetch'
+import { removeSessionFiles } from './session'
+
+/**
+ * The view-session server: serves the host page, hands it config and fresh
+ * credentials, receives its lifecycle reports, and proxies the view's kernel
+ * calls (one mechanism for CORS, self-signed local CAs, and keeping the kernel
+ * origin out of the page). Everything is nonce-scoped under `/s/<nonce>/`;
+ * loopback-only. Exits after `idleMs` without a request — the host page's
+ * heartbeat keeps a live session alive.
+ */
+
+const TOKEN_REFRESH_MARGIN_MS = 5 * 60_000
+const FALLBACK_TOKEN_TTL_MS = 3600_000
+const IDLE_SWEEP_MS = 60_000
+
+export type PageStatus = { state: string; error?: string; at: string }
+
+type TokenGrant = { token: string; expiresAt: number; kind: 'minted' | 'raw' }
+
+export function startViewServer(config: ViewServeConfig): Server {
+  const { session, proxy } = config
+  const base = `/s/${session.nonce}`
+  const hostDir = viewerDistDir()
+  const proxyFetch = proxy.caFile ? fetchWithCaFile(proxy.caFile) : globalThis.fetch
+  let status: PageStatus = { state: 'waiting', at: new Date().toISOString() }
+  let grant: TokenGrant | null = null
+  let lastActivity = Date.now()
+
+  /**
+   * Prefer a kernel-minted TTL-bound identity credential (what the GUI hands
+   * its iframes); fall back to the raw CLI credential so the session works
+   * anywhere the CLI itself can call.
+   */
+  async function freshGrant(): Promise<TokenGrant> {
+    if (grant && grant.expiresAt - Date.now() > TOKEN_REFRESH_MARGIN_MS) return grant
+    grant = await withKernelClient(config.kernel, async (ctx) => {
+      try {
+        const token = await ctx.client.as(ctx.credential).auth.mint()
+        return {
+          token,
+          expiresAt: jwtExpiry(token) ?? Date.now() + FALLBACK_TOKEN_TTL_MS,
+          kind: 'minted' as const,
+        }
+      } catch (error) {
+        console.log(
+          `mint failed (${error instanceof Error ? error.message : String(error)}) — falling back to the raw CLI credential`,
+        )
+        const token = ctx.credential
+        return {
+          token,
+          expiresAt: jwtExpiry(token) ?? Date.now() + FALLBACK_TOKEN_TTL_MS,
+          kind: 'raw' as const,
+        }
+      }
+    })
+    return grant
+  }
+
+  const server = createServer((req, res) => {
+    lastActivity = Date.now()
+    void route(req, res).catch((error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error)
+      // CORS headers even on failures — the caller may be the cross-origin
+      // view iframe, and an opaque error reads as a network failure there.
+      if (!res.headersSent) {
+        res.writeHead(502, {
+          'content-type': 'application/json',
+          ...corsHeaders(req.headers.origin),
+        })
+      }
+      res.end(JSON.stringify({ error: message }))
+    })
+  })
+
+  async function route(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = new URL(req.url ?? '/', 'http://localhost')
+    if (!url.pathname.startsWith(`${base}/`) && url.pathname !== base) {
+      res.writeHead(404).end()
+      return
+    }
+    const sub = url.pathname.slice(base.length) || '/'
+
+    if (sub === '/k' || sub.startsWith('/k/')) {
+      await proxyKernel(req, res, sub.slice('/k'.length), url.search)
+      return
+    }
+    if (sub === '/' || sub === '/index.html') {
+      await serveAsset(res, join(hostDir, 'index.html'), 'text/html; charset=utf-8')
+      return
+    }
+    if (sub === '/main.js') {
+      await serveAsset(res, join(hostDir, 'main.js'), 'text/javascript; charset=utf-8')
+      return
+    }
+    if (sub === '/config.json' && req.method === 'GET') {
+      json(res, 200, {
+        viewUrl: session.view.url,
+        viewPath: session.view.path ?? null,
+        viewName: session.view.name ?? null,
+        functionId: session.view.functionId,
+        handshake: session.view.handshake,
+        targetNodeId: session.target?.id ?? null,
+        targetPath: session.target?.path ?? null,
+        kernelUrl: proxy.direct ? proxy.kernelUrl : `${base}/k`,
+        identity: session.identity ?? null,
+        instance: session.instance ?? null,
+        sessionId: session.id,
+      })
+      return
+    }
+    if (sub === '/token' && req.method === 'POST') {
+      const fresh = await freshGrant()
+      json(res, 200, { token: fresh.token, expiresAt: fresh.expiresAt, kind: fresh.kind })
+      return
+    }
+    if (sub === '/status' && req.method === 'POST') {
+      const body = await readJson(req)
+      if (body && typeof body.state === 'string' && body.state !== 'alive') {
+        status = { state: body.state, error: asString(body.error), at: new Date().toISOString() }
+      }
+      res.writeHead(204).end()
+      return
+    }
+    if (sub === '/state' && req.method === 'GET') {
+      json(res, 200, status)
+      return
+    }
+    res.writeHead(404).end()
+  }
+
+  /** Forward a kernel call: verbatim headers/body both ways, CORS added. */
+  async function proxyKernel(
+    req: IncomingMessage,
+    res: ServerResponse,
+    suffix: string,
+    search: string,
+  ): Promise<void> {
+    const origin = req.headers.origin
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, corsHeaders(origin)).end()
+      return
+    }
+    const target = joinUrl(proxy.kernelUrl, suffix) + search
+    const headers: Record<string, string> = {}
+    for (const name of ['authorization', 'content-type', 'accept']) {
+      const value = req.headers[name]
+      if (typeof value === 'string') headers[name] = value
+    }
+    // Buffer the request body (envelope requests are small JSON): the caFile
+    // fetch path speaks node https and cannot consume a web-stream body.
+    // Response bodies still stream through.
+    const hasBody = req.method !== 'GET' && req.method !== 'HEAD'
+    const body = hasBody ? Buffer.concat(await collect(req)) : undefined
+    const upstream = await proxyFetch(target, {
+      method: req.method,
+      headers,
+      ...(body !== undefined ? { body } : {}),
+    } as RequestInit)
+    const responseHeaders: Record<string, string> = corsHeaders(origin)
+    const contentType = upstream.headers.get('content-type')
+    if (contentType) responseHeaders['content-type'] = contentType
+    res.writeHead(upstream.status, responseHeaders)
+    if (upstream.body) {
+      Readable.fromWeb(upstream.body as unknown as WebReadableStream).pipe(res)
+    } else {
+      res.end()
+    }
+  }
+
+  const idleTimer = setInterval(() => {
+    if (Date.now() - lastActivity > config.idleMs) void shutdown(0)
+  }, IDLE_SWEEP_MS)
+  idleTimer.unref()
+
+  async function shutdown(code: number): Promise<void> {
+    clearInterval(idleTimer)
+    server.close()
+    await removeSessionFiles(session.id)
+    process.exit(code)
+  }
+  process.on('SIGTERM', () => void shutdown(0))
+  process.on('SIGINT', () => void shutdown(0))
+
+  server.listen(session.port, '127.0.0.1')
+  return server
+}
+
+/**
+ * The prebuilt host-page bundle, shipped next to the CLI entry
+ * (`<pkg>/viewer/dist`). Dev runs (bun, no dist) build it on demand.
+ */
+export function viewerDistDir(): string {
+  const override = process.env.ASTRALE_VIEWER_DIR
+  if (override) return override
+  return join(dirname(process.argv[1] ?? '.'), '..', 'viewer', 'dist')
+}
+
+/** Ensure the host bundle exists; on a dev checkout, build it with Bun. */
+export async function ensureViewerAssets(): Promise<string> {
+  const dist = viewerDistDir()
+  if (existsSync(join(dist, 'main.js')) && existsSync(join(dist, 'index.html'))) return dist
+  const srcDir = join(dist, '..')
+  const bun = (
+    globalThis as { Bun?: { build: (o: object) => Promise<{ success: boolean; logs: unknown[] }> } }
+  ).Bun
+  if (bun && existsSync(join(srcDir, 'main.ts'))) {
+    const result = await bun.build({
+      entrypoints: [join(srcDir, 'main.ts')],
+      outdir: dist,
+      target: 'browser',
+      minify: false,
+    })
+    if (!result.success) throw new Error(`viewer build failed: ${result.logs.join('\n')}`)
+    const { copyFile } = await import('node:fs/promises')
+    await copyFile(join(srcDir, 'index.html'), join(dist, 'index.html'))
+    return dist
+  }
+  throw new Error(
+    `viewer bundle missing at ${dist} — reinstall the CLI (or run \`bun scripts/build.ts\` in a dev checkout)`,
+  )
+}
+
+function jwtExpiry(token: string): number | null {
+  try {
+    const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8')) as {
+      exp?: number
+    }
+    return typeof payload.exp === 'number' ? payload.exp * 1000 : null
+  } catch {
+    return null
+  }
+}
+
+function corsHeaders(origin: string | undefined): Record<string, string> {
+  return {
+    'access-control-allow-origin': origin ?? '*',
+    'access-control-allow-methods': 'GET,POST,PUT,PATCH,DELETE,OPTIONS',
+    'access-control-allow-headers': 'authorization, content-type, accept',
+    // Chrome private-network-access preflight (public page → loopback proxy).
+    'access-control-allow-private-network': 'true',
+    'access-control-max-age': '600',
+    vary: 'origin',
+  }
+}
+
+function joinUrl(baseUrl: string, suffix: string): string {
+  if (!suffix) return baseUrl
+  return baseUrl.replace(/\/$/, '') + suffix
+}
+
+function json(res: ServerResponse, code: number, body: unknown): void {
+  res.writeHead(code, { 'content-type': 'application/json' })
+  res.end(JSON.stringify(body))
+}
+
+async function serveAsset(res: ServerResponse, file: string, contentType: string): Promise<void> {
+  try {
+    const content = await readFile(file)
+    res.writeHead(200, { 'content-type': contentType, 'cache-control': 'no-store' })
+    res.end(content)
+  } catch {
+    res.writeHead(404).end()
+  }
+}
+
+async function collect(req: IncomingMessage): Promise<Buffer[]> {
+  const chunks: Buffer[] = []
+  for await (const chunk of req) chunks.push(chunk as Buffer)
+  return chunks
+}
+
+async function readJson(req: IncomingMessage): Promise<Record<string, unknown> | null> {
+  try {
+    return JSON.parse(Buffer.concat(await collect(req)).toString('utf8')) as Record<string, unknown>
+  } catch {
+    return null
+  }
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined
+}