@codemation/host 0.0.1

package/src/presentation/config/CodemationConfigNormalizer.ts

@@ -0,0 +1,179 @@
+import type { AnyCredentialType, Container, TypeToken, WorkflowDefinition } from "@codemation/core";
+import type { CodemationContainerRegistration } from "../../bootstrap/CodemationContainerRegistration";
+import type { CodemationAppContext } from "./CodemationAppContext";
+import type { CodemationClassToken } from "./CodemationClassToken";
+import type {
+  CodemationApplicationRuntimeConfig,
+  CodemationConfig,
+  CodemationDatabaseConfig,
+  CodemationEventBusConfig,
+  CodemationSchedulerConfig,
+} from "./CodemationConfig";
+
+export type NormalizedCodemationConfig = CodemationConfig &
+  Readonly<{
+    containerRegistrations: ReadonlyArray<CodemationContainerRegistration<unknown>>;
+  }>;
+
+export class CodemationConfigNormalizer {
+  normalize(config: CodemationConfig): NormalizedCodemationConfig {
+    const collected = this.collectRegistration(config);
+    const normalizedRuntime = this.normalizeRuntimeConfig(config);
+    const normalizedWorkflowDiscoveryDirectories = [
+      ...(config.workflowDiscovery?.directories ?? []),
+      ...collected.workflowDirectories,
+    ];
+
+    return {
+      ...config,
+      auth: config.app?.auth ?? config.auth,
+      containerRegistrations: collected.containerRegistrations,
+      credentialTypes: [...(config.credentialTypes ?? []), ...collected.credentialTypes],
+      log: config.app?.log ?? config.log,
+      runtime: normalizedRuntime,
+      whitelabel: config.app?.whitelabel ?? config.whitelabel,
+      workflowDiscovery:
+        normalizedWorkflowDiscoveryDirectories.length > 0
+          ? { directories: normalizedWorkflowDiscoveryDirectories }
+          : config.workflowDiscovery,
+      workflows: this.mergeWorkflows(config.workflows ?? [], collected.workflows),
+    };
+  }
+
+  private collectRegistration(config: CodemationConfig): Readonly<{
+    containerRegistrations: ReadonlyArray<CodemationContainerRegistration<unknown>>;
+    credentialTypes: ReadonlyArray<AnyCredentialType>;
+    workflows: ReadonlyArray<WorkflowDefinition>;
+    workflowDirectories: ReadonlyArray<string>;
+  }> {
+    if (!config.register) {
+      return {
+        containerRegistrations: [],
+        credentialTypes: [],
+        workflows: [],
+        workflowDirectories: [],
+      };
+    }
+
+    const containerRegistrations: Array<CodemationContainerRegistration<unknown>> = [];
+    const credentialTypes: Array<AnyCredentialType> = [];
+    const workflows: Array<WorkflowDefinition> = [];
+    const workflowDirectories: Array<string> = [];
+
+    const context: CodemationAppContext = {
+      registerCredentialType(type) {
+        credentialTypes.push(type);
+      },
+      registerNode<TValue>(token: TypeToken<TValue>, implementation?: CodemationClassToken<TValue>) {
+        containerRegistrations.push({
+          token,
+          useClass: implementation ?? (token as CodemationClassToken<TValue>),
+        });
+      },
+      registerValue<TValue>(token: TypeToken<TValue>, value: TValue) {
+        containerRegistrations.push({ token, useValue: value });
+      },
+      registerClass<TValue>(token: TypeToken<TValue>, implementation: CodemationClassToken<TValue>) {
+        containerRegistrations.push({ token, useClass: implementation });
+      },
+      registerFactory<TValue>(token: TypeToken<TValue>, factory: (container: Container) => TValue) {
+        containerRegistrations.push({ token, useFactory: factory });
+      },
+      registerWorkflow(workflow: WorkflowDefinition) {
+        workflows.push(workflow);
+      },
+      registerWorkflows(nextWorkflows: ReadonlyArray<WorkflowDefinition>) {
+        workflows.push(...nextWorkflows);
+      },
+      discoverWorkflows(...directories: ReadonlyArray<string>) {
+        workflowDirectories.push(...directories);
+      },
+    };
+
+    config.register(context);
+
+    return {
+      containerRegistrations,
+      credentialTypes,
+      workflows,
+      workflowDirectories,
+    };
+  }
+
+  private normalizeRuntimeConfig(config: CodemationConfig): CodemationApplicationRuntimeConfig | undefined {
+    if (!config.app) {
+      return config.runtime;
+    }
+    const nextRuntime: CodemationApplicationRuntimeConfig = {
+      ...(config.runtime ?? {}),
+      frontendPort: config.app.frontendPort ?? config.runtime?.frontendPort,
+      database: this.normalizeDatabaseConfig(config),
+      eventBus: this.normalizeEventBusConfig(config),
+      scheduler: this.normalizeSchedulerConfig(config),
+      engineExecutionLimits: config.app.engineExecutionLimits ?? config.runtime?.engineExecutionLimits,
+    };
+    return nextRuntime;
+  }
+
+  private normalizeDatabaseConfig(config: CodemationConfig): CodemationDatabaseConfig | undefined {
+    if (!config.app) {
+      return config.runtime?.database;
+    }
+    if (config.app.database) {
+      return config.app.database;
+    }
+    if (!config.app.databaseUrl) {
+      return config.runtime?.database;
+    }
+    return {
+      ...(config.runtime?.database ?? {}),
+      url: config.app.databaseUrl,
+    };
+  }
+
+  private normalizeSchedulerConfig(config: CodemationConfig): CodemationSchedulerConfig | undefined {
+    if (!config.app?.scheduler) {
+      return config.runtime?.scheduler;
+    }
+    const scheduler = config.app.scheduler;
+    return {
+      ...(config.runtime?.scheduler ?? {}),
+      kind:
+        scheduler.kind === "queue" ? "bullmq" : scheduler.kind === "inline" ? "local" : config.runtime?.scheduler?.kind,
+      queuePrefix: scheduler.queuePrefix ?? config.runtime?.scheduler?.queuePrefix,
+      workerQueues: scheduler.workerQueues ?? config.runtime?.scheduler?.workerQueues,
+    };
+  }
+
+  private normalizeEventBusConfig(config: CodemationConfig): CodemationEventBusConfig | undefined {
+    if (!config.app?.scheduler) {
+      return config.runtime?.eventBus;
+    }
+    const scheduler = config.app.scheduler;
+    const eventBusKind =
+      scheduler.kind === "queue" ? "redis" : scheduler.kind === "inline" ? "memory" : config.runtime?.eventBus?.kind;
+    return {
+      ...(config.runtime?.eventBus ?? {}),
+      kind: eventBusKind,
+      queuePrefix: scheduler.queuePrefix ?? config.runtime?.eventBus?.queuePrefix,
+      redisUrl: scheduler.redisUrl ?? config.runtime?.eventBus?.redisUrl,
+    };
+  }
+
+  private mergeWorkflows(
+    configuredWorkflows: ReadonlyArray<WorkflowDefinition>,
+    registeredWorkflows: ReadonlyArray<WorkflowDefinition>,
+  ): ReadonlyArray<WorkflowDefinition> | undefined {
+    if (configuredWorkflows.length === 0 && registeredWorkflows.length === 0) {
+      return undefined;
+    }
+    const workflowsById = new Map<string, WorkflowDefinition>();
+    for (const workflow of registeredWorkflows) {
+      workflowsById.set(workflow.id, workflow);
+    }
+    for (const workflow of configuredWorkflows) {
+      workflowsById.set(workflow.id, workflow);
+    }
+    return [...workflowsById.values()];
+  }
+}

package/src/presentation/config/CodemationLogConfig.ts

@@ -0,0 +1,22 @@
+/**
+ * Minimum level for namespaces matched by {@link CodemationLogRule.filter}.
+ * `silent` suppresses all log lines for matching namespaces.
+ */
+export type CodemationLogLevelName = "debug" | "info" | "warn" | "error" | "silent";
+
+/**
+ * One rule: {@link filter} is one glob or several (`*` = any substring; a lone `*` matches all namespaces).
+ * If multiple patterns are given, **any** match applies this rule’s level.
+ * Rules are evaluated in order; the **first** rule whose filter set matches wins.
+ */
+export type CodemationLogRule = Readonly<{
+  filter: string | ReadonlyArray<string>;
+  level: CodemationLogLevelName;
+}>;
+
+/**
+ * Either a single rule (`{ filter, level }`) or multiple `{ rules: [...] }`.
+ * Put broader patterns last, e.g. `{ filter: "codemation.webhooks.*", level: "info" }` then `{ filter: "*", level: "warn" }`.
+ * Use an array for `filter` to match several namespaces with the same level, e.g. `filter: ["codemation.webhooks.*", "codemation.engine.triggers"]`.
+ */
+export type CodemationLogConfig = Readonly<{ rules: ReadonlyArray<CodemationLogRule> }> | CodemationLogRule;

package/src/presentation/config/CodemationPackageManifest.ts

@@ -0,0 +1,9 @@
+export interface CodemationPluginPackageManifest {
+  readonly kind: "plugin";
+  readonly entry: string;
+  readonly exportName?: string;
+}
+
+export interface CodemationPackageManifest {
+  readonly plugin?: CodemationPluginPackageManifest;
+}

package/src/presentation/config/CodemationPlugin.ts

@@ -0,0 +1,20 @@
+import type { Container } from "@codemation/core";
+import type { LoggerFactory } from "../../application/logging/Logger";
+import type { AppConfig } from "./AppConfig";
+import type { CodemationRegistrationContextBase } from "./CodemationAppContext";
+
+export interface CodemationPluginContext extends CodemationRegistrationContextBase {
+  readonly container: Container;
+  readonly appConfig: AppConfig;
+  readonly loggerFactory: LoggerFactory;
+}
+
+export interface CodemationPlugin {
+  /**
+   * Optional npm package name for this plugin (e.g. `"@codemation/core-nodes-gmail"`).
+   * When set, the host merges configured and discovered plugin lists by this id so the same package is not
+   * registered twice when separate module graphs load duplicate class instances (different `constructor` values).
+   */
+  readonly pluginPackageId?: string;
+  register(context: CodemationPluginContext): void | Promise<void>;
+}

package/src/presentation/config/CodemationPluginListMerger.ts

@@ -0,0 +1,46 @@
+import type { CodemationPlugin } from "./CodemationPlugin";
+
+/**
+ * Merges explicitly configured plugins with auto-discovered plugins.
+ * Configured plugins are applied first; discovered plugins fill in gaps.
+ * Plugins that declare `pluginPackageId` are deduped by that string so the same npm package is not
+ * registered twice when the consumer config lists a plugin and discovery also finds it, or when two
+ * module evaluations produce different `constructor` identities for the same logical plugin.
+ */
+export class CodemationPluginListMerger {
+  merge(
+    configuredPlugins: ReadonlyArray<CodemationPlugin>,
+    discoveredPlugins: ReadonlyArray<CodemationPlugin>,
+  ): ReadonlyArray<CodemationPlugin> {
+    const pluginsByPackageId = new Map<string, CodemationPlugin>();
+    const pluginsByConstructor = new Map<unknown, CodemationPlugin>();
+    const result: CodemationPlugin[] = [];
+
+    const tryAdd = (plugin: CodemationPlugin): void => {
+      const packageId = plugin.pluginPackageId;
+      if (typeof packageId === "string" && packageId.trim().length > 0) {
+        const key = packageId.trim();
+        if (pluginsByPackageId.has(key)) {
+          return;
+        }
+        pluginsByPackageId.set(key, plugin);
+        result.push(plugin);
+        return;
+      }
+      const constructorKey = Object.getPrototypeOf(plugin)?.constructor ?? plugin;
+      if (pluginsByConstructor.has(constructorKey)) {
+        return;
+      }
+      pluginsByConstructor.set(constructorKey, plugin);
+      result.push(plugin);
+    };
+
+    for (const plugin of configuredPlugins) {
+      tryAdd(plugin);
+    }
+    for (const plugin of discoveredPlugins) {
+      tryAdd(plugin);
+    }
+    return result;
+  }
+}

package/src/presentation/config/CodemationWhitelabelConfig.ts

@@ -0,0 +1,9 @@
+/**
+ * Optional host shell whitelabeling (sidebar, login, document title).
+ * `logoPath` is resolved relative to the consumer project root.
+ */
+export interface CodemationWhitelabelConfig {
+  readonly productName?: string;
+  /** Relative to consumer project root, e.g. `branding/logo.svg`. */
+  readonly logoPath?: string;
+}

package/src/presentation/config/CodemationWorkflowDiscovery.ts

@@ -0,0 +1,3 @@
+export interface CodemationWorkflowDiscovery {
+  readonly directories?: ReadonlyArray<string>;
+}

package/src/presentation/http/ApiPaths.ts

@@ -0,0 +1,165 @@
+export class ApiPaths {
+  private static readonly apiBasePath = "/api";
+
+  private static readonly workflowsBasePath = `${this.apiBasePath}/workflows`;
+
+  private static readonly runsBasePath = `${this.apiBasePath}/runs`;
+
+  private static readonly credentialsBasePath = `${this.apiBasePath}/credentials`;
+
+  private static readonly oauth2BasePath = `${this.apiBasePath}/oauth2`;
+
+  private static readonly webhooksBasePath = `${this.apiBasePath}/webhooks`;
+
+  private static readonly usersBasePath = `${this.apiBasePath}/users`;
+
+  private static readonly whitelabelBasePath = `${this.apiBasePath}/whitelabel`;
+
+  static workflows(): string {
+    return this.workflowsBasePath;
+  }
+
+  static workflow(workflowId: string): string {
+    return `${this.workflowsBasePath}/${encodeURIComponent(workflowId)}`;
+  }
+
+  static workflowActivation(workflowId: string): string {
+    return `${this.workflow(workflowId)}/activation`;
+  }
+
+  static workflowRuns(workflowId: string): string {
+    return `${this.workflow(workflowId)}/runs`;
+  }
+
+  static workflowCredentialHealth(workflowId: string): string {
+    return `${this.workflow(workflowId)}/credential-health`;
+  }
+
+  static workflowDebuggerOverlay(workflowId: string): string {
+    return `${this.workflow(workflowId)}/debugger-overlay`;
+  }
+
+  static workflowDebuggerOverlayCopyRun(workflowId: string): string {
+    return `${this.workflowDebuggerOverlay(workflowId)}/copy-run`;
+  }
+
+  static workflowDebuggerOverlayBinaryUpload(workflowId: string): string {
+    return `${this.workflowDebuggerOverlay(workflowId)}/binary/upload`;
+  }
+
+  static workflowOverlayBinaryContent(workflowId: string, binaryId: string): string {
+    return `${this.workflow(workflowId)}/debugger-overlay/binary/${encodeURIComponent(binaryId)}/content`;
+  }
+
+  static runs(): string {
+    return this.runsBasePath;
+  }
+
+  static run(): string {
+    return this.runs();
+  }
+
+  static credentialTypes(): string {
+    return `${this.credentialsBasePath}/types`;
+  }
+
+  static credentialsEnvStatus(): string {
+    return `${this.credentialsBasePath}/env-status`;
+  }
+
+  static credentialInstances(): string {
+    return `${this.credentialsBasePath}/instances`;
+  }
+
+  static credentialInstance(instanceId: string, withSecrets?: boolean): string {
+    const base = `${this.credentialInstances()}/${encodeURIComponent(instanceId)}`;
+    return withSecrets ? `${base}?withSecrets=1` : base;
+  }
+
+  static credentialInstanceTest(instanceId: string): string {
+    return `${this.credentialInstance(instanceId)}/test`;
+  }
+
+  static credentialBindings(): string {
+    return `${this.apiBasePath}/credential-bindings`;
+  }
+
+  static oauth2Auth(instanceId: string): string {
+    return `${this.oauth2BasePath}/auth?instanceId=${encodeURIComponent(instanceId)}`;
+  }
+
+  static oauth2RedirectUri(): string {
+    return `${this.oauth2BasePath}/redirect-uri`;
+  }
+
+  static oauth2Disconnect(instanceId: string): string {
+    return `${this.oauth2BasePath}/disconnect?instanceId=${encodeURIComponent(instanceId)}`;
+  }
+
+  static workflowWebsocket(): string {
+    return `${this.workflowsBasePath}/ws`;
+  }
+
+  /** Dev gateway: stable browser WebSocket for build lifecycle (CLI → gateway → browser). */
+  static devGatewaySocket(): string {
+    return `${this.apiBasePath}/dev/socket`;
+  }
+
+  /** Dev gateway: HTTP notify endpoint used by the Codemation CLI during consumer rebuilds. */
+  static devGatewayNotify(): string {
+    return `${this.apiBasePath}/dev/notify`;
+  }
+
+  static webhooks(): string {
+    return this.webhooksBasePath;
+  }
+
+  static users(): string {
+    return this.usersBasePath;
+  }
+
+  static userInviteVerify(): string {
+    return `${this.usersBasePath}/invites/verify`;
+  }
+
+  static userInviteAccept(): string {
+    return `${this.usersBasePath}/invites/accept`;
+  }
+
+  static userInvites(): string {
+    return `${this.usersBasePath}/invites`;
+  }
+
+  static userInviteRegenerate(userId: string): string {
+    return `${this.usersBasePath}/${encodeURIComponent(userId)}/invites/regenerate`;
+  }
+
+  static userStatus(userId: string): string {
+    return `${this.usersBasePath}/${encodeURIComponent(userId)}/status`;
+  }
+
+  static runState(runId: string): string {
+    return `${this.runsBasePath}/${encodeURIComponent(runId)}`;
+  }
+
+  static runWorkflowSnapshot(runId: string): string {
+    return `${this.runState(runId)}/workflow-snapshot`;
+  }
+
+  static runNodePin(runId: string, nodeId: string): string {
+    return `${this.runState(runId)}/nodes/${encodeURIComponent(nodeId)}/pin`;
+  }
+
+  static runNode(runId: string, nodeId: string): string {
+    return `${this.runState(runId)}/nodes/${encodeURIComponent(nodeId)}/run`;
+  }
+
+  static runBinaryContent(runId: string, binaryId: string): string {
+    return `${this.runState(runId)}/binary/${encodeURIComponent(binaryId)}/content`;
+  }
+
+  /** Anonymous: consumer logo from `codemation.config.ts` whitelabel.logoPath. */
+  static whitelabelLogo(): string {
+    return `${this.whitelabelBasePath}/logo`;
+  }
+}

package/src/presentation/http/CodemationServerGatewayFactory.ts

@@ -0,0 +1,120 @@
+import { accessSync } from "node:fs";
+import path from "node:path";
+import type { QueryBus } from "../../application/bus/QueryBus";
+import type { WorkflowDto, WorkflowSummary } from "../../application/contracts/WorkflowViewContracts";
+import { WorkflowDefinitionMapper } from "../../application/mapping/WorkflowDefinitionMapper";
+import { GetWorkflowDetailQuery } from "../../application/queries/GetWorkflowDetailQuery";
+import { GetWorkflowSummariesQuery } from "../../application/queries/GetWorkflowSummariesQuery";
+import { ApplicationTokens } from "../../applicationTokens";
+import { CodemationApplication } from "../../codemationApplication";
+import { CodemationBootstrapRequest } from "../../bootstrap/CodemationBootstrapRequest";
+import { CodemationFrontendBootstrapRequest } from "../../bootstrap/CodemationFrontendBootstrapRequest";
+import type { CodemationConfig } from "../config/CodemationConfig";
+import { CodemationHonoApiApp } from "./hono/CodemationHonoApiAppFactory";
+
+type ServerGatewayContext = Readonly<{
+  application: CodemationApplication;
+  httpApi: CodemationHonoApiApp;
+  queryBus: QueryBus;
+  workflowDefinitionMapper: WorkflowDefinitionMapper;
+}>;
+
+export class CodemationServerGateway {
+  private static readonly contextsByConfig = new WeakMap<object, Promise<ServerGatewayContext>>();
+
+  constructor(
+    private readonly config: CodemationConfig,
+    private readonly consumerRoot: string,
+    private readonly configSource?: string,
+    private readonly workflowSources: ReadonlyArray<string> = [],
+    private readonly env?: Readonly<NodeJS.ProcessEnv>,
+  ) {}
+
+  async dispatch(request: Request): Promise<Response> {
+    return await (await this.getContext()).httpApi.fetch(request);
+  }
+
+  async prepare(): Promise<void> {
+    await this.getContext();
+  }
+
+  async close(): Promise<void> {
+    const cachedContext = CodemationServerGateway.contextsByConfig.get(this.config as object);
+    if (!cachedContext) {
+      return;
+    }
+    CodemationServerGateway.contextsByConfig.delete(this.config as object);
+    await (await cachedContext).application.stop();
+  }
+
+  async loadWorkflowSummaries(): Promise<ReadonlyArray<WorkflowSummary>> {
+    const context = await this.getContext();
+    const workflows = await context.queryBus.execute(new GetWorkflowSummariesQuery());
+    return workflows.map((workflow) => context.workflowDefinitionMapper.toSummary(workflow));
+  }
+
+  async loadWorkflowDetail(workflowId: string): Promise<WorkflowDto> {
+    const context = await this.getContext();
+    const workflow = await context.queryBus.execute(new GetWorkflowDetailQuery(workflowId));
+    if (!workflow) {
+      throw new Error(`Unknown workflowId: ${workflowId}`);
+    }
+    return await context.workflowDefinitionMapper.map(workflow);
+  }
+
+  private getContext(): Promise<ServerGatewayContext> {
+    const cachedContext = CodemationServerGateway.contextsByConfig.get(this.config as object);
+    if (cachedContext) {
+      return cachedContext;
+    }
+    const nextContext = this.createContext();
+    CodemationServerGateway.contextsByConfig.set(this.config as object, nextContext);
+    return nextContext;
+  }
+
+  private async createContext(): Promise<ServerGatewayContext> {
+    const repoRoot = this.detectWorkspaceRoot(this.consumerRoot);
+    const bootstrapRequest = new CodemationBootstrapRequest({
+      repoRoot,
+      consumerRoot: this.consumerRoot,
+      env: this.env,
+      workflowSources: this.resolveWorkflowSources(),
+    });
+    const application = new CodemationApplication();
+    application.useConfig(this.config);
+    await application.applyPlugins(bootstrapRequest);
+    await application.prepareContainer(bootstrapRequest);
+    await application.bootFrontend(new CodemationFrontendBootstrapRequest({ bootstrap: bootstrapRequest }));
+    return {
+      application,
+      httpApi: application.getContainer().resolve(CodemationHonoApiApp),
+      queryBus: application.getContainer().resolve(ApplicationTokens.QueryBus),
+      workflowDefinitionMapper: application.getContainer().resolve(WorkflowDefinitionMapper),
+    };
+  }
+
+  private resolveWorkflowSources(): ReadonlyArray<string> {
+    if (this.workflowSources.length > 0) {
+      return [...this.workflowSources];
+    }
+    if (!this.configSource || !this.config.workflows || this.config.workflows.length === 0) {
+      return [];
+    }
+    return [this.configSource];
+  }
+  private detectWorkspaceRoot(startDirectory: string): string {
+    let currentDirectory = path.resolve(startDirectory);
+    while (true) {
+      try {
+        accessSync(path.resolve(currentDirectory, "pnpm-workspace.yaml"));
+        return currentDirectory;
+      } catch {
+        const parentDirectory = path.dirname(currentDirectory);
+        if (parentDirectory === currentDirectory) {
+          return startDirectory;
+        }
+        currentDirectory = parentDirectory;
+      }
+    }
+  }
+}

package/src/presentation/http/HttpRequestJsonBodyReader.ts

@@ -0,0 +1,12 @@
+import { ApplicationRequestError } from "../../application/ApplicationRequestError";
+
+export class HttpRequestJsonBodyReader {
+  static async readJsonBody<TBody>(request: Request): Promise<TBody> {
+    try {
+      return (await request.json()) as TBody;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ApplicationRequestError(400, `Invalid JSON body: ${message}`);
+    }
+  }
+}

package/src/presentation/http/ServerHttpErrorResponseFactory.ts

@@ -0,0 +1,33 @@
+import { ApplicationRequestError } from "../../application/ApplicationRequestError";
+
+export class ServerHttpErrorResponseFactory {
+  static fromUnknown(error: unknown): Response {
+    if (error instanceof ApplicationRequestError) {
+      return Response.json(error.payload, { status: error.status });
+    }
+    this.logUnexpectedError(error);
+    const message = error instanceof Error ? error.message : String(error);
+    return Response.json({ error: message }, { status: 500 });
+  }
+
+  private static logUnexpectedError(error: unknown): void {
+    if (error instanceof Error) {
+      const stack = error.stack ?? `${error.name}: ${error.message}`;
+      const causeText = this.formatCause(error);
+      console.error(`[codemation-http] unhandled route error\n${stack}${causeText}`);
+      return;
+    }
+    console.error(`[codemation-http] unhandled route error\n${String(error)}`);
+  }
+
+  private static formatCause(error: Error): string {
+    if (!(error instanceof Error) || !("cause" in error) || !error.cause) {
+      return "";
+    }
+    const cause = error.cause;
+    if (cause instanceof Error) {
+      return `\nCaused by:\n${cause.stack ?? `${cause.name}: ${cause.message}`}`;
+    }
+    return `\nCaused by:\n${String(cause)}`;
+  }
+}

package/src/presentation/http/ServerHttpRouteParams.ts

@@ -0,0 +1 @@
+export type ServerHttpRouteParams = Readonly<Record<string, string>>;