@astrale-os/adapter-cloudflare 0.1.9 → 0.1.10

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'

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

@@ -0,0 +1,35 @@
+/**
+ * Kernel invocation primitives — the single place a view reaches the kernel,
+ * over the shell's proper `KernelClient` (`session.call`, wired by the sandboxed
+ * handshake: fresh delegation token per call, redirects followed). `callMethod`
+ * is the generic method-ref call; `invokeNode` is instance dispatch by node id
+ * (`@<id>::<method>` — the shell hands views node IDs, not paths); `nodeAddr`
+ * picks the stable address for a node.
+ */
+import type { KernelClient } from '@astrale-os/shell'
+
+import type { KernelNode } from './client'
+
+/** One kernel call through the live session (proper client: fresh token, redirects). */
+export function callMethod(
+  session: KernelClient,
+  method: string,
+  params: Record<string, unknown> = {},
+): Promise<unknown> {
+  return session.call(method, params)
+}
+
+/** Instance-method dispatch by node id. */
+export function invokeNode(
+  session: KernelClient,
+  nodeId: string,
+  method: string,
+  params: Record<string, unknown> = {},
+): Promise<unknown> {
+  return callMethod(session, `@${nodeId}::${method}`, params)
+}
+
+/** Stable instance address: tree path when known, else `@id`. */
+export function nodeAddr(node: KernelNode): string {
+  return node.path && node.path.startsWith('/') ? node.path : `@${node.id}`
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Graph-response transformers at the kernel boundary — turn raw `::get` /
+ * `::listChildren` / `::getLinks` payloads into the shapes features consume.
+ * Domain-neutral: per-class node→record mappers live in each feature's
+ * `*.mappers.ts` and build on `qualifiedString` here.
+ *
+ * Props are stored under QUALIFIED keys
+ * (`monitors.astrale.ai:class.Monitor.property.url`). The client must not import
+ * server schema, so values resolve by KEY SUFFIX (`.property.<name>`),
+ * preferring domain-qualified keys over kernel ones
+ * (`kernel.astrale.ai:interface.Named.property.name` would otherwise shadow
+ * `Monitor.property.name` — both end in `.property.name`).
+ */
+import type { KernelNode } from './client'
+
+/** Resolve a prop by `.property.<name>` suffix; domain keys win over kernel ones. */
+export function qualifiedProp(props: Record<string, unknown>, name: string): unknown {
+  const suffix = `.property.${name}`
+  let kernelFallback: unknown
+  for (const [key, value] of Object.entries(props)) {
+    if (!key.endsWith(suffix)) continue
+    if (key.startsWith('kernel.astrale.ai:')) {
+      if (kernelFallback === undefined) kernelFallback = value
+    } else {
+      return value
+    }
+  }
+  return kernelFallback
+}
+
+export function qualifiedString(props: Record<string, unknown>, name: string): string | undefined {
+  const v = qualifiedProp(props, name)
+  return typeof v === 'string' && v !== '' ? v : undefined
+}
+
+type RawLink = { class?: unknown; edgeClass?: unknown; target?: unknown; to?: unknown }
+
+/**
+ * Targets of a `::getLinks` response whose edge class ends with `classTail`
+ * (e.g. `'monitor_on_host'`). Tolerates bare-array and `{ links }` envelopes,
+ * and both `target`/`to` + `class`/`edgeClass`.
+ */
+export function linkTargets(raw: unknown, classTail: string): string[] {
+  const links: RawLink[] = Array.isArray(raw)
+    ? (raw as RawLink[])
+    : ((raw as { links?: RawLink[] } | null)?.links ?? [])
+  const out: string[] = []
+  for (const link of links) {
+    const cls =
+      typeof link.class === 'string'
+        ? link.class
+        : typeof link.edgeClass === 'string'
+          ? link.edgeClass
+          : ''
+    if (!cls.endsWith(classTail)) continue
+    const target =
+      typeof link.target === 'string'
+        ? link.target
+        : typeof link.to === 'string'
+          ? link.to
+          : undefined
+    if (target) out.push(target)
+  }
+  return out
+}
+
+/** A `::listChildren` response as a node array (bare array or enveloped). */
+export function asNodeArray(raw: unknown): KernelNode[] {
+  if (Array.isArray(raw)) return raw as KernelNode[]
+  const obj = raw as { children?: KernelNode[]; nodes?: KernelNode[] } | null
+  return obj?.children ?? obj?.nodes ?? []
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Tiny async-resource hook — load on mount / when `deps` change, expose a
+ * `reload()` for refresh buttons and post-mutation refetches. Mirrors the
+ * cancellation discipline of `use-node.ts` (stale resolutions are dropped).
+ */
+import { useCallback, useEffect, useState } from 'react'
+
+import { errorMessage } from './client'
+
+export type AsyncState<T> =
+  | { status: 'loading' }
+  | { status: 'ok'; data: T }
+  | { status: 'error'; message: string }
+
+export type AsyncResource<T> = {
+  state: AsyncState<T>
+  /** Refetch. Keeps showing the previous data while the reload is in flight. */
+  reload: () => void
+  /** True while a reload is in flight on top of an `ok` state. */
+  reloading: boolean
+}
+
+export function useAsync<T>(fn: () => Promise<T>, deps: unknown[]): AsyncResource<T> {
+  const [state, setState] = useState<AsyncState<T>>({ status: 'loading' })
+  const [reloading, setReloading] = useState(false)
+  const [epoch, setEpoch] = useState(0)
+
+  useEffect(() => {
+    let cancelled = false
+    setState((prev) => {
+      if (prev.status === 'ok') {
+        setReloading(true)
+        return prev // keep stale data visible during a reload
+      }
+      return { status: 'loading' }
+    })
+    fn()
+      .then((data) => {
+        if (cancelled) return
+        setReloading(false)
+        setState({ status: 'ok', data })
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return
+        setReloading(false)
+        setState({ status: 'error', message: errorMessage(err) })
+      })
+    return () => {
+      cancelled = true
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- deps are the caller's cache key
+  }, [...deps, epoch])
+
+  const reload = useCallback(() => setEpoch((e) => e + 1), [])
+  return { state, reload, reloading }
+}

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

@@ -0,0 +1,61 @@
+/**
+ * `useCapability` — the convention's WRITE primitive: a node method made
+ * interactive, wrapped in one uniform lifecycle (idle → running → done/failed).
+ * Every actuator (a form submit, a danger button) shares this machine instead
+ * of re-implementing busy/error flags by hand.
+ *
+ *   const check = useCapability(() => invokeNode(session, nodeId, 'check', {}))
+ *   …
+ *   if (await check.run()) reload()
+ *
+ * (This is the single seam where permission-gating would later land — a
+ * `permitted` flag computed from the node's affordances — without touching any
+ * presentational component.)
+ */
+import { useCallback, useState } from 'react'
+
+import { errorMessage } from './client'
+
+export type Phase = 'idle' | 'running' | 'done' | 'failed'
+
+export interface Capability<P = void> {
+  /** Phase of the most recent invocation. */
+  phase: Phase
+  /** Failure message when `phase === 'failed'`, else null. */
+  error: string | null
+  /** Invoke; resolves true on success, false on failure (error then set). */
+  run: [P] extends [void] ? () => Promise<boolean> : (params: P) => Promise<boolean>
+  /** Return to idle, clearing any error. */
+  reset: () => void
+}
+
+export function useCapability<P = void>(
+  perform: (params: P) => Promise<unknown>,
+): Capability<P> {
+  const [phase, setPhase] = useState<Phase>('idle')
+  const [error, setError] = useState<string | null>(null)
+
+  const run = useCallback(
+    async (params: P): Promise<boolean> => {
+      setPhase('running')
+      setError(null)
+      try {
+        await perform(params)
+        setPhase('done')
+        return true
+      } catch (err) {
+        setPhase('failed')
+        setError(errorMessage(err))
+        return false
+      }
+    },
+    [perform],
+  )
+
+  const reset = useCallback(() => {
+    setPhase('idle')
+    setError(null)
+  }, [])
+
+  return { phase, error, run, reset } as Capability<P>
+}

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

@@ -0,0 +1,61 @@
+import { useCallback, useEffect, useState } from 'react'
+
+import type { KernelClient } from '@astrale-os/shell'
+
+import { errorMessage, type KernelNode } from './client'
+
+export type NodeState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'ok'; node: KernelNode }
+  | { status: 'error'; message: string }
+
+/**
+ * Fetch a node by id via `@<id>::get`. Re-fetches when the target node id
+ * changes (`setTarget` hot-swap); stays `idle` until a target node id exists.
+ * `session` is a stable reference for the view's lifetime, so listing it as a
+ * dep never re-fires on its own — and the shell's client reads the fresh token
+ * at call time, so a `ctrl:tokenRefresh` needs no re-fetch.
+ *
+ * Returns the node state plus a `reload()` that re-fetches the current node —
+ * the view calls it after an instance method (e.g. `::check`) mutates the node
+ * so the fresh props render. It bumps an internal `nonce` dep, re-firing the
+ * effect.
+ */
+export function useNode(
+  session: KernelClient,
+  nodeId: string | undefined,
+): NodeState & { reload(): void } {
+  const [state, setState] = useState<NodeState>({ status: 'idle' })
+  const [nonce, setNonce] = useState(0)
+
+  const reload = useCallback(() => {
+    setNonce((n) => n + 1)
+  }, [])
+
+  useEffect(() => {
+    if (!nodeId) {
+      setState({ status: 'idle' })
+      return
+    }
+
+    let cancelled = false
+    setState({ status: 'loading' })
+    session
+      .call(`@${nodeId}::get`, {})
+      .then((result) => {
+        if (!cancelled) setState({ status: 'ok', node: result as KernelNode })
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) {
+          setState({ status: 'error', message: errorMessage(err) })
+        }
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [session, nodeId, nonce])
+
+  return { ...state, reload }
+}