infra-kit 0.1.126 → 0.1.127

package/src/dev/dev-server.ts

@@ -0,0 +1,796 @@
+/**
+ * Unified Development Server Runner
+ *
+ * Discovers and runs API apps under each `apps/<app>/api` folder that contains `serverless.yml`.
+ *
+ * Ports: `{APP}_PORT`, then `process.env.PORT`, then `dev.<app>.port` from infra-kit.json,
+ * else 3010. URL prefix: `dev.<app>.prefixUrl`, else `/api/v1`.
+ * Env vars should be provided via secrets manager (e.g. `doppler run -- pnpm dev-server`) or shell.
+ *
+ * This module is side-effect free on import: call `run()` (or construct `DevServerRunner`
+ * directly) to start. Signal handling and process exit are the entry point's responsibility.
+ *
+ * Runner messages append to `<cwd>/.infra-kit/dev-server.log`. Lambda / Powertools logs from
+ * handlers go to stdout.
+ */
+import chokidar from 'chokidar'
+import type { FSWatcher } from 'chokidar'
+import { exec } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import process from 'node:process'
+import util from 'node:util'
+
+import type { DevConfig } from 'src/lib/infra-kit-config'
+import { getInfraKitConfig } from 'src/lib/infra-kit-config'
+
+import {
+  classifyDistChange,
+  discoverApiApps as discoverApiAppsBare,
+  discoverUiApps as discoverUiAppsBare,
+  findMonorepoRoot,
+  getAppDistDirs,
+  getPackageDistDirs,
+  normalizeAppInclude as normalizeAppIncludePure,
+} from './discovery.js'
+import type { DiscoveredUiApp } from './discovery.js'
+import { findPortConflicts, resolvePort as resolvePortPure, resolvePrefixUrl as resolvePrefixUrlPure } from './ports.js'
+import { ServerlessLocalRun } from './serverless-local-run.js'
+import { defaultTurboWatchFactory } from './turbo-watch.js'
+import type { TurboWatchFactory, TurboWatchHandle } from './turbo-watch.js'
+import { defaultUiDevFactory } from './ui-dev.js'
+import type { UiDevFactory, UiDevHandle } from './ui-dev.js'
+
+/** Runner-only log file, resolved under the consumer repo's `.infra-kit/` dir at startup. */
+let LOG_FILE_PATH = path.join(process.cwd(), '.infra-kit', 'dev-server.log')
+
+/** Resolve `<cwd>/.infra-kit/dev-server.log`, ensure the dir exists, and clear the file. */
+function initLogFile(): void {
+  LOG_FILE_PATH = path.join(process.cwd(), '.infra-kit', 'dev-server.log')
+  fs.mkdirSync(path.dirname(LOG_FILE_PATH), { recursive: true })
+  fs.writeFileSync(LOG_FILE_PATH, `=== Dev Server Started: ${new Date().toISOString()} ===\n\n`)
+}
+
+const execFn = util.promisify(exec)
+
+type LogFn = (msg: string, level?: 'info' | 'warn' | 'error' | 'debug') => void
+
+/**
+ * Build seam: shells out to turbo by default ({@link launchScript}); injectable so
+ * tests can run the orchestrator without a real build. `logFn` is optional so both
+ * the verbose initial build and the terse restart builds keep their current output.
+ */
+export type BuildRunner = (cmd: string, logFn?: LogFn) => Promise<void>
+
+const launchScript = async (script: string, logFn?: LogFn): Promise<void> => {
+  try {
+    const { stderr } = await execFn(script)
+
+    if (stderr && logFn) logFn(`   (build) ${stderr.trim()}`, 'debug')
+    if (stderr && !logFn) console.error('stderr:', stderr)
+  } catch (error) {
+    const err = error as { stdout?: string; stderr?: string; message?: string }
+
+    if (logFn && (err.stdout || err.stderr)) {
+      if (err.stdout) logFn(`   stdout: ${err.stdout.trim()}`, 'error')
+      if (err.stderr) logFn(`   stderr: ${err.stderr.trim()}`, 'error')
+    }
+
+    throw error
+  }
+}
+
+/** Append raw text to the runner-only log file (the single tee-to-file seam). */
+function appendLogFile(text: string): void {
+  fs.appendFileSync(LOG_FILE_PATH, text)
+}
+
+/** Write a message to the console (routed by level) and tee it to the log file. */
+function log(message: string, level: 'info' | 'warn' | 'error' | 'debug' = 'info'): void {
+  if (level === 'error') {
+    console.error(message)
+  } else if (level === 'warn') {
+    console.warn(message)
+  } else {
+    process.stdout.write(`${message}\n`)
+  }
+
+  appendLogFile(`[${new Date().toISOString()}] [${level.toUpperCase()}] ${message}\n`)
+}
+
+/** Write pre-formatted table lines to stdout and tee them to the log file. */
+function logTable(lines: string[]): void {
+  const output = `${lines.join('\n')}\n`
+
+  process.stdout.write(`${output}\n`)
+  appendLogFile(`${output}\n`)
+}
+
+/** Center `s` within `width` columns (clamped, so a too-long string is never truncated). */
+function center(s: string, width: number): string {
+  const pad = Math.max(0, width - s.length)
+  const left = Math.floor(pad / 2)
+
+  return `${' '.repeat(left)}${s}${' '.repeat(pad - left)}`
+}
+
+/**
+ * Render a box-drawn table whose column widths are computed from the longest cell in
+ * each column, so every emitted line shares one width regardless of app-name length
+ * (the old fixed `padEnd` misaligned on long names). Borders are generated from the
+ * same widths, so they always match the rows.
+ */
+function renderTable(title: string, headers: string[], rows: string[][]): string[] {
+  const widths = headers.map((header, i) => {
+    return Math.max(
+      header.length,
+      ...rows.map((row) => {
+        return (row[i] ?? '').length
+      }),
+    )
+  })
+  // Grow the last column if the title is wider than the columns, so the title band never clips.
+  const columnsInner =
+    widths.reduce((sum, w) => {
+      return sum + w + 2
+    }, 0) +
+    (widths.length - 1)
+
+  const lastIdx = widths.length - 1
+
+  if (lastIdx >= 0 && title.length + 2 > columnsInner) {
+    widths[lastIdx] = (widths[lastIdx] ?? 0) + (title.length + 2 - columnsInner)
+  }
+
+  const inner =
+    widths.reduce((sum, w) => {
+      return sum + w + 2
+    }, 0) +
+    (widths.length - 1)
+  const blocks = widths.map((w) => {
+    return '─'.repeat(w + 2)
+  })
+  const rowLine = (cells: string[]): string => {
+    return `│ ${cells
+      .map((c, i) => {
+        return (c ?? '').padEnd(widths[i]!)
+      })
+      .join(' │ ')} │`
+  }
+
+  return [
+    '',
+    `┌${'─'.repeat(inner)}┐`,
+    `│${center(title, inner)}│`,
+    `├${blocks.join('┬')}┤`,
+    rowLine(headers),
+    `├${blocks.join('┼')}┤`,
+    ...rows.map(rowLine),
+    `└${blocks.join('┴')}┘`,
+    '',
+  ]
+}
+
+interface IApiAppConfig {
+  /** App folder name (e.g. backoffice, client) */
+  name: string
+  /** Package name from package.json (e.g. sls-trvl-client) */
+  packageName: string
+  path: string
+  port: number
+  prefixUrl: string
+}
+
+/**
+ * Runner options, parsed by the CLI entry point (`--watch`, `--app`) and threaded
+ * through `run()`. The entry owns flag parsing; the runner never reads `process.argv`
+ * itself. App selection is `--app` only; ports come from env/config (see `resolvePort`).
+ */
+export interface DevServerOptions {
+  /**
+   * Watch mode: start a long-lived `turbo watch build` engine (incremental rebuilds
+   * + dependency fan-out) and restart the affected server(s) when compiled `dist/`
+   * changes. Without it, `dev` builds and serves once and exits on signal.
+   */
+  watch?: boolean
+  /** Only run these app folder names (null/empty = all discovered). Filters BOTH api and ui apps. */
+  include?: string[] | null
+  /**
+   * Also run frontends: discover `apps/<app>/ui` with a `dev` script and start them via one
+   * delegated `turbo run dev` child (streamed to the terminal). Default (unset) = api-only,
+   * preserving today's behavior.
+   */
+  ui?: boolean
+}
+
+interface IAppServer {
+  app: IApiAppConfig
+  server: ServerlessLocalRun
+}
+
+export class DevServerRunner {
+  private readonly monorepoRoot: string
+  private readonly appServers: IAppServer[] = []
+  private watchDebounceTimers: Map<string, ReturnType<typeof setTimeout>> = new Map()
+  /** Active chokidar watcher in `--watch` mode; closed on {@link shutdown}. */
+  private watcher: FSWatcher | null = null
+  private static readonly WATCH_DEBOUNCE_MS = 400
+  /** Serialized restarts so rapid saves never bind :port while the previous server is still shutting down. */
+  private restartWorkChain: Promise<void> = Promise.resolve()
+  private static readonly PORT_RELEASE_DELAY_MS = 200
+  private readonly options: DevServerOptions
+  /** Build runner seam — real turbo shell-out by default, injectable for tests. */
+  private readonly runBuild: BuildRunner
+  /** `turbo watch` spawn seam — real detached child by default, injectable for tests. */
+  private readonly turboWatchFactory: TurboWatchFactory
+  /** Live `turbo watch` engine in `--watch` mode; reaped on {@link shutdown}. */
+  private turboWatch: TurboWatchHandle | null = null
+  /** `turbo run dev` (frontends) spawn seam — real detached child by default, injectable for tests. */
+  private readonly uiDevFactory: UiDevFactory
+  /** Live `turbo run dev` frontend engine in `--ui` mode; reaped on {@link shutdown}. */
+  private uiDev: UiDevHandle | null = null
+
+  constructor(
+    options: DevServerOptions = {},
+    runBuild: BuildRunner = launchScript,
+    turboWatchFactory: TurboWatchFactory = defaultTurboWatchFactory,
+    uiDevFactory: UiDevFactory = defaultUiDevFactory,
+  ) {
+    this.options = options
+    this.runBuild = runBuild
+    this.turboWatchFactory = turboWatchFactory
+    this.uiDevFactory = uiDevFactory
+    initLogFile()
+
+    // Walk up from the consumer repo cwd to the monorepo root.
+    this.monorepoRoot = findMonorepoRoot(process.cwd())
+    log(`Monorepo root: ${this.monorepoRoot}`)
+
+    if (process.env.DOPPLER_PROJECT != null || process.env.DOPPLER_ENVIRONMENT != null) {
+      log('🔐 Doppler env detected (DOPPLER_PROJECT / DOPPLER_ENVIRONMENT)', 'debug')
+    }
+  }
+
+  /**
+   * Discover API apps and resolve each app's port + URL prefix. Delegates bare
+   * filesystem discovery to {@link discoverApiAppsBare} and per-app resolution to
+   * the pure `resolvePort` / `resolvePrefixUrl`, preserving the original behavior.
+   */
+  private discoverApiApps(devConfig: DevConfig): IApiAppConfig[] {
+    return discoverApiAppsBare(this.monorepoRoot).map((app) => {
+      return {
+        ...app,
+        port: this.resolvePort(app.name, devConfig),
+        prefixUrl: this.resolvePrefixUrl(app.name, devConfig),
+      }
+    })
+  }
+
+  /**
+   * Read the `dev` section from the resolved infra-kit config. Defensive: any
+   * failure (not in an infra-kit project, missing/invalid config) resolves to an
+   * empty map so the dev-server always falls back to env vars + built-in defaults
+   * rather than refusing to start.
+   */
+  private async loadDevConfig(): Promise<DevConfig> {
+    try {
+      const config = await getInfraKitConfig()
+
+      return config.dev ?? {}
+    } catch {
+      return {}
+    }
+  }
+
+  /** Thin delegator to the pure {@link normalizeAppIncludePure} over the runner's `--app` list. */
+  private normalizeAppInclude(): string[] | null {
+    return normalizeAppIncludePure(this.options.include)
+  }
+
+  /** Thin delegator to the pure {@link resolvePortPure}, threading env + config. */
+  private resolvePort(appName: string, devConfig: DevConfig): number {
+    return resolvePortPure(appName, process.env, devConfig)
+  }
+
+  /** Thin delegator to the pure {@link resolvePrefixUrlPure}. */
+  private resolvePrefixUrl(appName: string, devConfig: DevConfig): string {
+    return resolvePrefixUrlPure(appName, devConfig)
+  }
+
+  public async start(): Promise<void> {
+    const include = this.normalizeAppInclude()
+    const watch = this.options.watch ?? false
+    const devConfig = await this.loadDevConfig()
+
+    process.env.POWERTOOLS_DEV ??= 'true'
+    process.env.LOG_LEVEL ??= 'DEBUG'
+
+    log('🚀 Starting Development Server Runner')
+
+    if (watch) {
+      log('👀 Watch mode: will rebuild and restart on file save')
+    }
+    log(`📂 Monorepo root: ${this.monorepoRoot}`)
+
+    const apps = this.selectApps(this.discoverApiApps(devConfig), include)
+    const uiApps = (this.options.ui ?? false) ? this.selectUiApps(include) : []
+
+    if (apps.length === 0 && uiApps.length === 0) {
+      log(this.options.ui ? '⚠️  No API or UI apps found to run' : '⚠️  No API apps found to run', 'warn')
+
+      return
+    }
+
+    // Build the API boot closure (dist must exist before servers import handlers).
+    if (apps.length > 0) {
+      log(`📦 Discovered ${apps.length} API app(s): ${this.formatAppList(apps)}`)
+      this.assertNoPortConflicts(apps)
+      await this.buildApps(apps, watch)
+    }
+
+    // Warm the UI dependency closure BEFORE spawning any persistent child (turbo watch / turbo run
+    // dev), so both see a warm cache and the cold-cache double-build race can't corrupt shared dist.
+    if (uiApps.length > 0) {
+      await this.buildUiApps(uiApps)
+    }
+
+    if (apps.length > 0) {
+      await this.startAllApps(apps)
+      log('🎉 All servers started!')
+      this.printServerTable(apps)
+      this.printRouteDump()
+      log(
+        `📝 Handler logs (AWS Powertools, logger.info/debug, etc.) → this terminal. Runner-only file: ${LOG_FILE_PATH}`,
+      )
+    }
+
+    if (watch && this.appServers.length > 0) {
+      this.setupWatch(apps)
+    }
+
+    // Frontends last: their delegated `turbo run dev` streams raw to the terminal below the BE table.
+    if (uiApps.length > 0) {
+      this.startUiDev(uiApps)
+    }
+  }
+
+  /** Discover `apps/<app>/ui` frontends (with a `dev` script), applying the `--app` include filter. */
+  private selectUiApps(include: string[] | null): DiscoveredUiApp[] {
+    const uiApps = discoverUiAppsBare(this.monorepoRoot)
+    const selected = include
+      ? uiApps.filter((a) => {
+          return include.includes(a.name)
+        })
+      : uiApps
+
+    if (selected.length > 0) {
+      log(
+        `🎨 Discovered ${selected.length} UI app(s): ${selected
+          .map((a) => {
+            return a.name
+          })
+          .join(', ')}`,
+      )
+    }
+
+    return selected
+  }
+
+  /**
+   * Warm ONLY each UI's dependency closure (`<pkg>^...` — deps, excluding the UI itself, so no full
+   * production `vite build`) with a cache-friendly (non-`--force`) turbo build. Non-fatal: if it
+   * fails, `turbo run dev`'s own `^build` retries and surfaces the error in its streamed output.
+   */
+  private async buildUiApps(uiApps: DiscoveredUiApp[]): Promise<void> {
+    const filters = uiApps
+      .map((a) => {
+        return `--filter=${a.packageName}^...`
+      })
+      .join(' ')
+
+    log('🔨 Warming UI dependency build cache (turbo)...')
+    try {
+      await this.runBuild(`pnpm exec turbo run build ${filters} --env-mode=loose`, log)
+      log('✅ UI deps built')
+    } catch (error) {
+      log(`⚠️  UI dep warm build failed (continuing; turbo run dev will build): ${String(error)}`, 'warn')
+    }
+  }
+
+  /**
+   * Start the frontends via ONE delegated `turbo run dev` child (streamed to the terminal). Reaped
+   * on {@link shutdown}. Concurrency ≥ the persistent UI `dev` task count (turbo hard-errors otherwise).
+   */
+  private startUiDev(uiApps: DiscoveredUiApp[]): void {
+    const names = uiApps
+      .map((a) => {
+        return a.name
+      })
+      .join(', ')
+
+    log(`🎨 Starting ${uiApps.length} UI dev server(s) via \`turbo run dev\`: ${names}`)
+    log('   (framework dev output streams below; each prints its own local URL)')
+
+    this.uiDev = this.uiDevFactory({
+      packageNames: uiApps.map((a) => {
+        return a.packageName
+      }),
+      cwd: process.cwd(),
+      concurrency: Math.max(uiApps.length + 4, 12),
+    })
+  }
+
+  /** Render an app list as `name:port, name:port` for log lines. */
+  private formatAppList(apps: Array<{ name: string; port: number }>): string {
+    return apps
+      .map((a) => {
+        return `${a.name}:${a.port}`
+      })
+      .join(', ')
+  }
+
+  /** Apply the `--app` include filter (logging it when applied). */
+  private selectApps(apps: IApiAppConfig[], include: string[] | null): IApiAppConfig[] {
+    if (!include) {
+      return apps
+    }
+
+    log(`🔍 Filtering to apps: ${include.join(', ')}`)
+
+    return apps.filter((app) => {
+      return include.includes(app.name)
+    })
+  }
+
+  /** Throw (after logging remediation tips) when two apps resolve to the same port. */
+  private assertNoPortConflicts(apps: IApiAppConfig[]): void {
+    const { duplicatePorts, conflictingApps } = findPortConflicts(apps)
+
+    if (duplicatePorts.length === 0) {
+      return
+    }
+
+    log(`⚠️  Port conflict detected! ${duplicatePorts.join(', ')}`, 'error')
+    log(`Conflicting apps: ${this.formatAppList(conflictingApps)}`, 'error')
+    log('\n💡 Tip: give each app a distinct port via `{APP}_PORT` env (e.g. `CLIENT_PORT=`,', 'error')
+    log('   `SEARCH_ENGINE_PORT=`) or `dev.<app>.port` in infra-kit.json; or run a subset with', 'error')
+    log('   `--app=<name>,<name>`.\n', 'error')
+    throw new Error(`Port conflict detected: ${duplicatePorts.join(', ')}`)
+  }
+
+  /** Build every app via turbo; rethrows the build error after logging stdout/stderr. */
+  private async buildApps(apps: IApiAppConfig[], watch: boolean): Promise<void> {
+    const filters = apps
+      .map((a) => {
+        return `--filter=${a.packageName}`
+      })
+      .join(' ')
+    // With `--watch`, always bypass Turbo cache so `tsc` runs and `dist/` matches disk (otherwise watch restarts can be no-ops).
+    const buildCmd = `pnpm exec turbo run build ${filters} --env-mode=loose${watch ? ' --force' : ''}`
+
+    log('🔨 Building API apps (turbo)...')
+    try {
+      await this.runBuild(buildCmd, log)
+      log('✅ Build complete')
+    } catch (buildError) {
+      log(`❌ Build failed: ${String(buildError)}`, 'error')
+      if (buildError instanceof Error && buildError.message) {
+        log(`   ${buildError.message}`, 'error')
+      }
+      const err = buildError as { stdout?: string; stderr?: string }
+
+      if (err.stdout) log(`   stdout: ${err.stdout.trim()}`, 'error')
+      if (err.stderr) log(`   stderr: ${err.stderr.trim()}`, 'error')
+      throw buildError
+    }
+  }
+
+  /**
+   * Start every app concurrently, collecting the ones that boot; per-app failures are logged,
+   * not fatal. Safe to parallelize because each app has a distinct port (guarded up-front) and a
+   * distinct `ServerlessLocalRun`, and `startOneApp` no longer mutates cwd. Push order into
+   * `appServers` is non-deterministic but nothing depends on it (the table renders from `apps`).
+   */
+  private async startAllApps(apps: IApiAppConfig[]): Promise<void> {
+    await Promise.all(
+      apps.map(async (app) => {
+        try {
+          const server = await this.startOneApp(app)
+
+          if (server) {
+            this.appServers.push({ app, server })
+          }
+        } catch (error) {
+          log(`❌ Failed to start ${app.name}: ${String(error)}`, 'error')
+        }
+      }),
+    )
+  }
+
+  private async startOneApp(app: IApiAppConfig): Promise<ServerlessLocalRun | null> {
+    log(`🔄 Starting ${app.name}...`)
+
+    // No `process.chdir` here: `ServerlessLocalRun` reads `serverless.yml` and imports the
+    // compiled handler from `controllersPath` (absolute), so the runner never mutates cwd —
+    // which is what makes concurrent boot/restart safe.
+    const server = new ServerlessLocalRun({
+      controllersPath: app.path,
+      prefixUrl: app.prefixUrl,
+      port: app.port,
+      appName: app.name,
+    })
+
+    await server.start()
+    log(`✅ ${app.name} started on port ${app.port}`)
+
+    return server
+  }
+
+  /** Run restart jobs one after another (watch can fire faster than close + listen). */
+  private scheduleRestartWork(work: () => Promise<void>): Promise<void> {
+    const run = this.restartWorkChain.then(
+      () => {
+        return work()
+      },
+      () => {
+        return work()
+      },
+    )
+
+    this.restartWorkChain = run.catch(() => {})
+
+    return run
+  }
+
+  private async delayPortRelease(): Promise<void> {
+    await new Promise((r) => {
+      return setTimeout(r, DevServerRunner.PORT_RELEASE_DELAY_MS)
+    })
+  }
+
+  /**
+   * Schedule a restart of the given apps (1 or N), serialized against other restarts via
+   * {@link scheduleRestartWork}. A single-app dist change passes `[app]`; a dependency-package
+   * dist change passes every running app. The `turbo watch` engine has already rebuilt `dist/`,
+   * so the runner only bounces the fastify server(s) — no build here.
+   */
+  private restart(apps: IApiAppConfig[]): Promise<void> {
+    return this.scheduleRestartWork(() => {
+      return this.runRestart(apps)
+    })
+  }
+
+  /** Resolve the requested apps to their live server slots (dropping any not running). */
+  private resolveRestartTargets(apps: IApiAppConfig[]): Array<{ idx: number; app: IApiAppConfig }> {
+    return apps
+      .map((app) => {
+        return {
+          idx: this.appServers.findIndex((e) => {
+            return e.app.name === app.name
+          }),
+          app,
+        }
+      })
+      .filter((t) => {
+        return t.idx >= 0
+      })
+  }
+
+  private async runRestart(apps: IApiAppConfig[]): Promise<void> {
+    const targets = this.resolveRestartTargets(apps)
+
+    if (targets.length === 0) return
+
+    const label = targets.length === 1 ? targets[0]!.app.name : `${targets.length} apps`
+
+    log(`🔄 Restarting ${label}...`)
+    await Promise.all(
+      targets.map(async ({ idx }) => {
+        try {
+          await this.appServers[idx]!.server.close()
+        } catch (err) {
+          log(`   Close warning: ${String(err)}`, 'debug')
+        }
+      }),
+    )
+
+    await this.delayPortRelease()
+
+    await Promise.all(
+      targets.map(async ({ idx, app }) => {
+        try {
+          const newServer = await this.startOneApp(app)
+
+          if (newServer) {
+            this.appServers[idx] = { app, server: newServer }
+          }
+        } catch (error) {
+          log(`❌ Failed to restart ${app.name}: ${String(error)}`, 'error')
+        }
+      }),
+    )
+    log(`✅ Restarted ${label}`)
+  }
+
+  /**
+   * Start the long-lived `turbo watch build` engine, then watch compiled `dist/` output to
+   * trigger restarts. A change under an app's `dist` restarts that app; a change under any
+   * `packages/<pkg>/dist` restarts every app (editing a shared lib rewrites only the lib's
+   * `dist`, so a package-dist change is the lib-rebuild signal). Restarts are build-less —
+   * the engine already rebuilt `dist/`.
+   */
+  private setupWatch(apps: IApiAppConfig[]): void {
+    this.turboWatch = this.turboWatchFactory({
+      packageNames: apps.map((a) => {
+        return a.packageName
+      }),
+      cwd: process.cwd(),
+      logFile: LOG_FILE_PATH,
+    })
+    log('👀 Watch mode: started `turbo watch build` engine; watching dist output')
+
+    const appDistDirs = getAppDistDirs(apps)
+    const packageDistDirs = getPackageDistDirs(this.monorepoRoot)
+    const allDistDirs = [...appDistDirs, ...packageDistDirs]
+
+    if (allDistDirs.length === 0) {
+      log('⚠️  No app or package dist directories found to watch (were they built?)', 'warn')
+
+      return
+    }
+
+    const usePoll = process.env.DEV_SERVER_CHOKIDAR_POLL === '1'
+
+    const watcher = chokidar.watch(allDistDirs, {
+      ignoreInitial: true,
+      awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 100 },
+      // Ignore tsc's incremental bookkeeping + sourcemaps: they rewrite on every build
+      // (even content-identical ones) and would bounce fastify onto no real change.
+      ignored: (p: string): boolean => {
+        return p.endsWith('.tsbuildinfo') || p.endsWith('.map')
+      },
+      ...(usePoll ? { usePolling: true, interval: 400 } : {}),
+    })
+
+    this.watcher = watcher
+
+    if (usePoll) {
+      log('👀 chokidar: usePolling enabled (DEV_SERVER_CHOKIDAR_POLL=1)', 'debug')
+    }
+
+    watcher.on('change', (filePath: string) => {
+      log(`👀 dist change detected: ${filePath}`, 'debug')
+
+      const change = classifyDistChange(filePath, appDistDirs, packageDistDirs)
+
+      if (change.kind === 'package') {
+        // A dependency package's dist was rebuilt — restart every app.
+        this.scheduleDebounced('__packages__', () => {
+          return this.restart(apps)
+        })
+
+        return
+      }
+
+      const app = apps.find((a) => {
+        return path.join(a.path, 'dist') === change.app
+      })
+
+      if (!app) return
+
+      this.scheduleDebounced(app.name, () => {
+        return this.restart([app])
+      })
+    })
+
+    log(`👀 Watching ${appDistDirs.length} app dist + ${packageDistDirs.length} package dist dir(s) for changes...`)
+  }
+
+  /**
+   * Debounce a restart under `key`: cancel any pending timer for the same key and start
+   * a fresh {@link DevServerRunner.WATCH_DEBOUNCE_MS} timer, so a burst of saves collapses
+   * into one restart. Errors from the scheduled work are logged, never thrown.
+   */
+  private scheduleDebounced(key: string, work: () => Promise<void>): void {
+    const existing = this.watchDebounceTimers.get(key)
+
+    if (existing) clearTimeout(existing)
+
+    const timer = setTimeout(() => {
+      this.watchDebounceTimers.delete(key)
+      work().catch((err) => {
+        log(`Restart error (${key}): ${String(err)}`, 'error')
+      })
+    }, DevServerRunner.WATCH_DEBOUNCE_MS)
+
+    this.watchDebounceTimers.set(key, timer)
+  }
+
+  /**
+   * Print the running-server table. The `Base URL` column carries each app's
+   * `prefixUrl` (e.g. `/api/v1`) so it is copy-pasteable — the old table showed a bare
+   * `http://localhost:<port>` that 404s against prefixed handler routes. A `Health`
+   * column surfaces the unprefixed `/__health` liveness URL.
+   */
+  private printServerTable(apps: IApiAppConfig[]): void {
+    const rows = apps.map((app) => {
+      return [
+        app.name,
+        String(app.port),
+        `http://localhost:${app.port}${app.prefixUrl}`,
+        `http://localhost:${app.port}/__health`,
+      ]
+    })
+
+    logTable(renderTable('🖥️  Running Servers', ['App', 'Port', 'Base URL', 'Health'], rows))
+  }
+
+  /**
+   * Dump each running app's registered `METHOD /path` routes at startup so the
+   * emulator is self-describing (no need to open `serverless.yml` to learn the routes).
+   * Reads the live route set via {@link ServerlessLocalRun.getRegisteredRoutes}.
+   */
+  private printRouteDump(): void {
+    if (this.appServers.length === 0) return
+
+    log('🗺️  Registered routes:')
+    for (const { app, server } of this.appServers) {
+      const routes = server.getRegisteredRoutes()
+
+      log(`   ${app.name} (${routes.length}): ${routes.length > 0 ? routes.join(', ') : '(none)'}`)
+    }
+  }
+
+  /**
+   * Stop watching, cancel any pending debounced restart, and close all running servers.
+   * Does not exit the process — the entry point owns exit.
+   */
+  public async shutdown(): Promise<void> {
+    log('🛑 Shutting down all servers...')
+
+    // Reap the long-lived engines FIRST (group SIGTERM→SIGKILL) so neither writes fresh dist nor
+    // holds a port mid-teardown. Reaped here (not only in the entry signal handler) because tests
+    // and any non-signal caller invoke shutdown() directly. Awaited so the SIGKILL escalation
+    // completes before the entry point's `process.exit`.
+    if (this.turboWatch) {
+      await this.turboWatch.kill()
+      this.turboWatch = null
+    }
+
+    if (this.uiDev) {
+      await this.uiDev.kill()
+      this.uiDev = null
+    }
+
+    for (const timer of this.watchDebounceTimers.values()) {
+      clearTimeout(timer)
+    }
+    this.watchDebounceTimers.clear()
+
+    if (this.watcher) {
+      await this.watcher.close()
+      this.watcher = null
+    }
+
+    for (const { server } of this.appServers) {
+      try {
+        await server.close()
+      } catch {
+        // ignore
+      }
+    }
+    log(`📝 Logs saved to: ${LOG_FILE_PATH}`)
+  }
+}
+
+/**
+ * Construct a {@link DevServerRunner}, start it, and return the instance so the caller
+ * (the CLI entry point) can wire signal handlers to `shutdown()` and own process exit.
+ */
+export async function run(options: DevServerOptions = {}): Promise<DevServerRunner> {
+  const runner = new DevServerRunner(options)
+
+  await runner.start()
+
+  return runner
+}