@astrale-os/adapter-cloudflare 0.1.9 → 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/core/keys.ts

@@ -1,28 +0,0 @@
-/**
- * Compiled-schema accessors — the ONE place class paths, method paths, and
- * qualified prop keys come from. Pure (schema-derived); never hand-write key
- * strings. `D` (the compiled domain) is the public `schema/compiled` entry,
- * re-exported here so `core/` and `runtime/` read it — plus the named keys —
- * from one place.
- */
-import { K } from '@astrale-os/kernel-core'
-
-import { D } from '../schema/compiled'
-
-export { D, K }
-
-/** Kernel ops/classes the logic addresses. */
-export const NODE_CREATE = K.Node.createNode.path.method.raw
-export const FOLDER_CLASS = K.Folder.path.class.raw
-export const NAME_KEY = K.Named.name.key
-
-/** Domain class paths. */
-export const NOTE_CLASS = D.Note.path.class.raw
-export const REFERENCES_EDGE = D.references.path.class.raw
-
-/** Qualified storage keys for Note node props. */
-export const NOTE_KEYS = {
-  title: D.Note.title.key,
-  body: D.Note.body.key,
-  summary: D.Note.summary.key,
-} as const

package/template/core/note.ts

@@ -1,148 +0,0 @@
-/**
- * Note context — method LOGIC, written once, transport-agnostic and testable.
- *
- * Each handler touches the kernel ONLY through `kernel.call(...)` (the universal
- * syscalls) plus its `params`, the resolved `Summarizer` PORT, and — for
- * instance methods — the source node's `path.raw`. It never names `fetch`, the
- * worker `env`, or a concrete provider: the port arrives ready-to-use from
- * `runtime/` (which built it from `deps`). Address callables/edges with
- * layout-independent forms — a `ClassPath` for the edge class, the `<id>::link`
- * instance form, and an `@<id>` id-form target.
- */
-import type { Summarizer } from '../integrations/summary/port'
-import {
-  FOLDER_CLASS,
-  NAME_KEY,
-  NODE_CREATE,
-  NOTE_CLASS,
-  NOTE_KEYS,
-  REFERENCES_EDGE,
-} from './keys'
-
-/** The minimal kernel surface the worker runtime exposes to a handler. */
-export type CallableKernel = { call(path: string, params: unknown): Promise<unknown> }
-
-/** 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`, stamping a
- * one-line `summary` from the resolved summarizer port (the external-API seam).
- */
-export async function createNote(
-  kernel: CallableKernel,
-  summarizer: Summarizer,
-  params: { title: string; body: string },
-): Promise<{ id: string; path: string }> {
-  const summary = await summarizer.summarize(params.body)
-  const path = `${NOTES_PARENT}/${slugify(params.title)}`
-  const created = (await kernel.call(NODE_CREATE, {
-    class: NOTE_CLASS,
-    path,
-    props: {
-      [NAME_KEY]: params.title,
-      [NOTE_KEYS.title]: params.title,
-      [NOTE_KEYS.body]: params.body,
-      [NOTE_KEYS.summary]: summary,
-    },
-  })) 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 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 `domain.ts`), so
- * the domain can lay down its initial state: the `/notes` folder, a couple of
- * starter Notes (each summarized through the port), and a `references` edge
- * between them. Idempotent: a re-run swallows `PATH_CONFLICT` per node.
- */
-export async function seed(
-  kernel: CallableKernel,
-  summarizer: Summarizer,
-): 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,
-          [NOTE_KEYS.title]: s.title,
-          [NOTE_KEYS.body]: s.body,
-          [NOTE_KEYS.summary]: await summarizer.summarize(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/integrations/summary/heuristic.ts

@@ -1,25 +0,0 @@
-/**
- * Heuristic summarizer — the ZERO-CONFIG default adapter. No network, no
- * secrets: a fresh scaffold summarizes notes out of the box on `pnpm dev`.
- * It takes the first sentence (clamped), which is good enough to demonstrate
- * the seam; flip `NOTE_SUMMARIZER=http` (see `registry.ts`) for a real model.
- */
-import type { Summarizer } from './port'
-
-const DEFAULT_MAX_LENGTH = 140
-
-/** Build the local, dependency-free summarizer. */
-export function createHeuristicSummarizer(opts: { maxLength?: number } = {}): Summarizer {
-  const maxLength = opts.maxLength ?? DEFAULT_MAX_LENGTH
-  return {
-    summarize(body) {
-      const trimmed = body.trim()
-      // First sentence, else the whole (clamped) body.
-      const firstSentence = trimmed.split(/(?<=[.!?])\s/)[0] ?? trimmed
-      const text = firstSentence || trimmed
-      const summary =
-        text.length <= maxLength ? text : `${text.slice(0, maxLength - 1).trimEnd()}…`
-      return Promise.resolve(summary)
-    },
-  }
-}

package/template/integrations/summary/http.ts

@@ -1,69 +0,0 @@
-/**
- * HTTP summarizer — the REAL external-API adapter: a single OpenAI-compatible
- * `POST /chat/completions` call. This is the shape your domain's external calls
- * take — config + secret from `env`, a timeout via `AbortSignal`, upstream
- * detail preserved in `cause`. Selected by `NOTE_SUMMARIZER=http` (registry.ts);
- * the default stays the no-network `heuristic` adapter so a fresh scaffold needs
- * no secret.
- *
- * `baseUrl` is anything OpenAI-compatible — `https://api.openai.com/v1`, a
- * Workers-AI gateway, or your OWN `ai-gateway` domain's `/v1` surface. On a soft
- * upstream failure it falls back to the heuristic rather than throwing: a flaky
- * summarizer must never block creating a note (see the port contract).
- */
-import { createHeuristicSummarizer } from './heuristic'
-import type { Summarizer } from './port'
-
-export interface HttpSummarizerConfig {
-  /** Bearer token for the upstream (a secret — ships via `.env.<env>`). */
-  apiKey: string
-  /** OpenAI-compatible base URL, e.g. `https://api.openai.com/v1`. */
-  baseUrl: string
-  /** Model id, e.g. `gpt-4o-mini`. */
-  model: string
-  /** Upstream request timeout in ms (default 15000). */
-  timeoutMs?: number
-}
-
-const DEFAULT_TIMEOUT_MS = 15_000
-const SYSTEM_PROMPT = 'Summarize the user note in one short sentence. Reply with the summary only.'
-
-/** Build the OpenAI-compatible HTTP summarizer (with a heuristic fallback). */
-export function createHttpSummarizer(config: HttpSummarizerConfig): Summarizer {
-  const fallback = createHeuristicSummarizer()
-  const endpoint = `${config.baseUrl.replace(/\/+$/, '')}/chat/completions`
-  return {
-    async summarize(body) {
-      try {
-        const res = await fetch(endpoint, {
-          method: 'POST',
-          headers: {
-            'content-type': 'application/json',
-            authorization: `Bearer ${config.apiKey}`,
-          },
-          body: JSON.stringify({
-            model: config.model,
-            messages: [
-              { role: 'system', content: SYSTEM_PROMPT },
-              { role: 'user', content: body },
-            ],
-          }),
-          signal: AbortSignal.timeout(config.timeoutMs ?? DEFAULT_TIMEOUT_MS),
-        })
-        if (!res.ok) {
-          throw new Error(`summarizer upstream returned ${res.status}`, {
-            cause: await res.text().catch(() => undefined),
-          })
-        }
-        const data = (await res.json()) as {
-          choices?: Array<{ message?: { content?: string } }>
-        }
-        const text = data.choices?.[0]?.message?.content?.trim()
-        return text || (await fallback.summarize(body))
-      } catch {
-        // Soft-fail: never block a note create on the summarizer.
-        return fallback.summarize(body)
-      }
-    },
-  }
-}

package/template/integrations/summary/port.ts

@@ -1,21 +0,0 @@
-/**
- * Summarizer — the PORT between the domain's logic and whatever produces a
- * note's one-line summary. This is the external-API seam every real domain has
- * (here: an LLM/summarization API), reduced to the narrowest interface the
- * logic needs.
- *
- * `core/` logic depends on THIS interface only — never on `fetch`, an SDK, or
- * `env`. Adapters in this folder implement it: `heuristic.ts` (the zero-config
- * default, no network) and `http.ts` (a real OpenAI-compatible call). The
- * registry picks one from `env`; the handler logic only ever sees the resolved
- * port. Swap or add a provider = one adapter + one arm in `registry.ts`.
- */
-export interface Summarizer {
-  /**
-   * Produce a short, single-line summary of `body`. Called once per note
-   * create/seed, so keep it fast and resilient. Adapters MUST resolve to a
-   * usable string (fall back to a heuristic rather than throwing on a soft
-   * upstream failure) — a flaky summarizer should never block creating a note.
-   */
-  summarize(body: string): Promise<string>
-}