@astrale-os/adapter-cloudflare 0.1.9 → 0.1.10

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

@@ -0,0 +1,91 @@
+import {
+  createShell,
+  type IntentMessage,
+  type IntentRegistry,
+  type KernelClient,
+  type Shell,
+} from '@astrale-os/shell'
+import { useEffect, useMemo, useState } from 'react'
+
+export type ShellStatus = 'loading' | 'ready' | 'standalone'
+
+export type ShellState = {
+  status: ShellStatus
+  /** The kernel handle once `ready` — view hooks call through `session.call`. */
+  session: KernelClient | null
+  /** Current target node id — updates on `setTarget` hot-swaps. */
+  nodeId: string | undefined
+  /** Why we fell back to `standalone` (no parent / handshake timeout). */
+  reason: string | null
+}
+
+/**
+ * Boots the real Astrale shell in sandboxed (child) mode: runs the init
+ * handshake with the parent window to obtain the kernel session + target node,
+ * then tracks `setTarget` hot-swaps. The shell's `KernelClient` owns the
+ * delegation token (refreshed by the parent) and the kernel transport, so view
+ * hooks just call `session.call('@<id>::<method>')`.
+ *
+ * Three outcomes:
+ *   - `loading`    — handshake in flight
+ *   - `ready`      — parent completed the handshake; `session`/`nodeId` populated
+ *   - `standalone` — no parent or it timed out (opened directly in a tab); the
+ *                    view renders a self-describing fallback
+ */
+export function useShell(): ShellState {
+  const [status, setStatus] = useState<ShellStatus>('loading')
+  const [session, setSession] = useState<KernelClient | null>(null)
+  const [nodeId, setNodeId] = useState<string | undefined>(undefined)
+  const [reason, setReason] = useState<string | null>(null)
+
+  useEffect(() => {
+    // Not framed (opened directly in a tab): skip the handshake entirely rather
+    // than waiting out the init timeout — there is no parent to answer it.
+    if (!window.parent || window.parent === window) {
+      setReason('not running inside a parent frame')
+      setStatus('standalone')
+      return
+    }
+
+    let cancelled = false
+    let shell: Shell | null = null
+
+    void (async () => {
+      try {
+        const built = createShell({ mode: 'sandboxed', initTimeoutMs: 5000 })
+        await built.init()
+        if (cancelled) {
+          void built.dispose()
+          return
+        }
+        shell = built
+
+        // Hand views the shell's real `KernelClient` directly. It reads the live
+        // (parent-refreshed) token on each call and owns the transport, so view
+        // hooks just call `session.call('@<id>::<method>', params)`.
+        setSession(built.kernel)
+        setNodeId(built.targetNodeId)
+        setStatus('ready')
+
+        // Hot-swap: the parent pushes a new target via the typed `setTarget`
+        // intent; the iframe stays mounted, only `nodeId` updates.
+        built.parent?.on('intent', (msg: IntentMessage) => {
+          if (msg.envelope.name !== 'setTarget') return
+          const payload = msg.envelope.payload as IntentRegistry['setTarget']['payload']
+          if (typeof payload.nodeId === 'string') setNodeId(payload.nodeId)
+        })
+      } catch (err) {
+        if (cancelled) return
+        setReason(err instanceof Error ? err.message : String(err))
+        setStatus('standalone')
+      }
+    })()
+
+    return () => {
+      cancelled = true
+      if (shell) void shell.dispose()
+    }
+  }, [])
+
+  return useMemo(() => ({ status, session, nodeId, reason }), [status, session, nodeId, reason])
+}

package/template/client/src/shell/view-router.tsx

@@ -0,0 +1,98 @@
+/**
+ * Tiny multi-view router for the domain's one SPA bundle.
+ *
+ * The domain declares several SPA Views, each mounted by the shell at its own
+ * path under `/ui/*` (e.g. `/ui/monitor`). The shell mounts ONE iframe per view,
+ * so inside the iframe `window.location.pathname` is that view's mount path. This
+ * bundle reads that path and renders the matching view — one build, many views.
+ *
+ * Two pieces:
+ *   - `resolveView` — map `window.location.pathname` → a view component.
+ *   - `ViewFrame`   — DRYs the shell-handshake gating (`loading`/`standalone`/
+ *     `ready`) every view repeats, so a view only writes its `ready` body.
+ *
+ * To add a view: write a `ViewComponent` (usually wrapping `ViewFrame`), add a
+ * `ROUTES` entry keyed by its mount path in `src/app.tsx`, and register a
+ * matching `defineView({ mount })` in the domain's `views/`.
+ */
+
+import type { ReactNode } from 'react'
+
+import type { KernelClient } from '@astrale-os/shell'
+
+import type { ShellState } from './use-shell'
+
+/** A view: given the shell state, render its tree. */
+export type ViewComponent = (shell: ShellState) => ReactNode
+
+/** Mount path → view component (key e.g. `/ui/monitor`). */
+export type ViewRoutes = Record<string, ViewComponent>
+
+/** Strip a single trailing slash (but keep a bare `/`). */
+function normalizePath(pathname: string): string {
+  return pathname.length > 1 && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname
+}
+
+/**
+ * Resolve the view for a mount path — exact match, tolerating a trailing slash.
+ * Returns `undefined` when no route is registered (caller renders a fallback).
+ */
+export function resolveView(
+  routes: ViewRoutes,
+  pathname: string = window.location.pathname,
+): ViewComponent | undefined {
+  return routes[normalizePath(pathname)]
+}
+
+/**
+ * Shared shell-handshake gate. Renders the `.wrap`/`.card` shell and:
+ *   - `loading`    → title + subline + "Waiting for the shell handshake…"
+ *   - `standalone` → title + subline + the "No parent shell" banner copy
+ *   - `ready`      → `children(session, nodeId)` (session is non-null here)
+ *
+ * Mirrors the markup/classes the original single-view app used, so styling is
+ * unchanged across views.
+ */
+export function ViewFrame({
+  shell,
+  title,
+  subline,
+  children,
+}: {
+  shell: ShellState
+  title: string
+  subline?: string
+  children: (session: KernelClient, nodeId: string | undefined) => ReactNode
+}) {
+  const { status, session, nodeId, reason } = shell
+
+  return (
+    <div className="wrap">
+      <div className="card">
+        {status === 'loading' && (
+          <>
+            <h1 className="title">{title}</h1>
+            {subline && <p className="subline">{subline}</p>}
+            <p className="muted">Waiting for the shell handshake…</p>
+          </>
+        )}
+
+        {status === 'standalone' && (
+          <>
+            <h1 className="title">{title}</h1>
+            {subline && <p className="subline">{subline}</p>}
+            <div className="banner">
+              No parent shell ({reason}). This view is meant to be mounted by the Astrale GUI, which
+              hands it a target node and a kernel session. Showing a standalone preview.
+            </div>
+            <p className="body muted">
+              When mounted by the shell, this card renders the node you opened.
+            </p>
+          </>
+        )}
+
+        {status === 'ready' && session && children(session, nodeId)}
+      </div>
+    </div>
+  )
+}

package/template/client/src/styles.css

@@ -3,11 +3,19 @@
   --fg: #171717;
   --muted: #737373;
   --border: #e5e5e5;
+  --border-strong: #d4d4d8;
   --card: #ffffff;
   --accent: #2563eb;
+  --accent-soft: rgba(37, 99, 235, 0.1);
   --warn-bg: #fffbeb;
   --warn-border: #fde68a;
   --warn-fg: #92400e;
+  --err: #dc2626;
+  --err-soft: rgba(220, 38, 38, 0.1);
+  --up: #16a34a;
+  --down: #dc2626;
+  --unknown: #737373;
+  --mono: ui-monospace, SFMono-Regular, Menlo, monospace;
 }
 
 * {
@@ -49,7 +57,7 @@ body {
 }
 
 .subline {
-  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-family: var(--mono);
   font-size: 0.72rem;
   color: var(--muted);
   margin: 0.25rem 0 1rem;
@@ -61,6 +69,8 @@ body {
   margin: 0 0 1rem;
 }
 
+/* ─── Banners ───────────────────────────────────────────────────────────── */
+
 .banner {
   border: 1px solid var(--warn-border);
   background: var(--warn-bg);
@@ -71,11 +81,57 @@ body {
   margin-bottom: 1rem;
 }
 
+.banner-error {
+  border-color: var(--err);
+  background: var(--err-soft);
+  color: var(--err);
+  word-break: break-word;
+}
+
+/* ─── Panel ─────────────────────────────────────────────────────────────── */
+
+.panel {
+  background: var(--card);
+  border: 1px solid var(--border);
+  border-radius: 0.7rem;
+  padding: 1.05rem 1.2rem;
+}
+
+.panel-danger {
+  border-color: color-mix(in srgb, var(--err) 45%, var(--border));
+}
+
+.panel-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  margin-bottom: 0.85rem;
+}
+
+.panel-title {
+  font-size: 1.1rem;
+  font-weight: 650;
+  margin: 0;
+}
+
+.panel-danger .panel-title {
+  color: var(--err);
+}
+
+.panel-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+/* ─── Key/value ─────────────────────────────────────────────────────────── */
+
 .kv {
   border: 1px solid var(--border);
   border-radius: 0.5rem;
   overflow: hidden;
-  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-family: var(--mono);
   font-size: 0.72rem;
 }
 
@@ -97,14 +153,131 @@ body {
 
 .kv-val {
   word-break: break-all;
+  min-width: 0;
 }
 
 .muted {
   color: var(--muted);
 }
 
-.section-label {
+.mono {
+  font-family: var(--mono);
   font-size: 0.78rem;
+}
+
+.link {
+  color: var(--accent);
+  text-decoration: none;
+}
+
+.link:hover {
+  text-decoration: underline;
+}
+
+/* ─── Status row + badge ────────────────────────────────────────────────── */
+
+.status-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  margin: 0 0 1rem;
+}
+
+.status-badge {
+  display: inline-block;
+  font-weight: 700;
+  font-size: 1rem;
+  letter-spacing: 0.04em;
+  padding: 0.3rem 0.85rem;
+  border-radius: 0.5rem;
+  color: #ffffff;
+}
+
+.status-up {
+  background: var(--up);
+}
+
+.status-down {
+  background: var(--down);
+}
+
+.status-unknown {
+  background: var(--unknown);
+}
+
+/* ─── Buttons ───────────────────────────────────────────────────────────── */
+
+.check-btn {
+  font: inherit;
   font-weight: 600;
-  margin: 0 0 0.5rem;
+  color: #ffffff;
+  background: var(--accent);
+  border: 0;
+  border-radius: 0.5rem;
+  padding: 0.4rem 0.85rem;
+  cursor: pointer;
+}
+
+.check-btn:hover:not(:disabled) {
+  opacity: 0.9;
+}
+
+.check-btn:disabled {
+  opacity: 0.55;
+  cursor: default;
+}
+
+/* ─── Empty state ───────────────────────────────────────────────────────── */
+
+.empty {
+  border: 1px dashed var(--border-strong);
+  border-radius: 0.6rem;
+  padding: 1.4rem 1.2rem;
+  text-align: center;
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+  align-items: center;
+}
+
+.empty-text {
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.85rem;
+}
+
+.empty-hint {
+  font-family: var(--mono);
+  font-size: 0.72rem;
+  color: var(--muted);
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: 0.4rem;
+  padding: 0.3rem 0.6rem;
+  word-break: break-all;
+}
+
+/* ─── Loading ───────────────────────────────────────────────────────────── */
+
+.loading-line {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin: 0;
+}
+
+.spinner {
+  width: 0.85rem;
+  height: 0.85rem;
+  border-radius: 50%;
+  border: 2px solid var(--border-strong);
+  border-top-color: var(--accent);
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
 }

package/template/client/src/ui/format.ts

@@ -0,0 +1,24 @@
+/** Shared display formatters — pure, presentation-side (used across views). */
+
+/**
+ * Coarse relative time for `lastCheckedAt`-style ISO stamps:
+ * `just now` / `5m ago` / `2h ago` / a `YYYY-MM-DD` date for anything older than
+ * 30 days. Returns `—` for a missing stamp and the raw string for an unparseable
+ * one.
+ */
+export function relativeTime(iso: string | undefined, now = Date.now()): string {
+  if (!iso) return '—'
+  const t = Date.parse(iso)
+  if (Number.isNaN(t)) return iso
+  const diff = now - t
+  if (diff < 0) return 'just now'
+  const s = Math.floor(diff / 1000)
+  if (s < 45) return 'just now'
+  const m = Math.floor(s / 60)
+  if (m < 60) return `${m}m ago`
+  const h = Math.floor(m / 60)
+  if (h < 48) return `${h}h ago`
+  const d = Math.floor(h / 24)
+  if (d < 30) return `${d}d ago`
+  return new Date(t).toISOString().slice(0, 10)
+}

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

@@ -0,0 +1,9 @@
+/**
+ * The design system — generic, feature-AGNOSTIC presentational primitives +
+ * display formatters, no domain knowledge and no kernel session. Feature-specific
+ * UI (e.g. the Monitor's StatusBadge) lives in that feature's own `ui/`, not here.
+ * Import from the barrel: `import { Panel, KV, relativeTime } from '@/ui'`.
+ */
+export { EmptyState, ErrorBanner, Panel, Spinner } from './surface'
+export { ExternalLink, KV, Mono } from './value'
+export { relativeTime } from './format'

package/template/client/src/ui/surface.tsx

@@ -0,0 +1,56 @@
+/** Containers + feedback surfaces — pure presentational. */
+import type { ReactNode } from 'react'
+
+/**
+ * A titled card section. `actions` render in the header (e.g. a button); `tone:
+ * 'danger'` tints the border/title for destructive panels.
+ */
+export function Panel({
+  title,
+  actions,
+  tone,
+  children,
+}: {
+  title: string
+  actions?: ReactNode
+  tone?: 'danger'
+  children: ReactNode
+}) {
+  return (
+    <section className={tone === 'danger' ? 'panel panel-danger' : 'panel'}>
+      <header className="panel-head">
+        <h2 className="panel-title">{title}</h2>
+        {actions && <div className="panel-actions">{actions}</div>}
+      </header>
+      {children}
+    </section>
+  )
+}
+
+/** A red alert banner for a failed call. */
+export function ErrorBanner({ children }: { children: ReactNode }) {
+  return (
+    <div className="banner banner-error" role="alert">
+      {children}
+    </div>
+  )
+}
+
+/** Teaching empty state — what's missing and an optional command that fixes it. */
+export function EmptyState({ children, hint }: { children: ReactNode; hint?: string }) {
+  return (
+    <div className="empty">
+      <p className="empty-text">{children}</p>
+      {hint && <code className="empty-hint">{hint}</code>}
+    </div>
+  )
+}
+
+/** A spinner with a label, for in-flight loads. */
+export function Spinner({ label }: { label: string }) {
+  return (
+    <p className="muted loading-line">
+      <span className="spinner" aria-hidden="true" /> {label}
+    </p>
+  )
+}

package/template/client/src/ui/value.tsx

@@ -0,0 +1,32 @@
+/** Inline value renderers — pure presentational. */
+import type { ReactNode } from 'react'
+
+/** One label/value row in a `.kv` grid. */
+export function KV({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <div className="kv-row">
+      <div className="kv-key">{label}</div>
+      <div className="kv-val">{children}</div>
+    </div>
+  )
+}
+
+/** Monospace inline value with a soft em-dash fallback. */
+export function Mono({ value, title }: { value: string | undefined; title?: string }) {
+  if (!value) return <span className="muted">—</span>
+  return (
+    <span className="mono" title={title ?? value}>
+      {value}
+    </span>
+  )
+}
+
+/** An external link rendered without its scheme, opening in a new tab. */
+export function ExternalLink({ url }: { url: string | undefined }) {
+  if (!url) return <span className="muted">—</span>
+  return (
+    <a className="mono link" href={url} target="_blank" rel="noreferrer noopener" title={url}>
+      {url.replace(/^https?:\/\//, '')}
+    </a>
+  )
+}

package/template/client/src/views/monitor.tsx

@@ -0,0 +1,30 @@
+/**
+ * The `ui-monitor` view (mount path `/ui/monitor`) — the Monitor detail panel.
+ *
+ * Mounted by the Astrale shell as a sandboxed iframe; `@/shell` (built on the
+ * real `@astrale-os/shell`) completes the handshake and hands over the kernel
+ * session + the target node id. `ViewFrame` gates the handshake (loading /
+ * standalone / ready); the `ready` body delegates to `MonitorCard`, the feature
+ * container that loads the node, renders its status/url/latency, and exposes a
+ * "Check now" probe.
+ *
+ * Pure composition — no data/transport logic lives here (that's `@/monitor` +
+ * `@/shell`).
+ */
+import { MonitorCard } from '@/monitor'
+import { type ShellState, ViewFrame } from '@/shell'
+
+export function MonitorView(shell: ShellState) {
+  return (
+    <ViewFrame shell={shell} title="Status monitor" subline="ui-monitor · Astrale view SPA">
+      {(session, nodeId) =>
+        nodeId ? (
+          // Keyed by node id so a target hot-swap remounts with fresh state.
+          <MonitorCard key={nodeId} session={session} nodeId={nodeId} />
+        ) : (
+          <div className="banner">No target Monitor — open this view from a Monitor node.</div>
+        )
+      }
+    </ViewFrame>
+  )
+}

package/template/client/tsconfig.json

@@ -11,7 +11,8 @@
     "skipLibCheck": true,
     "isolatedModules": true,
     "resolveJsonModule": true,
-    "verbatimModuleSyntax": true
+    "verbatimModuleSyntax": true,
+    "paths": { "@/*": ["./src/*"] }
   },
   "include": [
     "src/**/*.ts",

package/template/client/vite.config.ts

@@ -1,30 +1,29 @@
+import { fileURLToPath } from 'node:url'
+
 import viteReact from '@vitejs/plugin-react'
 import { defineConfig } from 'vite'
 
 /**
- * Client SPA for the domain's `ui-note` View. Built into `../.dist/`,
- * served by the generated worker via its `ASSETS` binding (`.astrale/`).
+ * Client SPA for the domain's Views. Built into `../.dist/`, served by the
+ * generated worker via its `ASSETS` binding (`.astrale/`).
  *
  * `base: '/ui/'` + `outDir: '../.dist'`: 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>`.
+ * SPA fallback for `/ui/<anything>` — `src/app.tsx` routes on the mount path.
  *
- * 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.
+ * Consumes `@astrale-os/shell` for the child handshake + the real kernel client:
+ * `src/shell/use-shell.ts` boots `createShell({ mode: 'sandboxed' })` and the
+ * feature hooks call kernel methods through `shell.kernel` (token refresh, codec
+ * negotiation, redirect following, delegation — all handled by the SDK).
  *
- * 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`.
+ * `@` is aliased to `src/` (mirrors tsconfig `paths`) so feature code imports
+ * `@/shell`, `@/ui`, `@/monitor`.
  */
 export default defineConfig({
   base: '/ui/',
   plugins: [viteReact()],
+  resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } },
   build: {
     outDir: '../.dist',
     emptyOutDir: true,

package/template/client/vitest.config.ts

@@ -1,18 +1,25 @@
+import { fileURLToPath } from 'node:url'
+
 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` build) so tests don't inherit the SPA build
- * options.
+ * Vitest config for the client SPA. A DOM env (`happy-dom`) backs the React
+ * render + the shell handshake the tests exercise. Kept separate from
+ * `vite.config.ts` (which sets the `/ui/` base + `../.dist` build) so tests
+ * don't inherit the SPA build options.
  */
 export default defineConfig({
   plugins: [viteReact()],
+  resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } },
   test: {
     environment: 'happy-dom',
     globals: true,
     include: ['__tests__/**/*.test.{ts,tsx}', 'src/**/*.test.{ts,tsx}'],
+    // `@astrale-os/*` ship bundler-targeted ESM (extensionless relative imports).
+    // vitest externalizes node_modules and uses Node's stricter ESM resolver,
+    // which wants explicit `.js`; inlining the scope makes vitest transform them
+    // through vite — the same context the build uses. Standard for these deps.
+    server: { deps: { inline: [/@astrale-os\//] } },
   },
 })

package/template/core/monitor/health.ts

@@ -0,0 +1,19 @@
+/**
+ * Health logic — PURE status rule, no I/O. Maps an observed probe result to the
+ * monitor's verdict. (Node identity/layout/seed data lives in `./node`; the
+ * kernel reads/writes live in `runtime/monitor/`; the network probe behind the
+ * `Prober` port in `integrations/prober/`.)
+ */
+
+/** A monitor's health verdict. `unknown` is the pre-first-check state. */
+export type HealthStatus = 'up' | 'down' | 'unknown'
+
+/**
+ * Map an observed HTTP status code to a verdict. `0` means the host was
+ * unreachable (DNS/timeout/refused) — that's `down`. 2xx/3xx is `up`; anything
+ * else (4xx/5xx) is `down`. Pure.
+ */
+export function classify(statusCode: number): HealthStatus {
+  if (statusCode >= 200 && statusCode < 400) return 'up'
+  return 'down'
+}