@astrale-os/adapter-cloudflare 0.5.0-beta.12 → 0.5.0-beta.13

package/src/build/frontend.ts

@@ -1,23 +1,33 @@
 import type { CompiledFrontendArtifact, DomainDefinition, FrontendFile } from '@astrale-os/sdk'
-import type { ReactFrontendArtifact } from '@astrale-os/sdk/react'
+import type { ChildProcess } from 'node:child_process'
 
 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 { existsSync } from 'node:fs'
 import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
+import { createServer } from 'node:net'
 import { dirname, join, resolve, sep } from 'node:path'
 
 export const FRONTEND_STAGE_DIR = '.astrale/frontend'
-const FRONTEND_REBUILD_DELAY_MS = 75
+const FRONTEND_BUILD_DIR = '.astrale/frontend-build'
 let stageGeneration = 0
 const buildQueues = new Map<string, Promise<void>>()
 
+export interface ViteBuildInput {
+  readonly projectDir: string
+  readonly output: string
+  readonly config?: string
+  readonly onLog?: (line: string) => void
+}
+
+export type ViteBuild = (input: ViteBuildInput) => 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
+  readonly buildVite?: ViteBuild
 }): Promise<CompiledFrontendArtifact | undefined> {
   const key = resolve(input.projectDir)
   const previous = buildQueues.get(key) ?? Promise.resolve()
@@ -40,6 +50,7 @@ async function buildFrontendUnlocked(input: {
   readonly definition: DomainDefinition
   readonly projectDir: string
   readonly onLog?: (line: string) => void
+  readonly buildVite?: ViteBuild
 }): Promise<CompiledFrontendArtifact | undefined> {
   const artifact = input.definition.frontend
   if (artifact === undefined) return undefined
@@ -50,44 +61,15 @@ async function buildFrontendUnlocked(input: {
       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 output = contained(input.projectDir, FRONTEND_BUILD_DIR, 'Vite frontend staging output')
+  await rm(output, { recursive: true, force: true })
+  await (input.buildVite ?? runViteBuild)({
+    projectDir: input.projectDir,
+    output,
+    ...(artifact.source.config === undefined ? {} : { config: artifact.source.config }),
+    ...(input.onLog === undefined ? {} : { onLog: input.onLog }),
+  })
+  const files = await readFiles(output)
   const compiled = await compileFrontend({
     artifact,
     baseHref: 'https://frontend.invalid/',
@@ -98,109 +80,53 @@ async function buildFrontendUnlocked(input: {
   return compiled
 }
 
-export interface FrontendWatchHandle {
+export interface FrontendDevHandle {
+  readonly url: string
   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: {
+/** Start the Domain project's own Vite server; the Worker remains the browser-facing origin. */
+export async function startFrontendDev(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 {
+}): Promise<FrontendDevHandle | 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)
+  if (artifact === undefined || artifact.source.kind !== 'vite') return undefined
+  const command = viteCommand(input.projectDir)
+  const port = await ephemeralPort('127.0.0.1')
+  const args = [
+    ...command.prefix,
+    '--host',
+    '127.0.0.1',
+    '--port',
+    String(port),
+    '--strictPort',
+    ...(artifact.source.config === undefined ? [] : ['--config', artifact.source.config]),
+  ]
+  const child = spawn(command.command, args, {
+    cwd: input.projectDir,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  const output: string[] = []
+  const collect = (buffer: Buffer) => {
+    for (const line of buffer.toString().split('\n')) {
+      if (line.trim() === '') continue
+      output.push(line)
+      if (output.length > 40) output.shift()
+      input.onLog?.(line)
     }
   }
-  const schedule = (path?: string) => {
-    if (stopped || !rebuildsFor(source, path)) return
-    pending = true
-    if (timer !== undefined) clearTimeout(timer)
-    timer = setTimeout(() => {
-      timer = undefined
-      void drain()
-    }, delayMs)
+  child.stdout?.on('data', collect)
+  child.stderr?.on('data', collect)
+  const url = `http://127.0.0.1:${port}`
+  try {
+    await waitUntilReady(url, child, output)
+  } catch (error) {
+    await stopChild(child)
+    throw error
   }
-  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'
-  )
+  return Object.freeze({ url, stop: () => stopChild(child) })
 }
 
 async function readFiles(root: string, current = ''): Promise<readonly FrontendFile[]> {
@@ -249,42 +175,6 @@ async function replaceStage(projectDir: string, files: readonly FrontendFile[]):
   }
 }
 
-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'
 }
@@ -298,7 +188,34 @@ function contained(root: string, input: string, label: string): string {
   return target
 }
 
-function runBuild(
+function viteCommand(projectDir: string): { command: string; prefix: readonly string[] } {
+  const command = join(projectDir, 'node_modules', '.bin', 'vite')
+  if (!existsSync(command)) {
+    throw new TypeError(
+      'Vite frontend requires the Domain project to install vite as a development dependency.',
+    )
+  }
+  return { command, prefix: [] }
+}
+
+async function runViteBuild(input: ViteBuildInput): Promise<void> {
+  const command = viteCommand(input.projectDir)
+  await runProcess(
+    command.command,
+    [
+      ...command.prefix,
+      'build',
+      '--outDir',
+      input.output,
+      '--emptyOutDir',
+      ...(input.config === undefined ? [] : ['--config', input.config]),
+    ],
+    input.projectDir,
+    input.onLog,
+  )
+}
+
+function runProcess(
   command: string,
   args: readonly string[],
   cwd: string,
@@ -318,7 +235,64 @@ function runBuild(
     child.on('exit', (code) =>
       code === 0
         ? resolveBuild()
-        : reject(new Error(`frontend build failed (code ${code ?? 1}):\n${output.slice(-1500)}`)),
+        : reject(
+            new Error(`Vite frontend build failed (code ${code ?? 1}):\n${output.slice(-1500)}`),
+          ),
     )
   })
 }
+
+function ephemeralPort(host: string): Promise<number> {
+  return new Promise((resolvePort, reject) => {
+    const server = createServer()
+    server.once('error', reject)
+    server.listen(0, host, () => {
+      const address = server.address()
+      const port = typeof address === 'object' && address !== null ? address.port : 0
+      server.close((error) => (error === undefined ? resolvePort(port) : reject(error)))
+    })
+  })
+}
+
+async function waitUntilReady(
+  url: string,
+  child: ChildProcess,
+  output: readonly string[],
+): Promise<void> {
+  const deadline = Date.now() + 15_000
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(
+        `Vite frontend dev server exited before becoming ready (code ${child.exitCode}).\n${output.join('\n')}`,
+      )
+    }
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(500) })
+      await response.body?.cancel()
+      return
+    } catch {
+      await new Promise((resolveDelay) => setTimeout(resolveDelay, 50))
+    }
+  }
+  throw new Error(`Vite frontend dev server did not become ready at ${url}.\n${output.join('\n')}`)
+}
+
+function stopChild(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.killed) return Promise.resolve()
+  return new Promise((resolveStop) => {
+    let settled = false
+    const finish = () => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolveStop()
+    }
+    const timer = setTimeout(() => {
+      if (child.exitCode === null) child.kill('SIGKILL')
+      finish()
+    }, 2_000)
+    timer.unref?.()
+    child.once('exit', finish)
+    child.kill('SIGTERM')
+  })
+}

package/src/build/index.ts

@@ -13,10 +13,10 @@
 export {
   buildFrontend,
   FRONTEND_STAGE_DIR,
-  watchFrontend,
-  type FrontendWatchHandle,
-  type FrontendWatchSubscribe,
-  type FrontendWatchSubscription,
+  startFrontendDev,
+  type FrontendDevHandle,
+  type ViteBuild,
+  type ViteBuildInput,
 } from './frontend.js'
 export { logTo, prepare } from './prepare.js'
 export { buildCloudflareWorker, type CloudflareWorkerBuild } from './worker.js'

package/src/build/prepare.ts

@@ -17,6 +17,7 @@ import { generateWranglerConfig } from './codegen/wrangler.js'
 
 const DEFAULT_PORT = 8787
 const DEPLOYMENT_VERSION_BINDING = 'ASTRALE_DEPLOYMENT_VERSION'
+const FRONTEND_DEV_BINDING = 'FRONTEND_DEV_URL'
 const WORKER_NAME_RE = /^[a-z0-9][a-z0-9-]*$/
 
 /** Prepare immutable generated Worker sources and Wrangler configuration. */
@@ -25,12 +26,23 @@ export async function prepare(
   ctx: WatchCtx | DeployCtx | BuildCtx,
   mode: 'build' | 'dev' | 'deploy',
   frontend?: CompiledFrontendArtifact,
+  frontendDevUrl?: string,
 ): 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\`.`,
     )
   }
+  if (Object.hasOwn(params.vars ?? {}, FRONTEND_DEV_BINDING)) {
+    throw new Error(
+      `cloudflare adapter: \`${FRONTEND_DEV_BINDING}\` is adapter-managed and cannot be set in \`vars\`.`,
+    )
+  }
+  if (frontendDevUrl !== undefined && (mode !== 'dev' || !localFrontendDefinition(ctx))) {
+    throw new TypeError(
+      'cloudflare adapter: frontendDevUrl requires a local Vite frontend in dev mode.',
+    )
+  }
   const astraleDir = join(ctx.projectDir, '.astrale')
   await mkdir(astraleDir, { recursive: true })
   await ensureIdentity(astraleDir, ctx.definition.schema.origin)
@@ -39,9 +51,14 @@ export async function prepare(
   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')) {
+  const developmentFrontend = mode === 'dev' && frontendDevUrl !== undefined
+  if (
+    !developmentFrontend &&
+    localFrontend !== (frontend !== undefined && frontend.artifact.source.kind !== 'external')
+  ) {
     throw new TypeError('cloudflare adapter: materialized frontend must match definition.frontend.')
   }
+  if (developmentFrontend) await mkdir(join(astraleDir, 'frontend'), { recursive: true })
 
   await writeFileAtomic(
     join(astraleDir, 'worker.gen.ts'),
@@ -67,6 +84,7 @@ export async function prepare(
         : undefined
   const vars = {
     ...(workerUrl ? { WORKER_URL: workerUrl } : {}),
+    ...(frontendDevUrl === undefined ? {} : { FRONTEND_DEV_URL: frontendDevUrl }),
     ...(mode === 'dev'
       ? { ...params.vars, ...('secrets' in ctx ? ctx.secrets : {}) }
       : { ...params.vars }),
@@ -79,6 +97,7 @@ export async function prepare(
           frontend: {
             directory: './frontend',
             routes: localFrontendRoutes(ctx.definition),
+            dev: frontendDevUrl !== undefined,
           },
         }
       : {}),
@@ -112,11 +131,20 @@ function localFrontendRoutes(
 ): 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(),
-  )
+  const routes = Object.values(frontend.routes as Readonly<Record<string, FrontendRoute>>)
+    .flatMap((route) =>
+      frontend.source.kind === 'vite' && frontend.source.spa && route.path !== '/'
+        ? [route.path, `${route.path}/*`]
+        : route.path === '/'
+          ? ['/*']
+          : [route.path],
+    )
+    .sort()
+  return Object.freeze(routes)
+}
+
+function localFrontendDefinition(ctx: WatchCtx | DeployCtx | BuildCtx): boolean {
+  return ctx.definition.frontend?.source.kind === 'vite'
 }
 
 async function writeFileAtomic(path: string, content: string): Promise<void> {

package/src/cloudflare.ts

@@ -14,6 +14,7 @@ import type { DeployFetch } from '@astrale-os/sdk/deployment'
 
 import { defineAdapter } from '@astrale-os/sdk'
 import { deployCheck } from '@astrale-os/sdk/deployment'
+import { resolve } from 'node:path'
 
 import type { CloudflareParams } from './params.js'
 
@@ -26,7 +27,7 @@ import {
   runWranglerDeploy,
   runWranglerDev,
   runWranglerTypes,
-  watchFrontend,
+  startFrontendDev,
 } from './build/index.js'
 
 export function cloudflare(
@@ -41,7 +42,7 @@ export function cloudflare(
     runWranglerDeploy,
     runWranglerDev,
     runWranglerTypes,
-    watchFrontend,
+    startFrontendDev,
     waitUntilLive,
   })
 }
@@ -55,7 +56,7 @@ interface CloudflareAdapterDependencies {
   readonly runWranglerDeploy: typeof runWranglerDeploy
   readonly runWranglerDev: typeof runWranglerDev
   readonly runWranglerTypes: typeof runWranglerTypes
-  readonly watchFrontend: typeof watchFrontend
+  readonly startFrontendDev: typeof startFrontendDev
   readonly waitUntilLive: typeof waitUntilLive
 }
 
@@ -64,6 +65,7 @@ export function cloudflareWithDependencies(
   envs: Record<string, CloudflareParams>,
   dependencies: CloudflareAdapterDependencies,
 ): DomainAdapter<CloudflareParams> {
+  const frontendDevUrls = new Map<string, string>()
   return defineAdapter<CloudflareParams>({
     name: 'cloudflare',
     envs,
@@ -78,44 +80,46 @@ export function cloudflareWithDependencies(
 
     async watch(params, ctx) {
       const onLog = dependencies.logTo()
-      const frontend = await dependencies.buildFrontend({
-        definition: ctx.definition,
-        projectDir: ctx.projectDir,
-        onLog,
-      })
-      const { configPath, port } = await dependencies.prepare(params, ctx, 'dev', frontend)
-      const handle = await dependencies.runWranglerDev({
-        projectDir: ctx.projectDir,
-        configPath,
-        port,
-        remote: Boolean(params.remote),
-        autoPickPort: params.port === undefined,
-        ...(params.host ? { ip: '0.0.0.0' } : {}),
-        onReload: ctx.onReload,
-        onLog,
-      })
-      let frontendWatch: ReturnType<typeof watchFrontend>
+      const projectKey = resolve(ctx.projectDir)
+      let frontendDev: Awaited<ReturnType<typeof startFrontendDev>>
+      let handle: Awaited<ReturnType<typeof runWranglerDev>> | undefined
       try {
-        frontendWatch = dependencies.watchFrontend({
+        frontendDev = await dependencies.startFrontendDev({
           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,
+        })
+        if (frontendDev !== undefined) frontendDevUrls.set(projectKey, frontendDev.url)
+        const { configPath, port } = await dependencies.prepare(
+          params,
+          ctx,
+          'dev',
+          undefined,
+          frontendDev?.url,
+        )
+        handle = await dependencies.runWranglerDev({
+          projectDir: ctx.projectDir,
+          configPath,
+          port,
+          remote: Boolean(params.remote),
+          autoPickPort: params.port === undefined,
+          ...(params.host ? { ip: '0.0.0.0' } : {}),
+          onReload: ctx.onReload,
+          onLog,
         })
       } catch (error) {
+        frontendDevUrls.delete(projectKey)
         try {
-          await handle.stop()
+          await frontendDev?.stop()
         } catch (cleanupError) {
           throw new AggregateError(
             [error, cleanupError],
-            'cloudflare frontend watcher startup failed and Wrangler cleanup also failed',
+            'cloudflare development startup failed and Vite cleanup also failed',
           )
         }
         throw error
       }
+      if (handle === undefined) throw new Error('cloudflare local Worker failed to start')
       // With --host the actionable URL is the PUBLIC one (the tunnel/proxy
       // front), not the local bind — print and spec-stamp that.
       return {
@@ -123,8 +127,9 @@ export function cloudflareWithDependencies(
         localUrl: handle.url,
         async stop() {
           const errors: unknown[] = []
+          frontendDevUrls.delete(projectKey)
           try {
-            await frontendWatch?.stop()
+            await frontendDev?.stop()
           } catch (error) {
             errors.push(error)
           }
@@ -141,17 +146,16 @@ export function cloudflareWithDependencies(
       }
     },
 
-    // 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 + frontend build), minus the spawn.
+    // Config hot-regen rewrites generated files only. Wrangler reloads its config and entry;
+    // the author-owned Vite process keeps its own source/config watch lifecycle.
     async regenerate(params, ctx) {
-      const frontend = await dependencies.buildFrontend({
-        definition: ctx.definition,
-        projectDir: ctx.projectDir,
-        onLog: dependencies.logTo(),
-      })
-      const { configPath } = await dependencies.prepare(params, ctx, 'dev', frontend)
+      const { configPath } = await dependencies.prepare(
+        params,
+        ctx,
+        'dev',
+        undefined,
+        frontendDevUrls.get(resolve(ctx.projectDir)),
+      )
       await dependencies.runWranglerTypes({
         projectDir: ctx.projectDir,
         configPath,