@astrale-os/adapter-cloudflare 0.4.10 → 0.5.0-beta.2

package/src/cloudflare.ts

@@ -2,44 +2,87 @@
  * `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
+ * config (the dev never sees a `wrangler.jsonc`), materializes the optional frontend
  * 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 CLI
  * prints and `astrale domain install <url>` consumes.
  */
 
-import type { DeployCtx, DomainAdapter, WatchCtx } from '@astrale-os/sdk'
+import type { DomainAdapter } from '@astrale-os/sdk'
 
 import { defineAdapter } from '@astrale-os/sdk'
-import { mkdir, rename, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
 
-import type { CloudflareParams } from './params'
+import type { CloudflareParams } from './params.js'
 
-import { buildClient, resolveClientDir } 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
+import {
+  bulkPutSecrets,
+  buildCloudflareWorker,
+  buildFrontend,
+  logTo,
+  prepare,
+  runWranglerDeploy,
+  runWranglerDev,
+  runWranglerTypes,
+  watchFrontend,
+} from './build/index.js'
 
 export function cloudflare(
   envs: Record<string, CloudflareParams>,
+): DomainAdapter<CloudflareParams> {
+  return cloudflareWithDependencies(envs, {
+    bulkPutSecrets,
+    buildCloudflareWorker,
+    buildFrontend,
+    logTo,
+    prepare,
+    runWranglerDeploy,
+    runWranglerDev,
+    runWranglerTypes,
+    watchFrontend,
+    waitUntilLive,
+  })
+}
+
+interface CloudflareAdapterDependencies {
+  readonly bulkPutSecrets: typeof bulkPutSecrets
+  readonly buildCloudflareWorker: typeof buildCloudflareWorker
+  readonly buildFrontend: typeof buildFrontend
+  readonly logTo: typeof logTo
+  readonly prepare: typeof prepare
+  readonly runWranglerDeploy: typeof runWranglerDeploy
+  readonly runWranglerDev: typeof runWranglerDev
+  readonly runWranglerTypes: typeof runWranglerTypes
+  readonly watchFrontend: typeof watchFrontend
+  readonly waitUntilLive: typeof waitUntilLive
+}
+
+/** Exact orchestration seam used by adapter-level deployment qualification. */
+export function cloudflareWithDependencies(
+  envs: Record<string, CloudflareParams>,
+  dependencies: CloudflareAdapterDependencies,
 ): DomainAdapter<CloudflareParams> {
   return defineAdapter<CloudflareParams>({
     name: 'cloudflare',
     envs,
 
+    async build(params, ctx) {
+      await dependencies.buildCloudflareWorker({
+        params,
+        context: ctx,
+        onLog: dependencies.logTo(),
+      })
+    },
+
     async watch(params, ctx) {
-      const clientDir = resolveCloudflareClientDir(params, ctx)
-      const { configPath, port } = await prepare(params, ctx, 'dev', {
-        servesClient: Boolean(clientDir),
-        bundleAssets: Boolean(clientDir),
+      const onLog = dependencies.logTo()
+      const frontend = await dependencies.buildFrontend({
+        definition: ctx.definition,
+        projectDir: ctx.projectDir,
+        onLog,
       })
-      if (clientDir) await buildClient(clientDir, ctx.projectDir, logTo())
-      const handle = await runWranglerDev({
+      const { configPath, port } = await dependencies.prepare(params, ctx, 'dev', frontend)
+      const handle = await dependencies.runWranglerDev({
         projectDir: ctx.projectDir,
         configPath,
         port,
@@ -47,58 +90,104 @@ export function cloudflare(
         autoPickPort: params.port === undefined,
         ...(params.host ? { ip: '0.0.0.0' } : {}),
         onReload: ctx.onReload,
-        onLog: logTo(),
+        onLog,
       })
+      let frontendWatch: ReturnType<typeof watchFrontend>
+      try {
+        frontendWatch = dependencies.watchFrontend({
+          definition: ctx.definition,
+          projectDir: ctx.projectDir,
+          onLog,
+          // Routes and source recipes are immutable for this watch generation.
+          // Wrangler already observes the atomically swapped asset stage, so a
+          // source rebuild needs no config regeneration.
+          onRebuild: ctx.onReload,
+        })
+      } catch (error) {
+        try {
+          await handle.stop()
+        } catch (cleanupError) {
+          throw new AggregateError(
+            [error, cleanupError],
+            'cloudflare frontend watcher startup failed and Wrangler cleanup also failed',
+          )
+        }
+        throw error
+      }
       // With --host the actionable URL is the PUBLIC one (the tunnel/proxy
       // front), not the local bind — print and spec-stamp that.
-      return { url: params.host ?? handle.url, stop: handle.stop }
+      return {
+        url: params.host ?? handle.url,
+        async stop() {
+          const errors: unknown[] = []
+          try {
+            await frontendWatch?.stop()
+          } catch (error) {
+            errors.push(error)
+          }
+          try {
+            await handle.stop()
+          } catch (error) {
+            errors.push(error)
+          }
+          if (errors.length === 1) throw errors[0]
+          if (errors.length > 1) {
+            throw new AggregateError(errors, 'cloudflare development cleanup failed')
+          }
+        },
+      }
     },
 
     // Config hot-regen: rewrite the generated files only — the running
     // `wrangler dev` watches its `--config` (and the worker entry) and reloads
     // them itself, so a `astrale.config.ts` edit lands without a restart.
-    // Mirrors `watch`'s prep exactly (codegen + client build), minus the spawn.
+    // Mirrors `watch`'s prep exactly (codegen + frontend build), minus the spawn.
     async regenerate(params, ctx) {
-      const clientDir = resolveCloudflareClientDir(params, ctx)
-      await prepare(params, ctx, 'dev', {
-        servesClient: Boolean(clientDir),
-        bundleAssets: Boolean(clientDir),
+      const frontend = await dependencies.buildFrontend({
+        definition: ctx.definition,
+        projectDir: ctx.projectDir,
+        onLog: dependencies.logTo(),
+      })
+      const { configPath } = await dependencies.prepare(params, ctx, 'dev', frontend)
+      await dependencies.runWranglerTypes({
+        projectDir: ctx.projectDir,
+        configPath,
+        onLog: dependencies.logTo(),
       })
-      if (clientDir) await buildClient(clientDir, ctx.projectDir, logTo())
     },
 
     async deploy(params, ctx) {
-      const clientDir = resolveCloudflareClientDir(params, ctx)
+      const frontend = await dependencies.buildFrontend({
+        definition: ctx.definition,
+        projectDir: ctx.projectDir,
+        onLog: dependencies.logTo(),
+      })
       const {
         configPath,
         fallbackConfigPath,
         workerName: name,
-      } = await prepare(params, ctx, 'deploy', {
-        servesClient: Boolean(clientDir),
-        bundleAssets: Boolean(clientDir),
-      })
-      if (clientDir) await buildClient(clientDir, ctx.projectDir, logTo())
-      const { url } = await runWranglerDeploy({
+      } = await dependencies.prepare(params, ctx, 'deploy', frontend)
+      const { url, deploymentVersion } = await dependencies.runWranglerDeploy({
         projectDir: ctx.projectDir,
         configPath,
         workerName: name,
         ...(fallbackConfigPath ? { fallbackConfigPath } : {}),
         ...(params.route ? { route: params.route } : {}),
-        onLog: logTo(),
+        onLog: dependencies.logTo(),
       })
       if (Object.keys(ctx.secrets).length > 0) {
-        await bulkPutSecrets({
+        await dependencies.bulkPutSecrets({
           projectDir: ctx.projectDir,
           configPath,
           secrets: ctx.secrets,
-          onLog: logTo(),
+          onLog: dependencies.logTo(),
         })
       }
       // A first deploy on a fresh `*.workers.dev` host can take ~30-60s to
       // propagate; an `astrale domain 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())
+      await dependencies.waitUntilLive(url, dependencies.logTo(), deploymentVersion)
       return { url }
     },
 
@@ -108,160 +197,50 @@ export function cloudflare(
   })
 }
 
-function resolveCloudflareClientDir(
-  params: CloudflareParams,
-  ctx: WatchCtx | DeployCtx,
-): string | undefined {
-  return resolveClientDir({
-    adapterName: 'cloudflare',
-    env: ctx.env,
-    projectDir: ctx.projectDir,
-    domain: ctx.domain,
-    ...(params.client ? { client: params.client } : {}),
-  })
-}
-
-// ── codegen orchestration ──────────────────────────────────────────────────
-
-export async function prepare(
-  params: CloudflareParams,
-  ctx: WatchCtx | DeployCtx,
-  mode: 'dev' | 'deploy',
-  clientAssets: { servesClient: boolean; bundleAssets: boolean } = {
-    servesClient: false,
-    bundleAssets: false,
-  },
-): 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)
-  // Instance-router service binding (on by default → admin-router): lets the
-  // worker reach other instances' hosts internally, so a cross-instance JWKS
-  // fetch doesn't 522. Resolved once, fed to BOTH codegens below.
-  const router = resolveRouter(params.router)
-  // Two distinct client signals: the WORKER's `/ui` hook and Wrangler's local
-  // assets binding. Direct Cloudflare deploys use both; managed deploys ship
-  // assets separately but still need the worker hook.
-  const servesClient = clientAssets.servesClient
-  const bundleAssets = clientAssets.bundleAssets
-
-  await writeFileAtomic(
-    join(astraleDir, 'worker.gen.ts'),
-    // Everything else — schema/methods/deps/views/functions/requires/postInstall —
-    // rides the `...domain` spread the generated entry imports from `../domain`;
-    // the only remaining build-time signal is whether to wire the /ui asset hook.
-    generateWorkerEntry({
-      origin: ctx.domain.origin,
-      hasClient: servesClient,
-      ...(router
-        ? {
-            router: {
-              binding: router.binding,
-              hostSuffix: router.hostSuffix,
-              minLabels: router.minLabels,
-            },
-          }
-        : {}),
-    }),
-  )
-
-  // 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.
-  // Dev behind a tunnel/proxy (`--host`) pins WORKER_URL the same way a routed
-  // deploy does — the per-request Host there is the proxy's INTERNAL hostname
-  // and would corrupt the worker's `iss`.
-  const workerUrl =
-    mode === 'deploy' && params.route
-      ? `https://${params.route}`
-      : mode === 'dev' && params.host
-        ? params.host
-        : 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: bundleAssets,
-    vars,
-    // Router service binding flows into BOTH the SELF and SELF-less fallback
-    // configs — the first-deploy two-pass must keep it. `admin-router` already
-    // exists, so unlike SELF it always resolves (no first-deploy chicken-egg).
-    ...(router ? { router: { binding: router.binding, service: router.service } } : {}),
-    // 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 writeFileAtomic(configPath, generateWranglerConfig({ ...baseConfig, selfBinding: true }))
-
-  let fallbackConfigPath: string | undefined
-  if (mode === 'deploy') {
-    fallbackConfigPath = join(astraleDir, 'wrangler.no-self.gen.jsonc')
-    await writeFileAtomic(
-      fallbackConfigPath,
-      generateWranglerConfig({ ...baseConfig, selfBinding: false }),
-    )
-  }
-
-  return {
-    configPath,
-    ...(fallbackConfigPath ? { fallbackConfigPath } : {}),
-    port: params.port ?? DEFAULT_PORT,
-    workerName: name,
-  }
-}
-
-/**
- * Write-then-rename: hot-regen rewrites these files while a live `wrangler dev`
- * watches them — a plain `writeFile` can be read truncated mid-write.
- */
-async function writeFileAtomic(path: string, content: string): Promise<void> {
-  const tmp = `${path}.tmp`
-  await writeFile(tmp, content)
-  await rename(tmp, path)
-}
-
 /**
- * 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.
+ * Poll until the deployed Worker health endpoint returns exactly 200.
  */
 async function waitUntilLive(
   url: string,
   onLog: (line: string) => void,
+  expectedDeploymentVersion?: string,
   timeoutMs = 90_000,
 ): Promise<void> {
   const probe = new URL('/health', url)
+  const metadata = new URL('/meta', url)
   const deadline = Date.now() + timeoutMs
   let waited = false
+  let lastStatus: number | undefined
+  let lastDeploymentVersion: string | undefined
   for (;;) {
     try {
       const res = await fetch(probe, { redirect: 'manual' })
-      if (res.status !== 404) return
+      lastStatus = res.status
+      await res.body?.cancel()
+      if (res.status === 200) {
+        if (expectedDeploymentVersion === undefined) return
+        const meta = await fetch(metadata, { redirect: 'manual' })
+        if (meta.status === 200) {
+          const body = (await meta.json()) as { deploymentVersion?: unknown }
+          lastDeploymentVersion =
+            typeof body.deploymentVersion === 'string' ? body.deploymentVersion : undefined
+          if (lastDeploymentVersion === expectedDeploymentVersion) return
+        } else {
+          await meta.body?.cancel()
+        }
+      }
     } 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
+      throw new Error(
+        `deployed Worker health did not reach HTTP 200 within ${Math.round(timeoutMs / 1000)}s` +
+          (lastStatus === undefined ? '' : ` (last status ${lastStatus})`) +
+          (expectedDeploymentVersion === undefined
+            ? ''
+            : `; deployment version ${JSON.stringify(lastDeploymentVersion)} ` +
+              `did not reach ${JSON.stringify(expectedDeploymentVersion)}`),
+      )
     }
     if (!waited) {
       waited = true
@@ -270,52 +249,3 @@ async function waitUntilLive(
     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, '')
-}
-
-/**
- * Resolve the instance-router config. ON by default (targets `admin-router`) so
- * every adapter-deployed worker can reach other instances' hosts internally and
- * verify cross-instance credentials without a 522; `false` disables it. The
- * returned shape carries every value the worker- and wrangler-codegen need.
- */
-export function resolveRouter(
-  ir: CloudflareParams['router'],
-): { binding: string; service: string; hostSuffix: string; minLabels: number } | undefined {
-  if (ir === false) return undefined
-  const cfg = ir ?? {}
-  return {
-    binding: cfg.binding ?? 'ROUTER',
-    service: cfg.service ?? 'admin-router',
-    hostSuffix: cfg.hostSuffix ?? '.astrale.ai',
-    minLabels: cfg.minLabels ?? 4,
-  }
-}
-
-export function logTo(): (line: string) => void {
-  return (line: string) => process.stderr.write(`\x1b[2m  ${line}\x1b[0m\n`)
-}

package/src/index.ts

@@ -5,8 +5,8 @@
  *   import { cloudflare } from '@astrale-os/adapter-cloudflare'
  *
  *   adapter: cloudflare({
- *     dev:  { client: { dir: 'client' }, secrets: '.env.dev' },
- *     prod: { client: { dir: 'client' }, route: 'crm.acme.dev', secrets: '.env.prod' },
+ *     dev:  { secrets: '.env.dev' },
+ *     prod: { route: 'crm.acme.dev', secrets: '.env.prod' },
  *   })
  *
  * `dev` runs `wrangler dev` locally; an env with no `route` ships to
@@ -17,5 +17,5 @@
  * `/build` toolkit and ships it through the Astrale platform.
  */
 
-export { cloudflare } from './cloudflare'
-export type { CloudflareParams } from './params'
+export { cloudflare } from './cloudflare.js'
+export type { CloudflareParams } from './params.js'

package/src/params.ts

@@ -1,5 +1,3 @@
-import type { ClientConfig } from './client'
-
 /**
  * `CloudflareParams` — the provider-typed config for the Cloudflare adapter.
  *
@@ -13,18 +11,16 @@ import type { ClientConfig } from './client'
  *   • remote (custom)  — `deploy()` with `route`; URL = https://<route>
  */
 export interface CloudflareParams {
-  /** Frontend assets to build and serve for this env's mounted `/ui` views. */
-  client?: ClientConfig
   /**
    * 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
+  readonly route?: string
   /** Gitignored secrets file (whole contents = secrets), e.g. `'.env.dev'`. */
-  secrets?: string
+  readonly secrets?: string
   /** Local dev port for `wrangler dev`. Default 8787. */
-  port?: number
+  readonly port?: number
   /**
    * Public URL the dev server is reached through (tunnel / sandbox preview /
    * reverse proxy), e.g. `'https://my-box.preview.dev'`. Sets BOTH effects an
@@ -33,13 +29,13 @@ export interface CloudflareParams {
    * identity (`iss`) doesn't drift to the proxy's internal hostname.
    * Usually injected by `pnpm dev --host <url>` rather than written here.
    */
-  host?: string
+  readonly host?: string
   /** Override the Worker name. Default: derived from the domain origin. */
-  workerName?: string
+  readonly workerName?: string
   /** Run `wrangler dev --remote` (edge isolate) instead of local workerd. */
-  remote?: boolean
+  readonly remote?: boolean
   /** Extra plain (non-secret) vars to inject as Worker vars. */
-  vars?: Record<string, string>
+  readonly 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,
@@ -58,7 +54,7 @@ export interface CloudflareParams {
    * 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>
+  readonly wrangler?: Record<string, unknown>
   /**
    * Route subrequests to platform INSTANCE hostnames through a service binding
    * instead of the public edge. A Cloudflare Worker can't fetch a same-zone
@@ -81,16 +77,16 @@ export interface CloudflareParams {
    *   router: false                      // opt out
    *   router: { service: 'my-router' }   // override target
    */
-  router?:
+  readonly router?:
     | false
     | {
         /** Router Worker the binding targets. Default `'admin-router'`. */
-        service?: string
+        readonly service?: string
         /** Service-binding name the worker reads. Default `'ROUTER'`. */
-        binding?: string
+        readonly binding?: string
         /** Host suffix that marks an instance host. Default `'.astrale.ai'`. */
-        hostSuffix?: string
+        readonly hostSuffix?: string
         /** Min dot-separated label count for an instance host. Default `4` (`<slug>.<region>.astrale.ai`). */
-        minLabels?: number
+        readonly minLabels?: number
       }
 }