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

package/src/build/frontend.ts

@@ -0,0 +1,324 @@
+import type { CompiledFrontendArtifact, DomainDefinition, FrontendFile } from '@astrale-os/sdk'
+import type { ReactFrontendArtifact } from '@astrale-os/sdk/react'
+
+import { compileFrontend } from '@astrale-os/sdk'
+import { compileReactEntrypoint } from '@astrale-os/sdk/react'
+import { spawn } from 'node:child_process'
+import { watch } from 'node:fs'
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, join, resolve, sep } from 'node:path'
+
+export const FRONTEND_STAGE_DIR = '.astrale/frontend'
+const FRONTEND_REBUILD_DELAY_MS = 75
+let stageGeneration = 0
+const buildQueues = new Map<string, Promise<void>>()
+
+/** Materialize one Domain-owned frontend recipe into an immutable adapter artifact. */
+export async function buildFrontend(input: {
+  readonly definition: DomainDefinition
+  readonly projectDir: string
+  readonly onLog?: (line: string) => void
+}): Promise<CompiledFrontendArtifact | undefined> {
+  const key = resolve(input.projectDir)
+  const previous = buildQueues.get(key) ?? Promise.resolve()
+  let release = (): void => {}
+  const current = new Promise<void>((resolveBuild) => {
+    release = resolveBuild
+  })
+  const tail = previous.then(() => current)
+  buildQueues.set(key, tail)
+  await previous
+  try {
+    return await buildFrontendUnlocked(input)
+  } finally {
+    release()
+    if (buildQueues.get(key) === tail) buildQueues.delete(key)
+  }
+}
+
+async function buildFrontendUnlocked(input: {
+  readonly definition: DomainDefinition
+  readonly projectDir: string
+  readonly onLog?: (line: string) => void
+}): Promise<CompiledFrontendArtifact | undefined> {
+  const artifact = input.definition.frontend
+  if (artifact === undefined) return undefined
+  if (artifact.source.kind === 'external') {
+    return compileFrontend({
+      artifact,
+      files: [],
+      provenance: { adapter: 'cloudflare', source: 'external' },
+    })
+  }
+
+  let files: readonly FrontendFile[]
+  if (artifact.source.kind === 'generated') {
+    files = artifact.source.files.map((file) => ({
+      path: file.path,
+      content:
+        typeof file.content === 'string' ? new TextEncoder().encode(file.content) : file.content,
+      ...(file.mediaType === undefined ? {} : { mediaType: file.mediaType }),
+    }))
+  } else if (artifact.source.kind === 'prebuilt') {
+    files = await readFiles(
+      contained(input.projectDir, artifact.source.directory, 'prebuilt frontend'),
+    )
+  } else {
+    if (isReactFrontend(artifact)) {
+      const root = contained(input.projectDir, artifact.source.root, 'React frontend root')
+      for (const file of compileReactEntrypoint(artifact)) {
+        const path = contained(root, file.path, 'generated React entrypoint')
+        await mkdir(dirname(path), { recursive: true })
+        await writeFile(path, file.content)
+      }
+    }
+    const output = contained(input.projectDir, artifact.source.outDir, 'Vite frontend output')
+    await rm(output, { recursive: true, force: true })
+    await runBuild(
+      artifact.source.command[0],
+      [
+        ...artifact.source.command.slice(1),
+        artifact.source.root,
+        '--outDir',
+        output,
+        '--emptyOutDir',
+      ],
+      input.projectDir,
+      input.onLog,
+    )
+    files = await readFiles(output)
+  }
+  const compiled = await compileFrontend({
+    artifact,
+    baseHref: 'https://frontend.invalid/',
+    files,
+    provenance: { adapter: 'cloudflare', source: artifact.source.kind },
+  })
+  await replaceStage(input.projectDir, compiled.files)
+  return compiled
+}
+
+export interface FrontendWatchHandle {
+  stop(): Promise<void>
+}
+
+export interface FrontendWatchSubscription {
+  close(): void
+}
+
+export type FrontendWatchSubscribe = (
+  root: string,
+  onChange: (path?: string) => void,
+  onError: (error: Error) => void,
+) => FrontendWatchSubscription
+
+/** Keep Wrangler's materialized frontend stage current without owning config regeneration. */
+export function watchFrontend(input: {
+  readonly definition: DomainDefinition
+  readonly projectDir: string
+  readonly onLog?: (line: string) => void
+  readonly onRebuild?: () => void
+  readonly delayMs?: number
+  readonly build?: typeof buildFrontend
+  readonly subscribe?: FrontendWatchSubscribe
+}): FrontendWatchHandle | undefined {
+  const artifact = input.definition.frontend
+  if (
+    artifact === undefined ||
+    artifact.source.kind === 'external' ||
+    artifact.source.kind === 'generated'
+  )
+    return undefined
+
+  const source = artifact.source
+  const root =
+    source.kind === 'prebuilt'
+      ? contained(input.projectDir, source.directory, 'prebuilt frontend watch root')
+      : resolve(input.projectDir)
+  const build = input.build ?? buildFrontend
+  const subscribe = input.subscribe ?? subscribeToFrontend
+  const delayMs = input.delayMs ?? FRONTEND_REBUILD_DELAY_MS
+  let stopped = false
+  let pending = false
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let running: Promise<void> | undefined
+
+  const drain = async (): Promise<void> => {
+    if (stopped || running !== undefined || !pending) return
+    pending = false
+    running = (async () => {
+      try {
+        await build({
+          definition: input.definition,
+          projectDir: input.projectDir,
+          onLog: input.onLog,
+        })
+        if (!stopped) input.onRebuild?.()
+      } catch (error) {
+        input.onLog?.(
+          `frontend rebuild failed; keeping the last good stage: ${error instanceof Error ? error.message : String(error)}`,
+        )
+      }
+    })()
+    await running
+    running = undefined
+    if (!stopped && pending) {
+      timer = setTimeout(() => {
+        timer = undefined
+        void drain()
+      }, delayMs)
+    }
+  }
+  const schedule = (path?: string) => {
+    if (stopped || !rebuildsFor(source, path)) return
+    pending = true
+    if (timer !== undefined) clearTimeout(timer)
+    timer = setTimeout(() => {
+      timer = undefined
+      void drain()
+    }, delayMs)
+  }
+  const subscription = subscribe(root, schedule, (error) => {
+    input.onLog?.(`frontend watcher failed: ${error.message}`)
+  })
+
+  return Object.freeze({
+    async stop() {
+      if (stopped) return
+      stopped = true
+      pending = false
+      if (timer !== undefined) clearTimeout(timer)
+      timer = undefined
+      subscription.close()
+      await running
+    },
+  })
+}
+
+function isReactFrontend(
+  artifact: DomainDefinition['frontend'],
+): artifact is ReactFrontendArtifact {
+  return (
+    artifact !== undefined && (artifact as { readonly framework?: unknown }).framework === 'react'
+  )
+}
+
+async function readFiles(root: string, current = ''): Promise<readonly FrontendFile[]> {
+  const directory = join(root, current)
+  const entries = await readdir(directory, { withFileTypes: true })
+  const files: FrontendFile[] = []
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const path = current === '' ? entry.name : `${current}/${entry.name}`
+    if (entry.isDirectory()) files.push(...(await readFiles(root, path)))
+    else if (entry.isFile())
+      files.push({ path, content: new Uint8Array(await readFile(join(root, path))) })
+  }
+  return files
+}
+
+async function replaceStage(projectDir: string, files: readonly FrontendFile[]): Promise<void> {
+  const stage = contained(projectDir, FRONTEND_STAGE_DIR, 'frontend stage')
+  const generation = `${process.pid}-${++stageGeneration}`
+  const next = `${stage}.next-${generation}`
+  const previous = `${stage}.previous-${generation}`
+  await rm(next, { recursive: true, force: true })
+  await mkdir(next, { recursive: true })
+  try {
+    for (const file of files) {
+      const path = contained(next, file.path, 'staged frontend file')
+      await mkdir(dirname(path), { recursive: true })
+      await writeFile(path, file.content)
+    }
+    await rm(previous, { recursive: true, force: true })
+    let retainedPrevious = false
+    try {
+      await rename(stage, previous)
+      retainedPrevious = true
+    } catch (error) {
+      if (!isMissing(error)) throw error
+    }
+    try {
+      await rename(next, stage)
+    } catch (error) {
+      if (retainedPrevious) await rename(previous, stage)
+      throw error
+    }
+    if (retainedPrevious) await rm(previous, { recursive: true, force: true })
+  } finally {
+    await rm(next, { recursive: true, force: true })
+  }
+}
+
+function subscribeToFrontend(
+  root: string,
+  onChange: (path?: string) => void,
+  onError: (error: Error) => void,
+): FrontendWatchSubscription {
+  const watcher = watch(root, { recursive: true }, (_event, path) => {
+    onChange(path === null ? undefined : String(path))
+  })
+  watcher.on('error', onError)
+  return watcher
+}
+
+function rebuildsFor(
+  source: Exclude<
+    NonNullable<DomainDefinition['frontend']>['source'],
+    { readonly kind: 'external' | 'generated' }
+  >,
+  path: string | undefined,
+): boolean {
+  if (path === undefined || source.kind === 'prebuilt') return true
+  const normalized = path.replaceAll('\\', '/')
+  if (
+    normalized === '.astrale' ||
+    normalized.startsWith('.astrale/') ||
+    normalized === 'node_modules' ||
+    normalized.startsWith('node_modules/') ||
+    normalized === '.git' ||
+    normalized.startsWith('.git/')
+  )
+    return false
+  const outDir = source.outDir.replace(/^\.\//u, '')
+  if (normalized === outDir || normalized.startsWith(`${outDir}/`)) return false
+  const root = source.root.replace(/^\.\//u, '')
+  return normalized !== `${root}/astrale.generated.tsx` && normalized !== `${root}/index.html`
+}
+
+function isMissing(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}
+
+function contained(root: string, input: string, label: string): string {
+  const base = resolve(root)
+  const target = resolve(base, input)
+  if (target !== base && !target.startsWith(`${base}${sep}`)) {
+    throw new TypeError(`${label} must remain within the Domain project root.`)
+  }
+  return target
+}
+
+function runBuild(
+  command: string,
+  args: readonly string[],
+  cwd: string,
+  onLog?: (line: string) => void,
+): Promise<void> {
+  return new Promise((resolveBuild, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    let output = ''
+    const collect = (buffer: Buffer) => {
+      const value = buffer.toString()
+      output += value
+      for (const line of value.split('\n')) if (line.trim() !== '') onLog?.(line)
+    }
+    child.stdout?.on('data', collect)
+    child.stderr?.on('data', collect)
+    child.on('error', reject)
+    child.on('exit', (code) =>
+      code === 0
+        ? resolveBuild()
+        : reject(new Error(`frontend build failed (code ${code ?? 1}):\n${output.slice(-1500)}`)),
+    )
+  })
+}

package/src/{build.ts → build/index.ts}

@@ -10,7 +10,20 @@
  * build on so the codegen/bundling/dev logic lives in exactly one place.
  */
 
-export { logTo, prepare } from './cloudflare'
-export { buildClient, CLIENT_DIST_DIR, resolveClientDir } from './client'
-export type { ClientConfig } from './client'
-export { runWranglerBundle, runWranglerDev } from './wrangler-cli'
+export {
+  buildFrontend,
+  FRONTEND_STAGE_DIR,
+  watchFrontend,
+  type FrontendWatchHandle,
+  type FrontendWatchSubscribe,
+  type FrontendWatchSubscription,
+} from './frontend.js'
+export { logTo, prepare } from './prepare.js'
+export { buildCloudflareWorker, type CloudflareWorkerBuild } from './worker.js'
+export {
+  bulkPutSecrets,
+  runWranglerBundle,
+  runWranglerDeploy,
+  runWranglerDev,
+  runWranglerTypes,
+} from './wrangler-cli.js'

package/src/{parse-output.ts → build/parse-output.ts}

@@ -6,6 +6,7 @@
 
 const READY_RE = /(?:Ready on|Listening on|⎔.*?at)\s+(https?:\/\/[^\s]+)/i
 const WORKERS_DEV_RE = /(https:\/\/[^\s]+\.workers\.dev)/i
+const VERSION_ID_RE = /(?:Current\s+)?Version ID:\s*([a-z0-9_-]+)/i
 
 /**
  * Local dev URL from `wrangler dev` output, normalized to an origin on the given
@@ -41,6 +42,11 @@ export function parseDeployUrl(text: string, route?: string): string | undefined
   return m ? m[1] : undefined
 }
 
+/** Cloudflare version published by the final Wrangler deploy pass. */
+export function parseDeployVersionId(text: string): string | undefined {
+  return VERSION_ID_RE.exec(text)?.[1]
+}
+
 /** 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 {

package/src/build/prepare.ts

@@ -0,0 +1,161 @@
+import type {
+  BuildCtx,
+  CompiledFrontendArtifact,
+  DeployCtx,
+  FrontendRoute,
+  WatchCtx,
+} from '@astrale-os/sdk'
+
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { CloudflareParams } from '../index.js'
+
+import { ensureIdentity } from './codegen/identity.js'
+import { generateWorkerEntry } from './codegen/worker.js'
+import { generateWranglerConfig } from './codegen/wrangler.js'
+
+const DEFAULT_PORT = 8787
+const DEPLOYMENT_VERSION_BINDING = 'ASTRALE_DEPLOYMENT_VERSION'
+const WORKER_NAME_RE = /^[a-z0-9][a-z0-9-]*$/
+
+/** Prepare immutable generated Worker sources and Wrangler configuration. */
+export async function prepare(
+  params: CloudflareParams,
+  ctx: WatchCtx | DeployCtx | BuildCtx,
+  mode: 'build' | 'dev' | 'deploy',
+  frontend?: CompiledFrontendArtifact,
+): Promise<{ configPath: string; fallbackConfigPath?: string; port: number; workerName: string }> {
+  if (Object.hasOwn(params.vars ?? {}, DEPLOYMENT_VERSION_BINDING)) {
+    throw new Error(
+      `cloudflare adapter: \`${DEPLOYMENT_VERSION_BINDING}\` is adapter-managed and cannot be set in \`vars\`.`,
+    )
+  }
+  const astraleDir = join(ctx.projectDir, '.astrale')
+  await mkdir(astraleDir, { recursive: true })
+  await ensureIdentity(astraleDir, ctx.definition.schema.origin)
+
+  const name = workerName(params, ctx.definition.schema.origin)
+  const router = resolveRouter(params.router)
+  const localFrontend =
+    ctx.definition.frontend !== undefined && ctx.definition.frontend.source.kind !== 'external'
+  if (localFrontend !== (frontend !== undefined && frontend.artifact.source.kind !== 'external')) {
+    throw new TypeError('cloudflare adapter: materialized frontend must match definition.frontend.')
+  }
+
+  await writeFileAtomic(
+    join(astraleDir, 'worker.gen.ts'),
+    generateWorkerEntry({
+      origin: ctx.definition.schema.origin,
+      ...(router
+        ? {
+            router: {
+              binding: router.binding,
+              hostSuffix: router.hostSuffix,
+              minLabels: router.minLabels,
+            },
+          }
+        : {}),
+    }),
+  )
+
+  const workerUrl =
+    mode === 'deploy' && params.route
+      ? `https://${params.route}`
+      : mode === 'dev' && params.host
+        ? params.host
+        : undefined
+  const vars = {
+    ...(workerUrl ? { WORKER_URL: workerUrl } : {}),
+    ...(mode === 'dev'
+      ? { ...params.vars, ...('secrets' in ctx ? ctx.secrets : {}) }
+      : { ...params.vars }),
+  }
+  const baseConfig = {
+    workerName: name,
+    ...(mode === 'deploy' && params.route ? { route: params.route } : {}),
+    ...(localFrontend
+      ? {
+          frontend: {
+            directory: './frontend',
+            routes: localFrontendRoutes(ctx.definition),
+          },
+        }
+      : {}),
+    vars,
+    ...(router ? { router: { binding: router.binding, service: router.service } } : {}),
+    ...(params.wrangler ? { wrangler: params.wrangler } : {}),
+  }
+
+  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,
+  }
+}
+
+function localFrontendRoutes(
+  definition: BuildCtx['definition'] | DeployCtx['definition'] | WatchCtx['definition'],
+): readonly string[] {
+  const frontend = definition.frontend
+  if (frontend === undefined || frontend.source.kind === 'external') return Object.freeze([])
+  return Object.freeze(
+    Object.values(frontend.routes as Readonly<Record<string, FrontendRoute>>)
+      .flatMap((route) => (route.path === undefined ? [] : [route.path]))
+      .sort(),
+  )
+}
+
+async function writeFileAtomic(path: string, content: string): Promise<void> {
+  const tmp = `${path}.tmp`
+  await writeFile(tmp, content)
+  await rename(tmp, path)
+}
+
+export function workerName(params: CloudflareParams, origin: string): string {
+  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
+  }
+  return origin
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .slice(0, 54)
+    .replace(/^-+|-+$/g, '')
+}
+
+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/build/worker.ts

@@ -0,0 +1,37 @@
+import type { BuildCtx, CompiledFrontendArtifact } from '@astrale-os/sdk'
+
+import { join } from 'node:path'
+
+import type { CloudflareParams } from '../params.js'
+
+import { buildFrontend } from './frontend.js'
+import { prepare } from './prepare.js'
+import { runWranglerBundle } from './wrangler-cli.js'
+
+export interface CloudflareWorkerBuild {
+  readonly frontend: CompiledFrontendArtifact | undefined
+  readonly configPath: string
+  readonly bundlePath: string
+}
+
+/** One shared frontend/config/Worker qualification lifecycle for Cloudflare-based adapters. */
+export async function buildCloudflareWorker(input: {
+  readonly params: CloudflareParams
+  readonly context: BuildCtx
+  readonly outDir?: string
+  readonly onLog?: (line: string) => void
+}): Promise<CloudflareWorkerBuild> {
+  const frontend = await buildFrontend({
+    definition: input.context.definition,
+    projectDir: input.context.projectDir,
+    onLog: input.onLog,
+  })
+  const { configPath } = await prepare(input.params, input.context, 'build', frontend)
+  const bundlePath = await runWranglerBundle({
+    projectDir: input.context.projectDir,
+    configPath,
+    outDir: input.outDir ?? join(input.context.projectDir, '.astrale', 'dist-build'),
+    onLog: input.onLog,
+  })
+  return Object.freeze({ frontend, configPath, bundlePath })
+}

package/src/{wrangler-cli.ts → build/wrangler-cli.ts}

@@ -14,9 +14,9 @@ import { existsSync, readdirSync } from 'node:fs'
 import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { createServer } from 'node:net'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 
-import { parseDeployUrl, parseDevReadyUrl } from './parse-output'
+import { parseDeployUrl, parseDeployVersionId, parseDevReadyUrl } from './parse-output.js'
 
 function wranglerCommand(projectDir: string): { cmd: string; prefix: string[] } {
   const local = join(projectDir, 'node_modules', '.bin', 'wrangler')
@@ -69,6 +69,7 @@ export async function runWranglerDev(args: {
   onReload: () => void
   onLog?: (line: string) => void
 }): Promise<DevHandle> {
+  await runWranglerTypes(args)
   const { cmd, prefix } = wranglerCommand(args.projectDir)
   const bindHost = args.ip ?? '127.0.0.1'
   if (args.autoPickPort && !(await portFree(args.port, bindHost))) {
@@ -103,10 +104,12 @@ export async function runWranglerDev(args: {
   // never answers) — the classic silent hang. Track build errors so the
   // safety net can fail LOUD instead of resolving a dead URL.
   let buildErrorTail = ''
+  let outputTail = ''
 
   const url = await new Promise<string>((resolve, reject) => {
     const onData = (buf: Buffer) => {
       const text = buf.toString()
+      outputTail = (outputTail + text).slice(-3000)
       for (const line of text.split('\n')) {
         if (line.trim()) args.onLog?.(line)
       }
@@ -128,7 +131,11 @@ export async function runWranglerDev(args: {
     child.on('exit', (code) => {
       if (!resolved) {
         resolved = true
-        reject(new Error(`wrangler dev exited before becoming ready (code ${code ?? 'null'}).`))
+        reject(
+          new Error(
+            `wrangler dev exited before becoming ready (code ${code ?? 'null'}).\n${outputTail}`,
+          ),
+        )
       }
     })
     child.on('error', (err) => {
@@ -174,7 +181,8 @@ export interface DeployArgs {
 
 export async function runWranglerDeploy(
   args: DeployArgs & { projectDir: string },
-): Promise<{ url: string; raw: string }> {
+): Promise<{ url: string; raw: string; deploymentVersion?: string }> {
+  await runWranglerTypes(args)
   const { cmd, prefix } = wranglerCommand(args.projectDir)
   const deploy = (configPath: string) =>
     runCapture(cmd, [...prefix, 'deploy', '--config', configPath], args.projectDir, args.onLog)
@@ -192,7 +200,7 @@ export async function runWranglerDeploy(
 export async function deployWithSelfFallback(
   deploy: (configPath: string) => Promise<{ code: number; out: string }>,
   args: DeployArgs,
-): Promise<{ url: string; raw: string }> {
+): Promise<{ url: string; raw: string; deploymentVersion?: string }> {
   let { code, out } = await deploy(args.configPath)
 
   if (code !== 0 && args.fallbackConfigPath && isSelfBindingMissing(out, args.workerName)) {
@@ -215,7 +223,8 @@ export async function deployWithSelfFallback(
   if (!url) {
     throw new Error(`could not determine deployed URL from wrangler output:\n${out.slice(-2000)}`)
   }
-  return { url, raw: out }
+  const deploymentVersion = parseDeployVersionId(out)
+  return { url, raw: out, ...(deploymentVersion === undefined ? {} : { deploymentVersion }) }
 }
 
 /**
@@ -309,6 +318,7 @@ export async function runWranglerBundle(args: {
   outDir: string
   onLog?: (line: string) => void
 }): Promise<string> {
+  await runWranglerTypes(args)
   const { cmd, prefix } = wranglerCommand(args.projectDir)
   const { code, out } = await runCapture(
     cmd,
@@ -322,3 +332,31 @@ export async function runWranglerBundle(args: {
   const preferred = js.find((f) => f.startsWith('worker')) ?? js[0]!
   return join(args.outDir, preferred)
 }
+
+/** Generate the exact binding and runtime types selected by the generated config. */
+export async function runWranglerTypes(args: {
+  readonly projectDir: string
+  readonly configPath: string
+  readonly onLog?: (line: string) => void
+}): Promise<string> {
+  const { cmd, prefix } = wranglerCommand(args.projectDir)
+  const outputPath = join(dirname(args.configPath), 'worker-configuration.d.ts')
+  const { code, out } = await runCapture(
+    cmd,
+    [
+      ...prefix,
+      'types',
+      outputPath,
+      '--env-interface',
+      'CloudflareEnv',
+      '--config',
+      args.configPath,
+    ],
+    args.projectDir,
+    args.onLog,
+  )
+  if (code !== 0) {
+    throw new Error(`wrangler types failed (code ${code}):\n${out.slice(-2000)}`)
+  }
+  return outputPath
+}