@codemation/cli 0.0.1

package/src/consumer/Loader.ts

@@ -0,0 +1,8 @@
+import type { ConsumerBuildOptions } from "./consumerBuildOptions.types";
+import { ConsumerOutputBuilder } from "./ConsumerOutputBuilder";
+
+export class ConsumerOutputBuilderLoader {
+  create(consumerRoot: string, buildOptions: ConsumerBuildOptions): ConsumerOutputBuilder {
+    return new ConsumerOutputBuilder(consumerRoot, undefined, buildOptions);
+  }
+}

package/src/consumer/consumerBuildOptions.types.ts

@@ -0,0 +1,12 @@
+export type EcmaScriptBuildTarget = "es2020" | "es2022";
+
+/**
+ * Options for `codemation build` / programmatic {@link ConsumerOutputBuilder} output.
+ * Mirrors common production-build toggles (source maps, emit target) similar in spirit to Next.js build tuning.
+ */
+export type ConsumerBuildOptions = Readonly<{
+  /** When true, emit `.js.map` (and inline sources in maps) for transpiled workflow modules. */
+  sourceMaps: boolean;
+  /** ECMAScript language version for emitted workflow JavaScript. */
+  target: EcmaScriptBuildTarget;
+}>;

package/src/database/ConsumerDatabaseConnectionResolver.ts

@@ -0,0 +1,18 @@
+import type { CodemationConfig } from "@codemation/host";
+import { DatabasePersistenceResolver } from "@codemation/host/persistence";
+import type { ResolvedDatabasePersistence } from "@codemation/host/persistence";
+
+/**
+ * Resolves TCP PostgreSQL vs PGlite vs none from env + {@link CodemationConfig} (same rules as the host runtime).
+ */
+export class ConsumerDatabaseConnectionResolver {
+  private readonly resolver = new DatabasePersistenceResolver();
+
+  resolve(processEnv: NodeJS.ProcessEnv, config: CodemationConfig, consumerRoot: string): ResolvedDatabasePersistence {
+    return this.resolver.resolve({
+      runtimeConfig: config.runtime ?? {},
+      env: processEnv,
+      consumerRoot,
+    });
+  }
+}

package/src/database/DatabaseMigrationsApplyService.ts

@@ -0,0 +1,76 @@
+import { CodemationConsumerConfigLoader } from "@codemation/host/server";
+import type { ResolvedDatabasePersistence } from "@codemation/host/persistence";
+import type { Logger } from "@codemation/host/next/server";
+
+import { ConsumerCliTsconfigPreparation } from "../consumer/ConsumerCliTsconfigPreparation";
+import { ConsumerDatabaseConnectionResolver } from "./ConsumerDatabaseConnectionResolver";
+import type { CliDatabaseUrlDescriptor } from "../user/CliDatabaseUrlDescriptor";
+import type { UserAdminConsumerDotenvLoader } from "../user/UserAdminConsumerDotenvLoader";
+
+export type DatabaseMigrationDeployer = {
+  deployPersistence(persistence: ResolvedDatabasePersistence, env?: Readonly<NodeJS.ProcessEnv>): Promise<void>;
+};
+
+/**
+ * Loads consumer config + env, resolves persistence, and runs Prisma migrations.
+ * Shared by `codemation db migrate` and `codemation dev` (cold start only).
+ */
+export class DatabaseMigrationsApplyService {
+  constructor(
+    private readonly cliLogger: Logger,
+    private readonly consumerDotenvLoader: UserAdminConsumerDotenvLoader,
+    private readonly tsconfigPreparation: ConsumerCliTsconfigPreparation,
+    private readonly configLoader: CodemationConsumerConfigLoader,
+    private readonly databaseConnectionResolver: ConsumerDatabaseConnectionResolver,
+    private readonly databaseUrlDescriptor: CliDatabaseUrlDescriptor,
+    private readonly hostPackageRoot: string,
+    private readonly migrationDeployer: DatabaseMigrationDeployer,
+  ) {}
+
+  /**
+   * Applies migrations when persistence is configured; no-op when there is no database (in-memory dev).
+   */
+  async applyForConsumer(consumerRoot: string, options?: Readonly<{ configPath?: string }>): Promise<void> {
+    await this.applyInternal(consumerRoot, options, false);
+  }
+
+  /**
+   * Same as {@link applyForConsumer} but throws when no database is configured (for `db migrate`).
+   */
+  async applyForConsumerRequiringPersistence(
+    consumerRoot: string,
+    options?: Readonly<{ configPath?: string }>,
+  ): Promise<void> {
+    await this.applyInternal(consumerRoot, options, true);
+  }
+
+  private async applyInternal(
+    consumerRoot: string,
+    options: Readonly<{ configPath?: string }> | undefined,
+    requirePersistence: boolean,
+  ): Promise<void> {
+    this.consumerDotenvLoader.load(consumerRoot);
+    this.tsconfigPreparation.applyWorkspaceTsconfigForTsxIfPresent(consumerRoot);
+    const resolution = await this.configLoader.load({
+      consumerRoot,
+      configPathOverride: options?.configPath,
+    });
+    const persistence = this.databaseConnectionResolver.resolve(process.env, resolution.config, consumerRoot);
+    if (persistence.kind === "none") {
+      if (requirePersistence) {
+        throw new Error(
+          "Database persistence is not configured. Set CodemationConfig.runtime.database (postgresql URL or PGlite).",
+        );
+      }
+      return;
+    }
+    process.env.CODEMATION_HOST_PACKAGE_ROOT = this.hostPackageRoot;
+    this.cliLogger.debug(
+      `Applying database migrations (${this.databaseUrlDescriptor.describePersistence(persistence)})`,
+    );
+    await this.migrationDeployer.deployPersistence(persistence, process.env);
+    this.cliLogger.info(
+      `Database migrations applied (${this.databaseUrlDescriptor.describePersistence(persistence)}).`,
+    );
+  }
+}

package/src/database/HostPackageRootResolver.ts

@@ -0,0 +1,26 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Locates the installed `@codemation/host` package root (contains `prisma/` and Prisma CLI).
+ * Uses ESM resolution (`@codemation/host` does not expose a CJS `require` entry).
+ */
+export class HostPackageRootResolver {
+  resolveHostPackageRoot(): string {
+    const entryUrl = import.meta.resolve("@codemation/host");
+    const entry = fileURLToPath(entryUrl);
+    let dir = path.dirname(entry);
+    for (let depth = 0; depth < 8; depth += 1) {
+      if (existsSync(path.join(dir, "prisma", "schema.prisma"))) {
+        return dir;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) {
+        break;
+      }
+      dir = parent;
+    }
+    throw new Error(`Could not locate prisma/schema.prisma near @codemation/host entry: ${entry}`);
+  }
+}

package/src/database/PrismaMigrateDeployInvoker.ts

@@ -0,0 +1,24 @@
+import { spawnSync } from "node:child_process";
+
+export type PrismaMigrateDeployResult = Readonly<{
+  status: number | null;
+}>;
+
+export interface PrismaMigrateDeployRunner {
+  run(args: Readonly<{ hostPackageRoot: string; env: NodeJS.ProcessEnv }>): PrismaMigrateDeployResult;
+}
+
+/**
+ * Runs `pnpm exec prisma migrate deploy` in the host package (where the Prisma schema lives).
+ */
+export class PrismaMigrateDeployInvoker implements PrismaMigrateDeployRunner {
+  run(args: Readonly<{ hostPackageRoot: string; env: NodeJS.ProcessEnv }>): PrismaMigrateDeployResult {
+    const result = spawnSync("pnpm", ["exec", "prisma", "migrate", "deploy"], {
+      cwd: args.hostPackageRoot,
+      env: args.env,
+      stdio: "inherit",
+      shell: false,
+    });
+    return { status: result.status };
+  }
+}

package/src/dev/Builder.ts

@@ -0,0 +1,45 @@
+import { CodemationConsumerConfigLoader } from "@codemation/host/server";
+import type { ServerLoggerFactory } from "@codemation/host/next/server";
+
+import { ConsumerEnvLoader } from "../consumer/ConsumerEnvLoader";
+import { ListenPortResolver } from "../runtime/ListenPortResolver";
+import { SourceMapNodeOptions } from "../runtime/SourceMapNodeOptions";
+
+import { DevelopmentGatewayNotifier } from "./DevelopmentGatewayNotifier";
+import { DevAuthSettingsLoader } from "./DevAuthSettingsLoader";
+import { DevHttpProbe } from "./DevHttpProbe";
+import { DevNextHostEnvironmentBuilder } from "./DevNextHostEnvironmentBuilder";
+import { DevSessionPortsResolver } from "./DevSessionPortsResolver";
+import { DevSessionServices } from "./DevSessionServices";
+import { DevSourceRestartCoordinator } from "./DevSourceRestartCoordinator";
+import { LoopbackPortAllocator } from "./LoopbackPortAllocator";
+import { RuntimeToolEntrypointResolver } from "./RuntimeToolEntrypointResolver";
+import { WatchRootsResolver } from "./WatchRootsResolver";
+
+export class DevSessionServicesBuilder {
+  constructor(private readonly loggerFactory: ServerLoggerFactory) {}
+
+  build(): DevSessionServices {
+    const consumerEnvLoader = new ConsumerEnvLoader();
+    const sourceMapNodeOptions = new SourceMapNodeOptions();
+    const listenPortResolver = new ListenPortResolver();
+    const loopbackPortAllocator = new LoopbackPortAllocator();
+    const cliLogger = this.loggerFactory.create("codemation-cli");
+    return new DevSessionServices(
+      consumerEnvLoader,
+      sourceMapNodeOptions,
+      new DevSessionPortsResolver(listenPortResolver, loopbackPortAllocator),
+      loopbackPortAllocator,
+      new DevHttpProbe(),
+      new RuntimeToolEntrypointResolver(),
+      new DevAuthSettingsLoader(new CodemationConsumerConfigLoader()),
+      new DevNextHostEnvironmentBuilder(consumerEnvLoader, sourceMapNodeOptions),
+      new WatchRootsResolver(),
+      new DevSourceRestartCoordinator(
+        new DevelopmentGatewayNotifier(cliLogger),
+        this.loggerFactory.createPerformanceDiagnostics("codemation-cli.performance"),
+        cliLogger,
+      ),
+    );
+  }
+}

package/src/dev/ConsumerEnvDotenvFilePredicate.ts

@@ -0,0 +1,12 @@
+import path from "node:path";
+
+/**
+ * True when `filePath` names a consumer dotenv file (`.env`, `.env.local`, …).
+ * Used by `codemation dev` to distinguish env-only changes from source rebuilds.
+ */
+export class ConsumerEnvDotenvFilePredicate {
+  matches(filePath: string): boolean {
+    const fileName = path.basename(filePath);
+    return fileName === ".env" || fileName.startsWith(".env.");
+  }
+}

package/src/dev/DevAuthSettingsLoader.ts

@@ -0,0 +1,27 @@
+import { randomUUID } from "node:crypto";
+
+import { CodemationConsumerConfigLoader } from "@codemation/host/server";
+
+export type DevResolvedAuthSettings = Readonly<{
+  authConfigJson: string;
+  skipUiAuth: boolean;
+}>;
+
+export class DevAuthSettingsLoader {
+  constructor(private readonly configLoader: CodemationConsumerConfigLoader) {}
+
+  resolveDevelopmentServerToken(rawToken: string | undefined): string {
+    if (rawToken && rawToken.trim().length > 0) {
+      return rawToken;
+    }
+    return randomUUID();
+  }
+
+  async loadForConsumer(consumerRoot: string): Promise<DevResolvedAuthSettings> {
+    const resolution = await this.configLoader.load({ consumerRoot });
+    return {
+      authConfigJson: JSON.stringify(resolution.config.auth ?? null),
+      skipUiAuth: resolution.config.auth?.allowUnauthenticatedInDevelopment === true,
+    };
+  }
+}

package/src/dev/DevBootstrapSummaryFetcher.ts

@@ -0,0 +1,15 @@
+import type { DevBootstrapSummaryJson } from "@codemation/host/next/server";
+
+/**
+ * Fetches {@link DevBootstrapSummaryJson} from the dev gateway (proxied to runtime-dev).
+ */
+export class DevBootstrapSummaryFetcher {
+  async fetch(gatewayBaseUrl: string): Promise<DevBootstrapSummaryJson | null> {
+    const normalized = gatewayBaseUrl.replace(/\/$/, "");
+    const response = await fetch(`${normalized}/api/dev/bootstrap-summary`);
+    if (!response.ok) {
+      return null;
+    }
+    return (await response.json()) as DevBootstrapSummaryJson;
+  }
+}

package/src/dev/DevCliBannerRenderer.ts

@@ -0,0 +1,106 @@
+import boxen from "boxen";
+import chalk from "chalk";
+import figlet from "figlet";
+import type { DevBootstrapSummaryJson } from "@codemation/host/next/server";
+
+/**
+ * Dev-only stdout branding (not the structured host logger).
+ * Renders the figlet banner once on cold start; append-only compact block after hot reload.
+ */
+export class DevCliBannerRenderer {
+  /**
+   * Figlet header only — call early so branding appears before migrations / gateway work.
+   */
+  renderBrandHeader(): void {
+    const titleLines = this.renderFigletTitle();
+    const subtitle = chalk.dim.italic("AI Automation framework");
+    const headerInner = `${titleLines}\n${subtitle}`;
+    const headerBox = boxen(headerInner, {
+      padding: { top: 0, bottom: 1, left: 1, right: 1 },
+      margin: { bottom: 0 },
+      borderStyle: "double",
+      borderColor: "cyan",
+      textAlignment: "center",
+    });
+    process.stdout.write(`${headerBox}\n`);
+  }
+
+  /**
+   * Runtime detail + active workflows (after bootstrap summary is available).
+   */
+  renderRuntimeSummary(summary: DevBootstrapSummaryJson): void {
+    const detailBody = this.buildDetailBody(summary);
+    const detailBox = boxen(detailBody, {
+      padding: { top: 0, bottom: 0, left: 1, right: 1 },
+      margin: { top: 1, bottom: 0 },
+      borderStyle: "round",
+      borderColor: "gray",
+      dimBorder: true,
+      title: chalk.bold("Runtime"),
+      titleAlignment: "center",
+    });
+    const activeSection = this.buildActiveWorkflowsSection(summary);
+    process.stdout.write(`${detailBox}\n${activeSection}\n`);
+  }
+
+  renderFull(summary: DevBootstrapSummaryJson): void {
+    this.renderBrandHeader();
+    this.renderRuntimeSummary(summary);
+  }
+
+  /**
+   * Shown after hot reload / watcher restarts (no figlet).
+   */
+  renderCompact(summary: DevBootstrapSummaryJson): void {
+    const body = this.buildDetailBody(summary);
+    const detailBox = boxen(body, {
+      padding: { top: 0, bottom: 0, left: 1, right: 1 },
+      margin: { top: 1, bottom: 0 },
+      borderStyle: "round",
+      borderColor: "gray",
+      dimBorder: true,
+      title: chalk.bold("Runtime (updated)"),
+      titleAlignment: "center",
+    });
+    const activeSection = this.buildActiveWorkflowsSection(summary);
+    process.stdout.write(`\n${detailBox}\n${activeSection}\n`);
+  }
+
+  private renderFigletTitle(): string {
+    try {
+      return chalk.cyan(figlet.textSync("Codemation", { font: "Slant" }));
+    } catch {
+      return chalk.cyan.bold("Codemation");
+    }
+  }
+
+  private buildDetailBody(summary: DevBootstrapSummaryJson): string {
+    const label = (text: string) => chalk.hex("#9ca3af")(text);
+    const value = (text: string) => chalk.whiteBright(text);
+    const lines = [
+      `${label("Log level")}     ${value(summary.logLevel)}`,
+      `${label("Database")}     ${value(summary.databaseLabel)}`,
+      `${label("Scheduler")}    ${value(summary.schedulerLabel)}`,
+      `${label("Event bus")}    ${value(summary.eventBusLabel)}`,
+    ];
+    if (summary.redisUrlRedacted) {
+      lines.push(`${label("Redis")}        ${value(summary.redisUrlRedacted)}`);
+    }
+    return lines.join("\n");
+  }
+
+  private buildActiveWorkflowsSection(summary: DevBootstrapSummaryJson): string {
+    const lines =
+      summary.activeWorkflows.length === 0
+        ? [chalk.dim("  (none active)")]
+        : summary.activeWorkflows.map((w) => `${chalk.whiteBright(`  • ${w.name} `)}${chalk.dim(`(${w.id})`)}`);
+    return boxen(lines.join("\n"), {
+      padding: { top: 0, bottom: 0, left: 0, right: 0 },
+      margin: { top: 1, bottom: 0 },
+      borderStyle: "single",
+      borderColor: "magenta",
+      title: chalk.bold("Active workflows"),
+      titleAlignment: "left",
+    });
+  }
+}

package/src/dev/DevConsumerPublishBootstrap.ts

@@ -0,0 +1,30 @@
+import type { Logger } from "@codemation/host/next/server";
+import { CodemationPluginDiscovery } from "@codemation/host/server";
+
+import { ConsumerBuildArtifactsPublisher } from "../build/ConsumerBuildArtifactsPublisher";
+import { ConsumerBuildOptionsParser } from "../build/ConsumerBuildOptionsParser";
+import { ConsumerOutputBuilderLoader } from "../consumer/Loader";
+import type { CliPaths } from "../path/CliPathResolver";
+
+/**
+ * Ensures `.codemation/output/current.json` and transpiled consumer config exist before the Next host boots.
+ * Without this, `codemation dev` can serve a stale built `codemation.config.js` (e.g. missing whitelabel).
+ */
+export class DevConsumerPublishBootstrap {
+  constructor(
+    private readonly cliLogger: Logger,
+    private readonly pluginDiscovery: CodemationPluginDiscovery,
+    private readonly artifactsPublisher: ConsumerBuildArtifactsPublisher,
+    private readonly outputBuilderLoader: ConsumerOutputBuilderLoader,
+    private readonly buildOptionsParser: ConsumerBuildOptionsParser,
+  ) {}
+
+  async ensurePublished(paths: CliPaths): Promise<void> {
+    const buildOptions = this.buildOptionsParser.parse({});
+    const builder = this.outputBuilderLoader.create(paths.consumerRoot, buildOptions);
+    const snapshot = await builder.ensureBuilt();
+    const discoveredPlugins = await this.pluginDiscovery.discover(paths.consumerRoot);
+    await this.artifactsPublisher.publish(snapshot, discoveredPlugins);
+    this.cliLogger.debug(`Dev: consumer output published (${snapshot.buildVersion}).`);
+  }
+}

package/src/dev/DevHttpProbe.ts

@@ -0,0 +1,54 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+export class DevHttpProbe {
+  async waitUntilUrlRespondsOk(url: string): Promise<void> {
+    for (let attempt = 0; attempt < 200; attempt += 1) {
+      try {
+        const response = await fetch(url);
+        if (response.ok || response.status === 404) {
+          return;
+        }
+      } catch {
+        // not listening yet
+      }
+      await delay(50);
+    }
+    throw new Error(`Timed out waiting for HTTP response from ${url}`);
+  }
+
+  async waitUntilGatewayHealthy(gatewayBaseUrl: string): Promise<void> {
+    const normalizedBase = gatewayBaseUrl.replace(/\/$/, "");
+    for (let attempt = 0; attempt < 200; attempt += 1) {
+      try {
+        const response = await fetch(`${normalizedBase}/api/dev/health`);
+        if (response.ok) {
+          return;
+        }
+      } catch {
+        // Server not listening yet.
+      }
+      await delay(50);
+    }
+    throw new Error("Timed out waiting for dev gateway HTTP health check.");
+  }
+
+  /**
+   * Polls until the runtime child serves bootstrap summary (after gateway is up, the disposable runtime may still be wiring).
+   */
+  async waitUntilBootstrapSummaryReady(gatewayBaseUrl: string): Promise<void> {
+    const normalizedBase = gatewayBaseUrl.replace(/\/$/, "");
+    const url = `${normalizedBase}/api/dev/bootstrap-summary`;
+    for (let attempt = 0; attempt < 200; attempt += 1) {
+      try {
+        const response = await fetch(url);
+        if (response.ok) {
+          return;
+        }
+      } catch {
+        // Runtime child restarting or not listening yet.
+      }
+      await delay(50);
+    }
+    throw new Error("Timed out waiting for dev runtime bootstrap summary.");
+  }
+}

package/src/dev/DevLock.ts

@@ -0,0 +1,98 @@
+import { mkdir, open, readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+type DevLockRecord = Readonly<{
+  pid: number;
+  startedAt: string;
+  consumerRoot: string;
+  nextPort: number;
+}>;
+
+export class DevLock {
+  private lockPath: string | null = null;
+
+  async acquire(args: Readonly<{ consumerRoot: string; nextPort: number }>): Promise<void> {
+    const lockPath = this.resolveLockPath(args.consumerRoot);
+    await mkdir(path.dirname(lockPath), { recursive: true });
+    const record: DevLockRecord = {
+      pid: process.pid,
+      startedAt: new Date().toISOString(),
+      consumerRoot: args.consumerRoot,
+      nextPort: args.nextPort,
+    };
+    try {
+      await this.writeExclusive(lockPath, JSON.stringify(record, null, 2));
+      this.lockPath = lockPath;
+      return;
+    } catch (error) {
+      const errorWithCode = error as Error & Readonly<{ code?: unknown }>;
+      if (errorWithCode.code !== "EEXIST") {
+        throw error;
+      }
+    }
+
+    const existingRecord = await this.readExistingRecord(lockPath);
+    if (existingRecord && this.isProcessAlive(existingRecord.pid)) {
+      throw new Error(
+        `codemation dev is already running for ${args.consumerRoot} (pid=${existingRecord.pid}, port=${existingRecord.nextPort}). Stop it before starting a new dev server.`,
+      );
+    }
+
+    await rm(lockPath, { force: true }).catch(() => null);
+    await this.writeExclusive(lockPath, JSON.stringify(record, null, 2));
+    this.lockPath = lockPath;
+  }
+
+  async release(): Promise<void> {
+    if (!this.lockPath) {
+      return;
+    }
+    const lockPath = this.lockPath;
+    this.lockPath = null;
+    await rm(lockPath, { force: true }).catch(() => null);
+  }
+
+  private resolveLockPath(consumerRoot: string): string {
+    return path.resolve(consumerRoot, ".codemation", "dev.lock");
+  }
+
+  private async writeExclusive(filePath: string, contents: string): Promise<void> {
+    const handle = await open(filePath, "wx");
+    try {
+      await handle.writeFile(contents, "utf8");
+    } finally {
+      await handle.close().catch(() => null);
+    }
+  }
+
+  private async readExistingRecord(lockPath: string): Promise<DevLockRecord | null> {
+    try {
+      const raw = await readFile(lockPath, "utf8");
+      const parsed = JSON.parse(raw) as Partial<DevLockRecord>;
+      if (
+        typeof parsed.pid !== "number" ||
+        typeof parsed.startedAt !== "string" ||
+        typeof parsed.consumerRoot !== "string" ||
+        typeof parsed.nextPort !== "number"
+      ) {
+        return null;
+      }
+      return parsed as DevLockRecord;
+    } catch {
+      return null;
+    }
+  }
+
+  private isProcessAlive(pid: number): boolean {
+    if (!Number.isInteger(pid) || pid <= 0) {
+      return false;
+    }
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/dev/DevNextHostEnvironmentBuilder.ts

@@ -0,0 +1,49 @@
+import path from "node:path";
+import process from "node:process";
+
+import { ConsumerEnvLoader } from "../consumer/ConsumerEnvLoader";
+import { SourceMapNodeOptions } from "../runtime/SourceMapNodeOptions";
+
+export class DevNextHostEnvironmentBuilder {
+  constructor(
+    private readonly consumerEnvLoader: ConsumerEnvLoader,
+    private readonly sourceMapNodeOptions: SourceMapNodeOptions,
+  ) {}
+
+  build(
+    args: Readonly<{
+      authConfigJson: string;
+      consumerRoot: string;
+      developmentServerToken: string;
+      nextPort: number;
+      skipUiAuth: boolean;
+      websocketPort: number;
+      runtimeDevUrl?: string;
+      /** Same manifest as `codemation build` / serve-web so @codemation/next-host can load consumer config (whitelabel, etc.). */
+      consumerOutputManifestPath?: string;
+    }>,
+  ): NodeJS.ProcessEnv {
+    const merged = this.consumerEnvLoader.mergeConsumerRootIntoProcessEnvironment(args.consumerRoot, process.env);
+    const manifestPath =
+      args.consumerOutputManifestPath ?? path.resolve(args.consumerRoot, ".codemation", "output", "current.json");
+    return {
+      ...merged,
+      PORT: String(args.nextPort),
+      CODEMATION_AUTH_CONFIG_JSON: args.authConfigJson,
+      CODEMATION_CONSUMER_ROOT: args.consumerRoot,
+      CODEMATION_CONSUMER_OUTPUT_MANIFEST_PATH: manifestPath,
+      CODEMATION_SKIP_UI_AUTH: args.skipUiAuth ? "true" : "false",
+      NEXT_PUBLIC_CODEMATION_SKIP_UI_AUTH: args.skipUiAuth ? "true" : "false",
+      CODEMATION_WS_PORT: String(args.websocketPort),
+      NEXT_PUBLIC_CODEMATION_WS_PORT: String(args.websocketPort),
+      CODEMATION_DEV_SERVER_TOKEN: args.developmentServerToken,
+      CODEMATION_SKIP_STARTUP_MIGRATIONS: "true",
+      NODE_OPTIONS: this.sourceMapNodeOptions.appendToNodeOptions(process.env.NODE_OPTIONS),
+      WS_NO_BUFFER_UTIL: "1",
+      WS_NO_UTF_8_VALIDATE: "1",
+      ...(args.runtimeDevUrl !== undefined && args.runtimeDevUrl.trim().length > 0
+        ? { CODEMATION_RUNTIME_DEV_URL: args.runtimeDevUrl.trim() }
+        : {}),
+    };
+  }
+}

package/src/dev/DevSessionPortsResolver.ts

@@ -0,0 +1,23 @@
+import { ListenPortResolver } from "../runtime/ListenPortResolver";
+import { LoopbackPortAllocator } from "./LoopbackPortAllocator";
+
+export class DevSessionPortsResolver {
+  constructor(
+    private readonly listenPorts: ListenPortResolver,
+    private readonly loopbackPorts: LoopbackPortAllocator,
+  ) {}
+
+  async resolve(
+    args: Readonly<{
+      devMode: "consumer" | "framework";
+      portEnv: string | undefined;
+      gatewayPortEnv: string | undefined;
+    }>,
+  ): Promise<Readonly<{ nextPort: number; gatewayPort: number }>> {
+    const nextPort = this.listenPorts.resolvePrimaryApplicationPort(args.portEnv);
+    const gatewayPort =
+      this.listenPorts.parsePositiveInteger(args.gatewayPortEnv) ??
+      (args.devMode === "consumer" ? nextPort : await this.loopbackPorts.allocate());
+    return { nextPort, gatewayPort };
+  }
+}

package/src/dev/DevSessionServices.ts

@@ -0,0 +1,29 @@
+import { ConsumerEnvLoader } from "../consumer/ConsumerEnvLoader";
+import { SourceMapNodeOptions } from "../runtime/SourceMapNodeOptions";
+
+import { DevAuthSettingsLoader } from "./DevAuthSettingsLoader";
+import { DevHttpProbe } from "./DevHttpProbe";
+import { DevNextHostEnvironmentBuilder } from "./DevNextHostEnvironmentBuilder";
+import { DevSessionPortsResolver } from "./DevSessionPortsResolver";
+import { DevSourceRestartCoordinator } from "./DevSourceRestartCoordinator";
+import { LoopbackPortAllocator } from "./LoopbackPortAllocator";
+import { RuntimeToolEntrypointResolver } from "./RuntimeToolEntrypointResolver";
+import { WatchRootsResolver } from "./WatchRootsResolver";
+
+/**
+ * Bundles dependencies for {@link DevCommand} so the command stays a thin orchestrator.
+ */
+export class DevSessionServices {
+  constructor(
+    readonly consumerEnvLoader: ConsumerEnvLoader,
+    readonly sourceMapNodeOptions: SourceMapNodeOptions,
+    readonly sessionPorts: DevSessionPortsResolver,
+    readonly loopbackPortAllocator: LoopbackPortAllocator,
+    readonly devHttpProbe: DevHttpProbe,
+    readonly runtimeEntrypointResolver: RuntimeToolEntrypointResolver,
+    readonly devAuthLoader: DevAuthSettingsLoader,
+    readonly nextHostEnvBuilder: DevNextHostEnvironmentBuilder,
+    readonly watchRootsResolver: WatchRootsResolver,
+    readonly sourceRestartCoordinator: DevSourceRestartCoordinator,
+  ) {}
+}