@astrale-os/adapter-cloudflare 0.1.9 → 0.2.0

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,59 @@
+/**
+ * `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 type { KernelClient } from '@astrale-os/shell'
+
+import { useCallback, useEffect, useState } from 'react'
+
+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,97 @@
+/**
+ * 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/status-page`). 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 { KernelClient } from '@astrale-os/shell'
+import type { ReactNode } from 'react'
+
+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/status-page`). */
+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>
+  )
+}

package/template/client/src/status/components/StatusCard.tsx

@@ -0,0 +1,50 @@
+/**
+ * StatusCard — the status feature's one container. It owns the data/logic: loads
+ * the node (`useCheckable`), wires the `check` write (`useCheck`), and composes
+ * the presentation. Handles the query's loading/error/ok states; on `ok` it
+ * renders a `Panel` with the check-error banner (if any) + the StatusBadge.
+ * "Check now" runs the check then reloads the node so the fresh status renders.
+ *
+ * The generic surfaces come from the `@/ui` design system; the only domain-shaped
+ * primitive is the shared `StatusBadge`.
+ */
+import type { KernelClient } from '@/shell'
+
+import { ErrorBanner, Panel, Spinner, StatusBadge } from '@/ui'
+
+import { useCheck, useCheckable } from '../hooks'
+
+export function StatusCard({ session, nodeId }: { session: KernelClient; nodeId: string }) {
+  const checkable = useCheckable(session, nodeId)
+  const check = useCheck(session, nodeId)
+
+  async function checkNow() {
+    if (await check.run()) checkable.reload()
+  }
+
+  if (checkable.state === 'idle' || checkable.state === 'loading') {
+    return <Spinner label="Loading…" />
+  }
+  if (checkable.state === 'error') {
+    return <ErrorBanner>Failed to load: {checkable.message}</ErrorBanner>
+  }
+
+  const record = checkable.record!
+  const checking = check.phase === 'running'
+  const checkButton = (
+    <button type="button" className="check-btn" onClick={checkNow} disabled={checking}>
+      {checking ? 'Checking…' : 'Check now'}
+    </button>
+  )
+
+  return (
+    <Panel title={record.name} actions={checkButton}>
+      {check.phase === 'failed' && check.error && (
+        <ErrorBanner>Check failed: {check.error}</ErrorBanner>
+      )}
+      <div className="status-row">
+        <StatusBadge status={record.status} />
+      </div>
+    </Panel>
+  )
+}

package/template/client/src/status/components/index.ts

@@ -0,0 +1 @@
+export { StatusCard } from './StatusCard'

package/template/client/src/status/hooks/index.ts

@@ -0,0 +1,3 @@
+export { useCheckable } from './useCheckable.query'
+export type { CheckableQuery } from './useCheckable.query'
+export { useCheck } from './useCheck.mutation'

package/template/client/src/status/hooks/useCheck.mutation.ts

@@ -0,0 +1,16 @@
+/** Run a checkable node's `check` — the feature's one write capability. */
+import { type Capability, type KernelClient, useCapability } from '@/shell'
+
+import { check } from '../status.api'
+
+/**
+ * Wrap `@<id>::check` in the shared `useCapability` lifecycle (idle → running →
+ * done/failed). The view runs it and, on success, reloads the node so the fresh
+ * status renders:
+ *
+ *   const probe = useCheck(session, nodeId)
+ *   if (await probe.run()) reload()
+ */
+export function useCheck(session: KernelClient, nodeId: string): Capability {
+  return useCapability(() => check(session, nodeId))
+}

package/template/client/src/status/hooks/useCheckable.query.ts

@@ -0,0 +1,64 @@
+/** Load a checkable node → typed record, with a `reload()` for post-check refresh. */
+import { useCallback, useRef, useState } from 'react'
+
+import { type KernelClient, useNode } from '@/shell'
+
+import type { CheckableRecord } from '../status.types'
+
+import { checkableFromNode } from '../status.mappers'
+
+export type CheckableQuery = {
+  /** Lifecycle of the underlying `@<id>::get`. */
+  state: 'idle' | 'loading' | 'error' | 'ok'
+  /** The projected record once `ok`. */
+  record?: CheckableRecord
+  /** Failure message once `error`. */
+  message?: string
+  /** Re-fetch the node — call after `check` mutates it server-side. */
+  reload(): void
+  /** True while a `reload()`-triggered re-fetch is in flight. */
+  reloading: boolean
+}
+
+/**
+ * Load the checkable node `nodeId` and project it to a `CheckableRecord`. Wraps
+ * `useNode` (which owns the `@<id>::get` + the hot-swap re-fetch) and re-exposes
+ * its `reload()` so the view can refresh after a `check`. `reloading` is true
+ * from the moment `reload()` is called until the re-fetch settles — distinct from
+ * the initial `loading`, so the view can show the existing record meanwhile.
+ */
+export function useCheckable(session: KernelClient, nodeId: string): CheckableQuery {
+  const node = useNode(session, nodeId)
+  const [reloading, setReloading] = useState(false)
+  // Two-phase reload tracker. `reload()` arms it as `'requested'`; once we
+  // observe `useNode` enter `loading` it advances to `'loading'`; the next time
+  // it leaves `loading` the re-fetch has settled, so we clear `reloading`. The
+  // two phases avoid clearing on the synchronous render BEFORE the effect runs
+  // (when the status is still the pre-reload `ok`).
+  const phase = useRef<'idle' | 'requested' | 'loading'>('idle')
+
+  if (phase.current === 'requested' && node.status === 'loading') {
+    phase.current = 'loading'
+  } else if (phase.current === 'loading' && node.status !== 'loading') {
+    phase.current = 'idle'
+    if (reloading) setReloading(false)
+  }
+
+  const nodeReload = node.reload
+  const reload = useCallback(() => {
+    phase.current = 'requested'
+    setReloading(true)
+    nodeReload()
+  }, [nodeReload])
+
+  switch (node.status) {
+    case 'ok':
+      return { state: 'ok', record: checkableFromNode(node.node), reload, reloading }
+    case 'error':
+      return { state: 'error', message: node.message, reload, reloading }
+    case 'loading':
+      return { state: 'loading', reload, reloading }
+    default:
+      return { state: 'idle', reload, reloading }
+  }
+}

package/template/client/src/status/index.ts

@@ -0,0 +1,7 @@
+/** The status feature — its api, types, mappers, hooks and components. One card,
+ * polymorphic over any `Checkable` node (Monitor or StatusPage). */
+export * from './components'
+export * from './hooks'
+export { check } from './status.api'
+export { checkableFromNode } from './status.mappers'
+export type { CheckableRecord } from './status.types'

package/template/client/src/status/status.api.ts

@@ -0,0 +1,12 @@
+/** Raw kernel calls for the status feature — node instance methods. */
+import { invokeNode, type KernelClient } from '@/shell'
+
+/**
+ * Run a checkable node's `check` instance method (`@<id>::check`). The single
+ * write both classes share: a Monitor probes its target URL, a StatusPage rolls
+ * its watched monitors up — each updates its own `status` prop server-side; the
+ * caller reloads the node to render the fresh value.
+ */
+export function check(session: KernelClient, nodeId: string): Promise<unknown> {
+  return invokeNode(session, nodeId, 'check', {})
+}

package/template/client/src/status/status.mappers.ts

@@ -0,0 +1,19 @@
+/** Node → typed record transform for the status feature. */
+import { type KernelNode, PROP, readProp, readPropBySuffix } from '@/shell'
+
+import type { CheckableRecord } from './status.types'
+
+const lastSegment = (path: string): string => path.split('/').filter(Boolean).pop() ?? path
+
+/**
+ * Project a `Checkable` `KernelNode` into a `CheckableRecord`: the name from the
+ * kernel `Named.name` key, the domain-qualified `status` read by suffix (default
+ * `'unknown'`).
+ */
+export function checkableFromNode(node: KernelNode): CheckableRecord {
+  const p = node.props ?? {}
+  return {
+    name: readProp(p, PROP.named.name) ?? lastSegment(node.path ?? '') ?? node.id,
+    status: readPropBySuffix(p, '.property.status') ?? 'unknown',
+  }
+}

package/template/client/src/status/status.types.ts

@@ -0,0 +1,11 @@
+/** The status feature's client type — what a `Checkable` node projects to. */
+
+/**
+ * Client-side projection of the `Checkable` node the view renders (a StatusPage).
+ * `status` stays a plain string — the page's rolled-up verdict
+ * (up/degraded/down/unknown), which `StatusBadge` renders.
+ */
+export type CheckableRecord = {
+  name: string
+  status: string
+}