@astrale-os/adapter-cloudflare 0.1.8 → 0.1.10

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

@@ -1,197 +0,0 @@
-/**
- * Minimal, self-contained reimplementation of the Astrale shell *child* init
- * handshake — just enough to learn which node this view is mounted for and to
- * keep its delegation token live, without pulling in `@astrale-os/shell` (and
- * its `kernel-client` transitive deps).
- *
- * Protocol (mirrors `shell/packages/shell/src/application/windowing/`):
- *   1. child posts `{ type: 'astrale-shell/init-request', version: 1 }` to the
- *      parent window via `window.postMessage(..., '*')`.
- *   2. parent replies with `{ type: 'astrale-shell/init-response', windowId }`
- *      and *transfers a MessagePort* (`event.ports[0]`).
- *   3. over that port the parent sends a `ctrl:handshake` carrying the session
- *      data — `windowId`, `kernelUrl`, `delegationToken`, `tokenExpiresAt`,
- *      `functionId`, and the `targetNodeId` (the node this view should render).
- *   4. child replies with `ctrl:handshakeAck` and keeps the port open.
- *
- * Steady state on the port:
- *   - `intent` `setTarget { nodeId }` — hot-swap the target node (re-render).
- *   - `ctrl:tokenRefresh { delegationToken, tokenExpiresAt }` — the parent
- *     pushes a FRESH token before the old one expires. We update the mutable
- *     `currentToken` so the next kernel call uses it (see `getToken()`).
- *
- * The iframe authenticates with the handshake `delegationToken` ONLY: the
- * parent minted it for this kernel, so the audience already matches — no
- * cookie, no whoami, no client-side minting. Actually CALLING the kernel lives
- * in `lib/kernel.ts` (a minimal inline JSON client).
- */
-
-const INIT_REQUEST_TYPE = 'astrale-shell/init-request'
-const INIT_RESPONSE_TYPE = 'astrale-shell/init-response'
-
-export type HandshakeData = {
-  windowId: string
-  kernelUrl?: string
-  functionId?: string
-  /** Opaque delegation credential the parent minted for this view. */
-  delegationToken?: string
-  /** Unix-ms expiry of `delegationToken`; advances on each `tokenRefresh`. */
-  tokenExpiresAt?: number
-  /** The node this view is mounted for — what we want to render. */
-  targetNodeId?: string
-}
-
-export type ShellSession = {
-  /** Handshake data captured at handshake time (token here is the INITIAL one). */
-  readonly data: HandshakeData
-  /** Convenience mirror of `data.kernelUrl` (satisfies `NodeSession`). */
-  readonly kernelUrl: string | undefined
-  /** The LIVE delegation token — reflects `tokenRefresh` pushes. */
-  getToken(): string | undefined
-  /** The LIVE token expiry (Unix ms) — reflects `tokenRefresh` pushes. */
-  getTokenExpiresAt(): number | undefined
-  /** Subscribe to `targetNodeId` hot-swaps pushed via `setTarget` intents. */
-  onTargetChange(cb: (nodeId: string | undefined) => void): () => void
-  /** Tear down listeners + the message port. */
-  dispose(): void
-}
-
-type CtrlMessage = {
-  type: 'ctrl'
-  version: number
-  action: string
-  data?: Record<string, unknown>
-}
-
-type IntentMessage = {
-  type: 'intent'
-  envelope?: { name?: string; payload?: Record<string, unknown> }
-}
-
-const isObj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null
-
-const asString = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined)
-
-/**
- * Run the child handshake. Resolves once the parent completes `ctrl:handshake`.
- * Rejects on timeout (no parent / not sandboxed) — callers should render a
- * standalone fallback in that case.
- */
-export function connectShell(timeoutMs = 5000): Promise<ShellSession> {
-  return new Promise((resolve, reject) => {
-    const parent = window.parent
-    if (!parent || parent === window) {
-      reject(new Error('not running inside a parent frame'))
-      return
-    }
-
-    let port: MessagePort | null = null
-    // Mutable token state — `tokenRefresh` updates these in place so later
-    // kernel calls read the fresh credential via `getToken()`.
-    let currentToken: string | undefined
-    let currentExpiresAt: number | undefined
-    const targetListeners = new Set<(nodeId: string | undefined) => void>()
-
-    const timer = setTimeout(() => {
-      cleanupWindow()
-      reject(new Error(`shell handshake timed out after ${timeoutMs}ms`))
-    }, timeoutMs)
-
-    function cleanupWindow() {
-      clearTimeout(timer)
-      window.removeEventListener('message', onWindowMessage)
-    }
-
-    // Steady-state port listener: target hot-swaps + token refreshes.
-    function onPortMessage(ev: MessageEvent) {
-      const msg = ev.data as unknown
-      if (!isObj(msg)) return
-
-      // Token refresh: the parent pushed a fresh credential. Swap it in place.
-      if (msg.type === 'ctrl' && (msg as CtrlMessage).action === 'tokenRefresh') {
-        const d = (msg as CtrlMessage).data ?? {}
-        const next = asString(d.delegationToken)
-        if (next) currentToken = next
-        if (typeof d.tokenExpiresAt === 'number') currentExpiresAt = d.tokenExpiresAt
-        return
-      }
-
-      // Hot-swap: `setTarget` intent carries a new nodeId.
-      if (msg.type === 'intent') {
-        const intent = msg as IntentMessage
-        if (intent.envelope?.name === 'setTarget') {
-          const raw = intent.envelope.payload?.nodeId
-          const nodeId = asString(raw)
-          for (const cb of targetListeners) cb(nodeId)
-        }
-      }
-    }
-
-    function onWindowMessage(ev: MessageEvent) {
-      const msg = ev.data as unknown
-      if (ev.source !== parent || !isObj(msg)) return
-      if (msg.type !== INIT_RESPONSE_TYPE) return
-
-      const received = ev.ports[0]
-      if (!received) return
-      port = received
-
-      port.onmessage = (portEv: MessageEvent) => {
-        const ctrl = portEv.data as unknown
-        if (!isObj(ctrl) || ctrl.type !== 'ctrl') {
-          onPortMessage(portEv)
-          return
-        }
-        const m = ctrl as CtrlMessage
-        if (m.action !== 'handshake' || !port) return
-
-        const d = (m.data ?? {}) as Record<string, unknown>
-        currentToken = asString(d.delegationToken)
-        currentExpiresAt = typeof d.tokenExpiresAt === 'number' ? d.tokenExpiresAt : undefined
-        const kernelUrl = asString(d.kernelUrl)
-
-        // Ack so the parent considers the child live.
-        port.postMessage({
-          type: 'ctrl',
-          version: 1,
-          action: 'handshakeAck',
-          data: { windowId: d.windowId },
-        })
-        // Switch the port to the steady-state listener (intents + tokenRefresh).
-        port.onmessage = onPortMessage
-        cleanupWindow()
-
-        resolve({
-          data: {
-            windowId: String(d.windowId ?? ''),
-            kernelUrl,
-            functionId: asString(d.functionId),
-            delegationToken: currentToken,
-            tokenExpiresAt: currentExpiresAt,
-            targetNodeId: asString(d.targetNodeId),
-          },
-          kernelUrl,
-          getToken: () => currentToken,
-          getTokenExpiresAt: () => currentExpiresAt,
-          onTargetChange(cb) {
-            targetListeners.add(cb)
-            return () => targetListeners.delete(cb)
-          },
-          dispose() {
-            cleanupWindow()
-            targetListeners.clear()
-            if (port) {
-              port.onmessage = null
-              port.close()
-            }
-          },
-        })
-      }
-      port.start()
-    }
-
-    window.addEventListener('message', onWindowMessage)
-    // targetOrigin '*' — the parent verifies our origin on its side.
-    parent.postMessage({ type: INIT_REQUEST_TYPE, version: 1 }, '*')
-  })
-}

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

@@ -1,66 +0,0 @@
-import { useEffect, useState } from 'react'
-
-import { kernelCall, type KernelNode } from './kernel'
-
-/**
- * The slice of the shell session this hook needs: where to call the kernel
- * (`kernelUrl`) and how to read the LIVE delegation token (`getToken()` —
- * which advances on `ctrl:tokenRefresh`). `ShellSession` satisfies this, and is
- * a stable reference for the component's lifetime (set once on handshake).
- */
-export type NodeSession = {
-  readonly kernelUrl: string | undefined
-  getToken(): string | undefined
-}
-
-export type NodeState =
-  | { status: 'idle' }
-  | { status: 'loading' }
-  | { status: 'ok'; node: KernelNode }
-  | { status: 'error'; message: string }
-
-/**
- * Fetch a node by id via `@<id>::get`, using the session's kernel URL + live
- * delegation token. Re-fetches when the target node id changes (`setTarget`
- * hot-swap) or when a token first becomes available. Stays `idle` until both a
- * target node id and a token exist.
- *
- * The effect keys on the token's PRESENCE (`hasToken`), not its value: a
- * `ctrl:tokenRefresh` swaps the token in place WITHOUT re-firing, and the next
- * fetch (triggered by a `setTarget` or remount) reads the fresh token via
- * `session.getToken()` at call time. `session` is stable, so listing it as a
- * dep is safe — it never causes a re-fire on its own.
- */
-export function useNode(session: NodeSession, nodeId: string | undefined): NodeState {
-  const hasToken = session.getToken() !== undefined
-  const [state, setState] = useState<NodeState>({ status: 'idle' })
-
-  useEffect(() => {
-    const token = session.getToken()
-    if (!nodeId || !session.kernelUrl || !token) {
-      setState({ status: 'idle' })
-      return
-    }
-
-    let cancelled = false
-    setState({ status: 'loading' })
-    kernelCall(session.kernelUrl, token, `@${nodeId}::get`, {})
-      .then((result) => {
-        if (!cancelled) setState({ status: 'ok', node: result as KernelNode })
-      })
-      .catch((err: unknown) => {
-        if (!cancelled) {
-          setState({
-            status: 'error',
-            message: err instanceof Error ? err.message : String(err),
-          })
-        }
-      })
-
-    return () => {
-      cancelled = true
-    }
-  }, [session, hasToken, nodeId])
-
-  return state
-}

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

@@ -1,85 +0,0 @@
-import { useEffect, useState } from 'react'
-
-import { connectShell, type HandshakeData, type ShellSession } from './shell'
-
-export type ShellStatus = 'loading' | 'ready' | 'standalone'
-
-export type ShellState = {
-  status: ShellStatus
-  /** Handshake data once `ready` (kernelUrl, token, etc). */
-  data: HandshakeData | null
-  /**
-   * The live session once `ready` — exposes `getToken()` (which reflects
-   * `tokenRefresh`) and `kernelUrl`. The node-fetch hook reads through this so
-   * it always uses the CURRENT token, not the one captured at handshake time.
-   */
-  session: ShellSession | null
-  /** Current target node id — updates on `setTarget` hot-swaps. */
-  nodeId: string | undefined
-  /** Reason we fell back to `standalone` (no parent / timeout). */
-  reason: string | null
-}
-
-/**
- * Runs the inline shell handshake once on mount and tracks the target node id.
- *
- * Three outcomes:
- *   - `loading`     — handshake in flight
- *   - `ready`       — parent completed the handshake; `data`/`session`/`nodeId`
- *                     populated
- *   - `standalone`  — no parent or it timed out (e.g. opened directly in a tab);
- *                     the view renders a self-describing fallback
- */
-export function useShell(): ShellState {
-  const [state, setState] = useState<ShellState>({
-    status: 'loading',
-    data: null,
-    session: null,
-    nodeId: undefined,
-    reason: null,
-  })
-
-  useEffect(() => {
-    let cancelled = false
-    let dispose: (() => void) | undefined
-
-    connectShell()
-      .then((session) => {
-        if (cancelled) {
-          session.dispose()
-          return
-        }
-        setState({
-          status: 'ready',
-          data: session.data,
-          session,
-          nodeId: session.data.targetNodeId,
-          reason: null,
-        })
-        const off = session.onTargetChange((nodeId) => {
-          setState((prev) => ({ ...prev, nodeId }))
-        })
-        dispose = () => {
-          off()
-          session.dispose()
-        }
-      })
-      .catch((err: unknown) => {
-        if (cancelled) return
-        setState({
-          status: 'standalone',
-          data: null,
-          session: null,
-          nodeId: undefined,
-          reason: err instanceof Error ? err.message : String(err),
-        })
-      })
-
-    return () => {
-      cancelled = true
-      dispose?.()
-    }
-  }, [])
-
-  return state
-}

package/template/methods/index.ts

@@ -1,66 +0,0 @@
-/**
- * Worker method wiring — the `methods` the codegen'd worker entry mounts. Thin
- * adapters around the shared logic in `./note`: the only thing that lives here
- * is the SDK typing and the `kernel` null-guard.
- *
- *   - `createNote` is interface-hosted (static) → `remoteInterfaceMethods`.
- *   - `reference`  is class-hosted (instance)   → `remoteMethod` +
- *                                                 `remoteClassMethods`.
- *   - `seed`       is class-hosted (static)     — the `postInstall` bootstrap.
- *
- * SDK-level `authorize` is an additive throw-to-deny check (returns void). For
- * finer worker checks see `assertPerm` / `requireOwnership` from
- * `@astrale-os/sdk`.
- */
-import {
-  remoteClassMethods,
-  remoteInterfaceMethods,
-  remoteMethod,
-  type SchemaMethodsImpl,
-} from '@astrale-os/sdk'
-
-import type { Env } from '../env'
-
-import { schema } from '../schema'
-import {
-  createNote as createNoteLogic,
-  reference as referenceLogic,
-  seed as seedLogic,
-} from './note'
-
-const method = remoteMethod<Env>()
-const interfaceMethods = remoteInterfaceMethods<Env>()
-const classMethods = remoteClassMethods<Env>()
-
-const NoteOpsMethods = interfaceMethods(schema, 'NoteOps', {
-  createNote: {
-    authorize: async () => undefined,
-    execute: ({ kernel, params }) => {
-      if (!kernel) throw new Error('createNote requires a kernel credential')
-      return createNoteLogic(kernel, params)
-    },
-  },
-})
-
-const reference = method(schema, 'Note', 'reference', {
-  authorize: async () => undefined,
-  execute: ({ kernel, self, params }) => {
-    if (!kernel) throw new Error('reference requires a kernel credential')
-    return referenceLogic(kernel, self.path.raw, params)
-  },
-})
-
-const seed = method(schema, 'Note', 'seed', {
-  authorize: async () => undefined,
-  execute: ({ kernel }) => {
-    if (!kernel) throw new Error('seed requires a kernel credential')
-    return seedLogic(kernel)
-  },
-})
-
-const NoteMethods = classMethods(schema, 'Note', { reference, seed })
-
-export const methods: SchemaMethodsImpl<typeof schema, Env> = {
-  interface: { NoteOps: NoteOpsMethods },
-  class: { Note: NoteMethods },
-}

package/template/methods/note.ts

@@ -1,131 +0,0 @@
-/**
- * Note context — method LOGIC, written once, transport-agnostic.
- *
- * Each handler touches the kernel ONLY through `kernel.call(...)` (the universal
- * syscalls) plus its `params` and, for instance methods, the source node's
- * `path.raw`. Address callables/edges with layout-independent forms — a
- * `ClassPath` for the edge class, the `<id>::link` instance form, and an
- * `@<id>` id-form target. Reserve an absolute path string for a node *location*.
- */
-import { K } from '@astrale-os/kernel-core'
-
-import { D } from '../schema/compiled'
-
-/** The minimal kernel surface the worker runtime exposes to a handler. */
-export type CallableKernel = { call(path: string, params: unknown): Promise<unknown> }
-
-const NODE_CREATE = K.Node.createNode.path.method.raw
-const NAME_KEY = K.Named.name.key
-const NOTE_CLASS = D.Note.path.class.raw
-const REFERENCES_EDGE = D.references.path.class.raw
-const TITLE_KEY = D.Note.title.key
-const BODY_KEY = D.Note.body.key
-
-/** Notes live under a `/notes` folder at the graph root (created by `seed`). */
-const NOTES_PARENT = '/notes'
-
-/** URL-safe slug + short random suffix to dodge same-ms collisions. */
-function slugify(text: string): string {
-  const stem =
-    text
-      .toLowerCase()
-      .normalize('NFD')
-      .replace(/[̀-ͯ]/g, '')
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-|-$/g, '')
-      .slice(0, 40) || 'note'
-  return `${stem}-${Date.now().toString(36).slice(-4)}${Math.random().toString(36).slice(2, 6)}`
-}
-
-/** `NoteOps.createNote` (static) — create a Note under `/notes`. */
-export async function createNote(
-  kernel: CallableKernel,
-  params: { title: string; body: string },
-): Promise<{ id: string; path: string }> {
-  const path = `${NOTES_PARENT}/${slugify(params.title)}`
-  const created = (await kernel.call(NODE_CREATE, {
-    class: NOTE_CLASS,
-    path,
-    props: { [NAME_KEY]: params.title, [TITLE_KEY]: params.title, [BODY_KEY]: params.body },
-  })) as { id: string }
-  return { id: created.id, path }
-}
-
-/** `Note.reference` (instance) — link this Note to another via `references`. */
-export async function reference(
-  kernel: CallableKernel,
-  selfPathRaw: string,
-  params: { target: string },
-): Promise<{ linked: string }> {
-  await kernel.call(`${selfPathRaw}::link`, {
-    edgeClass: REFERENCES_EDGE,
-    target: params.target,
-  })
-  return { linked: params.target }
-}
-
-const FOLDER_CLASS = K.Folder.path.class.raw
-
-const STARTERS: ReadonlyArray<{ slug: string; title: string; body: string }> = [
-  {
-    slug: 'welcome',
-    title: 'Welcome',
-    body: 'This note was created by `seed` after install. Edit it freely.',
-  },
-  { slug: 'getting-started', title: 'Getting started', body: 'Call `createNote` to add your own.' },
-]
-
-function isPathConflict(e: unknown): boolean {
-  return e instanceof Error && e.message.includes('PATH_CONFLICT')
-}
-
-/**
- * `Note.seed` (static) — the domain's post-install bootstrap. The kernel calls
- * it ONCE after install, as __SYSTEM__ (see `postInstall` in
- * `astrale.config.ts`), so the domain can lay down its initial state and
- * grants: the `/notes` folder, a couple of starter Notes, and a `references`
- * edge between them. Idempotent: a re-run swallows `PATH_CONFLICT` per node.
- */
-export async function seed(kernel: CallableKernel): Promise<{ seeded: number }> {
-  // 1. The `/notes` folder at the graph root.
-  try {
-    await kernel.call(NODE_CREATE, {
-      class: FOLDER_CLASS,
-      path: NOTES_PARENT,
-      props: { [NAME_KEY]: 'notes' },
-    })
-  } catch (e) {
-    if (!isPathConflict(e)) throw e
-  }
-
-  // 2. A couple of starter Notes under it.
-  const ids: Record<string, string> = {}
-  let seeded = 0
-  for (const s of STARTERS) {
-    try {
-      const created = (await kernel.call(NODE_CREATE, {
-        class: NOTE_CLASS,
-        path: `${NOTES_PARENT}/${s.slug}`,
-        props: { [NAME_KEY]: s.title, [TITLE_KEY]: s.title, [BODY_KEY]: s.body },
-      })) as { id: string }
-      ids[s.slug] = created.id
-      seeded++
-    } catch (e) {
-      if (!isPathConflict(e)) throw e
-    }
-  }
-
-  // 3. Link welcome → getting-started with a `references` edge (id-form on
-  //    both sides — layout-independent). Best-effort.
-  const from = ids.welcome
-  const to = ids['getting-started']
-  if (from && to) {
-    try {
-      await kernel.call(`@${from}::link`, { edgeClass: REFERENCES_EDGE, target: `@${to}` })
-    } catch (e) {
-      if (!isPathConflict(e)) throw e
-    }
-  }
-
-  return { seeded }
-}

package/template/schema/compiled.ts

@@ -1,14 +0,0 @@
-/**
- * Compiled view of the schema — resolved class/interface paths + prop keys.
- * `compileDomain` is pure (no env), so this is safe to import from the worker
- * and from build tooling alike.
- *
- *   - `D.Note.path.class.raw`        → the Note ClassPath, graph-facing form
- *   - `D.references.path.class.raw`  → the references edge ClassPath
- *   - `D.Note.title.key`            → the qualified prop key for `title`
- */
-import { compileDomain, type Domain } from '@astrale-os/kernel-core/domain'
-
-import { schema } from './index'
-
-export const D: Domain<typeof schema> = compileDomain(schema)

package/template/schema/note.ts

@@ -1,64 +0,0 @@
-/**
- * Note context — the domain's single bounded slice.
- *
- * One file per context: a class (or a few tightly-related classes) plus the
- * edges that bind them. Here that is the `NoteOps` interface, the `Note`
- * class that implements it, and the `references` edge from one Note to
- * another. To grow the domain, add `schema/<context>.ts` and register its
- * members in `schema/index.ts`.
- *
- *   - Interface `NoteOps`   one static op, `createNote`. Static → the impl
- *                           gets no `self`; it creates a brand-new Note.
- *   - Class `Note`          implements `[NoteOps, Container]`, inheriting
- *                           `createNote` and adding the instance method
- *                           `reference` (links this Note to another).
- *   - Edge `references`     Note → Note. Materialized at runtime by
- *                           `reference` (and by `seed`).
- */
-import { edgeClass, KernelSchema, nodeClass, nodeInterface } from '@astrale-os/kernel-core'
-import { fn } from '@astrale-os/kernel-dsl'
-import { z } from 'zod'
-
-/**
- * Thin ref to a created node — what node-creating ops return. A remote method
- * returns a plain `{ id, path }`, never `ref(SELF)` (whose full-Node value
- * does not round-trip over the worker wire).
- */
-export const NoteRef = z.object({ id: z.string(), path: z.string() })
-
-export const NoteOps = nodeInterface({
-  methods: {
-    createNote: fn({
-      static: true,
-      params: { title: z.string(), body: z.string() },
-      returns: NoteRef,
-    }),
-  },
-})
-
-export const Note = nodeClass({
-  implements: [NoteOps, KernelSchema.interfaces.Container],
-  props: {
-    title: z.string(),
-    body: z.string(),
-  },
-  methods: {
-    reference: fn({
-      params: { target: z.string() },
-      returns: z.object({ linked: z.string() }),
-    }),
-    // Post-install bootstrap (wired as `postInstall` in astrale.config.ts).
-    // Static: the kernel calls it ONCE after install, as __SYSTEM__, with no
-    // `self`. Must stay idempotent — a re-install runs it again.
-    seed: fn({
-      static: true,
-      returns: z.object({ seeded: z.number().int() }),
-    }),
-  },
-})
-
-export const references = edgeClass(
-  { as: 'from_note', types: [Note] },
-  { as: 'to_note', types: [Note] },
-  { props: { reason: z.string().optional() } },
-)

package/template/views/note.ts

@@ -1,21 +0,0 @@
-/**
- * `ui-note` — a rich View backed by the `client/` React + Vite SPA (instead of
- * an inline-HTML `render` like `welcome`). Because it declares `mount` rather
- * than `render`, the View node's iframe binding points at `<serving url>/ui/note`
- * — the SDK stamps it from the worker's live URL when it builds the install
- * bundle. The Cloudflare adapter serves `/ui/*` from `../dist-client` (built by
- * `client/` with base `/ui/`) via the Worker's `ASSETS` binding.
- *
- * `viewFor: selfOf(Note)` attaches a `view_for` edge to the `Note` class
- * meta-node, so the GUI offers this view for any Note instance.
- */
-import { selfOf } from '@astrale-os/kernel-dsl'
-import { defineView } from '@astrale-os/sdk'
-
-import { Note } from '../schema/note'
-
-export const note = defineView({
-  auth: 'public',
-  mount: '/ui/note',
-  viewFor: selfOf(Note),
-})