@astrale-os/adapter-cloudflare 0.1.8 → 0.1.10

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))
+}

package/template/client/src/monitor/hooks/useMonitor.query.ts

@@ -0,0 +1,64 @@
+/** Load a Monitor node → typed record, with a `reload()` for post-check refresh. */
+import { useCallback, useRef, useState } from 'react'
+
+import { type KernelClient, useNode } from '@/shell'
+
+import type { MonitorRecord } from '../monitor.types'
+
+import { monitorFromNode } from '../monitor.mappers'
+
+export type MonitorQuery = {
+  /** Lifecycle of the underlying `@<id>::get`. */
+  state: 'idle' | 'loading' | 'error' | 'ok'
+  /** The projected record once `ok`. */
+  record?: MonitorRecord
+  /** 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 Monitor node `nodeId` and project it to a `MonitorRecord`. 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 useMonitor(session: KernelClient, nodeId: string): MonitorQuery {
+  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: monitorFromNode(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/monitor/index.ts

@@ -0,0 +1,6 @@
+/** The Monitor feature — its api, types, mappers, hooks and components. */
+export * from './components'
+export * from './hooks'
+export { check } from './monitor.api'
+export { monitorFromNode, normalizeStatus } from './monitor.mappers'
+export type { MonitorRecord } from './monitor.types'

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

@@ -0,0 +1,11 @@
+/** Raw kernel calls for the Monitor feature — node instance methods. */
+import { invokeNode, type KernelClient } from '@/shell'
+
+/**
+ * Run the Monitor's `check` instance method (`@<id>::check`). Probes the target
+ * URL server-side and updates the node's `status`/`statusCode`/`latencyMs`/
+ * `lastCheckedAt` props; the caller reloads the node to render the fresh values.
+ */
+export function check(session: KernelClient, nodeId: string): Promise<unknown> {
+  return invokeNode(session, nodeId, 'check', {})
+}

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

@@ -0,0 +1,38 @@
+/** Node → typed record transforms for the Monitor feature. */
+import { type KernelNode, PROP, readProp, readPropBySuffix } from '@/shell'
+
+import type { MonitorRecord, MonitorStatus } from './monitor.types'
+
+const lastSegment = (path: string): string => path.split('/').filter(Boolean).pop() ?? path
+
+/** Coerce a string prop to a finite number, or `undefined`. */
+function readNumberBySuffix(props: Record<string, unknown>, suffix: string): number | undefined {
+  const raw = readPropBySuffix(props, suffix)
+  if (raw === undefined) return undefined
+  const n = Number(raw)
+  return Number.isFinite(n) ? n : undefined
+}
+
+/** Normalize the node's `status` prop to the three known states. */
+export function normalizeStatus(raw: string | undefined): MonitorStatus {
+  return raw === 'up' || raw === 'down' ? raw : 'unknown'
+}
+
+/**
+ * Project a Monitor `KernelNode` into a `MonitorRecord`. The name comes from the
+ * kernel `Named.name` key; the domain props (`url`/`status`/`statusCode`/
+ * `latencyMs`/`lastCheckedAt`) are domain-qualified, so read them by suffix.
+ */
+export function monitorFromNode(node: KernelNode): MonitorRecord {
+  const p = node.props ?? {}
+  return {
+    id: node.id,
+    path: node.path ?? '',
+    name: readProp(p, PROP.named.name) ?? lastSegment(node.path ?? '') ?? node.id,
+    url: readPropBySuffix(p, '.property.url') ?? '',
+    status: normalizeStatus(readPropBySuffix(p, '.property.status')),
+    statusCode: readNumberBySuffix(p, '.property.statusCode'),
+    latencyMs: readNumberBySuffix(p, '.property.latencyMs'),
+    lastCheckedAt: readPropBySuffix(p, '.property.lastCheckedAt'),
+  }
+}

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

@@ -0,0 +1,23 @@
+/** The Monitor feature's client types. */
+
+/** The three known states of a Monitor's normalized status. */
+export type MonitorStatus = 'up' | 'down' | 'unknown'
+
+/**
+ * Client-side projection of a Monitor node. Domain props are read off the
+ * kernel node by suffix (see `monitor.mappers.ts`); numeric props are coerced.
+ */
+export type MonitorRecord = {
+  id: string
+  path: string
+  name: string
+  url: string
+  /** up | down | unknown — normalized from the node's `status` prop. */
+  status: MonitorStatus
+  /** HTTP status code from the last check, if any. */
+  statusCode?: number
+  /** Round-trip latency of the last check, in milliseconds. */
+  latencyMs?: number
+  /** ISO timestamp of the last check, if any. */
+  lastCheckedAt?: string
+}

package/template/client/src/monitor/ui/MonitorDetails.UI.tsx

@@ -0,0 +1,38 @@
+/**
+ * MonitorDetails — the Monitor record's PRESENTATION, extracted pure. Given a
+ * projected `MonitorRecord`, it lays out the StatusBadge + the url/latency/
+ * statusCode/last-checked KV rows using the feature-agnostic `@/ui` primitives.
+ *
+ * Pure: no hooks, no kernel, no data loading — props in, DOM out. The container
+ * (`MonitorCard`) owns loading the record and wiring the "Check now" write.
+ */
+import { ExternalLink, KV, Mono, relativeTime } from '@/ui'
+
+import type { MonitorRecord } from '../monitor.types'
+
+import { StatusBadge } from './StatusBadge.UI'
+
+export function MonitorDetails({ record }: { record: MonitorRecord }) {
+  return (
+    <>
+      <div className="status-row">
+        <StatusBadge status={record.status} />
+      </div>
+
+      <div className="kv">
+        <KV label="url">
+          <ExternalLink url={record.url || undefined} />
+        </KV>
+        <KV label="latency">
+          <Mono value={record.latencyMs !== undefined ? `${record.latencyMs}ms` : undefined} />
+        </KV>
+        <KV label="status code">
+          <Mono value={record.statusCode !== undefined ? String(record.statusCode) : undefined} />
+        </KV>
+        <KV label="last checked">
+          <Mono value={relativeTime(record.lastCheckedAt)} title={record.lastCheckedAt} />
+        </KV>
+      </div>
+    </>
+  )
+}

package/template/client/src/monitor/ui/StatusBadge.UI.tsx

@@ -0,0 +1,14 @@
+/** Monitor status chip — pure presentational; styling lives in `styles.css`. */
+
+import type { MonitorStatus } from '../monitor.types'
+
+/**
+ * Color-coded status pill: up = green, down = red, unknown = muted. The label is
+ * the uppercased status (`UP` / `DOWN` / `UNKNOWN`). Monitor-specific — it knows
+ * the feature's up/down/unknown vocabulary — so it lives in `monitor/ui`, not the
+ * feature-agnostic `@/ui` design system.
+ */
+export function StatusBadge({ status }: { status: MonitorStatus }) {
+  const label = status === 'up' ? 'UP' : status === 'down' ? 'DOWN' : 'UNKNOWN'
+  return <span className={`status-badge status-${status}`}>{label}</span>
+}

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

@@ -0,0 +1,8 @@
+/**
+ * The Monitor feature's OWN presentation — monitor-specific, feature-aware UI
+ * (it knows the up/down/unknown status vocabulary and the record shape). Pure
+ * components, built on the feature-agnostic `@/ui` primitives. Import within the
+ * feature: `import { StatusBadge, MonitorDetails } from '../ui'`.
+ */
+export { StatusBadge } from './StatusBadge.UI'
+export { MonitorDetails } from './MonitorDetails.UI'

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

@@ -0,0 +1,67 @@
+/**
+ * Graph/prop helpers for the nodes the kernel returns — reading fully-qualified
+ * props and short class names off a `KernelNode`. Pure shaping: the kernel
+ * TRANSPORT now lives in `@astrale-os/shell` (`shell.kernel` → `session.call`),
+ * so this file no longer speaks the wire.
+ */
+
+/**
+ * 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 (`url`, `status`) 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.url')`.
+ */
+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
+}
+
+/**
+ * Operator-facing message for a failed kernel call. Errors from the shell's
+ * kernel client carry a numeric `code` (e.g. `NotFoundError` → `code 3002`) with
+ * the raw server text in `message`; surface them as `<code>: <message>` so the
+ * code stays visible. Plain errors fall back to their message.
+ */
+export function errorMessage(err: unknown): string {
+  if (err instanceof Error) {
+    const code = (err as { code?: unknown }).code
+    return typeof code === 'number' ? `${code}: ${err.message}` : err.message
+  }
+  return String(err)
+}

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

@@ -0,0 +1,20 @@
+/**
+ * The kernel boundary — everything for talking to the kernel and the GUI
+ * shell, plus the common read/write primitives features build their
+ * `.query`/`.mutation` hooks on. Import from the barrel: `@/shell`.
+ */
+export { classShortName, errorMessage, PROP, readProp, readPropBySuffix } from './client'
+export type { KernelNode } from './client'
+export { callMethod, invokeNode, nodeAddr } from './invoke'
+export type { KernelClient } from '@astrale-os/shell'
+export { useNode } from './use-node'
+export type { NodeState } from './use-node'
+export { useShell } from './use-shell'
+export type { ShellState, ShellStatus } from './use-shell'
+export { useAsync } from './use-async'
+export type { AsyncResource, AsyncState } from './use-async'
+export { useCapability } from './use-capability'
+export type { Capability, Phase } from './use-capability'
+export { asNodeArray, linkTargets, qualifiedProp, qualifiedString } from './transformers'
+export { resolveView, ViewFrame } from './view-router'
+export type { ViewComponent, ViewRoutes } from './view-router'