@astrale-os/adapter-cloudflare 0.4.4 → 0.4.5

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

@@ -1,67 +0,0 @@
-/**
- * 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

@@ -1,21 +0,0 @@
-/**
- * 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 type { GraphEdge } from './transformers'
-export { resolveView, ViewFrame } from './view-router'
-export type { ViewComponent, ViewRoutes } from './view-router'

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

@@ -1,35 +0,0 @@
-/**
- * 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

@@ -1,75 +0,0 @@
-/**
- * Graph-shape helpers at the kernel boundary — turn `shell.kernel.graph` results
- * (`graph.node` / `graph.children` / `graph.links`, backed by `function.get`)
- * into the shapes features consume. Domain-neutral: per-class node→record mappers
- * live in each feature's `*.mappers.ts` and build on `qualifiedString` here.
- *
- * The graph sugar already returns typed records (`{ nodes }`, `{ edges }`) — no
- * envelope-sniffing needed — so these are thin projections over those shapes.
- *
- * 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'
-
-/** One incident edge as `shell.kernel.graph.links` returns it (a `GraphEdgeWire`). */
-export type GraphEdge = {
-  class: string
-  source: string
-  target: string
-  slug?: string | null
-  props?: Record<string, unknown>
-}
-
-/** 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
-}
-
-/**
- * Targets of `graph.links` edges whose edge class ends with `classTail`
- * (e.g. `'monitor_on_host'`). Accepts the `graph.links` result (`{ edges }`) or a
- * bare `GraphEdge[]`.
- */
-export function linkTargets(
-  edges: GraphEdge[] | { edges: GraphEdge[] } | null | undefined,
-  classTail: string,
-): string[] {
-  const list: GraphEdge[] = Array.isArray(edges) ? edges : (edges?.edges ?? [])
-  const out: string[] = []
-  for (const edge of list) {
-    if (typeof edge.class !== 'string' || !edge.class.endsWith(classTail)) continue
-    if (typeof edge.target === 'string') out.push(edge.target)
-  }
-  return out
-}
-
-/**
- * The nodes of a `graph.children` / `graph.tree` result. Accepts the sugar result
- * (`{ nodes }`) or a bare `KernelNode[]`.
- */
-export function asNodeArray(
-  result: KernelNode[] | { nodes: KernelNode[] } | null | undefined,
-): KernelNode[] {
-  if (Array.isArray(result)) return result
-  return result?.nodes ?? []
-}

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

@@ -1,59 +0,0 @@
-/**
- * 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(() => {
-    setReloading(true)
-    setEpoch((e) => e + 1)
-  }, [])
-  return { state, reload, reloading }
-}

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

@@ -1,59 +0,0 @@
-/**
- * `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

@@ -1,81 +0,0 @@
-import type { KernelClient } from '@astrale-os/shell'
-
-import { useCallback, useEffect, useState } from 'react'
-
-import { errorMessage, type KernelNode } from './client'
-
-/**
- * The node shape `shell.kernel.get()` resolves — a graph `Node` ({@link
- * KernelClient.get} returns `Node | null`). Derived from the client's own
- * return type so this file never imports server schema; mapped onto the plain
- * {@link KernelNode} the view helpers consume by `toKernelNode`.
- */
-type GraphNode = NonNullable<Awaited<ReturnType<KernelClient['get']>>>
-
-/**
- * Project a graph `Node` onto the plain, schema-free {@link KernelNode}. `path`
- * and `class` arrive as typed `Path` instances over the wire — `String()` yields
- * their raw form (and is the identity on a plain string), so this stays correct
- * whether or not the client hydrates them.
- */
-function toKernelNode(node: GraphNode): KernelNode {
-  return {
-    id: String(node.id),
-    path: String(node.path),
-    class: String(node.class),
-    props: { ...node.props },
-  }
-}
-
-export type NodeState =
-  | { status: 'idle' }
-  | { status: 'loading' }
-  | { status: 'ok'; node: KernelNode }
-  | { status: 'error'; message: string }
-
-/**
- * Fetch a node by id through `shell.kernel.get('@<id>')`.
- * `null` means missing or masked; `reload()` refetches the current id.
- */
-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
-      .get(`@${nodeId}`)
-      .then((node) => {
-        if (cancelled) return
-        if (node === null) {
-          setState({ status: 'error', message: 'Node not found or not visible' })
-          return
-        }
-        setState({ status: 'ok', node: toKernelNode(node) })
-      })
-      .catch((err: unknown) => {
-        if (!cancelled) {
-          setState({ status: 'error', message: errorMessage(err) })
-        }
-      })
-
-    return () => {
-      cancelled = true
-    }
-  }, [session, nodeId, nonce])
-
-  return { ...state, reload }
-}

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

@@ -1,91 +0,0 @@
-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

@@ -1,97 +0,0 @@
-/**
- * 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/status-page`). 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 { KernelClient } from '@astrale-os/shell'
-import type { ReactNode } from 'react'
-
-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/status-page`). */
-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/ui/format.ts

@@ -1,24 +0,0 @@
-/** 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

@@ -1,10 +0,0 @@
-/**
- * The design system — generic, feature-AGNOSTIC presentational primitives +
- * display formatters, no domain knowledge and no kernel session. Import from the
- * barrel: `import { Panel, KV, relativeTime } from '@/ui'`. A view's own
- * health/status chips and other domain-shaped widgets live alongside their
- * feature, not here.
- */
-export { EmptyState, ErrorBanner, Panel, Spinner } from './surface'
-export { ExternalLink, KV, Mono } from './value'
-export { relativeTime } from './format'

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

@@ -1,56 +0,0 @@
-/** 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>
-  )
-}