@astrale-os/shell 0.1.1 → 0.3.0

package/src/application/apps.ts

@@ -0,0 +1,60 @@
+import type { BoundNode, DefOf, NodeRefInput } from '@astrale-os/kernel-client'
+
+import { D } from '@astrale-domains/shell-schema'
+import { normalizeRef } from '@astrale-os/kernel-client'
+
+import type { KernelClient } from '../kernel/client'
+import type { AppSession } from './session/session'
+import type { ShellDomainView, ShellSchema } from './view'
+
+import { openAppSession } from './session/open'
+
+/** An installed `Application` node. */
+export type ApplicationNode = BoundNode<DefOf<ShellSchema, 'Application'>, ShellSchema>
+
+export interface AppsNamespace {
+  /** `Application.install(target, space)`, bound as the resulting `Application`. */
+  install(target: string, space: NodeRefInput): Promise<ApplicationNode>
+  /** The apps installed in `space` (`installed_in` in-edges). */
+  in(space: NodeRefInput): Promise<ApplicationNode[]>
+  /** Resolve the app node and open its {@link AppSession}. */
+  open(app: NodeRefInput): Promise<AppSession>
+}
+
+/** The `installed_in` edge class — traversed to list a space's apps. */
+const INSTALLED_IN_EDGE = D.installed_in.path.class.raw
+
+export function createAppsNamespace(
+  kernel: KernelClient,
+  v: ShellDomainView,
+  deps?: { readonly now?: () => number },
+): AppsNamespace {
+  return {
+    async install(target, space) {
+      const created = (await v
+        .view()('Application')
+        .install({
+          target,
+          space: normalizeRef(space),
+        })) as { id: string }
+      const app = await v.view().node('Application', `@${created.id}`)
+      if (!app) throw new Error(`Application.install: app @${created.id} is not readable`)
+      return app
+    },
+
+    async in(space) {
+      const page = await kernel.neighbors(normalizeRef(space), INSTALLED_IN_EDGE, 'in')
+      const nodes = await page.all()
+      return nodes.flatMap((n) => {
+        const app = v.bindAs('Application', n)
+        return app ? [app] : []
+      })
+    },
+
+    async open(app) {
+      const node = await v.view().node('Application', app)
+      if (!node) throw new Error(`apps.open: application ${normalizeRef(app)} is not readable`)
+      return openAppSession({ kernel, ...(deps?.now ? { now: deps.now } : {}) }, node.id)
+    },
+  }
+}

package/src/application/namespaces.ts

@@ -0,0 +1,38 @@
+/**
+ * The OS-plane namespaces on the Shell — `shell.user` / `shell.spaces` /
+ * `shell.apps`. Framework-free: the shell-react hooks (§12.2) layer over
+ * exactly these. Pure closures over a lazy typed view — constructing this
+ * touches no kernel (safe before a sandboxed shell's `init()`).
+ */
+import type { KernelClient } from '../kernel/client'
+import type { AppsNamespace } from './apps'
+import type { SpacesNamespace } from './spaces'
+import type { UserNamespace } from './user'
+
+import { createAppsNamespace } from './apps'
+import { createSpacesNamespace } from './spaces'
+import { createUserNamespace } from './user'
+import { createShellDomainView } from './view'
+
+export interface OsNamespaces {
+  readonly user: UserNamespace
+  readonly spaces: SpacesNamespace
+  readonly apps: AppsNamespace
+}
+
+export interface CreateOsNamespacesDeps {
+  /** Injected clock, threaded into opened `AppSession`s (tests). */
+  readonly now?: () => number
+}
+
+export function createOsNamespaces(
+  kernel: KernelClient,
+  deps?: CreateOsNamespacesDeps,
+): OsNamespaces {
+  const v = createShellDomainView(kernel)
+  return {
+    user: createUserNamespace(kernel, v),
+    spaces: createSpacesNamespace(kernel, v),
+    apps: createAppsNamespace(kernel, v, deps),
+  }
+}

package/src/application/session/open.ts

@@ -0,0 +1,73 @@
+import type { UnresolvedIdentityExpr } from '@astrale-os/kernel-core'
+
+import type { KernelClient } from '../../kernel/client'
+import type { MountCredential } from '../../window/mount/params'
+import type { AppSession, AppView } from './session'
+
+import { createTokenCycle } from './token'
+
+/** The wire shape of `app::open`. */
+interface OpenResult {
+  readonly view: AppView | null
+  readonly appCredential: string
+  readonly delegation: UnresolvedIdentityExpr
+  readonly expiresAt: number
+}
+
+export interface OpenAppSessionDeps {
+  /** The shell kernel — dispatches AS THE USER, whose signature the delegate step needs. */
+  readonly kernel: KernelClient
+  /** Injected clock (tests). */
+  readonly now?: () => number
+}
+
+/**
+ * Open an app session: run `app::open` for the entry view + first recipe, then
+ * return an {@link AppSession}. The first token mints LAZILY — opening the view
+ * costs no token; `token()` (or `credential.refresh()`) runs the first
+ * delegate/getAccessToken cycle on demand. The {@link MountCredential} is driven
+ * by the mount machinery via `refresh` (no internal timer).
+ */
+export async function openAppSession(
+  deps: OpenAppSessionDeps,
+  app: { id: string } | string,
+): Promise<AppSession> {
+  const appId = typeof app === 'string' ? app : app.id
+  const { kernel } = deps
+  const now = deps.now ?? Date.now
+
+  const opened = (await kernel.call(`@${appId}::open`, {})) as OpenResult
+
+  const tokens = createTokenCycle({ kernel, appId, initialRecipe: opened.delegation, now })
+  let disposed = false
+
+  async function token(): Promise<string> {
+    if (disposed) throw new Error('AppSession is disposed')
+    if (tokens.needsRefresh()) return (await tokens.refresh()).token
+    return tokens.current()!.token
+  }
+
+  const credential: MountCredential = {
+    get token() {
+      return tokens.current()?.token ?? ''
+    },
+    get expiresAt() {
+      return tokens.current()?.expiresAt ?? 0
+    },
+    refresh: async () => {
+      if (disposed) throw new Error('AppSession is disposed')
+      const next = await tokens.refresh()
+      return { token: next.token, expiresAt: next.expiresAt }
+    },
+  }
+
+  return {
+    app: appId,
+    view: opened.view,
+    credential,
+    token,
+    dispose() {
+      disposed = true
+    },
+  }
+}

package/src/application/session/session.ts

@@ -0,0 +1,46 @@
+/**
+ * `AppSession` — the client half of the three-call app-opening protocol
+ * (`app::open` → user-signed `auth.delegate` → `app::getAccessToken`). The
+ * server contract lives in the shell domain's `Application` methods
+ * (`runtime/application/{open,get-access-token}`).
+ */
+import type { MountCredential } from '../../window/mount/params'
+
+/** The entry view returned by `app::open`, described for mounting. */
+export interface AppView {
+  readonly id: string
+  readonly path: string
+  readonly url?: string
+  readonly handshake?: string
+}
+
+/**
+ * A live app session: the entry view (mount-ready), a mount-compatible
+ * credential, and an on-demand `token()`. `dispose()` is idempotent; after it,
+ * `token()` and `credential.refresh()` reject.
+ */
+export interface AppSession {
+  /** The app node id this session speaks to. */
+  readonly app: string
+  /** The entry view (from `app::open`), or `null` when the app pins none. */
+  readonly view: AppView | null
+  /** Shell.mount-compatible credential — `token`/`expiresAt` track the live app token. */
+  readonly credential: MountCredential
+  /** The current app token; refreshes when within the margin of expiry. Single-flight. */
+  token(): Promise<string>
+  /** Idempotent teardown. */
+  dispose(): void
+}
+
+/** Which protocol step a refresh cycle failed at — carried on {@link AppSessionRefreshError}. */
+export type RefreshStep = 'delegate' | 'getAccessToken'
+
+/** A refresh cycle that failed, naming the step; prior session state is preserved. */
+export class AppSessionRefreshError extends Error {
+  readonly step: RefreshStep
+  constructor(step: RefreshStep, app: string, options?: { cause?: unknown }) {
+    super(`AppSession token refresh failed at '${step}' for @${app}`, options)
+    this.name = 'AppSessionRefreshError'
+    this.step = step
+  }
+}

package/src/application/session/token.ts

@@ -0,0 +1,87 @@
+import type { UnresolvedIdentityExpr } from '@astrale-os/kernel-core'
+
+import type { KernelClient } from '../../kernel/client'
+
+import { REFRESH_WINDOW_MS } from '../../kernel/delegation/token'
+import { AppSessionRefreshError } from './session'
+
+/** The wire shape of `app::getAccessToken`. */
+interface AccessTokenResult {
+  readonly credential: string
+  readonly expiresAt: number
+  /** The next ready-to-mint recipe (re-armed with the fresh app credential). */
+  readonly delegation: UnresolvedIdentityExpr
+  readonly appCredential: string
+}
+
+/** The current token, plus the recipe that mints its successor. */
+export interface TokenSlot {
+  readonly token: string
+  readonly expiresAt: number
+  readonly recipe: UnresolvedIdentityExpr
+}
+
+/** The app token's lifecycle: lazy first mint, single-flight refresh. */
+export interface TokenCycle {
+  current(): TokenSlot | null
+  needsRefresh(): boolean
+  /** Advance the slot via one delegate → getAccessToken exchange. Single-flight. */
+  refresh(): Promise<TokenSlot>
+}
+
+export function createTokenCycle(opts: {
+  /** The shell kernel — dispatches AS THE USER, whose signature the delegate step needs. */
+  kernel: KernelClient
+  appId: string
+  /** `app::open`'s first ready-to-mint recipe. */
+  initialRecipe: UnresolvedIdentityExpr
+  now: () => number
+}): TokenCycle {
+  const { kernel, appId, now } = opts
+
+  let slot: TokenSlot | null = null
+  let inFlight: Promise<TokenSlot> | null = null
+
+  // One delegate → getAccessToken exchange, minting the NEXT token from the last
+  // recipe. On failure `slot` is untouched (the throw carries the failed step).
+  async function cycle(): Promise<TokenSlot> {
+    const recipe = slot?.recipe ?? opts.initialRecipe
+    let envelope: string
+    try {
+      envelope = await kernel.auth.delegate({ delegation: recipe })
+    } catch (cause) {
+      throw new AppSessionRefreshError('delegate', appId, { cause })
+    }
+    let access: AccessTokenResult
+    try {
+      access = (await kernel.call(`@${appId}::getAccessToken`, {
+        delegation: envelope,
+      })) as AccessTokenResult
+    } catch (cause) {
+      throw new AppSessionRefreshError('getAccessToken', appId, { cause })
+    }
+    return { token: access.credential, expiresAt: access.expiresAt, recipe: access.delegation }
+  }
+
+  // Single-flight: concurrent callers share one in-flight cycle; the slot is
+  // only advanced on success.
+  function refresh(): Promise<TokenSlot> {
+    if (inFlight) return inFlight
+    const run = cycle()
+      .then((next) => {
+        slot = next
+        return next
+      })
+      .finally(() => {
+        if (inFlight === run) inFlight = null
+      })
+    inFlight = run
+    return run
+  }
+
+  return {
+    current: () => slot,
+    needsRefresh: () => slot === null || slot.expiresAt - now() - REFRESH_WINDOW_MS <= 0,
+    refresh,
+  }
+}

package/src/application/spaces.ts

@@ -0,0 +1,52 @@
+import type { BoundNode, DefOf, NodeRefInput } from '@astrale-os/kernel-client'
+
+import { normalizeRef } from '@astrale-os/kernel-client'
+
+import type { KernelClient } from '../kernel/client'
+import type { ShellDomainView, ShellSchema } from './view'
+
+/** A workspace `Space` node. */
+export type SpaceNode = BoundNode<DefOf<ShellSchema, 'Space'>, ShellSchema>
+
+export interface SpacesNamespace {
+  /** Children of the spaces directory — exactly the caller-readable spaces. */
+  list(): Promise<SpaceNode[]>
+  /** One space by ref, or `null` when missing / masked / not a space. */
+  get(ref: NodeRefInput): Promise<SpaceNode | null>
+  /** `Space.create` — creates the space (and selects it). */
+  create(opts?: { name?: string }): Promise<SpaceNode>
+}
+
+/** The spaces directory (mirrors the shell domain's `SPACES_DIR`). */
+const SPACES_DIR = '/spaces'
+
+export function createSpacesNamespace(kernel: KernelClient, v: ShellDomainView): SpacesNamespace {
+  return {
+    async list() {
+      const page = await kernel.children(SPACES_DIR)
+      const nodes = await page.all()
+      return nodes.flatMap((n) => {
+        const space = v.bindAs('Space', n)
+        return space ? [space] : []
+      })
+    },
+
+    async get(ref) {
+      const node = await kernel.get(normalizeRef(ref))
+      return node ? v.bindAs('Space', node) : null
+    },
+
+    async create(opts) {
+      // `Space.create`'s params are all-optional, so the typed dispatch collapses
+      // to `(opts?)`; the runtime still forwards a params object (resolveCallArgs),
+      // so pass `{ name }` through a create-shaped view of the same thunk.
+      const create = v.view()('Space').create as (params?: {
+        name?: string
+      }) => Promise<{ id: string }>
+      const created = await create(opts?.name !== undefined ? { name: opts.name } : undefined)
+      const space = await v.view().node('Space', `@${created.id}`)
+      if (!space) throw new Error(`Space.create: created space @${created.id} is not readable`)
+      return space
+    },
+  }
+}

package/src/application/user.ts

@@ -0,0 +1,54 @@
+import type { BoundNode, DefOf, NodeRefInput } from '@astrale-os/kernel-client'
+
+import { normalizeRef } from '@astrale-os/kernel-client'
+
+import type { KernelClient } from '../kernel/client'
+import type { SpaceNode } from './spaces'
+import type { ShellDomainView, ShellSchema } from './view'
+
+import { asArray } from './view'
+
+/** Self as the shell-domain `User` — typed `firstName`/`lastName`/`email`. */
+export type UserNode = BoundNode<DefOf<ShellSchema, 'User'>, ShellSchema>
+/** A `Role` a user holds. */
+export type RoleNode = BoundNode<DefOf<ShellSchema, 'Role'>, ShellSchema>
+
+export interface UserNamespace {
+  /** `whoami`, bound as the shell-domain `User`. */
+  me(): Promise<UserNode>
+  /** The `selected_space` edge target, or `null` when none is selected. */
+  currentSpace(): Promise<SpaceNode | null>
+  /** `user::switchSpace` — validate + repoint the `selected_space` edge. Idempotent. */
+  switchSpace(ref: NodeRefInput): Promise<void>
+  /** The `has_role` out-edges of self. */
+  roles(): Promise<RoleNode[]>
+}
+
+export function createUserNamespace(kernel: KernelClient, v: ShellDomainView): UserNamespace {
+  async function me(): Promise<UserNode> {
+    return v.view().bind('User', await kernel.auth.whoami())
+  }
+
+  return {
+    me,
+
+    async currentSpace() {
+      const self = await me()
+      const first = asArray(await self.out('selected_space'))[0]
+      return first ? v.bindAs('Space', first.raw) : null
+    },
+
+    async switchSpace(ref) {
+      const self = await me()
+      await self.call.switchSpace({ space: normalizeRef(ref) })
+    },
+
+    async roles() {
+      const self = await me()
+      return asArray(await self.out('has_role')).flatMap((r) => {
+        const role = v.bindAs('Role', r.raw)
+        return role ? [role] : []
+      })
+    },
+  }
+}

package/src/application/view.ts

@@ -0,0 +1,42 @@
+/**
+ * The typed plane the OS namespaces speak: `kernel.withSchema(schema)` over the
+ * shell domain (`@astrale-domains/shell-schema`). The bound view is built LAZILY
+ * (first call) so the sandboxed shell's "init() first" kernel guard applies
+ * uniformly — constructing namespaces touches no kernel.
+ */
+import type { BoundNode, DefOf, SchemaBoundView } from '@astrale-os/kernel-client'
+import type { Node } from '@astrale-os/kernel-core'
+
+import { schema } from '@astrale-domains/shell-schema'
+
+import type { KernelClient } from '../kernel/client'
+
+export type ShellSchema = typeof schema
+
+export interface ShellDomainView {
+  view(): SchemaBoundView<ShellSchema>
+  /** Bind `node` as `type` when its concrete class satisfies it, else `null`. */
+  bindAs<T extends 'User' | 'Space' | 'Application' | 'Role'>(
+    type: T,
+    node: Node,
+  ): BoundNode<DefOf<ShellSchema, T>, ShellSchema> | null
+}
+
+export function createShellDomainView(kernel: KernelClient): ShellDomainView {
+  let bound: SchemaBoundView<ShellSchema> | null = null
+  const view = (): SchemaBoundView<ShellSchema> => (bound ??= kernel.withSchema(schema))
+
+  return {
+    view,
+    bindAs(type, node) {
+      const v = view()
+      return v.bindAny(node).is(type) ? v.bind(type, node) : null
+    },
+  }
+}
+
+/** Normalize a typed traversal result (single | array | null) to an array. */
+export function asArray<T>(result: T | readonly T[] | null): T[] {
+  if (result === null) return []
+  return Array.isArray(result) ? [...result] : [result as T]
+}

package/src/{application/channels/children-channel.ts → channel/children.ts}

@@ -1,8 +1,8 @@
-import type { ShellMessage } from '../../domain/message/types'
-import type { Transport } from '../../ports/transport'
+import type { MessageOf, MessageType, ShellMessage } from '../message/message'
 import type { MessageObserver } from './observer'
-import type { MessageOf, MessageType } from './types'
+import type { Transport } from './transport'
 
+/** Multiplexed channels down to child windows, keyed by windowId. */
 export interface ChildrenChannel {
   send(windowId: string, message: ShellMessage): void
   on<T extends MessageType>(

package/src/{application/channels/types.ts → channel/listeners.ts}

@@ -1,11 +1,6 @@
-import type { ShellMessage } from '../../domain/message/types'
-
-export type MessageHandler<M extends ShellMessage = ShellMessage> = (message: M) => void
-
-export type MessageType = ShellMessage['type']
-
-export type MessageOf<T extends MessageType> = Extract<ShellMessage, { type: T }>
+import type { MessageHandler, MessageOf, MessageType, ShellMessage } from '../message/message'
 
+/** Per-message-type listener registry — the fan-out primitive channels share. */
 export interface MessageListeners {
   on<T extends MessageType>(type: T, handler: MessageHandler<MessageOf<T>>): () => void
   dispatch(message: ShellMessage): void

package/src/{adapters/message-port.transport.ts → channel/message-port.ts}

@@ -1,5 +1,5 @@
-import type { ShellMessage } from '../domain/message/types'
-import type { Transport } from '../ports/transport'
+import type { ShellMessage } from '../message/message'
+import type { Transport } from './transport'
 
 export type MessagePortTransportConfig = {
   port: MessagePort

package/src/{application/channels → channel}/observer.ts

@@ -1,9 +1,10 @@
-import type { ShellMessage } from '../../domain/message/types'
+import type { ShellMessage } from '../message/message'
 
 export type MessageDirection = 'inbound' | 'outbound'
 
 export type ObserverHandler = (message: ShellMessage, direction: MessageDirection) => void
 
+/** Tap on every message crossing this shell, in both directions (`shell.onMessage`). */
 export interface MessageObserver {
   notify(direction: MessageDirection, message: ShellMessage): void
   subscribe(handler: ObserverHandler): () => void

package/src/{application/channels/parent-channel.ts → channel/parent.ts}

@@ -1,10 +1,10 @@
-import type { ShellMessage } from '../../domain/message/types'
-import type { Transport } from '../../ports/transport'
+import type { MessageHandler, MessageOf, MessageType, ShellMessage } from '../message/message'
 import type { MessageObserver } from './observer'
-import type { MessageHandler, MessageOf, MessageType } from './types'
+import type { Transport } from './transport'
 
-import { createMessageListeners } from './types'
+import { createMessageListeners } from './listeners'
 
+/** The child's single channel up to its parent shell. */
 export interface ParentChannel {
   send(message: ShellMessage): void
   on<T extends MessageType>(type: T, handler: MessageHandler<MessageOf<T>>): () => void

package/src/{ports → channel}/transport.ts

@@ -1,5 +1,6 @@
-import type { ShellMessage } from '../domain/message/types'
+import type { ShellMessage } from '../message/message'
 
+/** The pipe a channel rides: one peer, ordered delivery, no reply semantics. */
 export interface Transport {
   send(message: ShellMessage): void
   onMessage(handler: (message: ShellMessage) => void): void