@astrale-os/adapter-cloudflare 0.1.0

package/src/params.ts

@@ -0,0 +1,49 @@
+/**
+ * `CloudflareParams` — the provider-typed config for the Cloudflare adapter.
+ *
+ * One type covers every env; per-env differences are just optional fields. The
+ * same `{ dev, prod, canary, … }` map a developer writes in `astrale.config.ts`
+ * is `Record<string, CloudflareParams>`.
+ *
+ * Three deployment shapes fall out of which fields are set:
+ *   • dev (local)      — `watch()` runs `wrangler dev`; URL = http://localhost:<port>
+ *   • dev-remote       — `deploy()` with no `route`; URL = https://<name>.<sub>.workers.dev
+ *   • remote (custom)  — `deploy()` with `route`; URL = https://<route>
+ */
+export interface CloudflareParams {
+  /**
+   * Custom route / hostname for a routed deploy, e.g. `'crm.acme.dev'`. Omit to
+   * deploy to `*.workers.dev`. Ignored by local `wrangler dev` (URL is
+   * localhost) but still used as the placeholder base domain there.
+   */
+  route?: string
+  /** Gitignored secrets file (whole contents = secrets), e.g. `'.env.dev'`. */
+  secrets?: string
+  /** Local dev port for `wrangler dev`. Default 8787. */
+  port?: number
+  /** Override the Worker name. Default: derived from the domain origin. */
+  workerName?: string
+  /** Run `wrangler dev --remote` (edge isolate) instead of local workerd. */
+  remote?: boolean
+  /** Extra plain (non-secret) vars to inject as Worker vars. */
+  vars?: Record<string, string>
+  /**
+   * Escape hatch: raw wrangler config deep-merged over the generated base. Use
+   * it to declare extra bindings the adapter has no typed field for — KV, R2,
+   * D1, queues, service bindings, extra `compatibility_flags`, cron `triggers`,
+   * Hyperdrive, etc.
+   *
+   *   wrangler: {
+   *     kv_namespaces: [{ binding: 'CACHE', id: '<kv-id>' }],
+   *     r2_buckets: [{ binding: 'FILES', bucket_name: 'my-bucket' }],
+   *   }
+   *
+   * The merge is additive: arrays concat (so your `services` keep the adapter's
+   * `SELF` binding and your `compatibility_flags` keep `nodejs_compat`); new
+   * keys are added as-is. The adapter-owned keys `name`, `main`, `assets`,
+   * `routes` are rejected — use `workerName` and `route` instead. Avoid
+   * the reserved binding names `SELF` and `ASSETS`. Durable Objects need extra
+   * worker-entry codegen and aren't supported through this field yet.
+   */
+  wrangler?: Record<string, unknown>
+}

package/src/parse-output.ts

@@ -0,0 +1,54 @@
+/**
+ * Pure parsers for `wrangler` stdout. Kept separate from the process-spawning in
+ * `wrangler-cli.ts` so the brittle bit — scraping wrangler's human output — is
+ * unit-testable against captured fixtures without shelling out.
+ */
+
+const READY_RE = /(?:Ready on|Listening on|⎔.*?at)\s+(https?:\/\/[^\s]+)/i
+const WORKERS_DEV_RE = /(https:\/\/[^\s]+\.workers\.dev)/i
+
+/**
+ * Local dev URL from `wrangler dev` output, normalized to an origin on the given
+ * port. Returns `undefined` when the output hasn't reported readiness yet.
+ *
+ * The fallback (when no explicit "Ready on" line) only accepts a localhost URL
+ * on the EXPECTED port — wrangler may print unrelated localhost URLs (e.g. an
+ * inspector/devtools endpoint on a different port) before readiness, and taking
+ * one of those would point `astrale instance install <url>` at a dead endpoint.
+ */
+export function parseDevReadyUrl(text: string, port: number): string | undefined {
+  const ready = READY_RE.exec(text)
+  if (ready) return normalizeLocal(ready[1]!, port)
+  // `port` is a number, so it's safe to interpolate into the pattern. The
+  // negative lookahead stops `:8787` from matching inside `:87870`.
+  const localhostOnPort = new RegExp(
+    `(https?://(?:localhost|127\\.0\\.0\\.1):${port})(?![0-9])`,
+    'i',
+  )
+  const m = localhostOnPort.exec(text)
+  return m ? normalizeLocal(m[1]!, port) : undefined
+}
+
+/**
+ * Authoritative public URL from `wrangler deploy` output. A custom-domain
+ * `route` wins (the deploy attaches it); otherwise the printed `*.workers.dev`
+ * URL. Returns `undefined` when neither is available (caller surfaces the raw
+ * output).
+ */
+export function parseDeployUrl(text: string, route?: string): string | undefined {
+  if (route) return `https://${route.replace(/\/.*$/, '')}`
+  const m = WORKERS_DEV_RE.exec(text)
+  return m ? m[1] : undefined
+}
+
+/** Normalize a local dev URL to an origin: `0.0.0.0` → `localhost`, fill the port. */
+export function normalizeLocal(url: string, port: number): string {
+  try {
+    const u = new URL(url)
+    if (u.hostname === '0.0.0.0') u.hostname = 'localhost'
+    if (!u.port) u.port = String(port)
+    return u.origin
+  } catch {
+    return `http://localhost:${port}`
+  }
+}

package/src/wrangler-cli.ts

@@ -0,0 +1,240 @@
+/**
+ * Thin wrapper around the `wrangler` binary — the only place the adapter shells
+ * out. `watch` runs `wrangler dev` (local workerd) and resolves once the worker
+ * reports its local URL; `deploy` runs `wrangler deploy` and parses the
+ * authoritative public URL from the output; secrets go through `wrangler secret
+ * bulk`. The wrangler binary is resolved from the project's `node_modules/.bin`,
+ * falling back to `npx wrangler`.
+ */
+
+import type { ChildProcess } from 'node:child_process'
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { parseDeployUrl, parseDevReadyUrl } from './parse-output'
+
+function wranglerCommand(projectDir: string): { cmd: string; prefix: string[] } {
+  const local = join(projectDir, 'node_modules', '.bin', 'wrangler')
+  if (existsSync(local)) return { cmd: local, prefix: [] }
+  return { cmd: 'npx', prefix: ['--yes', 'wrangler'] }
+}
+
+export interface DevHandle {
+  url: string
+  stop(): Promise<void>
+}
+
+export async function runWranglerDev(args: {
+  projectDir: string
+  configPath: string
+  port: number
+  remote: boolean
+  onReload: () => void
+  onLog?: (line: string) => void
+}): Promise<DevHandle> {
+  const { cmd, prefix } = wranglerCommand(args.projectDir)
+  const wranglerArgs = [
+    ...prefix,
+    'dev',
+    '--config',
+    args.configPath,
+    '--port',
+    String(args.port),
+    '--local-protocol',
+    'http',
+    '--ip',
+    '127.0.0.1',
+    ...(args.remote ? ['--remote'] : []),
+  ]
+
+  const child = spawn(cmd, wranglerArgs, {
+    cwd: args.projectDir,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, WRANGLER_SEND_METRICS: 'false' },
+  })
+
+  const fallbackUrl = `http://localhost:${args.port}`
+  let resolved = false
+
+  const url = await new Promise<string>((resolve, reject) => {
+    const onData = (buf: Buffer) => {
+      const text = buf.toString()
+      for (const line of text.split('\n')) {
+        if (line.trim()) args.onLog?.(line)
+      }
+      if (!resolved) {
+        const ready = parseDevReadyUrl(text, args.port)
+        if (ready) {
+          resolved = true
+          resolve(ready)
+        }
+      } else if (/Reloading|Detected changes|Updated/i.test(text)) {
+        args.onReload()
+      }
+    }
+    child.stdout?.on('data', onData)
+    child.stderr?.on('data', onData)
+    child.on('exit', (code) => {
+      if (!resolved) {
+        resolved = true
+        reject(new Error(`wrangler dev exited before becoming ready (code ${code ?? 'null'}).`))
+      }
+    })
+    child.on('error', (err) => {
+      if (!resolved) {
+        resolved = true
+        reject(err)
+      }
+    })
+    // Safety net: if we never matched a URL but the process is alive, assume the
+    // conventional localhost URL after a grace period.
+    setTimeout(() => {
+      if (!resolved && child.exitCode === null) {
+        resolved = true
+        resolve(fallbackUrl)
+      }
+    }, 15_000).unref?.()
+  })
+
+  return { url, stop: () => stopChild(child) }
+}
+
+export interface DeployArgs {
+  configPath: string
+  /** SELF-less config for the first-deploy two-pass (see `deployWithSelfFallback`). */
+  fallbackConfigPath?: string
+  /** The worker's own name, to scope the self-binding-missing detection. */
+  workerName?: string
+  route?: string
+  onLog?: (line: string) => void
+}
+
+export async function runWranglerDeploy(
+  args: DeployArgs & { projectDir: string },
+): Promise<{ url: string; raw: string }> {
+  const { cmd, prefix } = wranglerCommand(args.projectDir)
+  const deploy = (configPath: string) =>
+    runCapture(cmd, [...prefix, 'deploy', '--config', configPath], args.projectDir, args.onLog)
+  return deployWithSelfFallback(deploy, args)
+}
+
+/**
+ * Deploy with a one-time SELF-binding first-deploy recovery. A fresh worker that
+ * declares a `services: SELF` binding can't deploy (its own script doesn't exist
+ * yet); on THAT specific failure we deploy the SELF-less fallback to create the
+ * script, then redeploy WITH SELF so autobinding works. Steady state (every
+ * deploy after the first) is a single pass. The `deploy` runner is injected so
+ * the orchestration is unit-testable without shelling out.
+ */
+export async function deployWithSelfFallback(
+  deploy: (configPath: string) => Promise<{ code: number; out: string }>,
+  args: DeployArgs,
+): Promise<{ url: string; raw: string }> {
+  let { code, out } = await deploy(args.configPath)
+
+  if (code !== 0 && args.fallbackConfigPath && isSelfBindingMissing(out, args.workerName)) {
+    args.onLog?.(
+      'SELF service binding not resolvable yet (first deploy) — creating the worker, then re-binding SELF',
+    )
+    const first = await deploy(args.fallbackConfigPath)
+    if (first.code !== 0) {
+      throw new Error(
+        `wrangler deploy (no-self pass) failed (code ${first.code}):\n${first.out.slice(-2000)}`,
+      )
+    }
+    ;({ code, out } = await deploy(args.configPath))
+  }
+
+  if (code !== 0) {
+    throw new Error(`wrangler deploy failed (code ${code}):\n${out.slice(-2000)}`)
+  }
+  const url = parseDeployUrl(out, args.route)
+  if (!url) {
+    throw new Error(`could not determine deployed URL from wrangler output:\n${out.slice(-2000)}`)
+  }
+  return { url, raw: out }
+}
+
+/**
+ * True when wrangler failed specifically because the worker's OWN `SELF` service
+ * binding can't resolve yet (first deploy of a fresh script). Requires the
+ * worker name so an unrelated missing-service error doesn't trigger the two-pass.
+ */
+export function isSelfBindingMissing(out: string, workerName?: string): boolean {
+  const bindingError =
+    /could not resolve binding/i.test(out) ||
+    /service\b[^\n]*\bnot found/i.test(out) ||
+    /script\b[^\n]*\bnot found/i.test(out)
+  if (!bindingError || !/\bSELF\b/.test(out)) return false
+  return workerName ? out.includes(workerName) : true
+}
+
+export async function bulkPutSecrets(args: {
+  projectDir: string
+  configPath: string
+  secrets: Record<string, string>
+  onLog?: (line: string) => void
+}): Promise<void> {
+  const names = Object.keys(args.secrets)
+  if (names.length === 0) return
+  const { cmd, prefix } = wranglerCommand(args.projectDir)
+  const dir = await mkdtemp(join(tmpdir(), 'astrale-secrets-'))
+  const file = join(dir, 'secrets.json')
+  try {
+    await writeFile(file, JSON.stringify(args.secrets))
+    const { code, out } = await runCapture(
+      cmd,
+      [...prefix, 'secret', 'bulk', file, '--config', args.configPath],
+      args.projectDir,
+      args.onLog,
+    )
+    if (code !== 0) {
+      throw new Error(`wrangler secret bulk failed (code ${code}):\n${out.slice(-1500)}`)
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}
+
+// ── internals ──────────────────────────────────────────────────────────────
+
+function runCapture(
+  cmd: string,
+  args: string[],
+  cwd: string,
+  onLog?: (line: string) => void,
+): Promise<{ code: number; out: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, WRANGLER_SEND_METRICS: 'false' },
+    })
+    let out = ''
+    const onData = (buf: Buffer) => {
+      const text = buf.toString()
+      out += text
+      for (const line of text.split('\n')) if (line.trim()) onLog?.(line)
+    }
+    child.stdout?.on('data', onData)
+    child.stderr?.on('data', onData)
+    child.on('exit', (code) => resolve({ code: code ?? 1, out }))
+    child.on('error', reject)
+  })
+}
+
+async function stopChild(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null) return
+  await new Promise<void>((resolve) => {
+    child.on('exit', () => resolve())
+    child.kill('SIGTERM')
+    setTimeout(() => {
+      if (child.exitCode === null) child.kill('SIGKILL')
+      resolve()
+    }, 4000).unref?.()
+  })
+}

package/template/.env.example

@@ -0,0 +1,6 @@
+# Secrets for an env live in `.env.<env>` (e.g. .env.dev, .env.prod), pointed at
+# by `secrets:` in astrale.config.ts. The ENTIRE file is treated as secrets:
+# injected into the local runtime in dev, pushed to the Worker secret store in
+# prod. These files are gitignored — copy this to `.env.dev` and fill in.
+#
+# EXAMPLE_API_KEY=sk-...

package/template/README.md

@@ -0,0 +1,77 @@
+# astrale-domain
+
+A standalone [Astrale](https://astrale.ai) domain, deployed as a Cloudflare Worker.
+
+> **Requires [Bun](https://bun.sh)** — the `astrale-domain` CLI behind `pnpm dev`
+> / `pnpm prod` imports `astrale.config.ts` and your ★ files directly, so it
+> needs a TypeScript-native runtime.
+
+```bash
+pnpm install
+pnpm dev                          # wrangler dev → prints a local URL
+astrale instance install <url>    # mount it on an instance (CLI)
+pnpm prod                         # deploy prod → prints a URL
+```
+
+## What you write (★)
+
+```
+schema/      ★ classes + interfaces (the data model)
+methods/     ★ the execute() handlers
+views/       ★ iframe-mountable UIs
+functions/   ★ standalone Functions (e.g. the post-install seed)
+astrale.config.ts   identity (origin) · requires · postInstall · adapter
+```
+
+Everything else — the Worker entry, the wrangler config, the signing identity —
+is generated under `.astrale/` (gitignored) by the adapter. You never edit it.
+
+## The signing identity (back it up!)
+
+The first `pnpm dev`/`pnpm prod` generates an Ed25519 keypair at
+`.astrale/identity.ts`. That private key **is** this domain's identity: every
+instance that installs the domain verifies its credentials against it. The file
+is gitignored, so a fresh clone or a CI runner silently mints a **new** key —
+and redeploying with a new key breaks verification on every existing install.
+Back it up, or move it to a managed secret before deploying from more than one
+machine.
+
+## Extra bindings (KV, R2, D1, queues, …)
+
+The adapter owns the wrangler config, but you can declare extra bindings from
+`astrale.config.ts` via a `wrangler` block on any env — it's deep-merged into
+the generated config:
+
+```ts
+adapter: cloudflare({
+  dev: {
+    secrets: '.env.dev',
+    wrangler: {
+      kv_namespaces: [{ binding: 'CACHE', id: '<kv-id>' }],
+      r2_buckets: [{ binding: 'FILES', bucket_name: 'my-bucket' }],
+    },
+  },
+})
+```
+
+The merge is additive — arrays concat, so your `services` keep the adapter's
+`SELF` binding and your `compatibility_flags` keep `nodejs_compat`. The
+adapter-owned keys `name`, `main`, `assets`, `routes` are rejected (use
+`workerName` and `route`/`zone`); don't reuse the reserved binding names
+`SELF`/`ASSETS`. Durable Objects aren't supported through this field yet.
+
+## The loop
+
+- **Edit a handler** (`methods/`) → hot-reloads at the same URL. Nothing to reinstall.
+- **Edit the schema** (`schema/`) → rebuilds the graph; reinstall with `astrale instance install <url>`.
+- **`postInstall`** (the static `Note.seed` method) runs once after install, as
+  the system identity, so the domain can seed itself and set its own grants. It
+  must be a class-hosted static addressed by a typed colon-path
+  (`/:origin:class.X:seed`) — the kernel refuses tree paths here.
+
+## Identity
+
+`origin` (in `astrale.config.ts`, defaulting to `schema.domain`) is the domain's
+stable name — the same in every env; only the URL changes. The deployed Worker
+computes its own `binding.remoteUrl` at install from its public URL, so there's
+no hardcoded URL anywhere in your code.

package/template/astrale.config.ts

@@ -0,0 +1,35 @@
+/**
+ * astrale.config.ts — the single source of truth for this domain's identity and
+ * deployment. `origin` defaults to `schema.domain`; `postInstall` points at the
+ * static `Note.seed` method the kernel runs after install (a typed colon-path —
+ * the kernel refuses tree paths here, since they can't prove their origin);
+ * `adapter` chooses the target.
+ *
+ *   pnpm dev                       # wrangler dev → prints a local URL
+ *   astrale instance install <url> # mount it on an instance
+ *   pnpm prod                      # deploy prod → prints a URL
+ */
+import { cloudflare } from '@astrale-os/adapter-cloudflare'
+import { defineDomain } from '@astrale-os/devkit'
+
+import { schema } from './schema'
+
+export default defineDomain({
+  schema,
+  // origin defaults to `schema.domain`. Set it to another domain's origin to
+  // deliberately alias that identity (you'll get a DANGER prompt at install).
+  postInstall: `/:${schema.domain}:class.Note:seed`,
+  adapter: cloudflare({
+    // Local dev: `wrangler dev`. No route → URL is http://localhost:8787.
+    dev: { secrets: '.env.dev' },
+    // Custom-domain prod. Drop `route` to ship to *.workers.dev instead.
+    prod: { route: 'astrale-domain.example.dev', secrets: '.env.prod' },
+    // Need extra bindings (KV, R2, D1, queues, …)? Add a `wrangler` block to any
+    // env — it's deep-merged into the generated config (arrays concat, so the
+    // adapter's `SELF` binding and `nodejs_compat` are preserved):
+    //   dev: {
+    //     secrets: '.env.dev',
+    //     wrangler: { kv_namespaces: [{ binding: 'CACHE', id: '<kv-id>' }] },
+    //   },
+  }),
+})

package/template/client/README.md

@@ -0,0 +1,85 @@
+# astrale-domain-client — SPA for domain views
+
+A small React + Vite SPA that renders the domain's `ui-note` View. It is loaded
+inside an iframe mounted by the Astrale shell, runs the shell handshake to learn
+its target node id and a delegation token, fetches that Note from the kernel,
+and renders its title/body. Built into `../dist-client/` and served by the
+generated worker (`.astrale/`) under `/ui/*` via its `ASSETS` binding.
+
+## Self-contained on purpose
+
+This client depends only on `react`, `react-dom`, `vite`, and
+`@vitejs/plugin-react` — all on public npm. It does **not** import
+`@astrale-os/shell`, `@astrale-os/kernel-client`, or `@astrale-os/ui-components`,
+so the template builds with no registry auth and no workspace `link:`s. Two
+small subsets are reimplemented inline:
+
+- the shell child-handshake (`src/lib/shell.ts`), and
+- a minimal JSON kernel client (`src/lib/kernel.ts`).
+
+## Layout
+
+```
+src/
+  main.tsx              # entry → createRoot(App)
+  app.tsx               # the ui-note view (renders the loaded Note)
+  lib/
+    shell.ts            # inline shell child handshake (postMessage + MessagePort)
+    use-shell.ts        # React hook over the handshake (status + live session)
+    kernel.ts           # inline kernel JSON client (kernelCall + prop readers)
+    use-node.ts         # React hook: fetch a node via @<id>::get
+  styles.css            # self-contained styles (no Tailwind)
+__tests__/
+  harness.ts            # fake shell parent + fake kernel (fetch stub)
+  app.test.tsx          # handshake → render → setTarget → tokenRefresh
+  kernel.test.ts        # kernelCall wire shape + prop readers
+```
+
+## Dev loops
+
+```bash
+pnpm dev       # vite build --watch → ../dist-client/ (worker auto-reloads, no HMR)
+pnpm dev:hmr   # vite dev on http://127.0.0.1:5173/ (React fast-refresh)
+pnpm test      # vitest run (happy-dom; fake parent + fake kernel, JSON-only)
+```
+
+For HMR, set `VIEW_DEV_URL=http://127.0.0.1:5173` in the worker's `.dev.vars`;
+the generated worker forwards `/ui/*` to vite.
+
+## How it connects
+
+1. The domain declares the View in `../views/note.ts` with `mount: '/ui/note'`.
+   The SDK points the View node's iframe at `<serving url>/ui/note`.
+2. The shell mounts that iframe and completes the handshake: it transfers a
+   `MessagePort` and sends a `ctrl:handshake` carrying `kernelUrl`, a
+   `delegationToken` (+ `tokenExpiresAt`), and the `targetNodeId`. `useShell()`
+   surfaces a live session and tracks `setTarget` hot-swaps.
+3. `useNode(session, nodeId)` POSTs `@<id>::get` to `kernelUrl` with the
+   delegation token as `authorization` and renders the Note's `title`/`body`
+   (props are read by key suffix, since the domain origin is unknown at build
+   time). The iframe authenticates with the handshake token ONLY — the parent
+   minted it for this kernel, so the audience already matches (no cookie, no
+   whoami, no client-side minting).
+
+### Token refresh
+
+The parent pushes a fresh credential over the port as `ctrl:tokenRefresh`
+before the current one expires. `shell.ts` swaps it into a mutable `currentToken`
+so the next `kernelCall` (e.g. on the next `setTarget` or remount) uses it —
+`getToken()` always returns the live token, never the one captured at handshake.
+
+## Deferred — kept minimal on purpose
+
+The inline kernel client is **JSON-only** and read-only for this template:
+
+- no msgpack codec (the `application/vnd.astrale.kernel+msgpack` body),
+- no streaming (`output: 'stream'`) or binary (`output: 'binary'`) responses,
+- no redirect following — a `{ redirect }` envelope (remote-domain Functions)
+  throws rather than re-minting against the target worker,
+- no client-side credential minting / `whoami` (the handshake token is used
+  as-is), and
+- no writes — only `@<id>::get`.
+
+These all live in `@astrale-os/kernel-client` / `@astrale-os/shell`. To grow
+past the template, pull those in (and `link:` them in dev) instead of extending
+the inline subset.