@astrale-os/cli 1.0.0-beta.32 → 1.0.0-beta.43

package/src/lib/view/assets.ts

@@ -1,87 +0,0 @@
-import { existsSync, statSync } from 'node:fs'
-import { copyFile } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-/**
- * The prebuilt host-page bundle, shipped next to the CLI module
- * (`<pkg>/viewer/dist`). The module URL is authoritative because npm global
- * installs expose the CLI through a bin symlink outside the package root.
- */
-export function viewerDistDir(
-  moduleUrl = import.meta.url,
-  entry = process.argv[1] ?? '.',
-  executable = process.execPath,
-): string {
-  const override = process.env.ASTRALE_VIEWER_DIR
-  if (override) return override
-
-  const moduleDirectory = dirname(fileURLToPath(moduleUrl))
-  const published = join(moduleDirectory, '..', 'viewer', 'dist')
-  const source = join(moduleDirectory, '..', '..', '..', 'viewer', 'dist')
-  const legacy = join(dirname(entry), '..', 'viewer', 'dist')
-  const standalone = entry.startsWith('/$bunfs/')
-    ? join(dirname(executable), 'viewer', 'dist')
-    : undefined
-  const complete = [standalone, published, source, legacy].find(
-    (candidate): candidate is string => candidate !== undefined && hasViewerBundle(candidate),
-  )
-  if (complete) return complete
-
-  // A source checkout may intentionally omit generated dist assets. Keep the
-  // source-derived destination so ensureViewerAssets can build it on demand.
-  if (hasViewerSource(join(source, '..'))) return source
-
-  // Published installs cannot rebuild: preserve the package-relative path in
-  // the diagnostic instead of pointing at the npm prefix beside the bin link.
-  return published
-}
-
-/** Ensure the host bundle exists; on a dev checkout, build it with Bun. */
-export async function ensureViewerAssets(
-  moduleUrl = import.meta.url,
-  entry = process.argv[1] ?? '.',
-): Promise<string> {
-  const dist = viewerDistDir(moduleUrl, entry)
-  const srcDir = join(dist, '..')
-  if (hasViewerBundle(dist) && !viewerSourceIsNewer(srcDir, dist)) return dist
-  const bun = (
-    globalThis as { Bun?: { build: (o: object) => Promise<{ success: boolean; logs: unknown[] }> } }
-  ).Bun
-  if (bun && hasViewerSource(srcDir)) {
-    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')}`)
-    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 hasViewerBundle(directory: string): boolean {
-  return existsSync(join(directory, 'main.js')) && existsSync(join(directory, 'index.html'))
-}
-
-function hasViewerSource(directory: string): boolean {
-  return existsSync(join(directory, 'main.ts')) && existsSync(join(directory, 'index.html'))
-}
-
-function viewerSourceIsNewer(source: string, dist: string): boolean {
-  if (!hasViewerSource(source)) return false
-  if (!hasViewerBundle(dist)) return true
-  const newestSource = Math.max(
-    statSync(join(source, 'main.ts')).mtimeMs,
-    statSync(join(source, 'index.html')).mtimeMs,
-  )
-  const oldestOutput = Math.min(
-    statSync(join(dist, 'main.js')).mtimeMs,
-    statSync(join(dist, 'index.html')).mtimeMs,
-  )
-  return newestSource > oldestOutput
-}

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

@@ -1,41 +0,0 @@
-import type { ExternalOpenRequest, IntentMessage, Shell } from '@astrale-os/shell'
-
-import { replyToIntent } from '@astrale-os/shell'
-
-export interface ExternalOpenIntentHost {
-  open(request: ExternalOpenRequest): boolean
-}
-
-/** Register the root host's browser-owned external navigation effect. */
-export function installExternalOpenIntentHandler(
-  shell: Shell,
-  host: ExternalOpenIntentHost,
-): () => void {
-  return shell.onIntent('browser.openExternal', (message) => {
-    const opened = host.open(message.envelope.payload)
-    replyToIntent(shell.children, message.envelope.sender.windowId, message, {
-      outcome: opened ? 'opened' : 'blocked',
-    })
-  })
-}
-
-/** Open an external document without retaining a cross-origin opener capability. */
-export function openExternalBrowserWindow(
-  browser: Pick<Window, 'open'>,
-  request: ExternalOpenRequest,
-): boolean {
-  const popup = request.mode === 'popup'
-  const opened = browser.open('', '_blank', popup ? 'popup,width=720,height=760' : undefined)
-  if (opened === null) return false
-  try {
-    opened.opener = null
-    if (opened.opener !== null) throw new Error('Browser retained the opener capability.')
-    opened.location.replace(request.url)
-  } catch {
-    opened.close()
-    return false
-  }
-  return true
-}
-
-export type ExternalOpenIntentMessage = IntentMessage<'browser.openExternal'>

package/src/lib/view/external-open-origins.ts

@@ -1,37 +0,0 @@
-import { AstraleError } from '../../errors.js'
-
-/** Admit exact HTTPS origins explicitly granted by the CLI operator. */
-export function admitExternalOpenOrigins(input: readonly string[] | undefined): readonly string[] {
-  if (input === undefined) return Object.freeze([])
-  const admitted = new Set<string>()
-  for (const candidate of input) {
-    let url: URL
-    try {
-      url = new URL(candidate)
-    } catch (cause) {
-      throw invalidExternalOrigin(candidate, cause)
-    }
-    if (
-      url.protocol !== 'https:' ||
-      url.hostname.includes('*') ||
-      url.username !== '' ||
-      url.password !== '' ||
-      url.pathname !== '/' ||
-      url.search !== '' ||
-      url.hash !== ''
-    ) {
-      throw invalidExternalOrigin(candidate)
-    }
-    admitted.add(url.origin)
-  }
-  return Object.freeze([...admitted])
-}
-
-function invalidExternalOrigin(candidate: string, cause?: unknown): AstraleError {
-  return new AstraleError(
-    'INVALID_EXTERNAL_ORIGIN',
-    `External navigation grant "${candidate}" is not an exact HTTPS origin.`,
-    'Pass an origin such as https://connect.example.com with no credentials, path, query, or fragment.',
-    cause === undefined ? undefined : { cause },
-  )
-}

package/src/lib/view/host-capabilities.ts

@@ -1,17 +0,0 @@
-import type { HostCapabilities } from '@astrale-os/shell'
-
-import { admitHostCapabilities } from '@astrale-os/shell'
-
-/** Build the exact host grant handed to a CLI-hosted View session. */
-export function viewHostCapabilities(externalOrigins: readonly string[]): HostCapabilities {
-  return admitHostCapabilities({
-    version: 1,
-    navigation: {
-      openView: {},
-      ...(externalOrigins.length === 0 ? {} : { external: { origins: externalOrigins } }),
-    },
-    actions: {},
-    browser: {},
-    access: {},
-  })
-}

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

@@ -1,67 +0,0 @@
-import type { IntentMessage, MountedWindow, ResolvedView, Shell } from '@astrale-os/shell'
-
-export interface OpenIntentHost {
-  current(): MountedWindow | null
-  setCurrent(window: MountedWindow): void
-  mount(view: ResolvedView): Promise<MountedWindow>
-  opened(view: ResolvedView): 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)
-
-    host.setCurrent(next)
-    host.opened(selected)
-    // 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.route.key === viewId || `/:${view.route.key}` === 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',
-  )
-}

package/src/lib/view/port-allocation.ts

@@ -1,19 +0,0 @@
-import { join } from 'node:path'
-
-import { withFileLock } from '../../state/index'
-import { VIEW_DIR } from './session'
-
-const VIEW_PORT_LOCK = join(VIEW_DIR, 'ports.lock')
-
-/**
- * Keep the free-port probe and detached server startup in one cross-process
- * critical section. A probe alone is only advisory: without this lock, two
- * concurrent `astrale view` processes can both observe 4419 as free before
- * either child binds it.
- */
-export function withViewPortAllocationLock<T>(
-  fn: () => Promise<T>,
-  lockPath = VIEW_PORT_LOCK,
-): Promise<T> {
-  return withFileLock(lockPath, fn)
-}

package/src/lib/view/resolve.ts

@@ -1,111 +0,0 @@
-import type { ResolvedView as SessionResolvedView } from '@astrale-os/sdk/client/session'
-import type { ResolvedView } from '@astrale-os/shell'
-
-import { Path } from '@astrale-os/sdk/graph/path'
-
-import type { ConnectionContext } from '../../connection'
-
-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_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)`,
-  )
-}
-
-/** The owning Domain principal used when an explicit ViewPath has no target override. */
-export function viewOwnerTarget(viewPath: string): string {
-  const parsed = Path.parse(viewPath)
-  if (parsed.ast.anchor.kind !== 'domain') {
-    throw new AstraleError('INVALID_ARGUMENT', `ViewPath has no Domain owner: ${viewPath}`)
-  }
-  return `/:${parsed.ast.anchor.origin}`
-}
-
-/** One exact Shell selection plus stable presentation fields for CLI output. */
-export type ViewCandidate = ResolvedView & {
-  id: string
-  path: string
-  url: string
-  name?: string
-  handshake: 'shell' | 'none'
-  origin: 'self' | 'class'
-  issuer: string
-  etag: string
-  revision: string
-}
-
-export async function resolveViewCandidates(
-  ctx: ConnectionContext,
-  nodePath: string,
-): Promise<ViewCandidate[]> {
-  const target = Path.parse(nodePath).raw
-  const catalog = await ctx.session.viewsFor(target)
-  return catalog.views.map((route) => toCandidate(target, route))
-}
-
-function toCandidate(target: ResolvedView['target'], route: SessionResolvedView): ViewCandidate {
-  const key = String(route.key)
-  return Object.freeze({
-    target,
-    route,
-    id: key,
-    path: `/:${key}`,
-    url: route.href,
-    name: key.slice(key.lastIndexOf(':view.') + ':view.'.length),
-    handshake: route.handshake,
-    origin: route.declaration.target.kind === 'domain' ? 'self' : 'class',
-    issuer: route.issuer,
-    etag: route.etag,
-    revision: route.revision,
-  })
-}
-
-/** Strip presentation aliases before crossing the Shell mount boundary. */
-export function selectedView(candidate: ViewCandidate): ResolvedView {
-  return Object.freeze({ target: candidate.target, route: candidate.route })
-}
-
-/** The slug tail of a candidate: `view.dashboard` → `dashboard`. */
-export function candidateSlug(candidate: ViewCandidate): string {
-  return candidate.name ?? candidate.id.slice(candidate.id.lastIndexOf(':view.') + ':view.'.length)
-}
-
-export function pickCandidate(
-  candidates: ViewCandidate[],
-  nodePath: string,
-  slug?: string,
-): ViewCandidate | 'ambiguous' {
-  if (slug) {
-    const match = candidates.find(
-      (candidate) =>
-        candidate.id === slug || candidate.path === slug || candidateSlug(candidate) === 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'
-}

package/src/lib/view/server.ts

@@ -1,259 +0,0 @@
-import type { AuthApi } from '@astrale-os/sdk/auth'
-import type { IssuerId } from '@astrale-os/sdk/auth'
-import type { ReadableStream as WebReadableStream } from 'node:stream/web'
-
-import { readFile } from 'node:fs/promises'
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
-import { join } from 'node:path'
-import { Readable } from 'node:stream'
-
-import type { ViewServeConfig } from './session'
-
-import { withClientSession } from '../../connection'
-import { fetchWithCaFile } from '../ca-fetch'
-import { viewerDistDir } from './assets'
-import { removeSessionFiles } from './session'
-
-export { ensureViewerAssets, viewerDistDir } from './assets'
-
-/**
- * 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 VIEW_TOKEN_TTL_SECONDS = 4 * 60
-const TOKEN_REFRESH_MARGIN_MS = 60_000
-const FALLBACK_TOKEN_TTL_MS = VIEW_TOKEN_TTL_SECONDS * 1_000
-const IDLE_SWEEP_MS = 60_000
-
-export type PageStatus = { state: string; error?: string; at: string }
-
-type TokenGrant = { token: string; expiresAt: number; kind: 'minted' }
-
-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()
-
-  /** Mint one TTL-bound credential; raw CLI credentials never enter the browser session. */
-  async function freshGrant(): Promise<TokenGrant> {
-    if (grant && grant.expiresAt - Date.now() > TOKEN_REFRESH_MARGIN_MS) return grant
-    grant = await withClientSession(config.kernel, async ({ auth, target }) => {
-      const token = await mintViewCredential(auth, target.kernelIssuer)
-      return {
-        token,
-        expiresAt: jwtExpiry(token) ?? Date.now() + FALLBACK_TOKEN_TTL_MS,
-        kind: 'minted' 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, {
-        view: session.view,
-        kernelUrl: proxy.direct ? proxy.kernelUrl : `${base}/k`,
-        kernelIssuer: proxy.issuer,
-        identity: session.identity ?? null,
-        instance: session.instance ?? null,
-        sessionId: session.id,
-        externalOrigins: config.externalOrigins,
-      })
-      return
-    }
-    if (sub === '/token' && req.method === 'POST') {
-      if (session.view.route.handshake !== 'shell') {
-        json(res, 403, { error: 'plain views have no Astrale credential privilege' })
-        return
-      }
-      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
-}
-
-/** Mint a short-lived credential from the selected CLI identity proof. */
-export async function mintViewCredential(
-  auth: Pick<AuthApi, 'mint'>,
-  audience: IssuerId,
-): Promise<string> {
-  return auth.mint({
-    audience,
-    ttlSeconds: VIEW_TOKEN_TTL_SECONDS,
-  })
-}
-
-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
-}