@codemation/host 0.0.1

package/src/presentation/server/CodemationConsumerConfigLoader.ts

@@ -0,0 +1,270 @@
+import type { WorkflowDefinition } from "@codemation/core";
+import { access, stat } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { NamespacedUnregister } from "tsx/esm/api";
+import { register } from "tsx/esm/api";
+import type { CodemationConfig } from "../config/CodemationConfig";
+import { CodemationConfigNormalizer } from "../config/CodemationConfigNormalizer";
+import { logLevelPolicyFactory } from "../../infrastructure/logging/LogLevelPolicyFactory";
+import { ServerLoggerFactory } from "../../infrastructure/logging/ServerLoggerFactory";
+import { DiscoveredWorkflowsEmptyMessageFactory } from "./DiscoveredWorkflowsEmptyMessageFactory";
+import { CodemationConsumerConfigExportsResolver } from "./CodemationConsumerConfigExportsResolver";
+import { WorkflowDefinitionExportsResolver } from "./WorkflowDefinitionExportsResolver";
+import { WorkflowDiscoveryPathSegmentsComputer } from "./WorkflowDiscoveryPathSegmentsComputer";
+import { WorkflowModulePathFinder } from "./WorkflowModulePathFinder";
+
+export type CodemationConsumerConfigResolution = Readonly<{
+  config: CodemationConfig;
+  bootstrapSource: string | null;
+  workflowSources: ReadonlyArray<string>;
+}>;
+
+export class CodemationConsumerConfigLoader {
+  private static readonly importerRegistrationsByTsconfig = new Map<string, NamespacedUnregister>();
+  private readonly configExportsResolver = new CodemationConsumerConfigExportsResolver();
+  private readonly configNormalizer = new CodemationConfigNormalizer();
+  private readonly workflowModulePathFinder = new WorkflowModulePathFinder();
+  private readonly workflowDefinitionExportsResolver = new WorkflowDefinitionExportsResolver();
+  private readonly discoveredWorkflowsEmptyMessageFactory = new DiscoveredWorkflowsEmptyMessageFactory();
+  private readonly pathSegmentsComputer = new WorkflowDiscoveryPathSegmentsComputer();
+  private readonly performanceDiagnosticsLogger = new ServerLoggerFactory(
+    logLevelPolicyFactory,
+  ).createPerformanceDiagnostics("codemation-config-loader.timing");
+
+  async load(
+    args: Readonly<{ consumerRoot: string; configPathOverride?: string }>,
+  ): Promise<CodemationConsumerConfigResolution> {
+    const loadStarted = performance.now();
+    let mark = loadStarted;
+    const phaseMs = (label: string): void => {
+      const now = performance.now();
+      const delta = now - mark;
+      mark = now;
+      this.performanceDiagnosticsLogger.info(
+        `load.${label} +${delta.toFixed(1)}ms (cumulative ${(now - loadStarted).toFixed(1)}ms)`,
+      );
+    };
+    const bootstrapSource = await this.resolveConfigPath(args.consumerRoot, args.configPathOverride);
+    phaseMs("resolveConfigPath");
+    if (!bootstrapSource) {
+      throw new Error(
+        'Codemation config not found. Expected "codemation.config.ts" in the consumer project root or "src/".',
+      );
+    }
+    const moduleExports = await this.importModule(bootstrapSource);
+    phaseMs("importConfigModule");
+    const rawConfig = this.configExportsResolver.resolveConfig(moduleExports);
+    if (!rawConfig) {
+      throw new Error(`Config file does not export a Codemation config object: ${bootstrapSource}`);
+    }
+    const config = this.configNormalizer.normalize(rawConfig);
+    const workflowSources = await this.resolveWorkflowSources(args.consumerRoot, config);
+    phaseMs("resolveWorkflowSources");
+    const workflows = this.mergeWorkflows(
+      config.workflows ?? [],
+      await this.loadDiscoveredWorkflows(args.consumerRoot, config, workflowSources),
+    );
+    phaseMs("loadDiscoveredWorkflows");
+    const resolvedConfig: CodemationConfig = {
+      ...config,
+      workflows,
+    };
+    logLevelPolicyFactory.create().applyCodemationLogConfig(resolvedConfig.log);
+    return {
+      config: resolvedConfig,
+      bootstrapSource,
+      workflowSources,
+    };
+  }
+
+  private async resolveConfigPath(
+    consumerRoot: string,
+    configPathOverride: string | undefined,
+  ): Promise<string | null> {
+    if (configPathOverride) {
+      const explicitPath = path.isAbsolute(configPathOverride)
+        ? configPathOverride
+        : path.resolve(consumerRoot, configPathOverride);
+      if (!(await this.exists(explicitPath))) {
+        throw new Error(`Config file not found: ${explicitPath}`);
+      }
+      return explicitPath;
+    }
+    for (const candidate of this.getConventionCandidates(consumerRoot)) {
+      if (await this.exists(candidate)) {
+        return candidate;
+      }
+    }
+    return null;
+  }
+
+  private getConventionCandidates(consumerRoot: string): ReadonlyArray<string> {
+    return [
+      path.resolve(consumerRoot, "codemation.config.ts"),
+      path.resolve(consumerRoot, "codemation.config.js"),
+      path.resolve(consumerRoot, "src", "codemation.config.ts"),
+      path.resolve(consumerRoot, "src", "codemation.config.js"),
+    ];
+  }
+
+  private async resolveWorkflowSources(consumerRoot: string, config: CodemationConfig): Promise<ReadonlyArray<string>> {
+    if ((config.workflowDiscovery?.directories?.length ?? 0) === 0) {
+      return [];
+    }
+    const discoveredPaths = await this.workflowModulePathFinder.discoverModulePaths({
+      consumerRoot,
+      workflowDirectories: config.workflowDiscovery?.directories,
+      exists: (absolutePath) => this.exists(absolutePath),
+    });
+    return [...discoveredPaths].sort((left: string, right: string) => left.localeCompare(right));
+  }
+
+  private async loadDiscoveredWorkflows(
+    consumerRoot: string,
+    config: CodemationConfig,
+    workflowSources: ReadonlyArray<string>,
+  ): Promise<ReadonlyArray<WorkflowDefinition>> {
+    const workflowDiscoveryDirectories = config.workflowDiscovery?.directories ?? [];
+    const workflowsById = new Map<string, WorkflowDefinition>();
+    const loadedWorkflowModules = await Promise.all(
+      workflowSources.map(async (workflowSource: string) => ({
+        workflowSource,
+        segments: this.pathSegmentsComputer.compute({
+          consumerRoot,
+          workflowDiscoveryDirectories,
+          absoluteWorkflowModulePath: workflowSource,
+        }),
+        moduleExports: await this.importModule(workflowSource),
+      })),
+    );
+    for (const loadedWorkflowModule of loadedWorkflowModules) {
+      for (const workflow of this.workflowDefinitionExportsResolver.resolve(loadedWorkflowModule.moduleExports)) {
+        const enriched =
+          loadedWorkflowModule.segments && loadedWorkflowModule.segments.length > 0
+            ? ({ ...workflow, discoveryPathSegments: loadedWorkflowModule.segments } satisfies WorkflowDefinition)
+            : workflow;
+        workflowsById.set(workflow.id, enriched);
+      }
+    }
+    if (workflowsById.size === 0 && workflowSources.length > 0) {
+      throw new Error(this.discoveredWorkflowsEmptyMessageFactory.create(workflowSources));
+    }
+    return [...workflowsById.values()];
+  }
+
+  private mergeWorkflows(
+    configuredWorkflows: ReadonlyArray<WorkflowDefinition>,
+    discoveredWorkflows: ReadonlyArray<WorkflowDefinition>,
+  ): ReadonlyArray<WorkflowDefinition> {
+    const workflowsById = new Map<string, WorkflowDefinition>();
+    for (const workflow of discoveredWorkflows) {
+      workflowsById.set(workflow.id, workflow);
+    }
+    for (const workflow of configuredWorkflows) {
+      workflowsById.set(workflow.id, workflow);
+    }
+    return [...workflowsById.values()];
+  }
+
+  private async importModule(modulePath: string): Promise<Record<string, unknown>> {
+    if (this.shouldUseNativeRuntimeImport()) {
+      return await this.importModuleWithNativeRuntime(modulePath);
+    }
+    const tsconfigPath = await this.resolveTsconfigPath(modulePath);
+    const importSpecifier = await this.createImportSpecifier(modulePath);
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      try {
+        const importedModule = await this.getOrCreateImporter(tsconfigPath).import(importSpecifier, import.meta.url);
+        return importedModule as Record<string, unknown>;
+      } catch (error) {
+        if (!this.isStoppedTransformServiceError(error) || attempt === 2) {
+          throw error;
+        }
+        await this.resetImporter(tsconfigPath);
+      }
+    }
+    throw new Error(`Failed to import consumer module after retries: ${modulePath}`);
+  }
+
+  private async importModuleWithNativeRuntime(modulePath: string): Promise<Record<string, unknown>> {
+    const importedModule = await import(await this.createImportSpecifier(modulePath));
+    return importedModule as Record<string, unknown>;
+  }
+
+  private async resolveTsconfigPath(modulePath: string): Promise<string | false> {
+    const overridePath = process.env.CODEMATION_TSCONFIG_PATH;
+    if (overridePath && (await this.exists(overridePath))) {
+      return overridePath;
+    }
+    const discoveredPath = await this.findNearestTsconfig(modulePath);
+    return discoveredPath ?? false;
+  }
+
+  private getOrCreateImporter(tsconfigPath: string | false): NamespacedUnregister {
+    const cacheKey = tsconfigPath || "default";
+    const existingImporter = CodemationConsumerConfigLoader.importerRegistrationsByTsconfig.get(cacheKey);
+    if (existingImporter) {
+      return existingImporter;
+    }
+    const nextImporter = register({
+      namespace: this.toNamespace(cacheKey),
+      tsconfig: tsconfigPath,
+    });
+    CodemationConsumerConfigLoader.importerRegistrationsByTsconfig.set(cacheKey, nextImporter);
+    return nextImporter;
+  }
+
+  private async resetImporter(tsconfigPath: string | false): Promise<void> {
+    const cacheKey = tsconfigPath || "default";
+    const existingImporter = CodemationConsumerConfigLoader.importerRegistrationsByTsconfig.get(cacheKey);
+    if (!existingImporter) {
+      return;
+    }
+    CodemationConsumerConfigLoader.importerRegistrationsByTsconfig.delete(cacheKey);
+    await existingImporter.unregister().catch(() => null);
+  }
+
+  private toNamespace(cacheKey: string): string {
+    return `codemation_consumer_${cacheKey.replace(/[^a-zA-Z0-9_-]+/g, "_")}`;
+  }
+
+  private async findNearestTsconfig(modulePath: string): Promise<string | null> {
+    let currentDirectory = path.dirname(modulePath);
+    while (true) {
+      const candidate = path.resolve(currentDirectory, "tsconfig.json");
+      if (await this.exists(candidate)) {
+        return candidate;
+      }
+      const parentDirectory = path.dirname(currentDirectory);
+      if (parentDirectory === currentDirectory) {
+        return null;
+      }
+      currentDirectory = parentDirectory;
+    }
+  }
+
+  private async createImportSpecifier(modulePath: string): Promise<string> {
+    const moduleUrl = pathToFileURL(modulePath);
+    const moduleStats = await stat(modulePath);
+    moduleUrl.searchParams.set("t", String(moduleStats.mtimeMs));
+    return moduleUrl.href;
+  }
+
+  private shouldUseNativeRuntimeImport(): boolean {
+    return process.env.CODEMATION_TS_RUNTIME === "ts-node";
+  }
+
+  private isStoppedTransformServiceError(error: unknown): boolean {
+    return error instanceof Error && error.message.includes("The service is no longer running");
+  }
+
+  private async exists(filePath: string): Promise<boolean> {
+    try {
+      await access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/presentation/server/CodemationPluginDiscovery.ts

@@ -0,0 +1,151 @@
+import type { CodemationPackageManifest } from "../config/CodemationPackageManifest";
+import type { CodemationPlugin } from "../config/CodemationPlugin";
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export type CodemationDiscoveredPluginPackage = Readonly<{
+  packageName: string;
+  packageRoot: string;
+  manifest: NonNullable<CodemationPackageManifest["plugin"]>;
+  developmentEntry?: string;
+}>;
+
+export type CodemationResolvedPluginPackage = Readonly<
+  CodemationDiscoveredPluginPackage & {
+    plugin: CodemationPlugin;
+  }
+>;
+
+type PackageJsonShape = Readonly<{
+  codemation?: CodemationPackageManifest;
+  name?: string;
+  exports?: Readonly<Record<string, unknown>>;
+}>;
+
+export class CodemationPluginDiscovery {
+  async discover(consumerRoot: string): Promise<ReadonlyArray<CodemationDiscoveredPluginPackage>> {
+    const nodeModulesRoot = path.resolve(consumerRoot, "node_modules");
+    const packageRoots = await this.collectPackageRoots(nodeModulesRoot);
+    const discoveredPackages: CodemationDiscoveredPluginPackage[] = [];
+    for (const packageRoot of packageRoots) {
+      const packageJson = await this.readPackageJson(path.resolve(packageRoot, "package.json"));
+      const pluginManifest = packageJson.codemation?.plugin;
+      if (!packageJson.name || !pluginManifest || pluginManifest.kind !== "plugin") {
+        continue;
+      }
+      discoveredPackages.push({
+        packageName: packageJson.name,
+        packageRoot,
+        manifest: pluginManifest,
+        developmentEntry: this.resolveDevelopmentPluginEntry(packageJson),
+      });
+    }
+    return discoveredPackages.sort((left, right) => left.packageName.localeCompare(right.packageName));
+  }
+
+  async resolvePlugins(consumerRoot: string): Promise<ReadonlyArray<CodemationResolvedPluginPackage>> {
+    const discoveredPackages = await this.discover(consumerRoot);
+    return await this.resolveDiscoveredPackages(discoveredPackages);
+  }
+
+  async resolveDiscoveredPackages(
+    discoveredPackages: ReadonlyArray<CodemationDiscoveredPluginPackage>,
+  ): Promise<ReadonlyArray<CodemationResolvedPluginPackage>> {
+    const resolvedPackages: CodemationResolvedPluginPackage[] = [];
+    for (const discoveredPackage of discoveredPackages) {
+      resolvedPackages.push({
+        ...discoveredPackage,
+        plugin: await this.loadPlugin(discoveredPackage),
+      });
+    }
+    return resolvedPackages;
+  }
+
+  private async collectPackageRoots(nodeModulesRoot: string): Promise<ReadonlyArray<string>> {
+    try {
+      const entries = await readdir(nodeModulesRoot, { withFileTypes: true });
+      const packageRoots: string[] = [];
+      for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink()) {
+          continue;
+        }
+        if (entry.name.startsWith("@")) {
+          const scopedEntries = await readdir(path.resolve(nodeModulesRoot, entry.name), { withFileTypes: true });
+          for (const scopedEntry of scopedEntries) {
+            if (scopedEntry.isDirectory() || scopedEntry.isSymbolicLink()) {
+              packageRoots.push(path.resolve(nodeModulesRoot, entry.name, scopedEntry.name));
+            }
+          }
+          continue;
+        }
+        packageRoots.push(path.resolve(nodeModulesRoot, entry.name));
+      }
+      return packageRoots;
+    } catch {
+      return [];
+    }
+  }
+
+  private async readPackageJson(packageJsonPath: string): Promise<PackageJsonShape> {
+    try {
+      const rawPackageJson = await readFile(packageJsonPath, "utf8");
+      return JSON.parse(rawPackageJson) as PackageJsonShape;
+    } catch {
+      return {};
+    }
+  }
+
+  private async loadPlugin(discoveredPackage: CodemationDiscoveredPluginPackage): Promise<CodemationPlugin> {
+    const pluginModulePath = path.resolve(discoveredPackage.packageRoot, this.resolvePluginEntry(discoveredPackage));
+    const importedModule = (await import(pathToFileURL(pluginModulePath).href)) as Record<string, unknown>;
+    const pluginExportName = discoveredPackage.manifest.exportName;
+    const explicitExport = pluginExportName ? importedModule[pluginExportName] : undefined;
+    const exportedValue = explicitExport ?? importedModule.default ?? importedModule.codemationPlugin;
+    const plugin = this.resolvePluginValue(exportedValue);
+    if (!plugin) {
+      throw new Error(`Plugin package "${discoveredPackage.packageName}" did not export a Codemation plugin instance.`);
+    }
+    return plugin;
+  }
+
+  private resolvePluginValue(value: unknown): CodemationPlugin | null {
+    if (this.isPlugin(value)) {
+      return value;
+    }
+    if (this.isPluginConstructor(value)) {
+      return new value();
+    }
+    return null;
+  }
+
+  private isPlugin(value: unknown): value is CodemationPlugin {
+    return (
+      Boolean(value) && typeof value === "object" && typeof (value as { register?: unknown }).register === "function"
+    );
+  }
+
+  private isPluginConstructor(value: unknown): value is new () => CodemationPlugin {
+    return typeof value === "function" && this.isPlugin(value.prototype);
+  }
+
+  private resolvePluginEntry(discoveredPackage: CodemationDiscoveredPluginPackage): string {
+    if (
+      process.env.CODEMATION_PREFER_PLUGIN_SOURCE_ENTRY === "true" &&
+      typeof discoveredPackage.developmentEntry === "string" &&
+      discoveredPackage.developmentEntry.trim().length > 0
+    ) {
+      return discoveredPackage.developmentEntry;
+    }
+    return discoveredPackage.manifest.entry;
+  }
+
+  private resolveDevelopmentPluginEntry(packageJson: PackageJsonShape): string | undefined {
+    const exportRecord = packageJson.exports?.["./codemation-plugin"];
+    if (!exportRecord || typeof exportRecord !== "object") {
+      return undefined;
+    }
+    const importPath = (exportRecord as { import?: unknown }).import;
+    return typeof importPath === "string" && importPath.trim().length > 0 ? importPath : undefined;
+  }
+}

package/src/presentation/server/CodemationTsyringeParamInfoReader.ts

@@ -0,0 +1,26 @@
+export class CodemationTsyringeParamInfoReader {
+  private static readonly injectionTokenMetadataKey = "injectionTokens";
+  private static readonly designParamTypesMetadataKey = "design:paramtypes";
+
+  static read(target: object): ReadonlyArray<unknown> {
+    const designParamTypes = this.readDesignParamTypes(target);
+    const injectionTokens = this.readInjectionTokens(target);
+    Object.keys(injectionTokens).forEach((key: string) => {
+      designParamTypes[Number(key)] = injectionTokens[key];
+    });
+    return designParamTypes;
+  }
+
+  private static readDesignParamTypes(target: object): unknown[] {
+    const reflected = Reflect.getMetadata?.(this.designParamTypesMetadataKey, target);
+    return Array.isArray(reflected) ? [...reflected] : [];
+  }
+
+  private static readInjectionTokens(target: object): Record<string, unknown> {
+    const reflected = Reflect.getOwnMetadata?.(this.injectionTokenMetadataKey, target);
+    if (!reflected || typeof reflected !== "object") {
+      return {};
+    }
+    return reflected as Record<string, unknown>;
+  }
+}

package/src/presentation/server/CodemationTsyringeTypeInfoRegistrar.ts

@@ -0,0 +1,121 @@
+import type { Container, TypeToken, WorkflowDefinition } from "@codemation/core";
+
+import { CodemationTsyringeParamInfoReader } from "./CodemationTsyringeParamInfoReader";
+
+type InjectionDescriptor = Readonly<{
+  token?: unknown;
+}>;
+
+export class CodemationTsyringeTypeInfoRegistrar {
+  private readonly visitedTokens = new Set<unknown>();
+  private readonly visitedConfigObjects = new Set<object>();
+
+  constructor(private readonly container: Container) {}
+
+  registerWorkflowDefinitions(workflows: ReadonlyArray<WorkflowDefinition>): void {
+    for (const workflow of workflows) {
+      for (const node of workflow.nodes) {
+        this.registerTypeToken(node.type);
+        this.registerConfigTokens(node.config);
+      }
+    }
+  }
+
+  registerTypeToken(token: unknown): void {
+    if (typeof token !== "function" || this.visitedTokens.has(token)) {
+      return;
+    }
+    this.visitedTokens.add(token);
+    const paramInfo = CodemationTsyringeParamInfoReader.read(token);
+    for (const dependency of paramInfo) {
+      this.registerDependency(dependency);
+    }
+    this.registerFactoryProvider(token as new (...args: ReadonlyArray<unknown>) => unknown, paramInfo);
+  }
+
+  private registerDependency(dependency: unknown): void {
+    const token = this.resolveDependencyToken(dependency);
+    if (typeof token !== "function") {
+      return;
+    }
+    if (!this.container.isRegistered(token as TypeToken<unknown>, true)) {
+      return;
+    }
+    this.registerTypeToken(token);
+  }
+
+  private registerConfigTokens(value: unknown): void {
+    if (Array.isArray(value)) {
+      value.forEach((entry: unknown) => this.registerConfigTokens(entry));
+      return;
+    }
+    if (!value || typeof value !== "object") {
+      return;
+    }
+    if (this.visitedConfigObjects.has(value)) {
+      return;
+    }
+    this.visitedConfigObjects.add(value);
+    if ("type" in value && typeof value.type === "function") {
+      this.registerTypeToken(value.type);
+    }
+    Object.values(value).forEach((entry: unknown) => this.registerConfigTokens(entry));
+  }
+
+  private registerFactoryProvider(
+    token: new (...args: ReadonlyArray<unknown>) => unknown,
+    paramInfo: ReadonlyArray<unknown>,
+  ): void {
+    if (this.container.isRegistered(token as TypeToken<unknown>, true)) {
+      return;
+    }
+    const classToken = token as unknown as TypeToken<unknown>;
+    const constructorToken = token as unknown as new (...args: ReadonlyArray<unknown>) => unknown;
+    this.container.register(classToken, {
+      useFactory: (dependencyContainer) => {
+        const dependencies = paramInfo.map((dependency: unknown) =>
+          this.resolveFactoryDependency(dependencyContainer, dependency),
+        );
+        return new constructorToken(...dependencies);
+      },
+    });
+  }
+
+  private resolveDependencyToken(dependency: unknown): unknown {
+    if (this.isInjectionDescriptor(dependency)) {
+      return dependency.token;
+    }
+    return dependency;
+  }
+
+  private resolveFactoryDependency(dependencyContainer: Container, dependency: unknown): unknown {
+    const token = this.resolveDependencyToken(dependency);
+    if (typeof token === "function") {
+      if (dependencyContainer.isRegistered(token as TypeToken<unknown>, true)) {
+        try {
+          return dependencyContainer.resolve(token as TypeToken<unknown>);
+        } catch (error) {
+          if (!this.isMissingTypeInfoError(error)) {
+            throw error;
+          }
+        }
+      }
+      this.registerTypeToken(token);
+      const constructorToken = token as unknown as new (...args: ReadonlyArray<unknown>) => unknown;
+      const paramInfo = CodemationTsyringeParamInfoReader.read(token);
+      const nestedDependencies = paramInfo.map((entry: unknown) =>
+        this.resolveFactoryDependency(dependencyContainer, entry),
+      );
+      return new constructorToken(...nestedDependencies);
+    }
+    return dependencyContainer.resolve(token as TypeToken<unknown>);
+  }
+
+  private isInjectionDescriptor(value: unknown): value is InjectionDescriptor {
+    return value !== null && typeof value === "object" && "token" in value;
+  }
+
+  private isMissingTypeInfoError(error: unknown): boolean {
+    return error instanceof Error && error.message.includes("TypeInfo not known for");
+  }
+}

package/src/presentation/server/DevelopmentRuntimeRouteGuard.ts

@@ -0,0 +1,59 @@
+export type DevelopmentRuntimeSignal =
+  | Readonly<{ kind: "buildStarted"; buildVersion?: string }>
+  | Readonly<{ kind: "buildCompleted"; buildVersion?: string }>
+  | Readonly<{ kind: "buildFailed"; message: string }>;
+
+export class DevelopmentRuntimeRouteGuard {
+  static isAuthorized(request: Request): boolean {
+    if (this.isLoopbackRequest(request)) {
+      return true;
+    }
+    const expectedToken = process.env.CODEMATION_DEV_SERVER_TOKEN;
+    if (!expectedToken) {
+      return true;
+    }
+    return request.headers.get("x-codemation-dev-token") === expectedToken;
+  }
+
+  private static isLoopbackRequest(request: Request): boolean {
+    const requestUrl = new URL(request.url);
+    return requestUrl.hostname === "127.0.0.1" || requestUrl.hostname === "localhost" || requestUrl.hostname === "::1";
+  }
+
+  static async parseSignal(request: Request): Promise<DevelopmentRuntimeSignal> {
+    const payload = (await request.json()) as Readonly<{
+      kind?: unknown;
+      buildVersion?: unknown;
+      message?: unknown;
+    }>;
+    return DevelopmentRuntimeRouteGuard.parseSignalFromPayload(payload);
+  }
+
+  static parseSignalFromPayload(
+    payload: Readonly<{
+      kind?: unknown;
+      buildVersion?: unknown;
+      message?: unknown;
+    }>,
+  ): DevelopmentRuntimeSignal {
+    if (payload.kind === "buildStarted") {
+      return {
+        kind: payload.kind,
+        buildVersion: typeof payload.buildVersion === "string" ? payload.buildVersion : undefined,
+      };
+    }
+    if (payload.kind === "buildCompleted") {
+      return {
+        kind: payload.kind,
+        buildVersion: typeof payload.buildVersion === "string" ? payload.buildVersion : undefined,
+      };
+    }
+    if (payload.kind === "buildFailed" && typeof payload.message === "string" && payload.message.length > 0) {
+      return {
+        kind: payload.kind,
+        message: payload.message,
+      };
+    }
+    throw new Error("Unsupported development runtime signal.");
+  }
+}

package/src/presentation/server/DiscoveredWorkflowsEmptyMessageFactory.ts

@@ -0,0 +1,11 @@
+export class DiscoveredWorkflowsEmptyMessageFactory {
+  create(discoveredPaths: ReadonlyArray<string>): string {
+    const lines = discoveredPaths.map((p) => `  - ${p}`).join("\n");
+    return [
+      `Discovered ${discoveredPaths.length} file(s) under workflow discovery, but none export a WorkflowDefinition.`,
+      lines,
+      "",
+      "Move shared helpers outside the discovery directories (for example src/lib), or export at least one object with id, name, nodes, and edges from a workflow module.",
+    ].join("\n");
+  }
+}

package/src/presentation/server/WorkflowDefinitionExportsResolver.ts

@@ -0,0 +1,24 @@
+import type { WorkflowDefinition } from "@codemation/core";
+
+/**
+ * Collects exported values that match the {@link WorkflowDefinition} shape.
+ * Other exports (helpers, constants, type-only re-exports) are ignored.
+ */
+export class WorkflowDefinitionExportsResolver {
+  resolve(moduleExports: Readonly<Record<string, unknown>>): ReadonlyArray<WorkflowDefinition> {
+    const workflows: WorkflowDefinition[] = [];
+    for (const exportedValue of Object.values(moduleExports)) {
+      if (this.isWorkflowDefinition(exportedValue)) {
+        workflows.push(exportedValue);
+      }
+    }
+    return workflows;
+  }
+
+  private isWorkflowDefinition(value: unknown): value is WorkflowDefinition {
+    if (!value || typeof value !== "object") {
+      return false;
+    }
+    return "id" in value && "name" in value && "nodes" in value && "edges" in value;
+  }
+}