@astrale-os/adapter-cloudflare 0.1.0

package/template/client/src/lib/kernel.ts

@@ -0,0 +1,135 @@
+/**
+ * Minimal, self-contained kernel JSON client — just enough to load a node via
+ * `@<id>::get`, without pulling in `@astrale-os/kernel-client` (and its
+ * transitive deps). It reproduces the kernel ENVELOPE wire shape inline.
+ *
+ * Wire contract (authoritative source: `kernel/api/envelope/`):
+ *   - Request:  POST <kernelUrl> with headers
+ *       content-type: application/vnd.astrale.kernel+json
+ *       accept:       application/vnd.astrale.kernel+json
+ *       authorization: <delegationToken>      (BARE token — no "Bearer " prefix)
+ *     body JSON `{ method, params, id }` (see `encode.ts:encodeKernelRequest`).
+ *   - Response: JSON, exactly one of (decode precedence error → redirect → result,
+ *     mirroring `decode.ts:decodeKernelResponse`):
+ *       { error: { code, message }, id }   → throw Error("<code>: <message>")
+ *       { redirect, id }                   → throw (we don't follow redirects here)
+ *       { result, id }                     → return result
+ *
+ * Deliberately JSON-only: no msgpack codec, no streaming/binary, no redirect
+ * following, no schema/batching. Those live in `@astrale-os/kernel-client`,
+ * which this self-contained build omits on purpose.
+ */
+
+// From `kernel/api/envelope/types.ts` (KERNEL_CONTENT_TYPE_JSON). Inlined so the
+// template needs no @astrale-os import.
+const KERNEL_CONTENT_TYPE_JSON = 'application/vnd.astrale.kernel+json'
+
+// Module-local monotonic request id. Strings keep ids stable across reloads and
+// distinguishable in logs; the kernel echoes `id` back but we don't correlate
+// (one request per fetch).
+let idSeq = 0
+function nextId(): string {
+  idSeq += 1
+  return `c${idSeq}`
+}
+
+/**
+ * Prop key constants — the graph stores props with fully-qualified keys
+ * (`<domain>:<member>.property.<name>`). The kernel `Named.name` key is fixed
+ * and known; domain props (`title`, `body`) are qualified by the (build-time
+ * unknown) domain origin — read those by suffix with `readPropBySuffix`.
+ */
+export const PROP = {
+  named: {
+    name: 'kernel.astrale.ai:interface.Named.property.name',
+  },
+} as const
+
+export type KernelNode = {
+  id: string
+  path: string
+  class: string | { raw?: string }
+  props: Record<string, unknown>
+}
+
+export function readProp(props: Record<string, unknown>, key: string): string | undefined {
+  const v = props[key]
+  return typeof v === 'string' ? v : undefined
+}
+
+/**
+ * Read a string prop by key suffix — for domain-qualified props whose full key
+ * embeds the (build-time-unknown) domain origin. e.g.
+ * `readPropBySuffix(props, '.property.body')`.
+ */
+export function readPropBySuffix(
+  props: Record<string, unknown>,
+  suffix: string,
+): string | undefined {
+  for (const [k, v] of Object.entries(props)) {
+    if (k.endsWith(suffix) && typeof v === 'string') return v
+  }
+  return undefined
+}
+
+/** Short class name from a `class.raw` path `/:<domain>:class.<Name>` → `<Name>`. */
+export function classShortName(node: KernelNode): string {
+  const raw = (typeof node.class === 'string' ? node.class : node.class?.raw) ?? ''
+  const last = raw.split(':').pop() ?? ''
+  const dot = last.indexOf('.')
+  return dot >= 0 ? last.slice(dot + 1) : last
+}
+
+/**
+ * POST a single kernel call and return its `result`. Throws on a kernel error
+ * envelope or an unexpected redirect. `token` is the bare delegation credential
+ * from the shell handshake; the iframe authenticates SOLELY with it (the parent
+ * minted it for this kernel, so the audience already matches — no cookie/mint).
+ */
+export async function kernelCall(
+  kernelUrl: string,
+  token: string,
+  method: string,
+  params: Record<string, unknown> = {},
+): Promise<unknown> {
+  // The kernel routes on a trailing slash; the parent absolutizes the URL, but
+  // not always with the slash, so normalize here.
+  const url = kernelUrl.endsWith('/') ? kernelUrl : `${kernelUrl}/`
+  const id = nextId()
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'content-type': KERNEL_CONTENT_TYPE_JSON,
+      accept: KERNEL_CONTENT_TYPE_JSON,
+      authorization: token,
+    },
+    body: JSON.stringify({ method, params, id }),
+  })
+
+  let body: unknown
+  try {
+    body = await res.json()
+  } catch {
+    throw new Error(`kernel returned a non-JSON response (HTTP ${res.status})`)
+  }
+
+  if (body === null || typeof body !== 'object') {
+    throw new Error(`kernel returned an unexpected response (HTTP ${res.status})`)
+  }
+  const obj = body as Record<string, unknown>
+
+  // Decode precedence error → redirect → result (mirrors decodeKernelResponse).
+  if ('error' in obj && obj.error && typeof obj.error === 'object') {
+    const err = obj.error as { code?: unknown; message?: unknown }
+    const code = typeof err.code === 'number' ? err.code : 5000
+    const message = typeof err.message === 'string' ? err.message : 'Unknown error'
+    throw new Error(`${code}: ${message}`)
+  }
+  if ('redirect' in obj && obj.redirect) {
+    // Redirects (remote-domain Functions) aren't followed by this minimal
+    // client — they require credential re-minting against the target worker.
+    throw new Error('unexpected redirect from kernel (not supported by the template client)')
+  }
+  return obj.result
+}

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

@@ -0,0 +1,197 @@
+/**
+ * Minimal, self-contained reimplementation of the Astrale shell *child* init
+ * handshake — just enough to learn which node this view is mounted for and to
+ * keep its delegation token live, without pulling in `@astrale-os/shell` (and
+ * its `kernel-client` transitive deps).
+ *
+ * Protocol (mirrors `shell/packages/shell/src/application/windowing/`):
+ *   1. child posts `{ type: 'astrale-shell/init-request', version: 1 }` to the
+ *      parent window via `window.postMessage(..., '*')`.
+ *   2. parent replies with `{ type: 'astrale-shell/init-response', windowId }`
+ *      and *transfers a MessagePort* (`event.ports[0]`).
+ *   3. over that port the parent sends a `ctrl:handshake` carrying the session
+ *      data — `windowId`, `kernelUrl`, `delegationToken`, `tokenExpiresAt`,
+ *      `functionId`, and the `targetNodeId` (the node this view should render).
+ *   4. child replies with `ctrl:handshakeAck` and keeps the port open.
+ *
+ * Steady state on the port:
+ *   - `intent` `setTarget { nodeId }` — hot-swap the target node (re-render).
+ *   - `ctrl:tokenRefresh { delegationToken, tokenExpiresAt }` — the parent
+ *     pushes a FRESH token before the old one expires. We update the mutable
+ *     `currentToken` so the next kernel call uses it (see `getToken()`).
+ *
+ * The iframe authenticates with the handshake `delegationToken` ONLY: the
+ * parent minted it for this kernel, so the audience already matches — no
+ * cookie, no whoami, no client-side minting. Actually CALLING the kernel lives
+ * in `lib/kernel.ts` (a minimal inline JSON client).
+ */
+
+const INIT_REQUEST_TYPE = 'astrale-shell/init-request'
+const INIT_RESPONSE_TYPE = 'astrale-shell/init-response'
+
+export type HandshakeData = {
+  windowId: string
+  kernelUrl?: string
+  functionId?: string
+  /** Opaque delegation credential the parent minted for this view. */
+  delegationToken?: string
+  /** Unix-ms expiry of `delegationToken`; advances on each `tokenRefresh`. */
+  tokenExpiresAt?: number
+  /** The node this view is mounted for — what we want to render. */
+  targetNodeId?: string
+}
+
+export type ShellSession = {
+  /** Handshake data captured at handshake time (token here is the INITIAL one). */
+  readonly data: HandshakeData
+  /** Convenience mirror of `data.kernelUrl` (satisfies `NodeSession`). */
+  readonly kernelUrl: string | undefined
+  /** The LIVE delegation token — reflects `tokenRefresh` pushes. */
+  getToken(): string | undefined
+  /** The LIVE token expiry (Unix ms) — reflects `tokenRefresh` pushes. */
+  getTokenExpiresAt(): number | undefined
+  /** Subscribe to `targetNodeId` hot-swaps pushed via `setTarget` intents. */
+  onTargetChange(cb: (nodeId: string | undefined) => void): () => void
+  /** Tear down listeners + the message port. */
+  dispose(): void
+}
+
+type CtrlMessage = {
+  type: 'ctrl'
+  version: number
+  action: string
+  data?: Record<string, unknown>
+}
+
+type IntentMessage = {
+  type: 'intent'
+  envelope?: { name?: string; payload?: Record<string, unknown> }
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null
+
+const asString = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined)
+
+/**
+ * Run the child handshake. Resolves once the parent completes `ctrl:handshake`.
+ * Rejects on timeout (no parent / not sandboxed) — callers should render a
+ * standalone fallback in that case.
+ */
+export function connectShell(timeoutMs = 5000): Promise<ShellSession> {
+  return new Promise((resolve, reject) => {
+    const parent = window.parent
+    if (!parent || parent === window) {
+      reject(new Error('not running inside a parent frame'))
+      return
+    }
+
+    let port: MessagePort | null = null
+    // Mutable token state — `tokenRefresh` updates these in place so later
+    // kernel calls read the fresh credential via `getToken()`.
+    let currentToken: string | undefined
+    let currentExpiresAt: number | undefined
+    const targetListeners = new Set<(nodeId: string | undefined) => void>()
+
+    const timer = setTimeout(() => {
+      cleanupWindow()
+      reject(new Error(`shell handshake timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+
+    function cleanupWindow() {
+      clearTimeout(timer)
+      window.removeEventListener('message', onWindowMessage)
+    }
+
+    // Steady-state port listener: target hot-swaps + token refreshes.
+    function onPortMessage(ev: MessageEvent) {
+      const msg = ev.data as unknown
+      if (!isObj(msg)) return
+
+      // Token refresh: the parent pushed a fresh credential. Swap it in place.
+      if (msg.type === 'ctrl' && (msg as CtrlMessage).action === 'tokenRefresh') {
+        const d = (msg as CtrlMessage).data ?? {}
+        const next = asString(d.delegationToken)
+        if (next) currentToken = next
+        if (typeof d.tokenExpiresAt === 'number') currentExpiresAt = d.tokenExpiresAt
+        return
+      }
+
+      // Hot-swap: `setTarget` intent carries a new nodeId.
+      if (msg.type === 'intent') {
+        const intent = msg as IntentMessage
+        if (intent.envelope?.name === 'setTarget') {
+          const raw = intent.envelope.payload?.nodeId
+          const nodeId = asString(raw)
+          for (const cb of targetListeners) cb(nodeId)
+        }
+      }
+    }
+
+    function onWindowMessage(ev: MessageEvent) {
+      const msg = ev.data as unknown
+      if (ev.source !== parent || !isObj(msg)) return
+      if (msg.type !== INIT_RESPONSE_TYPE) return
+
+      const received = ev.ports[0]
+      if (!received) return
+      port = received
+
+      port.onmessage = (portEv: MessageEvent) => {
+        const ctrl = portEv.data as unknown
+        if (!isObj(ctrl) || ctrl.type !== 'ctrl') {
+          onPortMessage(portEv)
+          return
+        }
+        const m = ctrl as CtrlMessage
+        if (m.action !== 'handshake' || !port) return
+
+        const d = (m.data ?? {}) as Record<string, unknown>
+        currentToken = asString(d.delegationToken)
+        currentExpiresAt = typeof d.tokenExpiresAt === 'number' ? d.tokenExpiresAt : undefined
+        const kernelUrl = asString(d.kernelUrl)
+
+        // Ack so the parent considers the child live.
+        port.postMessage({
+          type: 'ctrl',
+          version: 1,
+          action: 'handshakeAck',
+          data: { windowId: d.windowId },
+        })
+        // Switch the port to the steady-state listener (intents + tokenRefresh).
+        port.onmessage = onPortMessage
+        cleanupWindow()
+
+        resolve({
+          data: {
+            windowId: String(d.windowId ?? ''),
+            kernelUrl,
+            functionId: asString(d.functionId),
+            delegationToken: currentToken,
+            tokenExpiresAt: currentExpiresAt,
+            targetNodeId: asString(d.targetNodeId),
+          },
+          kernelUrl,
+          getToken: () => currentToken,
+          getTokenExpiresAt: () => currentExpiresAt,
+          onTargetChange(cb) {
+            targetListeners.add(cb)
+            return () => targetListeners.delete(cb)
+          },
+          dispose() {
+            cleanupWindow()
+            targetListeners.clear()
+            if (port) {
+              port.onmessage = null
+              port.close()
+            }
+          },
+        })
+      }
+      port.start()
+    }
+
+    window.addEventListener('message', onWindowMessage)
+    // targetOrigin '*' — the parent verifies our origin on its side.
+    parent.postMessage({ type: INIT_REQUEST_TYPE, version: 1 }, '*')
+  })
+}

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

@@ -0,0 +1,66 @@
+import { useEffect, useState } from 'react'
+
+import { kernelCall, type KernelNode } from './kernel'
+
+/**
+ * The slice of the shell session this hook needs: where to call the kernel
+ * (`kernelUrl`) and how to read the LIVE delegation token (`getToken()` —
+ * which advances on `ctrl:tokenRefresh`). `ShellSession` satisfies this, and is
+ * a stable reference for the component's lifetime (set once on handshake).
+ */
+export type NodeSession = {
+  readonly kernelUrl: string | undefined
+  getToken(): string | undefined
+}
+
+export type NodeState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'ok'; node: KernelNode }
+  | { status: 'error'; message: string }
+
+/**
+ * Fetch a node by id via `@<id>::get`, using the session's kernel URL + live
+ * delegation token. Re-fetches when the target node id changes (`setTarget`
+ * hot-swap) or when a token first becomes available. Stays `idle` until both a
+ * target node id and a token exist.
+ *
+ * The effect keys on the token's PRESENCE (`hasToken`), not its value: a
+ * `ctrl:tokenRefresh` swaps the token in place WITHOUT re-firing, and the next
+ * fetch (triggered by a `setTarget` or remount) reads the fresh token via
+ * `session.getToken()` at call time. `session` is stable, so listing it as a
+ * dep is safe — it never causes a re-fire on its own.
+ */
+export function useNode(session: NodeSession, nodeId: string | undefined): NodeState {
+  const hasToken = session.getToken() !== undefined
+  const [state, setState] = useState<NodeState>({ status: 'idle' })
+
+  useEffect(() => {
+    const token = session.getToken()
+    if (!nodeId || !session.kernelUrl || !token) {
+      setState({ status: 'idle' })
+      return
+    }
+
+    let cancelled = false
+    setState({ status: 'loading' })
+    kernelCall(session.kernelUrl, token, `@${nodeId}::get`, {})
+      .then((result) => {
+        if (!cancelled) setState({ status: 'ok', node: result as KernelNode })
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) {
+          setState({
+            status: 'error',
+            message: err instanceof Error ? err.message : String(err),
+          })
+        }
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [session, hasToken, nodeId])
+
+  return state
+}

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

@@ -0,0 +1,85 @@
+import { useEffect, useState } from 'react'
+
+import { connectShell, type HandshakeData, type ShellSession } from './shell'
+
+export type ShellStatus = 'loading' | 'ready' | 'standalone'
+
+export type ShellState = {
+  status: ShellStatus
+  /** Handshake data once `ready` (kernelUrl, token, etc). */
+  data: HandshakeData | null
+  /**
+   * The live session once `ready` — exposes `getToken()` (which reflects
+   * `tokenRefresh`) and `kernelUrl`. The node-fetch hook reads through this so
+   * it always uses the CURRENT token, not the one captured at handshake time.
+   */
+  session: ShellSession | null
+  /** Current target node id — updates on `setTarget` hot-swaps. */
+  nodeId: string | undefined
+  /** Reason we fell back to `standalone` (no parent / timeout). */
+  reason: string | null
+}
+
+/**
+ * Runs the inline shell handshake once on mount and tracks the target node id.
+ *
+ * Three outcomes:
+ *   - `loading`     — handshake in flight
+ *   - `ready`       — parent completed the handshake; `data`/`session`/`nodeId`
+ *                     populated
+ *   - `standalone`  — no parent or it timed out (e.g. opened directly in a tab);
+ *                     the view renders a self-describing fallback
+ */
+export function useShell(): ShellState {
+  const [state, setState] = useState<ShellState>({
+    status: 'loading',
+    data: null,
+    session: null,
+    nodeId: undefined,
+    reason: null,
+  })
+
+  useEffect(() => {
+    let cancelled = false
+    let dispose: (() => void) | undefined
+
+    connectShell()
+      .then((session) => {
+        if (cancelled) {
+          session.dispose()
+          return
+        }
+        setState({
+          status: 'ready',
+          data: session.data,
+          session,
+          nodeId: session.data.targetNodeId,
+          reason: null,
+        })
+        const off = session.onTargetChange((nodeId) => {
+          setState((prev) => ({ ...prev, nodeId }))
+        })
+        dispose = () => {
+          off()
+          session.dispose()
+        }
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return
+        setState({
+          status: 'standalone',
+          data: null,
+          session: null,
+          nodeId: undefined,
+          reason: err instanceof Error ? err.message : String(err),
+        })
+      })
+
+    return () => {
+      cancelled = true
+      dispose?.()
+    }
+  }, [])
+
+  return state
+}

package/template/client/src/main.tsx

@@ -0,0 +1,9 @@
+import { createRoot } from 'react-dom/client'
+
+import './styles.css'
+import { App } from './app'
+
+const root = document.getElementById('root')
+if (!root) throw new Error('ui-note client: #root missing from index.html')
+
+createRoot(root).render(<App />)

package/template/client/src/styles.css

@@ -0,0 +1,107 @@
+:root {
+  --bg: #fafafa;
+  --fg: #171717;
+  --muted: #737373;
+  --border: #e5e5e5;
+  --card: #ffffff;
+  --accent: #2563eb;
+  --warn-bg: #fffbeb;
+  --warn-border: #fde68a;
+  --warn-fg: #92400e;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font: 14px/1.6 system-ui, -apple-system, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+
+#root {
+  min-height: 100vh;
+}
+
+.wrap {
+  max-width: 42rem;
+  margin: 0 auto;
+  padding: 1.5rem;
+}
+
+.card {
+  background: var(--card);
+  border: 1px solid var(--border);
+  border-radius: 0.75rem;
+  padding: 1.25rem 1.5rem;
+}
+
+.title {
+  font-size: 1.4rem;
+  font-weight: 600;
+  margin: 0;
+}
+
+.subline {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.72rem;
+  color: var(--muted);
+  margin: 0.25rem 0 1rem;
+  word-break: break-all;
+}
+
+.body {
+  white-space: pre-wrap;
+  margin: 0 0 1rem;
+}
+
+.banner {
+  border: 1px solid var(--warn-border);
+  background: var(--warn-bg);
+  color: var(--warn-fg);
+  border-radius: 0.5rem;
+  padding: 0.6rem 0.85rem;
+  font-size: 0.8rem;
+  margin-bottom: 1rem;
+}
+
+.kv {
+  border: 1px solid var(--border);
+  border-radius: 0.5rem;
+  overflow: hidden;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.72rem;
+}
+
+.kv-row {
+  display: grid;
+  grid-template-columns: 9rem 1fr;
+  gap: 0.75rem;
+  padding: 0.4rem 0.7rem;
+  border-top: 1px solid var(--border);
+}
+
+.kv-row:first-child {
+  border-top: 0;
+}
+
+.kv-key {
+  color: var(--muted);
+}
+
+.kv-val {
+  word-break: break-all;
+}
+
+.muted {
+  color: var(--muted);
+}
+
+.section-label {
+  font-size: 0.78rem;
+  font-weight: 600;
+  margin: 0 0 0.5rem;
+}

package/template/client/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "types": ["vite/client", "vitest/globals"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "__tests__/**/*.ts",
+    "__tests__/**/*.tsx",
+    "vite.config.ts",
+    "vitest.config.ts"
+  ],
+  "exclude": ["node_modules", "../dist-client"]
+}

package/template/client/vite.config.ts

@@ -0,0 +1,40 @@
+import viteReact from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+/**
+ * Client SPA for the domain's `ui-note` View. Built into `../dist-client/`,
+ * served by the generated worker via its `ASSETS` binding (`.astrale/`).
+ *
+ * `base: '/ui/'` + `outDir: '../dist-client'`: Vite emits asset refs as
+ * `/ui/assets/<hash>.js`; the worker strips the `/ui` prefix before delegating
+ * to `ASSETS`, so files resolve from the directory root. `index.html` is the
+ * SPA fallback for `/ui/<anything>`.
+ *
+ * Deliberately self-contained — only react/react-dom/vite/@vitejs/plugin-react,
+ * all on public npm — so the template builds without the @astrale-os registry
+ * or workspace `link:`s. Two small subsets are reimplemented inline: the shell
+ * child-handshake (`src/lib/shell.ts`, including `ctrl:tokenRefresh` so a
+ * pushed credential is picked up) and a minimal JSON kernel client
+ * (`src/lib/kernel.ts`, `@<id>::get`). Tests live in `__tests__/` and run on
+ * `vitest`/`happy-dom` (see `vitest.config.ts`) — vite never bundles them.
+ *
+ * Deferred on purpose (grow via `@astrale-os/kernel-client` if needed): no
+ * msgpack, no streaming/binary, no redirect following, no client-side minting,
+ * no writes. See `README.md`.
+ */
+export default defineConfig({
+  base: '/ui/',
+  plugins: [viteReact()],
+  build: {
+    outDir: '../dist-client',
+    emptyOutDir: true,
+    sourcemap: false,
+  },
+  // `pnpm dev:hmr` — set `VIEW_DEV_URL=http://127.0.0.1:5173` in the worker's
+  // `.dev.vars` to proxy `/ui/*` here and get React HMR.
+  server: {
+    host: '127.0.0.1',
+    port: 5173,
+    cors: true,
+  },
+})

package/template/client/vitest.config.ts

@@ -0,0 +1,18 @@
+import viteReact from '@vitejs/plugin-react'
+import { defineConfig } from 'vitest/config'
+
+/**
+ * Vitest config for the self-contained client. A DOM env (`happy-dom`) backs
+ * the React render + `window.postMessage`/`MessageChannel` used by the fake
+ * shell-parent harness. Kept separate from `vite.config.ts` (which sets the
+ * `/ui/` base + `../dist-client` build) so tests don't inherit the SPA build
+ * options.
+ */
+export default defineConfig({
+  plugins: [viteReact()],
+  test: {
+    environment: 'happy-dom',
+    globals: true,
+    include: ['__tests__/**/*.test.{ts,tsx}', 'src/**/*.test.{ts,tsx}'],
+  },
+})