@astrale-os/cli 0.4.0-alpha.13 → 0.6.0-alpha.0

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
+}

package/src/lib/view/session.ts

@@ -0,0 +1,123 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { paths } from '../env'
+
+/**
+ * View-session records: one detached server process per open view, tracked as
+ * `~/.astrale/view/<id>.json` (+ `<id>.log`, `<id>.config.json`). Records are
+ * garbage-collected on every `astrale view` invocation by probing the pid.
+ */
+
+export const VIEW_DIR = join(paths.home, 'view')
+
+export type ViewSessionRecord = {
+  id: string
+  pid: number
+  port: number
+  nonce: string
+  /** Host page URL, nonce-scoped: `http://127.0.0.1:<port>/s/<nonce>/`. */
+  pageUrl: string
+  view: {
+    url: string
+    functionId: string
+    handshake: 'shell' | 'none'
+    /** ViewPath or resolved view node path, when the view came from the graph. */
+    path?: string
+    name?: string
+  }
+  target?: { id?: string; path?: string }
+  instance?: string
+  identity?: string
+  createdAt: string
+}
+
+/** Everything the detached `view __serve` process needs, written before spawn. */
+export type ViewServeConfig = {
+  session: ViewSessionRecord
+  /** Kernel passthrough opts, re-resolved server-side for token mints. */
+  kernel: { url?: string; instance?: string; as?: string; creds?: string; timeout?: string }
+  /**
+   * Kernel the view dispatches to. `direct: true` hands the child the kernel
+   * URL itself (public https kernels — the router serves CORS, and Chrome's
+   * local-network-access rules forbid a public view origin fetching our
+   * loopback proxy). Otherwise the child gets the nonce-scoped proxy, which
+   * handles CORS and self-signed local CAs.
+   */
+  proxy: { kernelUrl: string; caFile?: string; direct: boolean }
+  idleMs: number
+}
+
+export const recordPath = (id: string): string => join(VIEW_DIR, `${id}.json`)
+export const logPath = (id: string): string => join(VIEW_DIR, `${id}.log`)
+export const configPath = (id: string): string => join(VIEW_DIR, `${id}.config.json`)
+
+export async function saveRecord(record: ViewSessionRecord): Promise<void> {
+  await mkdir(VIEW_DIR, { recursive: true })
+  await writeFile(recordPath(record.id), `${JSON.stringify(record, null, 2)}\n`)
+}
+
+export async function removeSessionFiles(id: string): Promise<void> {
+  await Promise.all([
+    rm(recordPath(id), { force: true }),
+    rm(configPath(id), { force: true }),
+    rm(logPath(id), { force: true }),
+  ])
+}
+
+export function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** List live sessions, removing records whose server process is gone. */
+export async function listSessions(): Promise<ViewSessionRecord[]> {
+  let entries: string[]
+  try {
+    entries = await readdir(VIEW_DIR)
+  } catch {
+    return []
+  }
+  const live: ViewSessionRecord[] = []
+  for (const entry of entries) {
+    if (!/^v-[0-9a-f]+\.json$/.test(entry)) continue
+    let record: ViewSessionRecord
+    try {
+      record = JSON.parse(await readFile(join(VIEW_DIR, entry), 'utf8')) as ViewSessionRecord
+    } catch {
+      continue
+    }
+    if (isAlive(record.pid)) live.push(record)
+    else await removeSessionFiles(record.id)
+  }
+  return live.sort((a, b) => a.createdAt.localeCompare(b.createdAt))
+}
+
+const CLOSE_GRACE_MS = 2000
+
+/** SIGTERM the session server (SIGKILL after a grace period), drop its files. */
+export async function closeSession(record: ViewSessionRecord): Promise<void> {
+  if (isAlive(record.pid)) {
+    try {
+      process.kill(record.pid, 'SIGTERM')
+    } catch {
+      // already gone
+    }
+    const deadline = Date.now() + CLOSE_GRACE_MS
+    while (isAlive(record.pid) && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 100))
+    }
+    if (isAlive(record.pid)) {
+      try {
+        process.kill(record.pid, 'SIGKILL')
+      } catch {
+        // already gone
+      }
+    }
+  }
+  await removeSessionFiles(record.id)
+}