@astrale-os/adapter-cloudflare 0.1.0

package/template/env.ts

@@ -0,0 +1,18 @@
+/**
+ * Worker runtime env. The adapter injects `WORKER_URL` and the bindings; your
+ * handlers receive this as `ctx.deps`. Secrets from `.env.<env>` arrive as
+ * extra string fields here. Add typed fields as you reference new secrets/vars.
+ */
+export interface Env {
+  /** The worker's canonical serving URL (its `iss` identity), injected by the
+   * adapter for routed deploys. Optional — dev / workers.dev resolve it from the
+   * per-request Host. */
+  WORKER_URL?: string
+  /** Workers Assets binding (serves the client SPA under /ui/*), when present. */
+  ASSETS?: { fetch(request: Request): Promise<Response> }
+  /** Self service binding (autobinding — a handler calling its own domain). */
+  SELF?: { fetch(request: Request): Promise<Response> }
+  /** Dev-only: forward /ui/* to a running Vite dev server. */
+  VIEW_DEV_URL?: string
+  [key: string]: unknown
+}

package/template/functions/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Function registry — one file per standalone Function under `functions/`,
+ * listed here. Each becomes a Function node at `/<origin>/core/functions/<key>`
+ * whose `binding.remoteUrl` the SDK stamps with the worker's public URL at
+ * install. (Note: the `postInstall` hook must be a CLASS-hosted static method —
+ * standalone Functions live at tree paths, which the kernel's origin guard
+ * refuses for postInstall.)
+ */
+export const functions = {}

package/template/methods/index.ts

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

@@ -0,0 +1,131 @@
+/**
+ * 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/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "astrale-domain",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astrale-domain dev",
+    "prod": "astrale-domain prod",
+    "deploy": "astrale-domain deploy",
+    "build": "astrale-domain build",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@astrale-os/adapter-cloudflare": ">=0.1.0 <1.0.0",
+    "@astrale-os/devkit": ">=0.1.0 <1.0.0",
+    "@astrale-os/kernel-core": ">=0.3.0 <1.0.0",
+    "@astrale-os/kernel-dsl": ">=0.1.0 <1.0.0",
+    "@astrale-os/sdk": ">=0.1.0 <1.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@typescript/native-preview": "latest",
+    "typescript": "~6.0.1-rc",
+    "wrangler": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/template/pnpm-workspace.yaml

@@ -0,0 +1,17 @@
+# The client SPA (served under /ui/*) is a workspace package, so a single
+# `pnpm install` at the project root installs both the domain and the client.
+packages:
+  - 'client'
+
+# pnpm blocks dependency build scripts by default; these need their postinstall
+# to run (workerd is wrangler's runtime — without it `pnpm dev`/`pnpm prod`
+# fail). Both spellings are set because pnpm renamed the key: v10 reads
+# `onlyBuiltDependencies`, v11+ reads `allowBuilds`; each ignores the other.
+onlyBuiltDependencies:
+  - esbuild
+  - sharp
+  - workerd
+allowBuilds:
+  esbuild: true
+  sharp: true
+  workerd: true

package/template/schema/compiled.ts

@@ -0,0 +1,14 @@
+/**
+ * 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/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Schema assembly — the one place the domain's contexts come together, and the
+ * single source of the domain's stable identity. `schema.domain` (the first arg
+ * to `defineSchema`) IS the origin: `astrale.config.ts` defaults `origin` to it,
+ * and the worker signs JWTs under it. The scaffolder set this string from your
+ * slug; change it here to rename the domain's identity.
+ *
+ * Add a context: author `schema/<context>.ts`, then import its members and list
+ * them in the `interfaces` / `classes` maps below.
+ */
+import { defineSchema, KernelSchema } from '@astrale-os/kernel-core'
+
+import { Note, NoteOps, references } from './note'
+
+export const schema = defineSchema('astrale-domain.example.dev', {
+  interfaces: { NoteOps },
+  classes: { Note, references },
+  imports: [KernelSchema],
+})
+
+export * from './note'

package/template/schema/note.ts

@@ -0,0 +1,64 @@
+/**
+ * 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/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["node"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["schema", "methods", "views", "functions", "env.ts", "astrale.config.ts"],
+  "exclude": ["node_modules", ".astrale", "dist-client"]
+}

package/template/views/index.ts

@@ -0,0 +1,10 @@
+/**
+ * View registry — one file per view under `views/`, assembled here. Slug = map
+ * key; each becomes a View node at `/<origin>/core/views/<slug>` whose iframe
+ * binding the SDK stamps with the worker's live serving URL when it builds the
+ * install bundle.
+ */
+import { note } from './note'
+import { welcome } from './welcome'
+
+export const views = { welcome, 'ui-note': note }

package/template/views/note.ts

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

package/template/views/welcome.ts

@@ -0,0 +1,35 @@
+/**
+ * `welcome` — a lightweight inline-HTML View, rendered straight from the worker
+ * (no SPA, no client bundle, no shell handshake). Because it has a `render`, the
+ * SDK mounts a worker route and the View node's iframe points at
+ * `<publicUrl>/views/welcome`. Add a rich, shell-connected view by dropping a
+ * `client/` SPA in and binding a View to `/ui/<route>` instead.
+ */
+import { defineView } from '@astrale-os/sdk'
+
+export const welcome = defineView({
+  auth: 'public',
+  render: ({ c }) =>
+    c.html(
+      `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>astrale domain</title>
+    <style>
+      body { font: 14px/1.6 system-ui, sans-serif; margin: 2rem; color: #111; max-width: 40rem; }
+      code { background: #f4f4f5; padding: 0.1rem 0.35rem; border-radius: 4px; }
+      h1 { font-size: 1.25rem; }
+    </style>
+  </head>
+  <body>
+    <h1>Your Astrale domain is live</h1>
+    <p>This inline-HTML view is rendered by the worker. The RPC surface and the
+       <code>seed</code> post-install hook run alongside it.</p>
+    <p>Edit <code>views/welcome.ts</code> to change this page — it hot-reloads at
+       the same URL.</p>
+  </body>
+</html>`,
+    ),
+})