@astrale-os/adapter-cloudflare 0.1.0

package/template/client/__tests__/app.test.tsx

@@ -0,0 +1,191 @@
+import { act, cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { App } from '../src/app'
+import { type CapturedRequest, installFakeKernel, installFakeParent, noteNode, ok } from './harness'
+
+const KERNEL_URL = 'https://k.example.test/api'
+const KERNEL_TYPE = 'application/vnd.astrale.kernel+json'
+
+afterEach(() => {
+  cleanup()
+})
+
+/**
+ * Let the handshake + any kernel fetch settle, flushing the resulting React
+ * state updates inside `act`. The handshake completes over a real MessagePort
+ * (async hops), so a microtask isn't enough — a short timer pump is. Wrapping
+ * it in `act` keeps the updates warning-free and committed before we assert.
+ */
+async function flush(ms = 20) {
+  await act(async () => {
+    await new Promise((r) => setTimeout(r, ms))
+  })
+}
+
+/** Common assertions on a captured kernel request for `@<id>::get`. */
+function expectGetCall(req: CapturedRequest, nodeId: string, token: string) {
+  // POST to the kernel URL with a trailing slash added.
+  expect(req.method).toBe('POST')
+  expect(req.url).toBe(`${KERNEL_URL}/`)
+  // Bare delegation token (no "Bearer ").
+  expect(req.headers['authorization']).toBe(token)
+  // Kernel JSON envelope content type on both content-type and accept.
+  expect(req.headers['content-type']).toBe(KERNEL_TYPE)
+  expect(req.headers['accept']).toBe(KERNEL_TYPE)
+  // Envelope body shape.
+  expect(req.body.method).toBe(`@${nodeId}::get`)
+  expect(req.body.params).toEqual({})
+  expect(req.body.id).toBeTruthy()
+}
+
+describe('ui-note view — handshake + real node render', () => {
+  it('completes the handshake, calls @<id>::get, and renders the Note', async () => {
+    const parent = installFakeParent({
+      windowId: 'win-1',
+      kernelUrl: KERNEL_URL,
+      functionId: 'ui-note',
+      delegationToken: 'tok-A',
+      tokenExpiresAt: Date.now() + 3_600_000,
+      targetNodeId: 'note-1',
+    })
+    const kernel = installFakeKernel(() =>
+      ok(noteNode({ id: 'note-1', name: 'My first note', body: 'Hello from the kernel.' })),
+    )
+
+    try {
+      render(<App />)
+      await flush()
+
+      // Parent observed the child's handshakeAck.
+      await expect(parent.ack).resolves.toBeUndefined()
+
+      // The Note renders its title (Named.name) and body.
+      expect(screen.getByText('My first note')).toBeTruthy()
+      expect(screen.getByText('Hello from the kernel.')).toBeTruthy()
+
+      // Exactly one kernel call, with the verified wire shape.
+      expect(kernel.calls).toHaveLength(1)
+      expectGetCall(kernel.calls[0]!, 'note-1', 'tok-A')
+    } finally {
+      kernel.restore()
+      parent.restore()
+    }
+  })
+
+  it('renders the kernel error envelope on the error path', async () => {
+    const parent = installFakeParent({
+      windowId: 'win-2',
+      kernelUrl: KERNEL_URL,
+      functionId: 'ui-note',
+      delegationToken: 'tok-A',
+      tokenExpiresAt: Date.now() + 3_600_000,
+      targetNodeId: 'missing-1',
+    })
+    const kernel = installFakeKernel(() => ({
+      error: { code: 3002, message: 'Path not found' },
+    }))
+
+    try {
+      render(<App />)
+      await flush()
+
+      expect(screen.getByText(/Failed to load the Note/)).toBeTruthy()
+      // The "<code>: <message>" surfaces from kernelCall.
+      expect(screen.getByText(/3002: Path not found/)).toBeTruthy()
+      expect(kernel.calls).toHaveLength(1)
+    } finally {
+      kernel.restore()
+      parent.restore()
+    }
+  })
+
+  it('re-fetches on a setTarget hot-swap', async () => {
+    const parent = installFakeParent({
+      windowId: 'win-3',
+      kernelUrl: KERNEL_URL,
+      functionId: 'ui-note',
+      delegationToken: 'tok-A',
+      tokenExpiresAt: Date.now() + 3_600_000,
+      targetNodeId: 'note-1',
+    })
+    const kernel = installFakeKernel((body) =>
+      // Respond per-target so the swap is observable.
+      body.method === '@note-2::get'
+        ? ok(noteNode({ id: 'note-2', name: 'Second note', body: 'Swapped in.' }))
+        : ok(noteNode({ id: 'note-1', name: 'First note', body: 'Original.' })),
+    )
+
+    try {
+      render(<App />)
+      await flush()
+      expect(screen.getByText('First note')).toBeTruthy()
+      expect(kernel.calls).toHaveLength(1)
+
+      // Parent pushes a new target node.
+      parent.setTarget('note-2')
+      await flush()
+
+      expect(screen.getByText('Second note')).toBeTruthy()
+      expect(screen.getByText('Swapped in.')).toBeTruthy()
+
+      // A second kernel call for the new node.
+      expect(kernel.calls).toHaveLength(2)
+      expectGetCall(kernel.calls[1]!, 'note-2', 'tok-A')
+    } finally {
+      kernel.restore()
+      parent.restore()
+    }
+  })
+
+  it('uses the refreshed token for calls after ctrl:tokenRefresh', async () => {
+    const parent = installFakeParent({
+      windowId: 'win-4',
+      kernelUrl: KERNEL_URL,
+      functionId: 'ui-note',
+      delegationToken: 'tok-A',
+      tokenExpiresAt: Date.now() + 1_000,
+      targetNodeId: 'note-1',
+    })
+    const kernel = installFakeKernel((body) =>
+      ok(noteNode({ id: body.method.slice(1, -5), name: 'Note', body: 'b' })),
+    )
+
+    try {
+      render(<App />)
+      await flush()
+      expect(kernel.calls).toHaveLength(1)
+      // First call used the handshake token.
+      expect(kernel.calls[0]!.headers['authorization']).toBe('tok-A')
+
+      // Parent pushes a fresh token, then triggers a new fetch via setTarget.
+      parent.tokenRefresh('tok-B', Date.now() + 3_600_000)
+      parent.setTarget('note-9')
+      await flush()
+
+      // The post-refresh call carries the NEW token.
+      expect(kernel.calls).toHaveLength(2)
+      expect(kernel.calls[1]!.body.method).toBe('@note-9::get')
+      expect(kernel.calls[1]!.headers['authorization']).toBe('tok-B')
+    } finally {
+      kernel.restore()
+      parent.restore()
+    }
+  })
+
+  it('falls back to a standalone preview with no parent', async () => {
+    // No fake parent installed → connectShell rejects fast because
+    // window.parent === window in this realm.
+    const kernel = installFakeKernel(() => ok(null))
+    try {
+      render(<App />)
+      await flush()
+
+      expect(screen.getByText(/No parent shell/)).toBeTruthy()
+      // Never hit the kernel in standalone mode.
+      expect(kernel.calls).toHaveLength(0)
+    } finally {
+      kernel.restore()
+    }
+  })
+})

package/template/client/__tests__/harness.ts

@@ -0,0 +1,221 @@
+/**
+ * Test harness — a FAKE shell parent + a FAKE kernel, so the client's inline
+ * handshake (`src/lib/shell.ts`) and JSON kernel client (`src/lib/kernel.ts`)
+ * can be exercised with no real GUI/kernel.
+ *
+ * The fake parent mirrors `runParentHandshake`
+ * (`shell/packages/shell/src/application/windowing/handshake.ts`):
+ *   - replies to `astrale-shell/init-request` with `init-response` + a
+ *     transferred `MessagePort` (`MessageChannel.port2`),
+ *   - posts `ctrl:handshake` over the port with the session data,
+ *   - resolves once it receives the child's `ctrl:handshakeAck`,
+ *   - then lets a test push `setTarget` intents and `ctrl:tokenRefresh`.
+ *
+ * The happy-dom env exposes Node's REAL `MessageChannel` (its own `MessagePort`
+ * is a no-op stub), so port delivery actually works. `MessageEvent` carries
+ * `source`/`ports` via its constructor, and `window.parent` is overridden so
+ * the child believes it is framed.
+ */
+
+const INIT_REQUEST_TYPE = 'astrale-shell/init-request'
+const INIT_RESPONSE_TYPE = 'astrale-shell/init-response'
+
+export type HandshakePayload = {
+  windowId: string
+  kernelUrl: string
+  functionId: string
+  delegationToken: string
+  tokenExpiresAt: number
+  targetNodeId?: string
+  mintIdentity?: string
+}
+
+export type FakeParent = {
+  /** Resolves once the child acks the handshake (mirrors runParentHandshake). */
+  readonly ack: Promise<void>
+  /** Hot-swap the target node via a `setTarget` intent. */
+  setTarget(nodeId: string): void
+  /** Push a fresh delegation token via `ctrl:tokenRefresh`. */
+  tokenRefresh(delegationToken: string, tokenExpiresAt: number): void
+  /** Restore `window.parent` and detach listeners. */
+  restore(): void
+}
+
+/**
+ * Install a fake shell parent. MUST be called BEFORE the child mounts (the
+ * child posts `init-request` to `window.parent` in a mount effect).
+ */
+export function installFakeParent(payload: HandshakePayload): FakeParent {
+  const originalParentDesc = Object.getOwnPropertyDescriptor(window, 'parent')
+
+  let port: MessagePort | null = null
+  let ackResolve!: () => void
+  const ack = new Promise<void>((r) => {
+    ackResolve = r
+  })
+
+  // The fake parent object — its `postMessage` receives the child's init-request.
+  const fakeParent = {
+    postMessage(message: unknown, _targetOrigin?: string) {
+      if (
+        message !== null &&
+        typeof message === 'object' &&
+        (message as { type?: unknown }).type === INIT_REQUEST_TYPE
+      ) {
+        onInitRequest()
+      }
+    },
+  }
+
+  function onInitRequest() {
+    const channel = new MessageChannel()
+    port = channel.port1
+
+    port.onmessage = (ev: MessageEvent) => {
+      const msg = ev.data as { type?: string; action?: string } | null
+      if (msg && msg.type === 'ctrl' && msg.action === 'handshakeAck') {
+        ackResolve()
+      }
+    }
+    port.start()
+
+    // Transfer port2 to the child via an init-response on `window`.
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: { type: INIT_RESPONSE_TYPE, version: 1, windowId: payload.windowId },
+        source: fakeParent as unknown as Window,
+        ports: [channel.port2],
+      }),
+    )
+
+    // Then the handshake control message carrying the session data.
+    port.postMessage({
+      type: 'ctrl',
+      version: 1,
+      action: 'handshake',
+      data: {
+        delegationToken: payload.delegationToken,
+        tokenExpiresAt: payload.tokenExpiresAt,
+        windowId: payload.windowId,
+        kernelUrl: payload.kernelUrl,
+        functionId: payload.functionId,
+        targetNodeId: payload.targetNodeId,
+        mintIdentity: payload.mintIdentity,
+      },
+    })
+  }
+
+  Object.defineProperty(window, 'parent', { value: fakeParent, configurable: true })
+
+  return {
+    ack,
+    setTarget(nodeId: string) {
+      port?.postMessage({
+        type: 'intent',
+        version: 1,
+        envelope: { name: 'setTarget', payload: { nodeId }, sender: { windowId: '<parent>' } },
+      })
+    },
+    tokenRefresh(delegationToken: string, tokenExpiresAt: number) {
+      port?.postMessage({
+        type: 'ctrl',
+        version: 1,
+        action: 'tokenRefresh',
+        data: { delegationToken, tokenExpiresAt },
+      })
+    },
+    restore() {
+      if (port) {
+        port.onmessage = null
+        port.close()
+      }
+      if (originalParentDesc) Object.defineProperty(window, 'parent', originalParentDesc)
+    },
+  }
+}
+
+// ─── Fake kernel (fetch stub) ────────────────────────────────────────────────
+
+export type CapturedRequest = {
+  url: string
+  method: string
+  headers: Record<string, string>
+  body: { method: string; params: unknown; id: unknown }
+}
+
+export type FakeKernel = {
+  /** Every request the client made, in order. */
+  readonly calls: CapturedRequest[]
+  /** Restore the global `fetch`. */
+  restore(): void
+}
+
+/**
+ * Replace global `fetch` with a stub that records each kernel request and
+ * returns whatever `respond` yields for it (a kernel envelope value, JSON-
+ * encoded). `respond` sees the parsed envelope body and the call index.
+ */
+export function installFakeKernel(
+  respond: (body: CapturedRequest['body'], index: number) => unknown,
+): FakeKernel {
+  const calls: CapturedRequest[] = []
+  const original = globalThis.fetch
+
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === 'string' ? input : input.toString()
+    const headers: Record<string, string> = {}
+    const h = init?.headers
+    if (h && typeof h === 'object' && !Array.isArray(h)) {
+      for (const [k, v] of Object.entries(h)) headers[k.toLowerCase()] = String(v)
+    }
+    const body = JSON.parse(String(init?.body ?? '{}')) as CapturedRequest['body']
+    const captured: CapturedRequest = {
+      url,
+      method: String(init?.method ?? 'GET'),
+      headers,
+      body,
+    }
+    calls.push(captured)
+    const envelope = respond(body, calls.length - 1)
+    return new Response(JSON.stringify(envelope), {
+      status: 200,
+      headers: { 'content-type': 'application/vnd.astrale.kernel+json' },
+    })
+  }) as typeof fetch
+
+  return {
+    calls,
+    restore() {
+      globalThis.fetch = original
+    },
+  }
+}
+
+/** Wrap a value as a success envelope `{ result }` (what the kernel returns). */
+export function ok(result: unknown): { result: unknown } {
+  return { result }
+}
+
+/** Build a minimal kernel Note node whose props carry title/body. */
+export function noteNode(opts: {
+  id: string
+  path?: string
+  name?: string
+  title?: string
+  body?: string
+  domain?: string
+}): { id: string; path: string; class: { raw: string }; props: Record<string, unknown> } {
+  const domain = opts.domain ?? 'notes.astrale.ai'
+  const props: Record<string, unknown> = {}
+  if (opts.name !== undefined) {
+    props['kernel.astrale.ai:interface.Named.property.name'] = opts.name
+  }
+  if (opts.title !== undefined) props[`${domain}:class.Note.property.title`] = opts.title
+  if (opts.body !== undefined) props[`${domain}:class.Note.property.body`] = opts.body
+  return {
+    id: opts.id,
+    path: opts.path ?? `/notes/${opts.id}`,
+    class: { raw: `/:${domain}:class.Note` },
+    props,
+  }
+}

package/template/client/__tests__/kernel.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { kernelCall, readProp, readPropBySuffix } from '../src/lib/kernel'
+import { installFakeKernel } from './harness'
+
+const TYPE = 'application/vnd.astrale.kernel+json'
+
+describe('kernelCall — inline JSON envelope client', () => {
+  let restore: (() => void) | undefined
+  afterEach(() => {
+    restore?.()
+    restore = undefined
+  })
+
+  it('POSTs the envelope with a trailing slash, bare token, and kernel content type', async () => {
+    const k = installFakeKernel(() => ({ result: { ok: true } }))
+    restore = k.restore
+    const result = await kernelCall('https://k.test/api', 'tok-X', '@n1::get', {})
+    expect(result).toEqual({ ok: true })
+
+    const req = k.calls[0]!
+    expect(req.method).toBe('POST')
+    expect(req.url).toBe('https://k.test/api/') // slash added
+    expect(req.headers['authorization']).toBe('tok-X')
+    expect(req.headers['content-type']).toBe(TYPE)
+    expect(req.headers['accept']).toBe(TYPE)
+    expect(req.body).toMatchObject({ method: '@n1::get', params: {} })
+    expect(req.body.id).toBeTruthy()
+  })
+
+  it('does not double the trailing slash when the URL already ends in one', async () => {
+    const k = installFakeKernel(() => ({ result: 1 }))
+    restore = k.restore
+    await kernelCall('https://k.test/api/', 'tok', '@n::get')
+    expect(k.calls[0]!.url).toBe('https://k.test/api/')
+  })
+
+  it('throws "<code>: <message>" on a kernel error envelope', async () => {
+    const k = installFakeKernel(() => ({ error: { code: 2004, message: 'Permission denied' } }))
+    restore = k.restore
+    await expect(kernelCall('https://k.test/api', 't', '@n::get')).rejects.toThrow(
+      '2004: Permission denied',
+    )
+  })
+
+  it('throws on an unexpected redirect envelope', async () => {
+    const k = installFakeKernel(() => ({ redirect: { url: 'https://other.test/api' } }))
+    restore = k.restore
+    await expect(kernelCall('https://k.test/api', 't', '@n::get')).rejects.toThrow(/redirect/)
+  })
+})
+
+describe('prop readers', () => {
+  it('readProp returns the string value at the exact key', () => {
+    expect(readProp({ a: 'x', b: 1 }, 'a')).toBe('x')
+    expect(readProp({ a: 'x' }, 'missing')).toBeUndefined()
+    expect(readProp({ a: 1 }, 'a')).toBeUndefined() // non-string
+  })
+
+  it('readPropBySuffix matches the first key ending with the suffix', () => {
+    const props = {
+      'notes.astrale.ai:class.Note.property.body': 'the body',
+      'kernel.astrale.ai:interface.Named.property.name': 'n',
+    }
+    expect(readPropBySuffix(props, '.property.body')).toBe('the body')
+    expect(readPropBySuffix(props, '.property.title')).toBeUndefined()
+  })
+})

package/template/client/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>astrale-domain · ui-note</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/client/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "astrale-domain-client",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "dev:hmr": "vite",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^5.0.4",
+    "happy-dom": "^20.0.0",
+    "vite": "^7.1.7",
+    "vitest": "^3.2.4"
+  }
+}

package/template/client/src/app.tsx

@@ -0,0 +1,94 @@
+import type { NodeSession } from './lib/use-node'
+
+import { classShortName, type KernelNode, PROP, readProp, readPropBySuffix } from './lib/kernel'
+import { useNode } from './lib/use-node'
+import { useShell } from './lib/use-shell'
+
+/**
+ * The `ui-note` view. Mounted by the Astrale shell as a sandboxed iframe; the
+ * parent completes the handshake (see `lib/shell.ts`) and pushes the target
+ * node id this view renders. The view then loads that Note from the kernel via
+ * a minimal inline JSON client (`lib/kernel.ts`, `@<id>::get`) and renders its
+ * title/body — no `@astrale-os/*` deps.
+ */
+export function App() {
+  const { status, session, nodeId, reason } = useShell()
+
+  return (
+    <div className="wrap">
+      <div className="card">
+        {status === 'loading' && (
+          <>
+            <h1 className="title">Note</h1>
+            <p className="subline">ui-note · Astrale view SPA</p>
+            <p className="muted">Waiting for the shell handshake…</p>
+          </>
+        )}
+
+        {status === 'standalone' && (
+          <>
+            <h1 className="title">Note</h1>
+            <p className="subline">ui-note · Astrale view SPA</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 token. Showing a standalone preview.
+            </div>
+            <p className="body muted">
+              When mounted by the shell, this card renders the Note you opened.
+            </p>
+          </>
+        )}
+
+        {status === 'ready' && session && <NoteCard session={session} nodeId={nodeId} />}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Renders one Note, loaded from the kernel via the live session. Split out so
+ * `useNode` is called unconditionally (the parent only mounts this once the
+ * handshake is `ready`, so `session` is non-null here).
+ */
+function NoteCard({ session, nodeId }: { session: NodeSession; nodeId: string | undefined }) {
+  const state = useNode(session, nodeId)
+
+  const title =
+    state.status === 'ok' ? (readProp(state.node.props, PROP.named.name) ?? 'Note') : 'Note'
+
+  return (
+    <>
+      <h1 className="title">{title}</h1>
+      <p className="subline">
+        {state.status === 'ok'
+          ? `${classShortName(state.node)} · ${state.node.path}`
+          : 'ui-note · Astrale view SPA'}
+      </p>
+
+      {state.status === 'idle' && (
+        <p className="body muted">Handshake complete, but no target node / token yet.</p>
+      )}
+
+      {state.status === 'loading' && <p className="muted">Loading the Note…</p>}
+
+      {state.status === 'error' && (
+        <div className="banner">Failed to load the Note: {state.message}</div>
+      )}
+
+      {state.status === 'ok' && <NoteBody node={state.node} />}
+    </>
+  )
+}
+
+/**
+ * The Note's `body` prop. Its key is domain-qualified
+ * (`<domain>:class.Note.property.body`), so read it by suffix rather than a
+ * build-time-unknown full key.
+ */
+function NoteBody({ node }: { node: KernelNode }) {
+  const body = readPropBySuffix(node.props, '.property.body')
+  if (!body) {
+    return <p className="body muted">This Note has no body.</p>
+  }
+  return <p className="body">{body}</p>
+}