@codemation/cli 0.0.4 → 0.0.7

package/src/commands/DevCommand.ts

@@ -1,25 +1,27 @@
 import type { Logger } from "@codemation/host/next/server";
-import { CodemationPluginDiscovery } from "@codemation/host/server";
 import { spawn, type ChildProcess } from "node:child_process";
 import { createRequire } from "node:module";
 import path from "node:path";
 import process from "node:process";
 
 import type { DatabaseMigrationsApplyService } from "../database/DatabaseMigrationsApplyService";
+import type { DevApiRuntimeFactory, DevApiRuntimeServerHandle } from "../dev/DevApiRuntimeFactory";
 import type { DevBootstrapSummaryFetcher } from "../dev/DevBootstrapSummaryFetcher";
+import type { CliDevProxyServer } from "../dev/CliDevProxyServer";
+import type { CliDevProxyServerFactory } from "../dev/CliDevProxyServerFactory";
 import type { DevCliBannerRenderer } from "../dev/DevCliBannerRenderer";
 import type { DevConsumerPublishBootstrap } from "../dev/DevConsumerPublishBootstrap";
 import { ConsumerEnvDotenvFilePredicate } from "../dev/ConsumerEnvDotenvFilePredicate";
+import type { DevRebuildQueueFactory } from "../dev/DevRebuildQueueFactory";
 import type { DevSourceWatcher } from "../dev/DevSourceWatcher";
 import { DevSessionServices } from "../dev/DevSessionServices";
 import { DevLockFactory } from "../dev/Factory";
 import { DevTrackedProcessTreeKiller } from "../dev/DevTrackedProcessTreeKiller";
 import { DevSourceWatcherFactory } from "../dev/Runner";
+import type { DevResolvedAuthSettings } from "../dev/DevAuthSettingsLoader";
 import { CliPathResolver, type CliPaths } from "../path/CliPathResolver";
-import { TypeScriptRuntimeConfigurator } from "../runtime/TypeScriptRuntimeConfigurator";
 import { NextHostConsumerServerCommandFactory } from "../runtime/NextHostConsumerServerCommandFactory";
-
-import type { DevResolvedAuthSettings } from "../dev/DevAuthSettingsLoader";
+import { TypeScriptRuntimeConfigurator } from "../runtime/TypeScriptRuntimeConfigurator";
 
 import type { DevMode, DevMutableProcessState, DevPreparedRuntime } from "./devCommandLifecycle.types";
 
@@ -28,7 +30,6 @@ export class DevCommand {
 
   constructor(
     private readonly pathResolver: CliPathResolver,
-    private readonly pluginDiscovery: CodemationPluginDiscovery,
     private readonly tsRuntime: TypeScriptRuntimeConfigurator,
     private readonly devLockFactory: DevLockFactory,
     private readonly devSourceWatcherFactory: DevSourceWatcherFactory,
@@ -41,15 +42,18 @@ export class DevCommand {
     private readonly consumerEnvDotenvFilePredicate: ConsumerEnvDotenvFilePredicate,
     private readonly devTrackedProcessTreeKiller: DevTrackedProcessTreeKiller,
     private readonly nextHostConsumerServerCommandFactory: NextHostConsumerServerCommandFactory,
+    private readonly devApiRuntimeFactory: DevApiRuntimeFactory,
+    private readonly cliDevProxyServerFactory: CliDevProxyServerFactory,
+    private readonly devRebuildQueueFactory: DevRebuildQueueFactory,
   ) {}
 
-  async execute(consumerRoot: string): Promise<void> {
-    const paths = await this.pathResolver.resolve(consumerRoot);
+  async execute(args: Readonly<{ consumerRoot: string; watchFramework?: boolean }>): Promise<void> {
+    const paths = await this.pathResolver.resolve(args.consumerRoot);
     this.devCliBannerRenderer.renderBrandHeader();
     this.tsRuntime.configure(paths.repoRoot);
     await this.databaseMigrationsApplyService.applyForConsumer(paths.consumerRoot);
     await this.devConsumerPublishBootstrap.ensurePublished(paths);
-    const devMode = this.resolveDevModeFromEnv();
+    const devMode = this.resolveDevMode(args);
     const { nextPort, gatewayPort } = await this.session.sessionPorts.resolve({
       devMode,
       portEnv: process.env.PORT,
@@ -58,35 +62,42 @@ export class DevCommand {
     const devLock = this.devLockFactory.create();
     await devLock.acquire({
       consumerRoot: paths.consumerRoot,
-      nextPort: devMode === "framework" ? nextPort : gatewayPort,
+      nextPort: devMode === "watch-framework" ? nextPort : gatewayPort,
     });
     const authSettings = await this.session.devAuthLoader.loadForConsumer(paths.consumerRoot);
     const watcher = this.devSourceWatcherFactory.create();
+    const processState = this.createInitialProcessState();
+    let proxyServer: CliDevProxyServer | null = null;
     try {
       const prepared = await this.prepareDevRuntime(paths, devMode, nextPort, gatewayPort, authSettings);
-      const processState = this.createInitialProcessState();
       const stopPromise = this.wireStopPromise(processState);
-      const uiProxyBase = await this.startConsumerUiProxyWhenNeeded(prepared, processState);
+      const uiProxyBase = await this.startPackagedUiWhenNeeded(prepared, processState);
+      proxyServer = await this.startProxyServer(prepared.gatewayPort, uiProxyBase);
       const gatewayBaseUrl = this.gatewayBaseHttpUrl(gatewayPort);
-      await this.spawnGatewayChildAndWaitForHealth(prepared, processState, gatewayBaseUrl, uiProxyBase);
+      await this.bootInitialRuntime(prepared, processState, proxyServer);
       await this.session.devHttpProbe.waitUntilBootstrapSummaryReady(gatewayBaseUrl);
       const initialSummary = await this.devBootstrapSummaryFetcher.fetch(gatewayBaseUrl);
       if (initialSummary) {
         this.devCliBannerRenderer.renderRuntimeSummary(initialSummary);
       }
-      this.bindShutdownSignalsToChildProcesses(processState);
-      this.spawnFrameworkNextHostWhenNeeded(prepared, processState, gatewayBaseUrl);
-      await this.startWatcherForSourceRestart(prepared, watcher, devMode, gatewayBaseUrl);
-      this.logConsumerDevHintWhenNeeded(devMode, gatewayPort);
+      this.bindShutdownSignalsToChildProcesses(processState, proxyServer);
+      await this.spawnDevUiWhenNeeded(prepared, processState, gatewayBaseUrl);
+      await this.startWatcherForSourceRestart(prepared, processState, watcher, devMode, gatewayBaseUrl, proxyServer);
+      this.logPackagedUiDevHintWhenNeeded(devMode, gatewayPort);
       await stopPromise;
     } finally {
+      processState.stopRequested = true;
+      await this.stopLiveProcesses(processState, proxyServer);
       await watcher.stop();
       await devLock.release();
     }
   }
 
-  private resolveDevModeFromEnv(): DevMode {
-    return process.env.CODEMATION_DEV_MODE === "framework" ? "framework" : "consumer";
+  private resolveDevMode(args: Readonly<{ watchFramework?: boolean }>): DevMode {
+    if (args.watchFramework === true || process.env.CODEMATION_DEV_MODE === "framework") {
+      return "watch-framework";
+    }
+    return "packaged-ui";
   }
 
   private async prepareDevRuntime(
@@ -99,19 +110,7 @@ export class DevCommand {
     const developmentServerToken = this.session.devAuthLoader.resolveDevelopmentServerToken(
       process.env.CODEMATION_DEV_SERVER_TOKEN,
     );
-    const gatewayEntrypoint = await this.session.runtimeEntrypointResolver.resolve({
-      packageName: "@codemation/dev-gateway",
-      repoRoot: paths.repoRoot,
-      sourceEntrypoint: "packages/dev-gateway/src/bin.ts",
-    });
-    const runtimeEntrypoint = await this.session.runtimeEntrypointResolver.resolve({
-      packageName: "@codemation/runtime-dev",
-      repoRoot: paths.repoRoot,
-      sourceEntrypoint: "packages/runtime-dev/src/bin.ts",
-    });
-    const runtimeWorkingDirectory = paths.repoRoot ?? paths.consumerRoot;
     const consumerEnv = this.session.consumerEnvLoader.load(paths.consumerRoot);
-    const discoveredPluginPackagesJson = JSON.stringify(await this.pluginDiscovery.discover(paths.consumerRoot));
     return {
       paths,
       devMode,
@@ -119,19 +118,17 @@ export class DevCommand {
       gatewayPort,
       authSettings,
       developmentServerToken,
-      gatewayEntrypoint,
-      runtimeEntrypoint,
-      runtimeWorkingDirectory,
-      discoveredPluginPackagesJson,
       consumerEnv,
     };
   }
 
   private createInitialProcessState(): DevMutableProcessState {
     return {
-      currentGateway: null,
-      currentNextHost: null,
-      currentUiNext: null,
+      currentDevUi: null,
+      currentPackagedUi: null,
+      currentPackagedUiBaseUrl: null,
+      currentRuntime: null,
+      isRestartingUi: false,
       stopRequested: false,
       stopResolve: null,
       stopReject: null,
@@ -149,20 +146,28 @@ export class DevCommand {
     return `http://127.0.0.1:${gatewayPort}`;
   }
 
-  /**
-   * Consumer mode: run `next start` for the host UI and wait until it responds, so the gateway can proxy to it.
-   * Framework mode: no separate UI child (Next runs in dev later).
-   */
-  private async startConsumerUiProxyWhenNeeded(
+  private async startPackagedUiWhenNeeded(
     prepared: DevPreparedRuntime,
     state: DevMutableProcessState,
   ): Promise<string> {
-    if (prepared.devMode !== "consumer") {
+    if (prepared.devMode !== "packaged-ui") {
       return "";
     }
     const websocketPort = prepared.gatewayPort;
-    const uiPort = await this.session.loopbackPortAllocator.allocate();
-    const uiProxyBase = `http://127.0.0.1:${uiPort}`;
+    const uiProxyBase =
+      state.currentPackagedUiBaseUrl ?? `http://127.0.0.1:${await this.session.loopbackPortAllocator.allocate()}`;
+    state.currentPackagedUiBaseUrl = uiProxyBase;
+    await this.spawnPackagedUi(prepared, state, prepared.authSettings, websocketPort, uiProxyBase);
+    return uiProxyBase;
+  }
+
+  private async spawnPackagedUi(
+    prepared: DevPreparedRuntime,
+    state: DevMutableProcessState,
+    authSettings: DevResolvedAuthSettings,
+    websocketPort: number,
+    uiProxyBase: string,
+  ): Promise<void> {
     const nextHostPackageJsonPath = this.require.resolve("@codemation/next-host/package.json");
     const nextHostRoot = path.dirname(nextHostPackageJsonPath);
     const nextHostCommand = await this.nextHostConsumerServerCommandFactory.create({ nextHostRoot });
@@ -172,94 +177,61 @@ export class DevCommand {
       "output",
       "current.json",
     );
-    state.currentUiNext = spawn(nextHostCommand.command, nextHostCommand.args, {
+    const uiPort = Number(new URL(uiProxyBase).port);
+    const nextHostEnvironment = this.session.nextHostEnvBuilder.buildConsumerUiProxy({
+      authConfigJson: authSettings.authConfigJson,
+      authSecret: authSettings.authSecret,
+      consumerRoot: prepared.paths.consumerRoot,
+      consumerOutputManifestPath,
+      developmentServerToken: prepared.developmentServerToken,
+      nextPort: uiPort,
+      publicBaseUrl: this.gatewayBaseHttpUrl(prepared.gatewayPort),
+      runtimeDevUrl: this.gatewayBaseHttpUrl(prepared.gatewayPort),
+      skipUiAuth: authSettings.skipUiAuth,
+      websocketPort,
+    });
+    state.currentPackagedUi = spawn(nextHostCommand.command, nextHostCommand.args, {
       cwd: nextHostCommand.cwd,
       ...this.devDetachedChildSpawnOptions(),
-      env: {
-        ...process.env,
-        ...prepared.consumerEnv,
-        PORT: String(uiPort),
-        CODEMATION_AUTH_CONFIG_JSON: prepared.authSettings.authConfigJson,
-        CODEMATION_CONSUMER_ROOT: prepared.paths.consumerRoot,
-        CODEMATION_CONSUMER_OUTPUT_MANIFEST_PATH: consumerOutputManifestPath,
-        CODEMATION_SKIP_UI_AUTH: prepared.authSettings.skipUiAuth ? "true" : "false",
-        AUTH_SECRET: prepared.authSettings.authSecret,
-        NEXTAUTH_SECRET: prepared.authSettings.authSecret,
-        NEXT_PUBLIC_CODEMATION_SKIP_UI_AUTH: prepared.authSettings.skipUiAuth ? "true" : "false",
-        CODEMATION_WS_PORT: String(websocketPort),
-        NEXT_PUBLIC_CODEMATION_WS_PORT: String(websocketPort),
-        CODEMATION_DEV_SERVER_TOKEN: prepared.developmentServerToken,
-        NODE_OPTIONS: this.session.sourceMapNodeOptions.appendToNodeOptions(process.env.NODE_OPTIONS),
-        WS_NO_BUFFER_UTIL: "1",
-        WS_NO_UTF_8_VALIDATE: "1",
-      },
+      env: nextHostEnvironment,
     });
-    state.currentUiNext.on("error", (error) => {
-      if (!state.stopRequested) {
-        state.stopRequested = true;
-        state.stopReject?.(error instanceof Error ? error : new Error(String(error)));
+    state.currentPackagedUi.on("error", (error) => {
+      if (state.stopRequested || state.isRestartingUi) {
+        return;
       }
+      state.stopRequested = true;
+      state.stopReject?.(error instanceof Error ? error : new Error(String(error)));
     });
-    state.currentUiNext.on("exit", (code) => {
-      if (state.stopRequested) {
+    state.currentPackagedUi.on("exit", (code) => {
+      if (state.stopRequested || state.isRestartingUi) {
         return;
       }
       state.stopRequested = true;
-      if (state.currentGateway?.exitCode === null) {
-        void this.devTrackedProcessTreeKiller.killProcessTreeRootedAt(state.currentGateway);
-      }
-      state.stopReject?.(new Error(`next start (consumer UI) exited unexpectedly with code ${code ?? 0}.`));
+      state.stopReject?.(new Error(`next start (packaged UI) exited unexpectedly with code ${code ?? 0}.`));
     });
     await this.session.devHttpProbe.waitUntilUrlRespondsOk(`${uiProxyBase}/`);
-    return uiProxyBase;
   }
 
-  private async spawnGatewayChildAndWaitForHealth(
+  private async startProxyServer(gatewayPort: number, uiProxyBase: string): Promise<CliDevProxyServer> {
+    const proxyServer = this.cliDevProxyServerFactory.create(gatewayPort);
+    proxyServer.setUiProxyTarget(uiProxyBase.length > 0 ? uiProxyBase : null);
+    await proxyServer.start();
+    await this.session.devHttpProbe.waitUntilGatewayHealthy(this.gatewayBaseHttpUrl(gatewayPort));
+    return proxyServer;
+  }
+
+  private async bootInitialRuntime(
     prepared: DevPreparedRuntime,
     state: DevMutableProcessState,
-    gatewayBaseUrl: string,
-    uiProxyBase: string,
+    proxyServer: CliDevProxyServer,
   ): Promise<void> {
-    const gatewayProcessEnv = this.session.consumerEnvLoader.mergeIntoProcessEnvironment(
-      process.env,
-      prepared.consumerEnv,
-    );
-    state.currentGateway = spawn(prepared.gatewayEntrypoint.command, prepared.gatewayEntrypoint.args, {
-      cwd: prepared.runtimeWorkingDirectory,
-      ...this.devDetachedChildSpawnOptions(),
-      env: {
-        ...gatewayProcessEnv,
-        ...prepared.gatewayEntrypoint.env,
-        CODEMATION_DEV_GATEWAY_HTTP_PORT: String(prepared.gatewayPort),
-        CODEMATION_RUNTIME_CHILD_BIN: prepared.runtimeEntrypoint.command,
-        CODEMATION_RUNTIME_CHILD_ARGS_JSON: JSON.stringify(prepared.runtimeEntrypoint.args),
-        CODEMATION_RUNTIME_CHILD_ENV_JSON: JSON.stringify(prepared.runtimeEntrypoint.env),
-        CODEMATION_RUNTIME_CHILD_CWD: prepared.runtimeWorkingDirectory,
-        CODEMATION_CONSUMER_ROOT: prepared.paths.consumerRoot,
-        CODEMATION_DISCOVERED_PLUGIN_PACKAGES_JSON: prepared.discoveredPluginPackagesJson,
-        CODEMATION_PREFER_PLUGIN_SOURCE_ENTRY: "true",
-        CODEMATION_DEV_SERVER_TOKEN: prepared.developmentServerToken,
-        CODEMATION_SKIP_STARTUP_MIGRATIONS: "true",
-        NODE_OPTIONS: this.session.sourceMapNodeOptions.appendToNodeOptions(process.env.NODE_OPTIONS),
-        WS_NO_BUFFER_UTIL: "1",
-        WS_NO_UTF_8_VALIDATE: "1",
-        ...(uiProxyBase.length > 0 ? { CODEMATION_DEV_UI_PROXY_TARGET: uiProxyBase } : {}),
-      },
+    const runtime = await this.createRuntime(prepared);
+    state.currentRuntime = runtime;
+    await proxyServer.activateRuntime({
+      httpPort: runtime.httpPort,
+      workflowWebSocketPort: runtime.workflowWebSocketPort,
     });
-    state.currentGateway.on("error", (error) => {
-      if (!state.stopRequested) {
-        state.stopRequested = true;
-        state.stopReject?.(error instanceof Error ? error : new Error(String(error)));
-      }
-    });
-    state.currentGateway.on("exit", (code) => {
-      if (state.stopRequested) {
-        return;
-      }
-      state.stopRequested = true;
-      state.stopReject?.(new Error(`codemation dev-gateway exited unexpectedly with code ${code ?? 0}.`));
-    });
-    await this.session.devHttpProbe.waitUntilGatewayHealthy(gatewayBaseUrl);
+    proxyServer.setBuildStatus("idle");
   }
 
   private devDetachedChildSpawnOptions(): Readonly<{
@@ -272,7 +244,10 @@ export class DevCommand {
       : { stdio: "inherit", detached: true };
   }
 
-  private bindShutdownSignalsToChildProcesses(state: DevMutableProcessState): void {
+  private bindShutdownSignalsToChildProcesses(
+    state: DevMutableProcessState,
+    proxyServer: CliDevProxyServer | null,
+  ): void {
     let shutdownInProgress = false;
     const runShutdown = async (): Promise<void> => {
       if (shutdownInProgress) {
@@ -281,13 +256,7 @@ export class DevCommand {
       shutdownInProgress = true;
       state.stopRequested = true;
       process.stdout.write("\n[codemation] Stopping..\n");
-      const children: ChildProcess[] = [];
-      for (const child of [state.currentUiNext, state.currentNextHost, state.currentGateway]) {
-        if (child && child.exitCode === null && child.signalCode === null) {
-          children.push(child);
-        }
-      }
-      await Promise.all(children.map((child) => this.devTrackedProcessTreeKiller.killProcessTreeRootedAt(child)));
+      await this.stopLiveProcesses(state, proxyServer);
       process.stdout.write("[codemation] Stopped.\n");
       state.stopResolve?.();
     };
@@ -298,64 +267,76 @@ export class DevCommand {
     }
   }
 
-  /**
-   * Framework mode: run `next dev` for the Next host with HMR, pointed at the dev gateway runtime URL.
-   */
-  private spawnFrameworkNextHostWhenNeeded(
+  private async spawnDevUiWhenNeeded(
     prepared: DevPreparedRuntime,
     state: DevMutableProcessState,
     gatewayBaseUrl: string,
-  ): void {
-    if (prepared.devMode !== "framework") {
+  ): Promise<void> {
+    if (prepared.devMode !== "watch-framework") {
       return;
     }
+    await this.spawnDevUi(prepared, state, gatewayBaseUrl, prepared.authSettings);
+  }
+
+  private async spawnDevUi(
+    prepared: DevPreparedRuntime,
+    state: DevMutableProcessState,
+    gatewayBaseUrl: string,
+    authSettings: DevResolvedAuthSettings,
+  ): Promise<void> {
     const websocketPort = prepared.gatewayPort;
     const nextHostPackageJsonPath = this.require.resolve("@codemation/next-host/package.json");
     const nextHostRoot = path.dirname(nextHostPackageJsonPath);
     const nextHostEnvironment = this.session.nextHostEnvBuilder.build({
-      authConfigJson: prepared.authSettings.authConfigJson,
+      authConfigJson: authSettings.authConfigJson,
       consumerRoot: prepared.paths.consumerRoot,
       developmentServerToken: prepared.developmentServerToken,
       nextPort: prepared.nextPort,
-      skipUiAuth: prepared.authSettings.skipUiAuth,
+      skipUiAuth: authSettings.skipUiAuth,
       websocketPort,
       runtimeDevUrl: gatewayBaseUrl,
     });
-    state.currentNextHost = spawn("pnpm", ["exec", "next", "dev"], {
+    state.currentDevUi = spawn("pnpm", ["exec", "next", "dev"], {
       cwd: nextHostRoot,
       ...this.devDetachedChildSpawnOptions(),
       env: nextHostEnvironment,
     });
-    state.currentNextHost.on("exit", (code) => {
+    state.currentDevUi.on("exit", (code) => {
       const normalizedCode = code ?? 0;
-      if (state.stopRequested) {
+      if (state.stopRequested || state.isRestartingUi) {
         return;
       }
       if (normalizedCode === 0) {
         state.stopRequested = true;
-        if (state.currentGateway?.exitCode === null) {
-          void this.devTrackedProcessTreeKiller.killProcessTreeRootedAt(state.currentGateway);
-        }
         state.stopResolve?.();
         return;
       }
       state.stopRequested = true;
       state.stopReject?.(new Error(`next host exited with code ${normalizedCode}.`));
     });
-    state.currentNextHost.on("error", (error) => {
-      if (!state.stopRequested) {
-        state.stopRequested = true;
-        state.stopReject?.(error instanceof Error ? error : new Error(String(error)));
+    state.currentDevUi.on("error", (error) => {
+      if (state.stopRequested || state.isRestartingUi) {
+        return;
       }
+      state.stopRequested = true;
+      state.stopReject?.(error instanceof Error ? error : new Error(String(error)));
     });
+    await this.session.devHttpProbe.waitUntilUrlRespondsOk(`http://127.0.0.1:${prepared.nextPort}/`);
   }
 
   private async startWatcherForSourceRestart(
     prepared: DevPreparedRuntime,
+    state: DevMutableProcessState,
     watcher: DevSourceWatcher,
     devMode: DevMode,
     gatewayBaseUrl: string,
+    proxyServer: CliDevProxyServer,
   ): Promise<void> {
+    const rebuildQueue = this.devRebuildQueueFactory.create({
+      run: async (request) => {
+        await this.runQueuedRebuild(prepared, state, gatewayBaseUrl, proxyServer, request);
+      },
+    });
     await watcher.start({
       roots: this.session.watchRootsResolver.resolve({
         consumerRoot: prepared.paths.consumerRoot,
@@ -365,32 +346,195 @@ export class DevCommand {
       onChange: async ({ changedPaths }) => {
         if (changedPaths.length > 0 && changedPaths.every((p) => this.consumerEnvDotenvFilePredicate.matches(p))) {
           process.stdout.write(
-            "\n[codemation] Consumer environment file changed (e.g. .env). Restart the `codemation dev` process so the gateway and runtime pick up updated variables (host `process.env` does not hot-reload).\n",
+            "\n[codemation] Consumer environment file changed (e.g. .env). Restart the `codemation dev` process so the runtime picks up updated variables (host `process.env` does not hot-reload).\n",
           );
           return;
         }
-        process.stdout.write("\n[codemation] Source change detected — rebuilding consumer…\n");
-        await this.session.sourceRestartCoordinator.runHandshakeAfterSourceChange(
-          gatewayBaseUrl,
-          prepared.developmentServerToken,
-        );
-        process.stdout.write("[codemation] Waiting for runtime to accept traffic…\n");
-        await this.session.devHttpProbe.waitUntilBootstrapSummaryReady(gatewayBaseUrl);
-        const json = await this.devBootstrapSummaryFetcher.fetch(gatewayBaseUrl);
-        if (json) {
-          this.devCliBannerRenderer.renderCompact(json);
+        try {
+          const shouldRepublishConsumerOutput = this.session.sourceChangeClassifier.shouldRepublishConsumerOutput({
+            changedPaths,
+            consumerRoot: prepared.paths.consumerRoot,
+          });
+          const shouldRestartUi = this.session.sourceChangeClassifier.requiresUiRestart({
+            changedPaths,
+            consumerRoot: prepared.paths.consumerRoot,
+          });
+          process.stdout.write(
+            shouldRestartUi
+              ? "\n[codemation] Source change detected — rebuilding consumer, restarting the runtime, and restarting the UI…\n"
+              : "\n[codemation] Source change detected — rebuilding consumer and restarting the runtime…\n",
+          );
+          await rebuildQueue.enqueue({
+            changedPaths,
+            shouldRepublishConsumerOutput,
+            shouldRestartUi,
+          });
+        } catch (error) {
+          await this.failDevSessionAfterIrrecoverableSourceError(state, proxyServer, error);
         }
-        process.stdout.write("[codemation] Runtime ready.\n");
       },
     });
   }
 
-  private logConsumerDevHintWhenNeeded(devMode: DevMode, gatewayPort: number): void {
-    if (devMode !== "consumer") {
+  private async runQueuedRebuild(
+    prepared: DevPreparedRuntime,
+    state: DevMutableProcessState,
+    gatewayBaseUrl: string,
+    proxyServer: CliDevProxyServer,
+    request: Readonly<{
+      changedPaths: ReadonlyArray<string>;
+      shouldRepublishConsumerOutput: boolean;
+      shouldRestartUi: boolean;
+    }>,
+  ): Promise<void> {
+    proxyServer.setBuildStatus("building");
+    proxyServer.broadcastBuildStarted();
+    try {
+      if (request.shouldRepublishConsumerOutput) {
+        await this.devConsumerPublishBootstrap.ensurePublished(prepared.paths);
+      }
+      await this.stopCurrentRuntime(state, proxyServer);
+      process.stdout.write("[codemation] Waiting for runtime to accept traffic…\n");
+      const runtime = await this.createRuntime(prepared);
+      state.currentRuntime = runtime;
+      await proxyServer.activateRuntime({
+        httpPort: runtime.httpPort,
+        workflowWebSocketPort: runtime.workflowWebSocketPort,
+      });
+      if (request.shouldRestartUi) {
+        await this.restartUiAfterSourceChange(prepared, state, gatewayBaseUrl);
+      }
+      await this.session.devHttpProbe.waitUntilBootstrapSummaryReady(gatewayBaseUrl);
+      const json = await this.devBootstrapSummaryFetcher.fetch(gatewayBaseUrl);
+      if (json) {
+        this.devCliBannerRenderer.renderCompact(json);
+      }
+      proxyServer.setBuildStatus("idle");
+      proxyServer.broadcastBuildCompleted(runtime.buildVersion);
+      process.stdout.write("[codemation] Runtime ready.\n");
+    } catch (error) {
+      proxyServer.setBuildStatus("idle");
+      proxyServer.broadcastBuildFailed(error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+  }
+
+  private async restartUiAfterSourceChange(
+    prepared: DevPreparedRuntime,
+    state: DevMutableProcessState,
+    gatewayBaseUrl: string,
+  ): Promise<void> {
+    const refreshedAuthSettings = await this.session.devAuthLoader.loadForConsumer(prepared.paths.consumerRoot);
+    process.stdout.write("[codemation] Restarting the UI process to apply source changes…\n");
+    state.isRestartingUi = true;
+    try {
+      if (prepared.devMode === "packaged-ui") {
+        await this.restartPackagedUi(prepared, state, refreshedAuthSettings);
+        return;
+      }
+      await this.restartDevUi(prepared, state, gatewayBaseUrl, refreshedAuthSettings);
+    } finally {
+      state.isRestartingUi = false;
+    }
+  }
+
+  private async restartPackagedUi(
+    prepared: DevPreparedRuntime,
+    state: DevMutableProcessState,
+    authSettings: DevResolvedAuthSettings,
+  ): Promise<void> {
+    if (
+      state.currentPackagedUi &&
+      state.currentPackagedUi.exitCode === null &&
+      state.currentPackagedUi.signalCode === null
+    ) {
+      await this.devTrackedProcessTreeKiller.killProcessTreeRootedAt(state.currentPackagedUi);
+    }
+    state.currentPackagedUi = null;
+    const uiProxyBaseUrl = state.currentPackagedUiBaseUrl;
+    if (!uiProxyBaseUrl) {
+      throw new Error("Packaged UI proxy base URL is missing during UI restart.");
+    }
+    await this.spawnPackagedUi(prepared, state, authSettings, prepared.gatewayPort, uiProxyBaseUrl);
+  }
+
+  private async restartDevUi(
+    prepared: DevPreparedRuntime,
+    state: DevMutableProcessState,
+    gatewayBaseUrl: string,
+    authSettings: DevResolvedAuthSettings,
+  ): Promise<void> {
+    if (state.currentDevUi && state.currentDevUi.exitCode === null && state.currentDevUi.signalCode === null) {
+      await this.devTrackedProcessTreeKiller.killProcessTreeRootedAt(state.currentDevUi);
+    }
+    state.currentDevUi = null;
+    await this.spawnDevUi(prepared, state, gatewayBaseUrl, authSettings);
+  }
+
+  private async failDevSessionAfterIrrecoverableSourceError(
+    state: DevMutableProcessState,
+    proxyServer: CliDevProxyServer | null,
+    error: unknown,
+  ): Promise<void> {
+    const exception = error instanceof Error ? error : new Error(String(error));
+    state.stopRequested = true;
+    await this.stopLiveProcesses(state, proxyServer);
+    state.stopReject?.(exception);
+  }
+
+  private async stopLiveProcesses(state: DevMutableProcessState, proxyServer: CliDevProxyServer | null): Promise<void> {
+    await this.stopCurrentRuntime(state, proxyServer);
+    const children: ChildProcess[] = [];
+    for (const child of [state.currentPackagedUi, state.currentDevUi]) {
+      if (child && child.exitCode === null && child.signalCode === null) {
+        children.push(child);
+      }
+    }
+    await Promise.all(children.map((child) => this.devTrackedProcessTreeKiller.killProcessTreeRootedAt(child)));
+    if (proxyServer) {
+      await proxyServer.stop();
+    }
+  }
+
+  private async stopCurrentRuntime(
+    state: DevMutableProcessState,
+    proxyServer: CliDevProxyServer | null,
+  ): Promise<void> {
+    const runtime = state.currentRuntime;
+    state.currentRuntime = null;
+    if (proxyServer) {
+      await proxyServer.activateRuntime(null);
+    }
+    if (runtime) {
+      await runtime.stop();
+    }
+  }
+
+  private async createRuntime(prepared: DevPreparedRuntime): Promise<DevApiRuntimeServerHandle> {
+    const runtimeEnvironment = this.session.consumerEnvLoader.mergeIntoProcessEnvironment(
+      process.env,
+      prepared.consumerEnv,
+    );
+    return await this.devApiRuntimeFactory.create({
+      consumerRoot: prepared.paths.consumerRoot,
+      runtimeWorkingDirectory: process.cwd(),
+      env: {
+        ...runtimeEnvironment,
+        CODEMATION_DEV_SERVER_TOKEN: prepared.developmentServerToken,
+        CODEMATION_SKIP_STARTUP_MIGRATIONS: "true",
+        NODE_OPTIONS: this.session.sourceMapNodeOptions.appendToNodeOptions(process.env.NODE_OPTIONS),
+        WS_NO_BUFFER_UTIL: "1",
+        WS_NO_UTF_8_VALIDATE: "1",
+      },
+    });
+  }
+
+  private logPackagedUiDevHintWhenNeeded(devMode: DevMode, gatewayPort: number): void {
+    if (devMode !== "packaged-ui") {
       return;
     }
     this.cliLogger.info(
-      `codemation dev (consumer): open http://127.0.0.1:${gatewayPort} — uses the packaged @codemation/next-host UI. For framework UI HMR, set CODEMATION_DEV_MODE=framework.`,
+      `codemation dev: open http://127.0.0.1:${gatewayPort} — this uses the packaged @codemation/next-host UI. Use \`codemation dev --watch-framework\` only when working on the framework UI itself.`,
     );
   }
 }