@astrale-os/shell 0.1.1 → 0.2.0

package/src/application/shell.ts

@@ -1,433 +0,0 @@
-import type { FunctionSchema } from '@astrale-os/kernel-client'
-
-import type { IntentMiddleware } from '../domain/intent/pipeline'
-import type { IntentRegistry } from '../domain/message/registries'
-import type { WindowCapabilities, SandboxProfile } from '../domain/window/config'
-import type { Window } from '../domain/window/window'
-import type { KernelClient } from '../ports/kernel-client'
-import type { ShellAdapter } from '../ports/shell-adapter'
-import type { ChildrenChannel, ChildrenChannelController } from './channels/children-channel'
-import type { MessageObserver, ObserverHandler } from './channels/observer'
-import type { ParentChannel, ParentChannelController } from './channels/parent-channel'
-import type { IntentPipeline } from './intent/pipeline-runner'
-import type { LocalIntentHandler } from './intent/router'
-import type { KernelFacadeController } from './kernel-facade'
-import type { LifecycleController } from './windowing/lifecycle-controller'
-import type { MountController } from './windowing/mount-controller'
-
-import { createKernelClientAdapter } from '../adapters/kernel-client.adapter'
-import { createChildrenChannel } from './channels/children-channel'
-import { createMessageObserver } from './channels/observer'
-import { createIntentPipeline } from './intent/pipeline-runner'
-import { createIntentRouter } from './intent/router'
-import { createKernelFacade } from './kernel-facade'
-import { performChildInit } from './windowing/child-init'
-import { createLifecycleController } from './windowing/lifecycle-controller'
-import { createMountController } from './windowing/mount-controller'
-
-// ─── Re-exports ─────────────────────────────────────────────────────────────
-
-export type { MessageDirection, ObserverHandler } from './channels/observer'
-export type { ParentChannel } from './channels/parent-channel'
-export type { ChildrenChannel } from './channels/children-channel'
-export type { MessageHandler } from './channels/types'
-
-// ─── Mount API ──────────────────────────────────────────────────────────────
-
-export type MountParams = {
-  readonly host: HTMLElement
-  readonly url: string
-  readonly functionId: string
-  readonly capabilities: WindowCapabilities
-  readonly targetNodeId?: string
-  /** See `WindowConfig.sandbox` — `null` opts the iframe out of the attribute. */
-  readonly sandbox?: SandboxProfile | null
-  readonly handshakeTimeoutMs?: number
-  readonly delegationTtlSeconds?: number
-  /**
-   * `'shell'` (default) runs the parent-side handshake, opening a MessagePort
-   * transport with delegation tokens and an intent channel. `'none'` mounts a
-   * plain iframe with no transport — used for hosted views that don't speak
-   * the shell protocol (`BlaxelComputer.deployFunction(kind:'view')`), so they
-   * render immediately instead of paying the 5 s handshake timeout. In `'none'`
-   * mode `capabilities` / `targetNodeId` / `delegationTtlSeconds` are inert
-   * (no channel to deliver them).
-   */
-  readonly handshake?: 'shell' | 'none'
-}
-
-export type CloseResult =
-  | { kind: 'closed' }
-  | { kind: 'refused'; reason?: string }
-  | { kind: 'noop' }
-
-export type MountedWindow = {
-  readonly windowId: string
-  readonly window: Window
-  readonly handle: { element: HTMLIFrameElement | HTMLElement }
-  close(opts?: { force?: boolean; timeoutMs?: number }): Promise<CloseResult>
-}
-
-// ─── Shell ──────────────────────────────────────────────────────────────────
-
-export interface Shell {
-  readonly parent: ParentChannel | null
-  readonly children: ChildrenChannel
-  readonly kernel: KernelClient
-  readonly windows: ReadonlyMap<string, Window>
-  readonly targetNodeId?: string
-
-  use(middleware: IntentMiddleware): Shell
-  onMessage(handler: ObserverHandler): () => void
-  onIntent<K extends keyof IntentRegistry>(name: K, handler: LocalIntentHandler<K>): () => void
-
-  mount(params: MountParams): Promise<MountedWindow>
-  close(windowId: string, opts?: { force?: boolean; timeoutMs?: number }): Promise<CloseResult>
-
-  init(): Promise<Shell>
-  dispose(): Promise<void>
-}
-
-// ─── Config ─────────────────────────────────────────────────────────────────
-
-export type StandaloneConfig = {
-  readonly mode: 'standalone'
-  readonly kernelUrl: string
-  readonly credential?: string
-  readonly getCredential?: () => string
-  readonly mintIdentity?: string
-  readonly schema?: FunctionSchema[]
-  readonly adapter?: ShellAdapter
-  readonly windowId?: string
-  /**
-   * Optional wire-layer `fetch` shim for the kernel transport. A cookie-fronted
-   * SPA passes a wrapper adding `credentials:'include'` + refresh-on-401 and an
-   * empty `credential`, so a router unseals the cookie into a Bearer (the SPA
-   * holds no token). Omit it (the default) for token-based callers — including
-   * every sandboxed child view, which authenticates with a delegation token.
-   */
-  readonly fetch?: typeof fetch
-}
-
-export type SandboxedConfig = {
-  readonly mode: 'sandboxed'
-  readonly schema?: FunctionSchema[]
-  readonly parentWindow?: WindowProxy
-  readonly initTimeoutMs?: number
-  readonly adapter?: ShellAdapter
-}
-
-export type ShellConfig = StandaloneConfig | SandboxedConfig
-
-const DEFAULT_ROOT_WINDOW_ID = 'root'
-/** Trusted sender id stamped on intents arriving from the parent channel. */
-const PARENT_SENDER_ID = '<parent>'
-
-// ─── Factory ────────────────────────────────────────────────────────────────
-
-export function createShell(config: ShellConfig): Shell {
-  return config.mode === 'standalone' ? createStandaloneShell(config) : createSandboxedShell(config)
-}
-
-// ─── Standalone ─────────────────────────────────────────────────────────────
-
-function createStandaloneShell(config: StandaloneConfig): Shell {
-  const windowId = config.windowId ?? DEFAULT_ROOT_WINDOW_ID
-  const observer = createMessageObserver()
-  const getCredential =
-    config.getCredential ??
-    (() => {
-      if (config.credential === undefined) {
-        throw new Error('Standalone shell requires credential or getCredential')
-      }
-      return config.credential
-    })
-  const adapter = createKernelClientAdapter({
-    url: config.kernelUrl,
-    schema: config.schema,
-    getCredential,
-    mintIdentity: config.mintIdentity,
-    fetch: config.fetch,
-  })
-  const kernel = createKernelFacade({
-    adapter,
-    getCredential,
-    url: config.kernelUrl,
-    mintIdentity: config.mintIdentity,
-  })
-
-  const lifecycle = createLifecycleController()
-  const windows = new Map<string, Window>()
-
-  const childrenChannel = createChildrenChannel({
-    observer,
-    onDeliveryFailed: (toWindowId) => lifecycle.markCrashed(toWindowId),
-  })
-
-  const pipeline = createIntentPipeline()
-  const router = createIntentRouter({
-    selfWindowId: windowId,
-    pipeline,
-    parent: null,
-    children: childrenChannel,
-    windows,
-  })
-
-  childrenChannel.on('intent', (windowId, message) => {
-    void router.handleInbound('child', message, windowId)
-  })
-
-  let mountController: MountController | null = null
-  function getMountController(): MountController {
-    if (mountController) return mountController
-    if (!config.adapter) {
-      throw new Error('Shell.mount() requires a ShellAdapter in the config')
-    }
-    mountController = createMountController({
-      adapter: config.adapter,
-      kernel,
-      kernelUrl: config.kernelUrl,
-      mintIdentity: config.mintIdentity,
-      childrenChannel,
-      windows,
-      lifecycle,
-    })
-    return mountController
-  }
-
-  return buildShellFacade({
-    parent: null,
-    childrenChannel,
-    kernel,
-    pipeline,
-    observer,
-    lifecycle,
-    windows,
-    getMountController,
-    onIntent: (name, handler) => router.onLocal(name, handler),
-    onDispose: async () => {
-      if (mountController) await mountController.dispose()
-      childrenChannel.dispose()
-      adapter.disconnect()
-    },
-  })
-}
-
-// ─── Sandboxed child ────────────────────────────────────────────────────────
-
-type SandboxedState = {
-  windowId: string
-  kernelUrl: string
-  targetNodeId?: string
-  mintIdentity?: string
-  kernel: KernelFacadeController
-  parent: ParentChannelController
-}
-
-function createSandboxedShell(config: SandboxedConfig): Shell {
-  const observer = createMessageObserver()
-  const lifecycle = createLifecycleController()
-  const windows = new Map<string, Window>()
-  const childrenChannel = createChildrenChannel({
-    observer,
-    onDeliveryFailed: (toWindowId) => lifecycle.markCrashed(toWindowId),
-  })
-  const pipeline = createIntentPipeline()
-
-  let state: SandboxedState | null = null
-  let router: ReturnType<typeof createIntentRouter> | null = null
-  let mountController: MountController | null = null
-
-  // Buffer intent subscriptions made before `init()` resolves — the router
-  // is only built once the handshake completes, but consumers want to call
-  // `onIntent` at construction time.
-  type PendingIntentSub = {
-    name: string
-    handler: LocalIntentHandler
-    unsubscribed: boolean
-    off?: () => void
-  }
-  const pendingIntentSubs: PendingIntentSub[] = []
-
-  function subscribeIntent<K extends keyof IntentRegistry>(
-    name: K,
-    handler: LocalIntentHandler<K>,
-  ): () => void {
-    if (router) return router.onLocal(name, handler)
-    const entry: PendingIntentSub = {
-      name: name as string,
-      handler: handler as LocalIntentHandler,
-      unsubscribed: false,
-    }
-    pendingIntentSubs.push(entry)
-    return () => {
-      entry.unsubscribed = true
-      // After init, `off` is the router's real disposer (set during replay);
-      // before init, flipping `unsubscribed` is enough (replay skips it).
-      entry.off?.()
-    }
-  }
-
-  const requireState = (): SandboxedState => {
-    if (!state) throw new Error('Sandboxed shell not initialized — call shell.init() first')
-    return state
-  }
-
-  const kernelProxy: KernelClient = {
-    call: (path, params) => requireState().kernel.call(path, params),
-    mintDelegation: () => requireState().kernel.mintDelegation(),
-    authToken: () => requireState().kernel.authToken(),
-    get url() {
-      return requireState().kernel.url
-    },
-  }
-
-  const parentProxy: ParentChannel = {
-    send: (message) => requireState().parent.send(message),
-    on: (type, handler) => requireState().parent.on(type, handler),
-  }
-
-  function getMountController(): MountController {
-    if (mountController) return mountController
-    if (!config.adapter) {
-      throw new Error('Shell.mount() requires a ShellAdapter in the config')
-    }
-    const current = requireState()
-    mountController = createMountController({
-      adapter: config.adapter,
-      kernel: kernelProxy,
-      kernelUrl: current.kernelUrl,
-      mintIdentity: current.mintIdentity,
-      childrenChannel,
-      windows,
-      lifecycle,
-    })
-    return mountController
-  }
-
-  return buildShellFacade({
-    parent: parentProxy,
-    childrenChannel,
-    kernel: kernelProxy,
-    pipeline,
-    observer,
-    lifecycle,
-    windows,
-    getMountController,
-    targetNodeId: () => state?.targetNodeId,
-    onIntent: subscribeIntent,
-    init: async () => {
-      const result = await performChildInit({
-        parent: config.parentWindow ?? window.parent,
-        timeoutMs: config.initTimeoutMs,
-        schema: config.schema,
-      })
-
-      state = {
-        windowId: result.windowId,
-        kernelUrl: result.kernelUrl,
-        targetNodeId: result.targetNodeId,
-        mintIdentity: result.mintIdentity,
-        kernel: result.kernel,
-        parent: result.parentChannel(observer),
-      }
-
-      router = createIntentRouter({
-        selfWindowId: state.windowId,
-        pipeline,
-        parent: state.parent,
-        children: childrenChannel,
-        windows,
-      })
-
-      childrenChannel.on('intent', (windowId, message) => {
-        void router!.handleInbound('child', message, windowId)
-      })
-      state.parent.on('intent', (message) => {
-        void router!.handleInbound('parent', message, PARENT_SENDER_ID)
-      })
-
-      // Replay subscriptions registered before init. Capture each real disposer
-      // so a post-init unsubscribe (via the closure returned at subscribe time)
-      // actually removes the handler from the router instead of no-op'ing.
-      for (const entry of pendingIntentSubs) {
-        if (entry.unsubscribed) continue
-        entry.off = router.onLocal(entry.name as keyof IntentRegistry, entry.handler)
-      }
-      pendingIntentSubs.length = 0
-    },
-    onDispose: async () => {
-      if (mountController) await mountController.dispose()
-      childrenChannel.dispose()
-      state?.parent.dispose()
-      state?.kernel.dispose()
-    },
-  })
-}
-
-// ─── Shared facade builder ──────────────────────────────────────────────────
-
-type FacadeDeps = {
-  parent: ParentChannel | null
-  childrenChannel: ChildrenChannelController
-  kernel: KernelClient
-  pipeline: IntentPipeline
-  observer: MessageObserver
-  lifecycle: LifecycleController
-  windows: Map<string, Window>
-  getMountController: () => MountController
-  onIntent: <K extends keyof IntentRegistry>(name: K, handler: LocalIntentHandler<K>) => () => void
-  targetNodeId?: () => string | undefined
-  init?: () => Promise<void>
-  onDispose: () => Promise<void>
-}
-
-function buildShellFacade(deps: FacadeDeps): Shell {
-  let disposed = false
-
-  const shell: Shell = {
-    get parent() {
-      return deps.parent
-    },
-    children: deps.childrenChannel,
-    kernel: deps.kernel,
-    windows: deps.windows,
-    get targetNodeId() {
-      return deps.targetNodeId?.()
-    },
-
-    use(middleware) {
-      deps.pipeline.use(middleware)
-      return shell
-    },
-
-    onMessage(handler) {
-      return deps.observer.subscribe(handler)
-    },
-
-    onIntent(name, handler) {
-      return deps.onIntent(name, handler)
-    },
-
-    mount(params) {
-      return deps.getMountController().mount(params)
-    },
-
-    close(windowId, opts) {
-      return deps.getMountController().close(windowId, opts)
-    },
-
-    async init() {
-      if (deps.init) await deps.init()
-      return shell
-    },
-
-    async dispose() {
-      if (disposed) return
-      disposed = true
-      await deps.onDispose()
-    },
-  }
-
-  return shell
-}