@astrale-os/adapter-cloudflare 0.1.8 → 0.1.10

package/template/client/src/shell/invoke.ts

@@ -0,0 +1,35 @@
+/**
+ * Kernel invocation primitives — the single place a view reaches the kernel,
+ * over the shell's proper `KernelClient` (`session.call`, wired by the sandboxed
+ * handshake: fresh delegation token per call, redirects followed). `callMethod`
+ * is the generic method-ref call; `invokeNode` is instance dispatch by node id
+ * (`@<id>::<method>` — the shell hands views node IDs, not paths); `nodeAddr`
+ * picks the stable address for a node.
+ */
+import type { KernelClient } from '@astrale-os/shell'
+
+import type { KernelNode } from './client'
+
+/** One kernel call through the live session (proper client: fresh token, redirects). */
+export function callMethod(
+  session: KernelClient,
+  method: string,
+  params: Record<string, unknown> = {},
+): Promise<unknown> {
+  return session.call(method, params)
+}
+
+/** Instance-method dispatch by node id. */
+export function invokeNode(
+  session: KernelClient,
+  nodeId: string,
+  method: string,
+  params: Record<string, unknown> = {},
+): Promise<unknown> {
+  return callMethod(session, `@${nodeId}::${method}`, params)
+}
+
+/** Stable instance address: tree path when known, else `@id`. */
+export function nodeAddr(node: KernelNode): string {
+  return node.path && node.path.startsWith('/') ? node.path : `@${node.id}`
+}

package/template/client/src/shell/transformers.ts

@@ -0,0 +1,72 @@
+/**
+ * Graph-response transformers at the kernel boundary — turn raw `::get` /
+ * `::listChildren` / `::getLinks` payloads into the shapes features consume.
+ * Domain-neutral: per-class node→record mappers live in each feature's
+ * `*.mappers.ts` and build on `qualifiedString` here.
+ *
+ * Props are stored under QUALIFIED keys
+ * (`monitors.astrale.ai:class.Monitor.property.url`). The client must not import
+ * server schema, so values resolve by KEY SUFFIX (`.property.<name>`),
+ * preferring domain-qualified keys over kernel ones
+ * (`kernel.astrale.ai:interface.Named.property.name` would otherwise shadow
+ * `Monitor.property.name` — both end in `.property.name`).
+ */
+import type { KernelNode } from './client'
+
+/** Resolve a prop by `.property.<name>` suffix; domain keys win over kernel ones. */
+export function qualifiedProp(props: Record<string, unknown>, name: string): unknown {
+  const suffix = `.property.${name}`
+  let kernelFallback: unknown
+  for (const [key, value] of Object.entries(props)) {
+    if (!key.endsWith(suffix)) continue
+    if (key.startsWith('kernel.astrale.ai:')) {
+      if (kernelFallback === undefined) kernelFallback = value
+    } else {
+      return value
+    }
+  }
+  return kernelFallback
+}
+
+export function qualifiedString(props: Record<string, unknown>, name: string): string | undefined {
+  const v = qualifiedProp(props, name)
+  return typeof v === 'string' && v !== '' ? v : undefined
+}
+
+type RawLink = { class?: unknown; edgeClass?: unknown; target?: unknown; to?: unknown }
+
+/**
+ * Targets of a `::getLinks` response whose edge class ends with `classTail`
+ * (e.g. `'monitor_on_host'`). Tolerates bare-array and `{ links }` envelopes,
+ * and both `target`/`to` + `class`/`edgeClass`.
+ */
+export function linkTargets(raw: unknown, classTail: string): string[] {
+  const links: RawLink[] = Array.isArray(raw)
+    ? (raw as RawLink[])
+    : ((raw as { links?: RawLink[] } | null)?.links ?? [])
+  const out: string[] = []
+  for (const link of links) {
+    const cls =
+      typeof link.class === 'string'
+        ? link.class
+        : typeof link.edgeClass === 'string'
+          ? link.edgeClass
+          : ''
+    if (!cls.endsWith(classTail)) continue
+    const target =
+      typeof link.target === 'string'
+        ? link.target
+        : typeof link.to === 'string'
+          ? link.to
+          : undefined
+    if (target) out.push(target)
+  }
+  return out
+}
+
+/** A `::listChildren` response as a node array (bare array or enveloped). */
+export function asNodeArray(raw: unknown): KernelNode[] {
+  if (Array.isArray(raw)) return raw as KernelNode[]
+  const obj = raw as { children?: KernelNode[]; nodes?: KernelNode[] } | null
+  return obj?.children ?? obj?.nodes ?? []
+}

package/template/client/src/shell/use-async.ts

@@ -0,0 +1,56 @@
+/**
+ * Tiny async-resource hook — load on mount / when `deps` change, expose a
+ * `reload()` for refresh buttons and post-mutation refetches. Mirrors the
+ * cancellation discipline of `use-node.ts` (stale resolutions are dropped).
+ */
+import { useCallback, useEffect, useState } from 'react'
+
+import { errorMessage } from './client'
+
+export type AsyncState<T> =
+  | { status: 'loading' }
+  | { status: 'ok'; data: T }
+  | { status: 'error'; message: string }
+
+export type AsyncResource<T> = {
+  state: AsyncState<T>
+  /** Refetch. Keeps showing the previous data while the reload is in flight. */
+  reload: () => void
+  /** True while a reload is in flight on top of an `ok` state. */
+  reloading: boolean
+}
+
+export function useAsync<T>(fn: () => Promise<T>, deps: unknown[]): AsyncResource<T> {
+  const [state, setState] = useState<AsyncState<T>>({ status: 'loading' })
+  const [reloading, setReloading] = useState(false)
+  const [epoch, setEpoch] = useState(0)
+
+  useEffect(() => {
+    let cancelled = false
+    setState((prev) => {
+      if (prev.status === 'ok') {
+        setReloading(true)
+        return prev // keep stale data visible during a reload
+      }
+      return { status: 'loading' }
+    })
+    fn()
+      .then((data) => {
+        if (cancelled) return
+        setReloading(false)
+        setState({ status: 'ok', data })
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return
+        setReloading(false)
+        setState({ status: 'error', message: errorMessage(err) })
+      })
+    return () => {
+      cancelled = true
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- deps are the caller's cache key
+  }, [...deps, epoch])
+
+  const reload = useCallback(() => setEpoch((e) => e + 1), [])
+  return { state, reload, reloading }
+}

package/template/client/src/shell/use-capability.ts

@@ -0,0 +1,61 @@
+/**
+ * `useCapability` — the convention's WRITE primitive: a node method made
+ * interactive, wrapped in one uniform lifecycle (idle → running → done/failed).
+ * Every actuator (a form submit, a danger button) shares this machine instead
+ * of re-implementing busy/error flags by hand.
+ *
+ *   const check = useCapability(() => invokeNode(session, nodeId, 'check', {}))
+ *   …
+ *   if (await check.run()) reload()
+ *
+ * (This is the single seam where permission-gating would later land — a
+ * `permitted` flag computed from the node's affordances — without touching any
+ * presentational component.)
+ */
+import { useCallback, useState } from 'react'
+
+import { errorMessage } from './client'
+
+export type Phase = 'idle' | 'running' | 'done' | 'failed'
+
+export interface Capability<P = void> {
+  /** Phase of the most recent invocation. */
+  phase: Phase
+  /** Failure message when `phase === 'failed'`, else null. */
+  error: string | null
+  /** Invoke; resolves true on success, false on failure (error then set). */
+  run: [P] extends [void] ? () => Promise<boolean> : (params: P) => Promise<boolean>
+  /** Return to idle, clearing any error. */
+  reset: () => void
+}
+
+export function useCapability<P = void>(
+  perform: (params: P) => Promise<unknown>,
+): Capability<P> {
+  const [phase, setPhase] = useState<Phase>('idle')
+  const [error, setError] = useState<string | null>(null)
+
+  const run = useCallback(
+    async (params: P): Promise<boolean> => {
+      setPhase('running')
+      setError(null)
+      try {
+        await perform(params)
+        setPhase('done')
+        return true
+      } catch (err) {
+        setPhase('failed')
+        setError(errorMessage(err))
+        return false
+      }
+    },
+    [perform],
+  )
+
+  const reset = useCallback(() => {
+    setPhase('idle')
+    setError(null)
+  }, [])
+
+  return { phase, error, run, reset } as Capability<P>
+}

package/template/client/src/shell/use-node.ts

@@ -0,0 +1,61 @@
+import { useCallback, useEffect, useState } from 'react'
+
+import type { KernelClient } from '@astrale-os/shell'
+
+import { errorMessage, type KernelNode } from './client'
+
+export type NodeState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'ok'; node: KernelNode }
+  | { status: 'error'; message: string }
+
+/**
+ * Fetch a node by id via `@<id>::get`. Re-fetches when the target node id
+ * changes (`setTarget` hot-swap); stays `idle` until a target node id exists.
+ * `session` is a stable reference for the view's lifetime, so listing it as a
+ * dep never re-fires on its own — and the shell's client reads the fresh token
+ * at call time, so a `ctrl:tokenRefresh` needs no re-fetch.
+ *
+ * Returns the node state plus a `reload()` that re-fetches the current node —
+ * the view calls it after an instance method (e.g. `::check`) mutates the node
+ * so the fresh props render. It bumps an internal `nonce` dep, re-firing the
+ * effect.
+ */
+export function useNode(
+  session: KernelClient,
+  nodeId: string | undefined,
+): NodeState & { reload(): void } {
+  const [state, setState] = useState<NodeState>({ status: 'idle' })
+  const [nonce, setNonce] = useState(0)
+
+  const reload = useCallback(() => {
+    setNonce((n) => n + 1)
+  }, [])
+
+  useEffect(() => {
+    if (!nodeId) {
+      setState({ status: 'idle' })
+      return
+    }
+
+    let cancelled = false
+    setState({ status: 'loading' })
+    session
+      .call(`@${nodeId}::get`, {})
+      .then((result) => {
+        if (!cancelled) setState({ status: 'ok', node: result as KernelNode })
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) {
+          setState({ status: 'error', message: errorMessage(err) })
+        }
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [session, nodeId, nonce])
+
+  return { ...state, reload }
+}

package/template/client/src/shell/use-shell.ts

@@ -0,0 +1,91 @@
+import {
+  createShell,
+  type IntentMessage,
+  type IntentRegistry,
+  type KernelClient,
+  type Shell,
+} from '@astrale-os/shell'
+import { useEffect, useMemo, useState } from 'react'
+
+export type ShellStatus = 'loading' | 'ready' | 'standalone'
+
+export type ShellState = {
+  status: ShellStatus
+  /** The kernel handle once `ready` — view hooks call through `session.call`. */
+  session: KernelClient | null
+  /** Current target node id — updates on `setTarget` hot-swaps. */
+  nodeId: string | undefined
+  /** Why we fell back to `standalone` (no parent / handshake timeout). */
+  reason: string | null
+}
+
+/**
+ * Boots the real Astrale shell in sandboxed (child) mode: runs the init
+ * handshake with the parent window to obtain the kernel session + target node,
+ * then tracks `setTarget` hot-swaps. The shell's `KernelClient` owns the
+ * delegation token (refreshed by the parent) and the kernel transport, so view
+ * hooks just call `session.call('@<id>::<method>')`.
+ *
+ * Three outcomes:
+ *   - `loading`    — handshake in flight
+ *   - `ready`      — parent completed the handshake; `session`/`nodeId` populated
+ *   - `standalone` — no parent or it timed out (opened directly in a tab); the
+ *                    view renders a self-describing fallback
+ */
+export function useShell(): ShellState {
+  const [status, setStatus] = useState<ShellStatus>('loading')
+  const [session, setSession] = useState<KernelClient | null>(null)
+  const [nodeId, setNodeId] = useState<string | undefined>(undefined)
+  const [reason, setReason] = useState<string | null>(null)
+
+  useEffect(() => {
+    // Not framed (opened directly in a tab): skip the handshake entirely rather
+    // than waiting out the init timeout — there is no parent to answer it.
+    if (!window.parent || window.parent === window) {
+      setReason('not running inside a parent frame')
+      setStatus('standalone')
+      return
+    }
+
+    let cancelled = false
+    let shell: Shell | null = null
+
+    void (async () => {
+      try {
+        const built = createShell({ mode: 'sandboxed', initTimeoutMs: 5000 })
+        await built.init()
+        if (cancelled) {
+          void built.dispose()
+          return
+        }
+        shell = built
+
+        // Hand views the shell's real `KernelClient` directly. It reads the live
+        // (parent-refreshed) token on each call and owns the transport, so view
+        // hooks just call `session.call('@<id>::<method>', params)`.
+        setSession(built.kernel)
+        setNodeId(built.targetNodeId)
+        setStatus('ready')
+
+        // Hot-swap: the parent pushes a new target via the typed `setTarget`
+        // intent; the iframe stays mounted, only `nodeId` updates.
+        built.parent?.on('intent', (msg: IntentMessage) => {
+          if (msg.envelope.name !== 'setTarget') return
+          const payload = msg.envelope.payload as IntentRegistry['setTarget']['payload']
+          if (typeof payload.nodeId === 'string') setNodeId(payload.nodeId)
+        })
+      } catch (err) {
+        if (cancelled) return
+        setReason(err instanceof Error ? err.message : String(err))
+        setStatus('standalone')
+      }
+    })()
+
+    return () => {
+      cancelled = true
+      if (shell) void shell.dispose()
+    }
+  }, [])
+
+  return useMemo(() => ({ status, session, nodeId, reason }), [status, session, nodeId, reason])
+}

package/template/client/src/shell/view-router.tsx

@@ -0,0 +1,98 @@
+/**
+ * Tiny multi-view router for the domain's one SPA bundle.
+ *
+ * The domain declares several SPA Views, each mounted by the shell at its own
+ * path under `/ui/*` (e.g. `/ui/monitor`). The shell mounts ONE iframe per view,
+ * so inside the iframe `window.location.pathname` is that view's mount path. This
+ * bundle reads that path and renders the matching view — one build, many views.
+ *
+ * Two pieces:
+ *   - `resolveView` — map `window.location.pathname` → a view component.
+ *   - `ViewFrame`   — DRYs the shell-handshake gating (`loading`/`standalone`/
+ *     `ready`) every view repeats, so a view only writes its `ready` body.
+ *
+ * To add a view: write a `ViewComponent` (usually wrapping `ViewFrame`), add a
+ * `ROUTES` entry keyed by its mount path in `src/app.tsx`, and register a
+ * matching `defineView({ mount })` in the domain's `views/`.
+ */
+
+import type { ReactNode } from 'react'
+
+import type { KernelClient } from '@astrale-os/shell'
+
+import type { ShellState } from './use-shell'
+
+/** A view: given the shell state, render its tree. */
+export type ViewComponent = (shell: ShellState) => ReactNode
+
+/** Mount path → view component (key e.g. `/ui/monitor`). */
+export type ViewRoutes = Record<string, ViewComponent>
+
+/** Strip a single trailing slash (but keep a bare `/`). */
+function normalizePath(pathname: string): string {
+  return pathname.length > 1 && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname
+}
+
+/**
+ * Resolve the view for a mount path — exact match, tolerating a trailing slash.
+ * Returns `undefined` when no route is registered (caller renders a fallback).
+ */
+export function resolveView(
+  routes: ViewRoutes,
+  pathname: string = window.location.pathname,
+): ViewComponent | undefined {
+  return routes[normalizePath(pathname)]
+}
+
+/**
+ * Shared shell-handshake gate. Renders the `.wrap`/`.card` shell and:
+ *   - `loading`    → title + subline + "Waiting for the shell handshake…"
+ *   - `standalone` → title + subline + the "No parent shell" banner copy
+ *   - `ready`      → `children(session, nodeId)` (session is non-null here)
+ *
+ * Mirrors the markup/classes the original single-view app used, so styling is
+ * unchanged across views.
+ */
+export function ViewFrame({
+  shell,
+  title,
+  subline,
+  children,
+}: {
+  shell: ShellState
+  title: string
+  subline?: string
+  children: (session: KernelClient, nodeId: string | undefined) => ReactNode
+}) {
+  const { status, session, nodeId, reason } = shell
+
+  return (
+    <div className="wrap">
+      <div className="card">
+        {status === 'loading' && (
+          <>
+            <h1 className="title">{title}</h1>
+            {subline && <p className="subline">{subline}</p>}
+            <p className="muted">Waiting for the shell handshake…</p>
+          </>
+        )}
+
+        {status === 'standalone' && (
+          <>
+            <h1 className="title">{title}</h1>
+            {subline && <p className="subline">{subline}</p>}
+            <div className="banner">
+              No parent shell ({reason}). This view is meant to be mounted by the Astrale GUI, which
+              hands it a target node and a kernel session. Showing a standalone preview.
+            </div>
+            <p className="body muted">
+              When mounted by the shell, this card renders the node you opened.
+            </p>
+          </>
+        )}
+
+        {status === 'ready' && session && children(session, nodeId)}
+      </div>
+    </div>
+  )
+}