@astrale-os/adapter-cloudflare 0.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@astrale-os/adapter-cloudflare",
+  "version": "0.1.0",
+  "description": "Deploy an Astrale domain as a standalone Cloudflare Worker",
+  "keywords": [
+    "adapter",
+    "astrale",
+    "cloudflare",
+    "domain",
+    "workers"
+  ],
+  "license": "MIT",
+  "author": "Astrale",
+  "files": [
+    "dist",
+    "src",
+    "template"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "jose": "^6.1.3",
+    "@astrale-os/devkit": "0.1.0"
+  },
+  "devDependencies": {
+    "@astrale-os/ox": ">=0.1.0 <1.0.0",
+    "@types/node": "^22.0.0",
+    "@typescript/native-preview": "latest",
+    "oxfmt": "latest",
+    "oxlint": "latest",
+    "typescript": "~6.0.1-rc",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run",
+    "lint": "oxlint .",
+    "format": "pnpm exec oxfmt --write .",
+    "format:check": "pnpm exec oxfmt --check .",
+    "build": "rm -rf dist && tsgo"
+  }
+}

package/src/client.ts

@@ -0,0 +1,54 @@
+/**
+ * Build the optional client SPA (the Views' UI). Best-effort: if the project
+ * has no `client/` or no resolvable Vite, we skip — the RPC surface and inline
+ * Views still work without a built SPA.
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+export async function buildClient(
+  clientDir: string,
+  projectDir: string,
+  onLog?: (line: string) => void,
+): Promise<void> {
+  const viteBin = [
+    join(clientDir, 'node_modules', '.bin', 'vite'),
+    join(projectDir, 'node_modules', '.bin', 'vite'),
+  ].find((p) => existsSync(p))
+  if (!viteBin) {
+    // The project has a client/ but its deps aren't installed — wrangler would
+    // otherwise fail cryptically on the missing dist-client assets dir. Fail
+    // loud with the fix (the client is a workspace package — one install covers it).
+    throw new Error(
+      `client build: vite not found in ${clientDir}. Run \`pnpm install\` at the project root ` +
+        `first (the client/ SPA is a workspace package).`,
+    )
+  }
+  const { code, out } = await runCapture(viteBin, ['build'], clientDir, onLog)
+  if (code !== 0) {
+    throw new Error(`client build failed (code ${code}):\n${out.slice(-1500)}`)
+  }
+}
+
+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'] })
+    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)
+  })
+}

package/src/cloudflare.ts

@@ -0,0 +1,228 @@
+/**
+ * `cloudflare(envs)` — the Cloudflare deployment adapter.
+ *
+ * Owns everything target-specific: it codegens the Worker entry + wrangler
+ * config (the dev never sees a `wrangler.jsonc`), builds the optional client
+ * SPA, and shells out to `wrangler`. `watch` → `wrangler dev` (local URL);
+ * `deploy` → `wrangler deploy` (workers.dev or a custom-domain URL); secrets →
+ * `wrangler secret bulk`. Both `watch` and `deploy` return the URL the devkit
+ * prints and `astrale instance install <url>` consumes.
+ */
+
+import type { DeployCtx, DomainAdapter, WatchCtx } from '@astrale-os/devkit'
+
+import { defineAdapter, hasStarModule } from '@astrale-os/devkit'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { CloudflareParams } from './params'
+
+import { buildClient } from './client'
+import { ensureIdentity } from './codegen/identity'
+import { generateWorkerEntry } from './codegen/worker'
+import { generateWranglerConfig } from './codegen/wrangler'
+import { bulkPutSecrets, runWranglerDeploy, runWranglerDev } from './wrangler-cli'
+
+const DEFAULT_PORT = 8787
+
+export function cloudflare(
+  envs: Record<string, CloudflareParams>,
+): DomainAdapter<CloudflareParams> {
+  return defineAdapter<CloudflareParams>({
+    name: 'cloudflare',
+    envs,
+
+    async watch(params, ctx) {
+      const { configPath, port } = await prepare(params, ctx, 'dev')
+      if (ctx.clientDir) await buildClient(ctx.clientDir, ctx.projectDir, logTo())
+      const handle = await runWranglerDev({
+        projectDir: ctx.projectDir,
+        configPath,
+        port,
+        remote: Boolean(params.remote),
+        onReload: ctx.onReload,
+        onLog: logTo(),
+      })
+      return { url: handle.url, stop: handle.stop }
+    },
+
+    async deploy(params, ctx) {
+      const {
+        configPath,
+        fallbackConfigPath,
+        workerName: name,
+      } = await prepare(params, ctx, 'deploy')
+      if (ctx.clientDir) await buildClient(ctx.clientDir, ctx.projectDir, logTo())
+      const { url } = await runWranglerDeploy({
+        projectDir: ctx.projectDir,
+        configPath,
+        workerName: name,
+        ...(fallbackConfigPath ? { fallbackConfigPath } : {}),
+        ...(params.route ? { route: params.route } : {}),
+        onLog: logTo(),
+      })
+      if (Object.keys(ctx.secrets).length > 0) {
+        await bulkPutSecrets({
+          projectDir: ctx.projectDir,
+          configPath,
+          secrets: ctx.secrets,
+          onLog: logTo(),
+        })
+      }
+      // A first deploy on a fresh `*.workers.dev` host can take ~30-60s to
+      // propagate; an `astrale instance install <url>` issued right away would
+      // 404 (Cloudflare 1042). Block until the URL actually serves so the
+      // install line we print is immediately actionable.
+      await waitUntilLive(url, logTo())
+      return { url }
+    },
+
+    secretsFile(params) {
+      return params.secrets
+    },
+  })
+}
+
+// ── codegen orchestration ──────────────────────────────────────────────────
+
+async function prepare(
+  params: CloudflareParams,
+  ctx: WatchCtx | DeployCtx,
+  mode: 'dev' | 'deploy',
+): Promise<{ configPath: string; fallbackConfigPath?: string; port: number; workerName: string }> {
+  const astraleDir = join(ctx.projectDir, '.astrale')
+  await mkdir(astraleDir, { recursive: true })
+  await ensureIdentity(astraleDir, ctx.domain.origin)
+
+  const name = workerName(params, ctx.domain.origin)
+  // Shared ★-files probe: must agree with the codegen's `import { views } from
+  // '../views'` resolution (folder index OR sibling file) — a folder-only
+  // existsSync would deploy a worker whose graph silently lacks a sibling-file
+  // module the diagnostic spec includes.
+  const hasViews = hasStarModule(ctx.projectDir, 'views')
+  const hasFunctions = hasStarModule(ctx.projectDir, 'functions')
+  const hasClient = Boolean(ctx.clientDir)
+
+  await writeFile(
+    join(astraleDir, 'worker.gen.ts'),
+    generateWorkerEntry({
+      origin: ctx.domain.origin,
+      ...(ctx.domain.postInstall ? { postInstall: ctx.domain.postInstall } : {}),
+      requires: ctx.domain.requires,
+      hasViews,
+      hasFunctions,
+      hasClient,
+    }),
+  )
+
+  // Pin the worker's canonical serving URL (its `iss` identity) for routed
+  // deploys: a routed worker may ALSO be reachable via `*.workers.dev`, so
+  // resolving the URL from the per-request Host would let `iss` drift between
+  // hostnames. Dev + workers.dev-only deploys are single-host, so the worker
+  // falls back to the per-request Host (always the canonical URL there).
+  // An explicit `vars.WORKER_URL` (e.g. a tunnel/proxy front) wins.
+  const workerUrl = mode === 'deploy' && params.route ? `https://${params.route}` : undefined
+
+  // Dev injects secrets as local vars (the gitignored .astrale config never
+  // ships); deploy keeps secrets out of the config and pushes them encrypted.
+  const vars = {
+    ...(workerUrl ? { WORKER_URL: workerUrl } : {}),
+    ...(mode === 'dev' ? { ...params.vars, ...ctx.secrets } : { ...params.vars }),
+  }
+
+  const baseConfig = {
+    workerName: name,
+    ...(mode === 'deploy' && params.route ? { route: params.route } : {}),
+    hasClient,
+    vars,
+    // Escape hatch: extra bindings (KV/R2/D1/queues/…) deep-merged on top. Same
+    // overlay in dev and deploy — it's infra, not env-specific plumbing — and it
+    // flows into both the SELF and the SELF-less fallback config below.
+    ...(params.wrangler ? { wrangler: params.wrangler } : {}),
+  }
+
+  // Always self-bind: it enables autobinding (a handler calling its own domain).
+  // Locally the dev registry resolves it; on deploy the first deploy of a fresh
+  // worker can't (the script doesn't exist yet), so we also emit a SELF-less
+  // fallback config that `runWranglerDeploy` uses for a one-time two-pass deploy.
+  const configPath = join(astraleDir, 'wrangler.gen.jsonc')
+  await writeFile(configPath, generateWranglerConfig({ ...baseConfig, selfBinding: true }))
+
+  let fallbackConfigPath: string | undefined
+  if (mode === 'deploy') {
+    fallbackConfigPath = join(astraleDir, 'wrangler.no-self.gen.jsonc')
+    await writeFile(
+      fallbackConfigPath,
+      generateWranglerConfig({ ...baseConfig, selfBinding: false }),
+    )
+  }
+
+  return {
+    configPath,
+    ...(fallbackConfigPath ? { fallbackConfigPath } : {}),
+    port: params.port ?? DEFAULT_PORT,
+    workerName: name,
+  }
+}
+
+/**
+ * Poll the deployed URL until the worker answers (anything but the Cloudflare
+ * 1042 "no script on this host" 404), or give up after `timeoutMs`. Resolves
+ * silently on the fast path; logs only when propagation actually makes us wait.
+ */
+async function waitUntilLive(
+  url: string,
+  onLog: (line: string) => void,
+  timeoutMs = 90_000,
+): Promise<void> {
+  const probe = new URL('/health', url)
+  const deadline = Date.now() + timeoutMs
+  let waited = false
+  for (;;) {
+    try {
+      const res = await fetch(probe, { redirect: 'manual' })
+      if (res.status !== 404) return
+    } catch {
+      // Network hiccup — treat like "not live yet" and keep polling.
+    }
+    if (Date.now() >= deadline) {
+      onLog(`URL not reachable yet after ${Math.round(timeoutMs / 1000)}s — it may need a moment.`)
+      return
+    }
+    if (!waited) {
+      waited = true
+      onLog('waiting for the URL to go live (first deploys can take ~30-60s)…')
+    }
+    await new Promise((r) => setTimeout(r, 3000))
+  }
+}
+
+const WORKER_NAME_RE = /^[a-z0-9][a-z0-9-]*$/
+
+export function workerName(params: CloudflareParams, origin: string): string {
+  // An explicit name is the deployed worker's identity (and the SELF service
+  // target) — validate and reject an invalid one rather than silently rewriting
+  // it, so the dev fixes it instead of deploying under a surprising name.
+  if (params.workerName !== undefined) {
+    if (!WORKER_NAME_RE.test(params.workerName) || params.workerName.length > 63) {
+      throw new Error(
+        `cloudflare adapter: invalid \`workerName\` "${params.workerName}". A Cloudflare worker ` +
+          'name must be lowercase, start with a letter or digit, contain only letters, digits and ' +
+          'dashes, and be at most 63 chars.',
+      )
+    }
+    return params.workerName
+  }
+  // Derive from the origin: lowercase, collapse non-alphanumerics to a dash, then
+  // SLICE before trimming dashes so a cut landing mid-dash can't leave a trailing
+  // "-" (which wrangler rejects).
+  return origin
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .slice(0, 54)
+    .replace(/^-+|-+$/g, '')
+}
+
+function logTo(): (line: string) => void {
+  return (line: string) => process.stderr.write(`\x1b[2m  ${line}\x1b[0m\n`)
+}

package/src/codegen/identity.ts

@@ -0,0 +1,40 @@
+/**
+ * Ensure the domain has a stable Ed25519 signing identity at
+ * `.astrale/identity.ts`. Generated ONCE (first `dev`/`deploy` or by the
+ * scaffolder) and never regenerated — the private key IS the domain's identity,
+ * so rotating it would orphan every instance that installed the old key. The
+ * file is gitignored; for real production this key should graduate to a managed
+ * secret.
+ */
+
+import { exportJWK, generateKeyPair } from 'jose'
+import { existsSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export async function ensureIdentity(astraleDir: string, origin: string): Promise<void> {
+  const file = join(astraleDir, 'identity.ts')
+  if (existsSync(file)) return
+
+  const { privateKey } = await generateKeyPair('EdDSA', { extractable: true })
+  const jwk = (await exportJWK(privateKey)) as Record<string, unknown>
+  jwk.alg = 'EdDSA'
+  jwk.kid = `${origin}-key`
+
+  await mkdir(astraleDir, { recursive: true })
+  await writeFile(
+    file,
+    `// AUTO-GENERATED stable signing identity for "${origin}" — do not edit, do not commit.\n` +
+      `export const PRIVATE_JWK = ${JSON.stringify(jwk, null, 2)} as const\n`,
+  )
+
+  // Loud on purpose: the file is gitignored, so a fresh clone / CI runner
+  // silently mints a NEW key — and a redeploy with a new key breaks JWKS
+  // verification on every instance that installed the old one, with no hint
+  // why. Make the lifecycle visible the one time it happens.
+  process.stderr.write(
+    `\x1b[33m!\x1b[0m new signing identity generated at .astrale/identity.ts (kid ${String(jwk.kid)}).\n` +
+      `  This key IS "${origin}"'s identity: back it up (or move it to a managed secret) —\n` +
+      `  deploying from another machine without it re-keys the domain and breaks existing installs.\n`,
+  )
+}

package/src/codegen/merge.ts

@@ -0,0 +1,92 @@
+/**
+ * Deep-merge for the generated wrangler config. `base` is what the adapter
+ * generates; `overlay` is the dev's `params.wrangler` escape hatch. The merge
+ * is additive so a dev can declare extra bindings without losing the adapter's
+ * invariants:
+ *   - plain objects      → recurse
+ *   - arrays             → concat, de-duplicating BOTH primitive members and
+ *                          object bindings by an identity key (`binding` /
+ *                          `pattern` / `queue` / `name`, else structural value),
+ *                          with the overlay entry overriding a base entry of the
+ *                          same identity. So a dev overlay that re-declares the
+ *                          adapter's `SELF` service (or any binding) replaces it
+ *                          instead of emitting a duplicate wrangler rejects.
+ *   - scalars / new keys → overlay wins
+ *
+ * Protecting the load-bearing keys (`main`, `assets`, …) is policy enforced by
+ * the caller (`generateWranglerConfig`), not here — this stays a generic merge.
+ */
+export function deepMergeConfig(
+  base: Record<string, unknown>,
+  overlay: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base }
+  for (const [key, value] of Object.entries(overlay)) {
+    const prev = out[key]
+    if (isPlainObject(prev) && isPlainObject(value)) {
+      out[key] = deepMergeConfig(prev, value)
+    } else if (Array.isArray(prev) && Array.isArray(value)) {
+      out[key] = mergeArrays(prev, value)
+    } else {
+      out[key] = value
+    }
+  }
+  return out
+}
+
+/**
+ * Concat two arrays, de-duplicating by identity. Primitives dedup by value;
+ * objects dedup by an identity key (`binding`/`pattern`/`queue`/`name`, else
+ * their structural JSON) with the later (overlay) entry overriding an earlier
+ * (base) one at the base entry's position. This stops a re-declared object
+ * binding (e.g. a second `SELF` service) from producing a duplicate that
+ * wrangler rejects, while still appending genuinely distinct bindings.
+ */
+function mergeArrays(a: unknown[], b: unknown[]): unknown[] {
+  const out: unknown[] = []
+  const seenPrimitives = new Set<unknown>()
+  const indexByKey = new Map<string, number>()
+  for (const item of [...a, ...b]) {
+    if (isPrimitive(item)) {
+      if (seenPrimitives.has(item)) continue
+      seenPrimitives.add(item)
+      out.push(item)
+      continue
+    }
+    const key = identityKey(item)
+    const existing = indexByKey.get(key)
+    if (existing !== undefined) {
+      out[existing] = item // overlay (later) overrides the base entry in place
+      continue
+    }
+    indexByKey.set(key, out.length)
+    out.push(item)
+  }
+  return out
+}
+
+/**
+ * Stable identity for an array's object member: the first recognized wrangler
+ * binding field (`binding` for services/KV/R2/D1/queue producers, `pattern` for
+ * routes, `queue` for consumers, `name` as a generic fallback), else the member's
+ * full structural JSON so identical objects dedup but distinct ones all survive.
+ */
+function identityKey(item: unknown): string {
+  const rec = item as Record<string, unknown>
+  for (const field of ['binding', 'pattern', 'queue', 'name']) {
+    if (typeof rec[field] === 'string') return `${field}:${rec[field] as string}`
+  }
+  try {
+    return `json:${JSON.stringify(item)}`
+  } catch {
+    return `ref:${String(item)}`
+  }
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
+function isPrimitive(v: unknown): boolean {
+  return v === null || (typeof v !== 'object' && typeof v !== 'function')
+}

package/src/codegen/worker.ts

@@ -0,0 +1,105 @@
+/**
+ * Codegen for the Cloudflare Worker entry (`.astrale/worker.gen.ts`).
+ *
+ * The dev writes only schema/methods/views/functions; this generates the
+ * `export default { fetch }` plumbing the adapter owns. Key properties:
+ *
+ *  • Per-request `url` = the live serving origin (`scheme://host`). It is passed
+ *    only to `createRemoteServer({ url })`; the SDK stamps every
+ *    `binding.remoteUrl` from that single value at spec-build time — so deployed
+ *    Function nodes point back at THIS worker with zero hardcoded URLs.
+ *  • Self-issued JWKS: a Worker can't fetch its own hostname; the verifier
+ *    resolves a credential whose `iss` is this worker from the in-memory key,
+ *    so no self-fetch is attempted (the worker's JWKS is served as a normal
+ *    route by createRemoteServer).
+ *  • Self-binding (autobinding): when a handler calls back into its OWN domain
+ *    (`ctx.callRemote`), the redirect resolves to this worker's own host — a
+ *    forbidden same-host subrequest. We route those through the `SELF` service
+ *    binding instead.
+ *  • SPA: `/ui/*` is served from the `ASSETS` binding (or proxied to Vite in
+ *    dev via `VIEW_DEV_URL`).
+ */
+
+export interface WorkerCodegenOptions {
+  origin: string
+  postInstall?: string
+  requires: readonly string[]
+  hasViews: boolean
+  hasFunctions: boolean
+  hasClient: boolean
+}
+
+export function generateWorkerEntry(opts: WorkerCodegenOptions): string {
+  const optionalImports = [
+    opts.hasViews ? `import { views } from '../views'` : `const views = undefined`,
+    opts.hasFunctions ? `import { functions } from '../functions'` : `const functions = undefined`,
+  ].join('\n')
+
+  const postInstallLine =
+    opts.postInstall !== undefined
+      ? `const POST_INSTALL = ${JSON.stringify(opts.postInstall)}`
+      : `const POST_INSTALL = undefined`
+
+  return `// AUTO-GENERATED by @astrale-os/adapter-cloudflare — do not edit.
+// Regenerated on every \`astrale-domain dev|deploy\`. Edit schema/methods/views
+// instead. (origin: ${opts.origin})
+import { defineRemoteDomain } from '@astrale-os/sdk'
+import { createWorkerEntry } from '@astrale-os/sdk/server'
+
+import { schema } from '../schema'
+import { methods } from '../methods'
+${optionalImports}
+import { PRIVATE_JWK } from './identity'
+
+const REQUIRES = ${JSON.stringify(opts.requires)}
+${postInstallLine}
+
+interface Env {
+  WORKER_URL?: string
+  ASSETS?: { fetch(request: Request): Promise<Response> }
+  SELF?: { fetch(request: Request): Promise<Response> }
+  VIEW_DEV_URL?: string
+  [key: string]: unknown
+}
+
+// All the shared worker plumbing — JWKS self-fetch shim, SELF-binding routing,
+// per-URL app cache, canonical iss resolution — lives in createWorkerEntry.
+export default createWorkerEntry<Env>({
+  // The worker's serving URL = its identity (iss). Prefer the adapter-injected
+  // WORKER_URL (pins one canonical host for routed deploys, so iss stays stable
+  // even when also reachable via *.workers.dev); fall back to the per-request
+  // host for dev / workers.dev-only (single-host → it IS the canonical URL).
+  resolveUrl: (env, requestOrigin) => env.WORKER_URL ?? requestOrigin,
+  selfBinding: (env) => env.SELF,
+  build: (url, env) => {
+    const domain = defineRemoteDomain()({
+      schema,
+      methods,
+      ...(views ? { views } : {}),
+      ...(functions ? { remoteFunctions: functions } : {}),
+    })
+    return {
+      domain,
+      deps: env,
+      url,
+      privateKey: PRIVATE_JWK,
+      ...(POST_INSTALL ? { postInstall: POST_INSTALL } : {}),
+      ...(REQUIRES.length ? { requires: REQUIRES } : {}),
+    }
+  },
+  // SPA under /ui/* (views with a client renderer).
+  before: (env, url, request) => {
+    if (env.ASSETS && (url.pathname === '/ui' || url.pathname.startsWith('/ui/'))) {
+      if (env.VIEW_DEV_URL) {
+        const devBase = env.VIEW_DEV_URL.replace(/\\/$/, '')
+        return fetch(new Request(\`\${devBase}\${url.pathname}\${url.search}\`, request))
+      }
+      const stripped = url.pathname.replace(/^\\/ui\\/?/, '/')
+      const rewritten = new URL(stripped + url.search, url.origin)
+      return env.ASSETS.fetch(new Request(rewritten, request))
+    }
+    return undefined
+  },
+})
+`
+}

package/src/codegen/wrangler.ts

@@ -0,0 +1,95 @@
+/**
+ * Codegen for the Worker config (`.astrale/wrangler.gen.jsonc`). This is the
+ * `wrangler.jsonc` that used to be hand-copied into every domain — now an
+ * internal adapter detail the dev never sees.
+ *
+ * `main` is `./worker.gen.ts` (same dir). `assets.directory` is `../dist-client`
+ * (the project's Vite build). A `SELF` service binding enables autobinding
+ * (a handler calling back into its own domain). Custom-domain deploys attach a
+ * `custom_domain` route; otherwise the Worker ships to `*.workers.dev`.
+ *
+ * A dev's `params.wrangler` escape hatch is deep-merged on top of this base
+ * (extra bindings: KV, R2, D1, queues, …) — see `mergeUserConfig`.
+ */
+
+import { deepMergeConfig } from './merge'
+
+export interface WranglerCodegenOptions {
+  workerName: string
+  /** Full custom hostname for a routed deploy (e.g. 'crm.acme.dev'). */
+  route?: string
+  /** Whether the project has a built client SPA to serve under /ui/*. */
+  hasClient: boolean
+  /** Plain (non-secret) vars to bake in. */
+  vars?: Record<string, string>
+  /** Add the SELF service binding (autobinding). */
+  selfBinding: boolean
+  /**
+   * Raw wrangler config to deep-merge over the generated base — the escape
+   * hatch for extra bindings (KV, R2, D1, queues, service bindings, extra
+   * `compatibility_flags`, cron `triggers`, …). Arrays concat; new keys are
+   * added as-is. The adapter-owned keys `name`, `main`, `assets`, `routes` are
+   * rejected (throws) — use `workerName` / `route` instead.
+   */
+  wrangler?: Record<string, unknown>
+}
+
+const COMPATIBILITY_DATE = '2025-03-01'
+
+export function generateWranglerConfig(opts: WranglerCodegenOptions): string {
+  const config: Record<string, unknown> = {
+    name: opts.workerName,
+    main: './worker.gen.ts',
+    compatibility_date: COMPATIBILITY_DATE,
+    compatibility_flags: ['nodejs_compat', 'nodejs_compat_populate_process_env'],
+    workers_dev: true,
+    observability: { enabled: true },
+  }
+
+  if (opts.route) {
+    config.routes = [{ pattern: opts.route, custom_domain: true }]
+  }
+
+  if (opts.hasClient) {
+    config.assets = {
+      directory: '../dist-client',
+      binding: 'ASSETS',
+      not_found_handling: 'single-page-application',
+      run_worker_first: true,
+    }
+  }
+
+  if (opts.selfBinding) {
+    config.services = [{ binding: 'SELF', service: opts.workerName }]
+  }
+
+  if (opts.vars && Object.keys(opts.vars).length > 0) {
+    config.vars = opts.vars
+  }
+
+  const merged = opts.wrangler ? mergeUserConfig(config, opts.wrangler) : config
+  return JSON.stringify(merged, null, 2) + '\n'
+}
+
+/** Keys the adapter owns and won't let `params.wrangler` clobber. */
+const ADAPTER_OWNED_KEYS = ['name', 'main', 'assets', 'routes']
+
+/**
+ * Deep-merge the dev's raw wrangler overlay over the generated config, after
+ * refusing any attempt to override an adapter-owned key. Throwing (rather than
+ * silently dropping) keeps a stray `main` from breaking the Worker unnoticed.
+ */
+function mergeUserConfig(
+  base: Record<string, unknown>,
+  user: Record<string, unknown>,
+): Record<string, unknown> {
+  const collisions = ADAPTER_OWNED_KEYS.filter((k) => k in user)
+  if (collisions.length > 0) {
+    throw new Error(
+      `wrangler: cannot override adapter-managed key(s): ${collisions.join(', ')}. ` +
+        'Use `workerName` for the worker name and `route` for routing; ' +
+        '`main` and `assets` are generated by the adapter.',
+    )
+  }
+  return deepMergeConfig(base, user)
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * `@astrale-os/adapter-cloudflare` — deploy an Astrale domain as a standalone
+ * Cloudflare Worker.
+ *
+ *   import { cloudflare } from '@astrale-os/adapter-cloudflare'
+ *
+ *   adapter: cloudflare({
+ *     dev:  { secrets: '.env.dev' },
+ *     prod: { route: 'crm.acme.dev', secrets: '.env.prod' },
+ *   })
+ *
+ * `dev` runs `wrangler dev` locally; an env with no `route` ships to
+ * `*.workers.dev`; an env with a `route` ships to that custom domain.
+ */
+
+export { cloudflare } from './cloudflare'
+export type { CloudflareParams } from './params'