@astrale-os/adapter-cloudflare 0.1.9 → 0.1.10

package/template/client/__tests__/harness.ts

@@ -1,7 +1,11 @@
 /**
- * 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.
+ * Test harness — a FAKE shell parent + a FAKE kernel, so the client's shell
+ * handshake (now `@astrale-os/shell`, `createShell({ mode: 'sandboxed' })`) and
+ * its kernel calls can be exercised with no real GUI/kernel.
+ *
+ * `fakeKernelSession()` is the unit-test counterpart: a `KernelClient` whose
+ * `call` hits the fake kernel directly (no handshake), for hooks tested in
+ * isolation.
  *
  * The fake parent mirrors `runParentHandshake`
  * (`shell/packages/shell/src/application/windowing/handshake.ts`):
@@ -17,6 +21,8 @@
  * the child believes it is framed.
  */
 
+import type { KernelClient } from '@/shell'
+
 const INIT_REQUEST_TYPE = 'astrale-shell/init-request'
 const INIT_RESPONSE_TYPE = 'astrale-shell/init-response'
 
@@ -196,26 +202,75 @@ export function ok(result: unknown): { result: unknown } {
   return { result }
 }
 
-/** Build a minimal kernel Note node whose props carry title/body. */
-export function noteNode(opts: {
+/**
+ * A `KernelClient` for unit tests that exercise feature hooks WITHOUT a
+ * handshake. Its `call` POSTs the kernel JSON envelope (`{ method, params, id }`)
+ * so the `installFakeKernel` fetch stub records it and `body.method`/
+ * `body.params` assertions hold — same wire the real `shell.kernel` speaks to a
+ * JSON kernel. The credential surface (`mintDelegation`/`authToken`/`url`) is
+ * stubbed minimally — the isolated hooks under test only ever touch `call`.
+ */
+export function fakeKernelSession(kernelUrl = 'https://k.example.test/api'): KernelClient {
+  let idSeq = 0
+  return {
+    async call(method: string, params: unknown = {}): Promise<unknown> {
+      idSeq += 1
+      const res = await fetch(kernelUrl, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/vnd.astrale.kernel+json',
+          accept: 'application/vnd.astrale.kernel+json',
+          authorization: 'tok-A',
+        },
+        body: JSON.stringify({ method, params, id: `c${idSeq}` }),
+      })
+      const obj = (await res.json()) as Record<string, unknown>
+      if (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}`)
+      }
+      return obj.result
+    },
+    mintDelegation: async () => '<fake>',
+    authToken: () => '<fake>',
+    url: kernelUrl,
+  }
+}
+
+/**
+ * Build a minimal kernel Monitor node whose props carry url/status/statusCode/
+ * latencyMs/lastCheckedAt, with the same domain-qualified key format the kernel
+ * uses (`<domain>:class.Monitor.property.<name>`). The name uses the kernel
+ * `Named.name` key.
+ */
+export function monitorNode(opts: {
   id: string
   path?: string
   name?: string
-  title?: string
-  body?: string
+  url?: string
+  status?: string
+  statusCode?: string
+  latencyMs?: string
+  lastCheckedAt?: string
   domain?: string
 }): { id: string; path: string; class: { raw: string }; props: Record<string, unknown> } {
-  const domain = opts.domain ?? 'notes.astrale.ai'
+  const domain = opts.domain ?? 'monitors.astrale.ai'
+  const base = `${domain}:class.Monitor.property`
   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
+  if (opts.url !== undefined) props[`${base}.url`] = opts.url
+  if (opts.status !== undefined) props[`${base}.status`] = opts.status
+  if (opts.statusCode !== undefined) props[`${base}.statusCode`] = opts.statusCode
+  if (opts.latencyMs !== undefined) props[`${base}.latencyMs`] = opts.latencyMs
+  if (opts.lastCheckedAt !== undefined) props[`${base}.lastCheckedAt`] = opts.lastCheckedAt
   return {
     id: opts.id,
-    path: opts.path ?? `/notes/${opts.id}`,
-    class: { raw: `/:${domain}:class.Note` },
+    path: opts.path ?? `/monitors/${opts.id}`,
+    class: { raw: `/:${domain}:class.Monitor` },
     props,
   }
 }

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

@@ -1,68 +1,83 @@
-import { afterEach, describe, expect, it } from 'vitest'
+import { describe, expect, it } from 'vitest'
 
-import { kernelCall, readProp, readPropBySuffix } from '../src/lib/kernel'
-import { installFakeKernel } from './harness'
+import { qualifiedString, readProp, readPropBySuffix } from '@/shell'
+import { monitorFromNode, normalizeStatus } from '@/monitor'
+import { relativeTime } from '@/ui'
+import { monitorNode } from './harness'
 
-const TYPE = 'application/vnd.astrale.kernel+json'
-
-describe('kernelCall — inline JSON envelope client', () => {
-  let restore: (() => void) | undefined
-  afterEach(() => {
-    restore?.()
-    restore = undefined
+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('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('readPropBySuffix matches the first key ending with the suffix', () => {
+    const props = {
+      'monitors.astrale.ai:class.Monitor.property.url': 'https://x.test',
+      'kernel.astrale.ai:interface.Named.property.name': 'n',
+    }
+    expect(readPropBySuffix(props, '.property.url')).toBe('https://x.test')
+    expect(readPropBySuffix(props, '.property.status')).toBeUndefined()
   })
 
-  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('qualifiedString prefers a domain key over the kernel one for the same suffix', () => {
+    const props = {
+      'kernel.astrale.ai:interface.Named.property.name': 'kernel name',
+      'monitors.astrale.ai:class.Monitor.property.name': 'domain name',
+    }
+    expect(qualifiedString(props, 'name')).toBe('domain name')
   })
+})
 
-  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',
+describe('monitorFromNode mapper', () => {
+  it('projects name, url, normalized status and coerced numbers', () => {
+    const record = monitorFromNode(
+      monitorNode({
+        id: 'mon-1',
+        name: 'API health',
+        url: 'https://api.test/health',
+        status: 'up',
+        statusCode: '200',
+        latencyMs: '42',
+        lastCheckedAt: '2026-06-14T10:00:00Z',
+      }),
     )
+    expect(record).toMatchObject({
+      id: 'mon-1',
+      name: 'API health',
+      url: 'https://api.test/health',
+      status: 'up',
+      statusCode: 200,
+      latencyMs: 42,
+      lastCheckedAt: '2026-06-14T10:00:00Z',
+    })
   })
 
-  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/)
+  it('falls back to the path segment for the name and unknown for a missing status', () => {
+    const record = monitorFromNode(monitorNode({ id: 'mon-9', path: '/monitors/edge' }))
+    expect(record.name).toBe('edge')
+    expect(record.status).toBe('unknown')
+    expect(record.url).toBe('')
+    expect(record.statusCode).toBeUndefined()
   })
 })
 
-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
+describe('normalizeStatus', () => {
+  it('passes through up/down and maps everything else to unknown', () => {
+    expect(normalizeStatus('up')).toBe('up')
+    expect(normalizeStatus('down')).toBe('down')
+    expect(normalizeStatus('weird')).toBe('unknown')
+    expect(normalizeStatus(undefined)).toBe('unknown')
   })
+})
 
-  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()
+describe('relativeTime', () => {
+  const now = Date.parse('2026-06-14T12:00:00Z')
+  it('renders coarse buckets and a dash for missing input', () => {
+    expect(relativeTime(undefined, now)).toBe('—')
+    expect(relativeTime('2026-06-14T11:55:00Z', now)).toBe('5m ago')
+    expect(relativeTime('2026-06-14T10:00:00Z', now)).toBe('2h ago')
+    expect(relativeTime('not-a-date', now)).toBe('not-a-date')
   })
 })

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

@@ -0,0 +1,111 @@
+/**
+ * What the presentation/logic seam unlocks:
+ *
+ *  1. PRESENTATION components (`@/ui` and a feature's own `monitor/ui`) test with
+ *     ZERO infrastructure — no fake shell, no fake kernel, no session. Just props
+ *     in, DOM out. (Contrast app.test.tsx, which stands up a handshake + kernel
+ *     stub to reach the same markup.)
+ *  2. FEATURE hooks (`@/monitor`) test against a bare `KernelClient` (the fake
+ *     kernel fetch stub) with no handshake — the write lifecycle and the
+ *     reload signal are verified once, in isolation.
+ */
+import { act, cleanup, render, renderHook, screen, waitFor } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { useCheck, useMonitor } from '@/monitor'
+import { StatusBadge } from '@/monitor/ui'
+import { fakeKernelSession, installFakeKernel, monitorNode, ok } from './harness'
+
+afterEach(cleanup)
+
+describe('presentation is pure (no kernel, no session, no shell)', () => {
+  it('StatusBadge renders the label and tone class for each status', () => {
+    const { rerender } = render(<StatusBadge status="up" />)
+    expect(screen.getByText('UP').className).toContain('status-up')
+
+    rerender(<StatusBadge status="down" />)
+    expect(screen.getByText('DOWN').className).toContain('status-down')
+
+    rerender(<StatusBadge status="unknown" />)
+    expect(screen.getByText('UNKNOWN').className).toContain('status-unknown')
+  })
+})
+
+describe('useMonitor — query + reload signal', () => {
+  it('loads the record, then exposes reloading across a reload()', async () => {
+    const session = fakeKernelSession()
+    let status = 'down'
+    const kernel = installFakeKernel(() =>
+      ok(monitorNode({ id: 'mon-1', name: 'API', url: 'https://x.test', status })),
+    )
+
+    try {
+      const { result } = renderHook(() => useMonitor(session, 'mon-1'))
+      await waitFor(() => expect(result.current.state).toBe('ok'))
+      expect(result.current.record?.status).toBe('down')
+      expect(result.current.reloading).toBe(false)
+
+      // Server-side status flips; a reload picks it up and flags `reloading`.
+      status = 'up'
+      act(() => {
+        result.current.reload()
+      })
+      expect(result.current.reloading).toBe(true)
+
+      await waitFor(() => expect(result.current.reloading).toBe(false))
+      expect(result.current.record?.status).toBe('up')
+    } finally {
+      kernel.restore()
+    }
+  })
+
+  it('surfaces a node-load error', async () => {
+    const session = fakeKernelSession()
+    const kernel = installFakeKernel(() => ({ error: { code: 3002, message: 'Path not found' } }))
+    try {
+      const { result } = renderHook(() => useMonitor(session, 'missing'))
+      await waitFor(() => expect(result.current.state).toBe('error'))
+      expect(result.current.message).toMatch(/Path not found/)
+    } finally {
+      kernel.restore()
+    }
+  })
+})
+
+describe('useCheck — the shared write-lifecycle', () => {
+  it('idle → running → done, then resolves true', async () => {
+    const session = fakeKernelSession()
+    const kernel = installFakeKernel(() => ok(null))
+    try {
+      const { result } = renderHook(() => useCheck(session, 'mon-1'))
+      expect(result.current.phase).toBe('idle')
+
+      let returned: boolean | undefined
+      await act(async () => {
+        returned = await result.current.run()
+      })
+      expect(returned).toBe(true)
+      expect(result.current.phase).toBe('done')
+      expect(result.current.error).toBeNull()
+    } finally {
+      kernel.restore()
+    }
+  })
+
+  it('captures a failure: phase failed, error set, resolves false', async () => {
+    const session = fakeKernelSession()
+    const kernel = installFakeKernel(() => ({ error: { code: 2004, message: 'Permission denied' } }))
+    try {
+      const { result } = renderHook(() => useCheck(session, 'mon-1'))
+      let returned: boolean | undefined
+      await act(async () => {
+        returned = await result.current.run()
+      })
+      expect(returned).toBe(false)
+      expect(result.current.phase).toBe('failed')
+      expect(result.current.error).toMatch(/Permission denied/)
+    } finally {
+      kernel.restore()
+    }
+  })
+})

package/template/client/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>astrale-domain · ui-note</title>
+    <title>astrale-domain · view</title>
   </head>
   <body>
     <div id="root"></div>

package/template/client/package.json

@@ -11,6 +11,7 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@astrale-os/shell": ">=0.1.0 <1.0.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0"
   },

package/template/client/src/app.tsx

@@ -1,94 +1,51 @@
-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.
+ * Multi-view router for the domain's one SPA bundle.
+ *
+ * The domain declares its SPA Views, each served from THIS one bundle under
+ * `/ui/*` and mounted by the shell as its own iframe at its own mount path:
+ *   - `/ui/monitor` → the Monitor detail panel (`views/monitor.tsx`)
+ *
+ * Because the shell mounts one iframe per view at its mount path, inside the
+ * iframe `window.location.pathname` is that path. `App` reads it (via
+ * `resolveView`) and renders the matching view; an unregistered path shows a
+ * self-describing fallback.
+ *
+ * To add a view:
+ *   1. write a `ViewComponent` (usually wrapping `ViewFrame` — see `views/`),
+ *   2. add a `ROUTES` entry below keyed by its mount path,
+ *   3. register a matching `defineView({ mount: '/ui/<path>' })` in the domain's
+ *      `views/` so the shell mounts an iframe there.
  */
-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>
-          </>
-        )}
+import { resolveView, useShell, type ViewRoutes } from '@/shell'
+import { MonitorView } from '@/views/monitor'
 
-        {status === 'ready' && session && <NoteCard session={session} nodeId={nodeId} />}
-      </div>
-    </div>
-  )
+const ROUTES: ViewRoutes = {
+  '/ui/monitor': MonitorView,
 }
 
-/**
- * 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>}
+export function App() {
+  const shell = useShell()
+  const View = resolveView(ROUTES)
 
-      {state.status === 'error' && (
-        <div className="banner">Failed to load the Note: {state.message}</div>
-      )}
+  if (!View) return <UnknownView />
 
-      {state.status === 'ok' && <NoteBody node={state.node} />}
-    </>
-  )
+  return <>{View(shell)}</>
 }
 
-/**
- * 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>
+/** Fallback when the iframe's mount path has no registered view. */
+function UnknownView() {
+  return (
+    <div className="wrap">
+      <div className="card">
+        <h1 className="title">No view here</h1>
+        <p className="subline">Astrale view SPA</p>
+        <div className="banner">
+          No view registered for {window.location.pathname}. Add a ROUTES entry in{' '}
+          <code>src/app.tsx</code> (and a matching <code>defineView({'{ mount }'})</code> in the
+          domain's <code>views/</code>).
+        </div>
+      </div>
+    </div>
+  )
 }

package/template/client/src/main.tsx

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

package/template/client/src/monitor/components/MonitorCard.tsx

@@ -0,0 +1,50 @@
+/**
+ * MonitorCard — the Monitor feature's one container. It owns the data/logic:
+ * loads the node (`useMonitor`), wires the `check` write (`useCheck`), and
+ * composes the presentation. Handles the query's loading/error/ok states; on
+ * `ok` it renders a `Panel` whose body is the check-error banner (if any) plus
+ * the pure `MonitorDetails` view, with a "Check now" button that runs the probe
+ * then reloads the node so the fresh values render.
+ *
+ * Thin by design: the record's layout lives in `monitor/ui` (`MonitorDetails`);
+ * the generic surfaces come from the `@/ui` design system.
+ */
+import type { KernelClient } from '@/shell'
+
+import { ErrorBanner, Panel, Spinner } from '@/ui'
+
+import { useCheck, useMonitor } from '../hooks'
+import { MonitorDetails } from '../ui'
+
+export function MonitorCard({ session, nodeId }: { session: KernelClient; nodeId: string }) {
+  const monitor = useMonitor(session, nodeId)
+  const probe = useCheck(session, nodeId)
+
+  async function checkNow() {
+    if (await probe.run()) monitor.reload()
+  }
+
+  if (monitor.state === 'idle' || monitor.state === 'loading') {
+    return <Spinner label="Loading the Monitor…" />
+  }
+  if (monitor.state === 'error') {
+    return <ErrorBanner>Failed to load the Monitor: {monitor.message}</ErrorBanner>
+  }
+
+  const record = monitor.record!
+  const checking = probe.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}>
+      {probe.phase === 'failed' && probe.error && (
+        <ErrorBanner>Check failed: {probe.error}</ErrorBanner>
+      )}
+      <MonitorDetails record={record} />
+    </Panel>
+  )
+}

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

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

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

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

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

@@ -0,0 +1,16 @@
+/** Run a Monitor's `check` probe — the feature's one write capability. */
+import { type Capability, type KernelClient, useCapability } from '@/shell'
+
+import { check } from '../monitor.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))
+}