infra-kit 0.1.126 → 0.1.128

package/src/commands/init/init.ts

@@ -277,6 +277,7 @@ export const buildShellBody = (): string => {
   return [
     'zmodload zsh/stat 2>/dev/null',
     'zmodload zsh/datetime 2>/dev/null',
+    'zmodload zsh/sched 2>/dev/null',
     // eslint-disable-next-line no-template-curly-in-string
     'if [[ -z "${INFRA_KIT_SESSION}" ]]; then',
     '  export INFRA_KIT_SESSION=$(head -c 4 /dev/urandom | xxd -p)',
@@ -287,11 +288,30 @@ export const buildShellBody = (): string => {
     ': ${_INFRA_KIT_LAST_CLEAR_MTIME:=0}',
     // eslint-disable-next-line no-template-curly-in-string
     ': ${_INFRA_KIT_SHELL_STARTED:=${EPOCHSECONDS:-0}}',
-    'export _INFRA_KIT_LAST_LOAD_MTIME _INFRA_KIT_LAST_CLEAR_MTIME _INFRA_KIT_SHELL_STARTED',
+    // Warm-cache source TTL (seconds); MUST equal DEFAULT_WARM_TTL_SECONDS (node
+    // eviction) — both 2h. A warm file older than this is not sourced at startup.
+    // eslint-disable-next-line no-template-curly-in-string
+    ': ${_INFRA_KIT_WARM_TTL:=7200}',
+    'export _INFRA_KIT_LAST_LOAD_MTIME _INFRA_KIT_LAST_CLEAR_MTIME _INFRA_KIT_SHELL_STARTED _INFRA_KIT_WARM_TTL',
     `env-load() { local f m; f=$(${runCmd} env-load "$@") || return; m=$(zstat +mtime -- "$f" 2>/dev/null || echo 0); _INFRA_KIT_LAST_LOAD_MTIME=$m; source "$f"; ${runCmd} env-status; }`,
-    `env-clear() { local f m; f=$(${runCmd} env-clear) || return; m=$(zstat +mtime -- "$f" 2>/dev/null || echo 0); _INFRA_KIT_LAST_CLEAR_MTIME=$m; source "$f"; ${runCmd} env-status; }`,
+    `env-clear() { local f m; f=$(${runCmd} env-clear "$@") || return; m=$(zstat +mtime -- "$f" 2>/dev/null || echo 0); _INFRA_KIT_LAST_CLEAR_MTIME=$m; source "$f"; ${runCmd} env-status; }`,
     `env-status() { ${runCmd} env-status; }`,
     `alias ik='${runCmd}'`,
+    // Print an async notice without corrupting an already-drawn prompt. The
+    // startup poll fires via `sched` at an IDLE prompt (ZLE active) which does
+    // NOT redraw the prompt, so a bare `print` lands appended to the visible
+    // prompt line and looks like un-removable typed input. When ZLE is active we
+    // erase the current line (CR + clear-to-EOL), print the message on its own
+    // line, then `zle reset-prompt` to redraw the prompt below it. In precmd /
+    // shell-startup (ZLE inactive) `zle` is false and this is a plain stderr
+    // print above the about-to-be-drawn prompt — unchanged behavior.
+    '_infra_kit_notify() {',
+    // When ZLE is active, erase the current prompt line first and redraw after;
+    // both are no-ops when ZLE is inactive so this stays a plain stderr print.
+    "  zle && print -u2 -n $'\\r\\e[K'",
+    '  print -u2 -- "$1"',
+    '  zle && zle reset-prompt',
+    '}',
     '_infra_kit_autoload() {',
     '  [[ -z "$INFRA_KIT_SESSION" ]] && return',
     // eslint-disable-next-line no-template-curly-in-string
@@ -306,18 +326,73 @@ export const buildShellBody = (): string => {
     '    source "$load_file"',
     '    _INFRA_KIT_LAST_LOAD_MTIME=$load_mtime',
     // eslint-disable-next-line no-template-curly-in-string
-    '    print -u2 "infra-kit: auto-loaded vars for ${INFRA_KIT_ENV_CONFIG:-?}"',
+    '    _infra_kit_notify "infra-kit: auto-loaded vars for ${INFRA_KIT_ENV_CONFIG:-?}"',
     '  fi',
     '  if (( clear_mtime > _INFRA_KIT_LAST_CLEAR_MTIME && clear_mtime >= _INFRA_KIT_SHELL_STARTED && clear_mtime > load_mtime )); then',
     '    source "$clear_file"',
     '    _INFRA_KIT_LAST_CLEAR_MTIME=$clear_mtime',
-    '    print -u2 "infra-kit: auto-cleared env"',
+    '    _infra_kit_notify "infra-kit: auto-cleared env"',
     '  fi',
     '}',
     'autoload -Uz add-zsh-hook',
     'if (( _INFRA_KIT_SHELL_STARTED > 0 )); then',
     '  add-zsh-hook precmd _infra_kit_autoload',
     'fi',
+    // Non-blocking startup poll: the shell-startup spawn (below) writes env-load.sh
+    // asynchronously (node + Doppler fetch, ~0.5-2s), so the FIRST precmd — which
+    // fires before the first prompt — runs before the file lands and sources nothing;
+    // without this the vars only appear after the user's first command. This one-shot
+    // re-arming poll re-runs the precmd sourcer once per second, at the idle prompt
+    // with NO user command, until it sources the freshly written file (its mtime is
+    // >= _INFRA_KIT_SHELL_STARTED so the existing gate accepts it) OR the startup
+    // window closes. _infra_kit_autoload sets _INFRA_KIT_LAST_LOAD_MTIME on a
+    // successful source, which lifts it to >= _INFRA_KIT_SHELL_STARTED and stops the
+    // re-arm. Bounded to WINDOW seconds so an unconfigured project / down Doppler
+    // that never writes a file only costs a handful of no-op ticks, then falls back
+    // to the precmd hook. Sources the same freshly written file as precmd, so there
+    // is no stale/last-known-good secrets window.
+    '_INFRA_KIT_AUTOLOAD_WINDOW=6',
+    'export _INFRA_KIT_AUTOLOAD_WINDOW',
+    '_infra_kit_poll_autoload() {',
+    '  _infra_kit_autoload',
+    // eslint-disable-next-line no-template-curly-in-string
+    '  if (( _INFRA_KIT_LAST_LOAD_MTIME < _INFRA_KIT_SHELL_STARTED )) && (( ${EPOCHSECONDS:-0} - _INFRA_KIT_SHELL_STARTED < _INFRA_KIT_AUTOLOAD_WINDOW )); then',
+    '    (( $+builtins[sched] )) && sched +1 _infra_kit_poll_autoload',
+    '  fi',
+    '}',
+    // Warm cache: source the project-scoped last-known-good env-load.sh INSTANTLY at
+    // startup (pure zsh, no node/Doppler) so vars are present at prompt-0, before the
+    // backgrounded refresh lands. `key` is sha256 of the canonical project dir passed
+    // in by the caller — byte-identical to node's warmCacheKey (printf %s | shasum,
+    // full 64-hex). Skips when: no sha tool (degrade to poll), no warm file, a project
+    // clear-marker is at least as new (clear wins ties), or the file is past TTL
+    // (bounds a rotated secret served at prompt-0). Deliberately does NOT set
+    // _INFRA_KIT_LAST_LOAD_MTIME (leaves it 0) so the poll/precmd still source the
+    // fresh SESSION file (different path, newer mtime) and upgrade warm->fresh.
+    '_infra_kit_warm_source() {',
+    '  local canon="$1" key',
+    '  if (( $+commands[shasum] )); then',
+    '    key=$(printf %s "$canon" | shasum -a 256 | cut -c1-64)',
+    '  elif (( $+commands[sha256sum] )); then',
+    '    key=$(printf %s "$canon" | sha256sum | cut -c1-64)',
+    '  else',
+    '    return',
+    '  fi',
+    // eslint-disable-next-line no-template-curly-in-string
+    '  local cache_root="${XDG_CACHE_HOME:-$HOME/.cache}/infra-kit"',
+    '  local warm="$cache_root/projects/$key/env-load.sh"',
+    '  local wclear="$cache_root/projects/$key/env-clear.sh"',
+    '  [[ -f "$warm" ]] || return',
+    '  local wm=0 cm=0',
+    '  wm=$(zstat +mtime -- "$warm" 2>/dev/null || echo 0)',
+    '  [[ -f "$wclear" ]] && cm=$(zstat +mtime -- "$wclear" 2>/dev/null || echo 0)',
+    '  (( cm >= wm )) && return',
+    // eslint-disable-next-line no-template-curly-in-string
+    '  (( ${EPOCHSECONDS:-0} - wm >= _INFRA_KIT_WARM_TTL )) && return',
+    '  source "$warm"',
+    // eslint-disable-next-line no-template-curly-in-string
+    '  _infra_kit_notify "infra-kit: loaded cached vars for ${INFRA_KIT_ENV_CONFIG:-?} (refreshing…)"',
+    '}',
     // One-shot env auto-load when a NEW shell opens inside an infra-kit project
     // or worktree (config: envAutoLoad.trigger "shell-startup"). Cheap pure-zsh
     // project gate (walk up for infra-kit.json) avoids spawning node in unrelated
@@ -325,17 +400,24 @@ export const buildShellBody = (): string => {
     // project root (INFRA_KIT_ENV_PROJECT_ROOT), so cd'ing into a DIFFERENT project
     // re-loads instead of silently keeping the previous project's secrets. The spawn
     // is DETACHED+backgrounded ( ... & ) so it never blocks the prompt; it only
-    // WRITES env-load.sh and the precmd hook above is the sole sourcer (picked up on
-    // a subsequent prompt). Trade-off: the gate can't read the merged JSON config, so
-    // a fresh shell in a project WITHOUT envAutoLoad still spawns one background
-    // process that resolves config, finds nothing, and exits.
+    // WRITES env-load.sh. The startup poll armed right after (and the precmd hook as
+    // a later-prompt fallback) sources the file once it lands. Trade-off: the gate
+    // can't read the merged JSON config, so a fresh shell in a project WITHOUT
+    // envAutoLoad still spawns one background process that resolves config, finds
+    // nothing, and exits.
     '_infra_kit_startup_autoload() {',
     '  [[ -z "$INFRA_KIT_SESSION" ]] && return',
     '  local dir="$PWD" prev=""',
     '  while [[ -n "$dir" && "$dir" != "$prev" ]]; do',
     '    if [[ -f "$dir/infra-kit.json" ]]; then',
     '      [[ -n "$INFRA_KIT_ENV_CONFIG" && "$dir" == "$INFRA_KIT_ENV_PROJECT_ROOT" ]] && return',
-    `      ( ${runCmd} env-autoload & ) >/dev/null 2>&1`,
+    // canon = realpath of the project dir; the SAME string node hashes for the warm
+    // key (passed via --project-dir), so the two keys are byte-identical.
+    // eslint-disable-next-line no-template-curly-in-string
+    '      local canon="${dir:A}"',
+    '      _infra_kit_warm_source "$canon"',
+    `      ( ${runCmd} env-autoload --project-dir "$canon" & ) >/dev/null 2>&1`,
+    '      (( $+builtins[sched] )) && sched +1 _infra_kit_poll_autoload',
     '      return',
     '    fi',
     '    prev="$dir"',

package/src/dev/__tests__/dev-server-options.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+
+import { toDevServerOptions } from 'src/entry/dev-server'
+import type { DevCliOptions } from 'src/entry/dev-server'
+
+/**
+ * Flag/option parsing for the dev-server CLI entry. `toDevServerOptions` maps the
+ * raw Commander flag object (comma-joined strings) to the typed `DevServerOptions`
+ * the orchestrator consumes. Pure function — no fixtures.
+ */
+describe('toDevServerOptions — CLI flag parsing', () => {
+  it('splits --app into an include list', () => {
+    const opts = toDevServerOptions({ app: 'client,backoffice' } satisfies DevCliOptions)
+
+    expect(opts.include).toEqual(['client', 'backoffice'])
+  })
+
+  it('trims whitespace and drops empty segments in comma lists', () => {
+    const opts = toDevServerOptions({ app: ' client , , backoffice ,' } satisfies DevCliOptions)
+
+    expect(opts.include).toEqual(['client', 'backoffice'])
+  })
+
+  it('maps a missing --app to null (means "all apps")', () => {
+    const opts = toDevServerOptions({} satisfies DevCliOptions)
+
+    expect(opts.include).toBeNull()
+  })
+
+  it('maps an all-empty comma list to null rather than an empty array', () => {
+    const opts = toDevServerOptions({ app: ' , , ' } satisfies DevCliOptions)
+
+    expect(opts.include).toBeNull()
+  })
+
+  it('defaults watch to false when the flag is absent', () => {
+    expect(toDevServerOptions({} satisfies DevCliOptions).watch).toBe(false)
+  })
+
+  it('passes --watch through as true', () => {
+    expect(toDevServerOptions({ watch: true } satisfies DevCliOptions).watch).toBe(true)
+  })
+
+  it('parses a combined flag set (--app --watch) in one pass', () => {
+    const opts = toDevServerOptions({ app: 'a,b', watch: true } satisfies DevCliOptions)
+
+    expect(opts).toEqual({ watch: true, include: ['a', 'b'], ui: false })
+  })
+
+  it('defaults ui to false when --ui is absent (api-only, backward compatible)', () => {
+    expect(toDevServerOptions({} satisfies DevCliOptions).ui).toBe(false)
+  })
+
+  it('passes --ui through as true', () => {
+    expect(toDevServerOptions({ ui: true } satisfies DevCliOptions).ui).toBe(true)
+  })
+})

package/src/dev/__tests__/dev-server.test.ts

@@ -0,0 +1,420 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import process from 'node:process'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { DevServerRunner } from 'src/dev/dev-server'
+
+import {
+  canBind,
+  createTempTracker,
+  getFreePort,
+  handlerSource,
+  makeMonorepo,
+  restoreCwd,
+  restoreEnv,
+  snapshotCwd,
+  snapshotEnv,
+  spyStdoutWrite,
+} from './fixtures'
+
+/**
+ * Deterministic orchestration tier: a real monorepo fixture + the REAL ServerlessLocalRun
+ * spawn, but the turbo build is replaced with an injected fake (2nd constructor arg) that
+ * records its calls and refreshes each app's dist output. No chokidar, no watch, no timers
+ * — start() then shutdown() is the whole lifecycle under test.
+ */
+const temp = createTempTracker()
+let envSnapshot: NodeJS.ProcessEnv
+let cwdSnapshot: string
+
+beforeEach(() => {
+  envSnapshot = snapshotEnv()
+  cwdSnapshot = snapshotCwd()
+})
+
+afterEach(() => {
+  restoreCwd(cwdSnapshot)
+  restoreEnv(envSnapshot)
+  temp.cleanup()
+})
+
+describe('devServerRunner — start/shutdown lifecycle (fake build, real spawn)', () => {
+  it('boots each discovered app on its resolved port and serves /__health, then frees every port on shutdown', async () => {
+    const root = temp.register(
+      makeMonorepo([
+        { name: 'alpha', packageName: 'alpha-api', withHandler: true },
+        { name: 'beta', packageName: 'beta-api', withHandler: true },
+      ]),
+    )
+
+    // Distinct free ports via env keep the conflict pre-check happy and avoid collisions.
+    const alphaPort = await getFreePort()
+    const betaPort = await getFreePort()
+
+    process.env.ALPHA_PORT = String(alphaPort)
+    process.env.BETA_PORT = String(betaPort)
+
+    // Fake build: record the command and (re)write fresh dist output for each app.
+    const buildCalls: string[] = []
+    const apiDirs = ['alpha', 'beta'].map((name) => {
+      return path.join(root, 'apps', name, 'api')
+    })
+    const fakeRunBuild = async (cmd: string): Promise<void> => {
+      buildCalls.push(cmd)
+      for (const dir of apiDirs) {
+        fs.writeFileSync(path.join(dir, 'dist', 'handler.js'), handlerSource(1))
+      }
+    }
+
+    // The runner resolves the monorepo root from cwd, so run from the fixture root.
+    process.chdir(root)
+    const runner = new DevServerRunner({}, fakeRunBuild)
+
+    await runner.start()
+
+    // The build seam was invoked (the initial turbo build).
+    expect(buildCalls.length).toBeGreaterThan(0)
+
+    // Both real servers are listening and answer their health route with their own port.
+    const alphaHealth = (await (await fetch(`http://127.0.0.1:${alphaPort}/__health`)).json()) as {
+      app: string
+      port: number
+    }
+    const betaHealth = (await (await fetch(`http://127.0.0.1:${betaPort}/__health`)).json()) as {
+      app: string
+      port: number
+    }
+
+    expect(alphaHealth).toMatchObject({ app: 'alpha', port: alphaPort })
+    expect(betaHealth).toMatchObject({ app: 'beta', port: betaPort })
+
+    // Ports are held while running.
+    expect(await canBind(alphaPort)).toBe(false)
+    expect(await canBind(betaPort)).toBe(false)
+
+    await runner.shutdown()
+
+    // shutdown() releases every port so a fresh listener can bind again.
+    expect(await canBind(alphaPort)).toBe(true)
+    expect(await canBind(betaPort)).toBe(true)
+  })
+})
+
+describe('start — port-conflict pre-check', () => {
+  it('throws a clear error naming the port when two apps resolve to the same port', async () => {
+    const root = temp.register(makeMonorepo([{ name: 'client' }, { name: 'backoffice' }]))
+
+    // No per-app config and no env override => both resolve to 3010.
+    delete process.env.PORT
+    process.chdir(root)
+    const runner = new DevServerRunner({})
+
+    // The duplicate-port guard runs before any turbo build, so start() rejects
+    // hermetically without ever shelling out.
+    await expect(runner.start()).rejects.toThrow(/Port conflict detected: 3010/)
+  })
+
+  it('does not throw the conflict error when apps resolve to distinct ports', async () => {
+    const root = temp.register(makeMonorepo([{ name: 'client' }, { name: 'backoffice' }]))
+
+    // Distinct per-app ports via env keep the pre-check happy; the build step then
+    // fails (no turbo in the fixture) — proving we got past the port guard.
+    process.env.CLIENT_PORT = '3010'
+    process.env.BACKOFFICE_PORT = '3011'
+    process.chdir(root)
+    const runner = new DevServerRunner({})
+
+    await expect(runner.start()).rejects.not.toThrow(/Port conflict/)
+  })
+})
+
+describe('start — --app selection + env-resolved port', () => {
+  it('runs only the --app subset (skipping the rest) and resolves its port from {APP}_PORT', async () => {
+    const root = temp.register(
+      makeMonorepo([
+        { name: 'client', packageName: 'client-api', withHandler: true },
+        { name: 'backoffice', packageName: 'backoffice-api', withHandler: true },
+      ]),
+    )
+    const apiDirs = ['client', 'backoffice'].map((name) => {
+      return path.join(root, 'apps', name, 'api')
+    })
+    const fakeRunBuild = async (): Promise<void> => {
+      for (const dir of apiDirs) {
+        fs.writeFileSync(path.join(dir, 'dist', 'handler.js'), handlerSource(1))
+      }
+    }
+
+    // `--app client` selects one app; its port comes purely from the CLIENT_PORT env var.
+    const clientPort = await getFreePort()
+    const backofficePort = await getFreePort()
+
+    delete process.env.PORT
+    process.env.CLIENT_PORT = String(clientPort)
+    process.env.BACKOFFICE_PORT = String(backofficePort)
+    process.chdir(root)
+    const runner = new DevServerRunner({ include: ['client'] }, fakeRunBuild)
+
+    await runner.start()
+
+    try {
+      // Only `client` booted, on its {APP}_PORT-resolved port.
+      const health = (await (await fetch(`http://127.0.0.1:${clientPort}/__health`)).json()) as {
+        app: string
+        port: number
+      }
+
+      expect(health).toMatchObject({ app: 'client', port: clientPort })
+
+      // `backoffice` was filtered out by --app, so its port never gets bound.
+      expect(await canBind(backofficePort)).toBe(true)
+    } finally {
+      await runner.shutdown()
+    }
+  })
+})
+
+/** Boot a single-app monorepo fixture, capturing stdout across start(); returns the output + runner. */
+const bootAndCaptureStdout = async (
+  temp: ReturnType<typeof createTempTracker>,
+  appName: string,
+): Promise<{ out: string; runner: DevServerRunner }> => {
+  const root = temp.register(makeMonorepo([{ name: appName, packageName: `${appName}-api`, withHandler: true }]))
+  const port = await getFreePort()
+
+  process.env[`${appName.replace(/-/g, '_').toUpperCase()}_PORT`] = String(port)
+
+  const apiDir = path.join(root, 'apps', appName, 'api')
+  const fakeRunBuild = async (): Promise<void> => {
+    fs.writeFileSync(path.join(apiDir, 'dist', 'handler.js'), handlerSource(1))
+  }
+
+  const writes: string[] = []
+  const spy = spyStdoutWrite(writes)
+
+  process.chdir(root)
+  const runner = new DevServerRunner({}, fakeRunBuild)
+
+  try {
+    await runner.start()
+  } finally {
+    spy.mockRestore()
+  }
+
+  return { out: writes.join(''), runner }
+}
+
+describe('devServerRunner — startup server table', () => {
+  it('renders truthful, aligned rows: prefix in the base URL, a /__health URL, equal-width lines', async () => {
+    // A long app name is exactly what broke the old fixed-width padEnd(24) table.
+    const longName = 'super-long-application-name'
+    const { out, runner } = await bootAndCaptureStdout(temp, longName)
+
+    try {
+      // Truthful: the base URL carries the /api/v1 prefix and the health URL is shown.
+      expect(out).toContain('/api/v1')
+      expect(out).toContain('/__health')
+      expect(out).toContain(longName)
+
+      // Aligned: every box-drawn line shares one width (measured in UTF-16 units, as the
+      // renderer computes them — the title emoji is a surrogate pair, so code-point counts differ).
+      const tableLines = out.split('\n').filter((line) => {
+        return /^[┌│├└]/.test(line)
+      })
+
+      expect(tableLines.length).toBeGreaterThan(0)
+      expect(
+        new Set(
+          tableLines.map((line) => {
+            return line.length
+          }),
+        ).size,
+      ).toBe(1)
+    } finally {
+      await runner.shutdown()
+    }
+  }, 15000)
+})
+
+describe('devServerRunner — startup route dump', () => {
+  it('lists each app registered METHOD /path routes at startup', async () => {
+    const { out, runner } = await bootAndCaptureStdout(temp, 'epsilon')
+
+    try {
+      expect(out).toContain('Registered routes')
+      expect(out).toContain('epsilon')
+      // The monorepo fixture declares a single GET /api/v1/ping route.
+      expect(out).toContain('GET /api/v1/ping')
+    } finally {
+      await runner.shutdown()
+    }
+  }, 15000)
+})
+
+describe('devServerRunner — watch mode (dist-watch, build-less restart)', () => {
+  it('restarts on a dist change without rebuilding, spawns the turbo engine, and reaps it on shutdown', async () => {
+    const root = temp.register(makeMonorepo([{ name: 'omega', packageName: 'omega-api', withHandler: true }]))
+    const realRoot = fs.realpathSync(root)
+    const apiDir = path.join(realRoot, 'apps', 'omega', 'api')
+    const distHandler = path.join(apiDir, 'dist', 'handler.js')
+
+    const omegaPort = await getFreePort()
+
+    process.env.OMEGA_PORT = String(omegaPort)
+    // Hermetic polling so the dist watcher fires without relying on native fs events.
+    process.env.DEV_SERVER_CHOKIDAR_POLL = '1'
+
+    // Fake build: boot build only. In turbo mode the on-change rebuild is owned by the
+    // (faked) turbo engine, so runBuild must NOT be called again after boot.
+    const buildCalls: string[] = []
+    const fakeRunBuild = async (cmd: string): Promise<void> => {
+      buildCalls.push(cmd)
+      fs.writeFileSync(distHandler, handlerSource(1))
+    }
+
+    // No-op turbo engine: record that it was asked to start (+ with which packages) and
+    // that it was killed on shutdown, without spawning a real child.
+    let killed = false
+    let spawnedPackages: string[] | null = null
+    const fakeTurboWatch = (opts: { packageNames: string[] }): { kill: () => Promise<void> } => {
+      spawnedPackages = opts.packageNames
+
+      return {
+        kill: (): Promise<void> => {
+          killed = true
+
+          return Promise.resolve()
+        },
+      }
+    }
+
+    process.chdir(root)
+    const runner = new DevServerRunner({ watch: true }, fakeRunBuild, fakeTurboWatch)
+
+    await runner.start()
+
+    try {
+      const v1 = (await (await fetch(`http://127.0.0.1:${omegaPort}/api/v1/ping`)).json()) as { version: number }
+
+      expect(v1.version).toBe(1)
+
+      // The turbo engine was started, scoped to the app package.
+      expect(spawnedPackages).toEqual(['omega-api'])
+
+      // Exactly one build so far: the boot build. No rebuild happens on a dist change.
+      const buildsAfterBoot = buildCalls.length
+
+      expect(buildsAfterBoot).toBe(1)
+
+      // Let chokidar finish its initial scan, then simulate the turbo engine emitting a
+      // fresh dist build (v2) — the signal the dev-server restarts on.
+      await new Promise((r) => {
+        return setTimeout(r, 1200)
+      })
+      fs.writeFileSync(distHandler, handlerSource(2))
+
+      const deadline = Date.now() + 8000
+      let sawV2 = false
+
+      while (Date.now() < deadline && !sawV2) {
+        try {
+          const body = (await (await fetch(`http://127.0.0.1:${omegaPort}/api/v1/ping`)).json()) as { version: number }
+
+          if (body.version === 2) {
+            sawV2 = true
+            break
+          }
+        } catch {
+          // Server briefly down mid-restart; keep polling.
+        }
+        await new Promise((r) => {
+          return setTimeout(r, 100)
+        })
+      }
+
+      // Restarted and served the new dist on the same port…
+      expect(sawV2).toBe(true)
+      // …without any additional build (the restart is build-less in turbo mode).
+      expect(buildCalls).toHaveLength(buildsAfterBoot)
+    } finally {
+      await runner.shutdown()
+    }
+
+    // shutdown() reaped the turbo engine and freed the port.
+    expect(killed).toBe(true)
+    expect(await canBind(omegaPort)).toBe(true)
+  }, 15000)
+})
+
+describe('devServerRunner — --ui (frontends via delegated turbo run dev)', () => {
+  it('warms UI deps, spawns the ui-dev child scoped to ui packages, and reaps it on shutdown', async () => {
+    const root = temp.register(
+      makeMonorepo([{ name: 'shop', packageName: 'shop-api', withHandler: true, ui: { packageName: 'shop-ui' } }]),
+    )
+    const apiDir = path.join(root, 'apps', 'shop', 'api')
+    const shopPort = await getFreePort()
+
+    process.env.SHOP_PORT = String(shopPort)
+
+    const buildCalls: string[] = []
+    const fakeRunBuild = async (cmd: string): Promise<void> => {
+      buildCalls.push(cmd)
+      fs.writeFileSync(path.join(apiDir, 'dist', 'handler.js'), handlerSource(1))
+    }
+
+    // turbo watch isn't used without --watch; a no-op factory keeps the seam satisfied.
+    const noopTurboWatch = (): { kill: () => Promise<void> } => {
+      return {
+        kill: (): Promise<void> => {
+          return Promise.resolve()
+        },
+      }
+    }
+
+    let uiKilled = false
+    let uiPackages: string[] | null = null
+    let uiConcurrency = 0
+    const fakeUiDev = (opts: { packageNames: string[]; concurrency: number }): { kill: () => Promise<void> } => {
+      uiPackages = opts.packageNames
+      uiConcurrency = opts.concurrency
+
+      return {
+        kill: (): Promise<void> => {
+          uiKilled = true
+
+          return Promise.resolve()
+        },
+      }
+    }
+
+    process.chdir(root)
+    const runner = new DevServerRunner({ ui: true }, fakeRunBuild, noopTurboWatch, fakeUiDev)
+
+    await runner.start()
+
+    try {
+      // The API app still boots and serves (api + ui run together).
+      const health = (await (await fetch(`http://127.0.0.1:${shopPort}/__health`)).json()) as { app: string }
+
+      expect(health.app).toBe('shop')
+
+      // The ui-dev child was spawned, scoped to the UI package only, with adequate concurrency.
+      expect(uiPackages).toEqual(['shop-ui'])
+      expect(uiConcurrency).toBeGreaterThanOrEqual(1)
+
+      // A UI dependency-closure warm build ran (deps-only `^...`, not the UI's own build).
+      expect(
+        buildCalls.some((c) => {
+          return c.includes('shop-ui^...')
+        }),
+      ).toBe(true)
+    } finally {
+      await runner.shutdown()
+    }
+
+    // shutdown() reaped the ui-dev child and freed the API port.
+    expect(uiKilled).toBe(true)
+    expect(await canBind(shopPort)).toBe(true)
+  }, 15000)
+})