@codemation/host 0.0.1

package/src/bootstrap/runtime/ResolvedImplementationSelectionFactory.ts

@@ -0,0 +1,118 @@
+import { BullmqScheduler } from "@codemation/queue-bullmq";
+import type { WorkerRuntimeScheduler } from "../../infrastructure/runtime/WorkerRuntimeScheduler";
+import type { ResolvedDatabasePersistence } from "../../infrastructure/persistence/DatabasePersistenceResolver";
+import { DatabasePersistenceResolver } from "../../infrastructure/persistence/DatabasePersistenceResolver";
+import { SchedulerPersistenceCompatibilityValidator } from "../../infrastructure/persistence/SchedulerPersistenceCompatibilityValidator";
+import type {
+  CodemationApplicationRuntimeConfig,
+  CodemationEventBusKind,
+  CodemationSchedulerKind,
+} from "../../presentation/config/CodemationConfig";
+
+export type ResolvedImplementationSelection = Readonly<{
+  databasePersistence: ResolvedDatabasePersistence;
+  eventBusKind: CodemationEventBusKind;
+  queuePrefix: string;
+  redisUrl?: string;
+  schedulerKind: CodemationSchedulerKind;
+  workerRuntimeScheduler?: WorkerRuntimeScheduler;
+}>;
+
+export class ResolvedImplementationSelectionFactory {
+  constructor(
+    private readonly databasePersistenceResolver: DatabasePersistenceResolver = new DatabasePersistenceResolver(),
+    private readonly schedulerPersistenceCompatibilityValidator: SchedulerPersistenceCompatibilityValidator = new SchedulerPersistenceCompatibilityValidator(),
+  ) {}
+
+  resolve(
+    args: Readonly<{
+      consumerRoot: string;
+      runtimeConfig: CodemationApplicationRuntimeConfig;
+      env: Readonly<NodeJS.ProcessEnv>;
+    }>,
+  ): ResolvedImplementationSelection {
+    const databasePersistence = this.databasePersistenceResolver.resolve({
+      runtimeConfig: args.runtimeConfig,
+      env: args.env,
+      consumerRoot: args.consumerRoot,
+    });
+    const redisUrl = args.runtimeConfig.eventBus?.redisUrl ?? args.env.REDIS_URL;
+    const schedulerKind = this.resolveSchedulerKind(args.runtimeConfig, args.env, redisUrl);
+    const eventBusKind = this.resolveEventBusKind(args.runtimeConfig, args.env, schedulerKind, redisUrl);
+    const queuePrefix =
+      args.runtimeConfig.scheduler?.queuePrefix ??
+      args.runtimeConfig.eventBus?.queuePrefix ??
+      args.env.QUEUE_PREFIX ??
+      "codemation";
+    if (schedulerKind === "bullmq" && eventBusKind !== "redis") {
+      throw new Error(
+        "BullMQ scheduling requires a Redis event bus so worker events can be forwarded to connected clients.",
+      );
+    }
+    if (eventBusKind === "redis" && !redisUrl) {
+      throw new Error("Redis event bus requires runtime.eventBus.redisUrl or REDIS_URL.");
+    }
+    this.schedulerPersistenceCompatibilityValidator.validate({ schedulerKind, persistence: databasePersistence });
+    const workerRuntimeScheduler =
+      schedulerKind === "bullmq"
+        ? new BullmqScheduler({ url: this.requireRedisUrl(redisUrl) }, queuePrefix)
+        : undefined;
+    return {
+      databasePersistence,
+      eventBusKind,
+      queuePrefix,
+      redisUrl,
+      schedulerKind,
+      workerRuntimeScheduler,
+    };
+  }
+
+  private resolveSchedulerKind(
+    runtimeConfig: CodemationApplicationRuntimeConfig,
+    env: Readonly<NodeJS.ProcessEnv>,
+    redisUrl: string | undefined,
+  ): CodemationSchedulerKind {
+    const configuredKind = runtimeConfig.scheduler?.kind ?? this.readSchedulerKind(env.CODEMATION_SCHEDULER);
+    if (configuredKind) {
+      return configuredKind;
+    }
+    return redisUrl ? "bullmq" : "local";
+  }
+
+  private resolveEventBusKind(
+    runtimeConfig: CodemationApplicationRuntimeConfig,
+    env: Readonly<NodeJS.ProcessEnv>,
+    schedulerKind: CodemationSchedulerKind,
+    redisUrl: string | undefined,
+  ): CodemationEventBusKind {
+    const configuredKind = runtimeConfig.eventBus?.kind ?? this.readEventBusKind(env.CODEMATION_EVENT_BUS);
+    if (configuredKind) {
+      return configuredKind;
+    }
+    if (schedulerKind === "bullmq") {
+      return "redis";
+    }
+    return redisUrl ? "redis" : "memory";
+  }
+
+  private readSchedulerKind(value: string | undefined): CodemationSchedulerKind | undefined {
+    if (value === "local" || value === "bullmq") {
+      return value;
+    }
+    return undefined;
+  }
+
+  private readEventBusKind(value: string | undefined): CodemationEventBusKind | undefined {
+    if (value === "memory" || value === "redis") {
+      return value;
+    }
+    return undefined;
+  }
+
+  private requireRedisUrl(redisUrl: string | undefined): string {
+    if (!redisUrl) {
+      throw new Error("Redis-backed runtime requires runtime.eventBus.redisUrl or REDIS_URL.");
+    }
+    return redisUrl;
+  }
+}

package/src/client.ts

@@ -0,0 +1,3 @@
+export type { Logger, LoggerFactory } from "./application/logging/Logger";
+export { BrowserLoggerFactory } from "./infrastructure/logging/BrowserLoggerFactory";
+export type { CodemationWhitelabelConfig } from "./presentation/config/CodemationWhitelabelConfig";

package/src/codemationApplication.ts

@@ -0,0 +1,311 @@
+import "reflect-metadata";
+
+import type { Container, WorkflowDefinition } from "@codemation/core";
+import { CoreTokens } from "@codemation/core";
+import type { BootRuntimeSummary } from "./application/dev/BootRuntimeSummary.types";
+import "./application/commands/CopyRunToWorkflowDebuggerCommandHandler";
+import "./application/commands/CredentialCommandHandlers";
+import "./application/commands/HandleWebhookInvocationCommandHandler";
+import "./application/commands/ReplayWorkflowNodeCommandHandler";
+import "./application/commands/ReplaceMutableRunWorkflowSnapshotCommandHandler";
+import "./application/commands/ReplaceWorkflowDebuggerOverlayCommandHandler";
+import "./application/commands/SetPinnedNodeInputCommandHandler";
+import "./application/commands/SetWorkflowActivationCommandHandler";
+import "./application/commands/StartWorkflowRunCommandHandler";
+import "./application/commands/UploadOverlayPinnedBinaryCommandHandler";
+import "./application/commands/UserAccountCommandHandlers";
+import "./application/queries/CredentialQueryHandlers";
+import "./application/queries/GetRunBinaryAttachmentQueryHandler";
+import "./application/queries/GetRunStateQueryHandler";
+import "./application/queries/GetWorkflowDebuggerOverlayQueryHandler";
+import "./application/queries/GetWorkflowDetailQueryHandler";
+import "./application/queries/GetWorkflowOverlayBinaryAttachmentQueryHandler";
+import "./application/queries/GetWorkflowSummariesQueryHandler";
+import "./application/queries/ListWorkflowRunsQueryHandler";
+import "./application/queries/UserAccountQueryHandlers";
+import "./application/binary/OverlayPinnedBinaryUploadService";
+import "./presentation/http/hono/registrars/BinaryHonoApiRouteRegistrar";
+import "./presentation/http/hono/registrars/CredentialHonoApiRouteRegistrar";
+import "./presentation/http/hono/registrars/DevHonoApiRouteRegistrar";
+import "./presentation/http/hono/registrars/OAuth2HonoApiRouteRegistrar";
+import "./presentation/http/hono/registrars/RunHonoApiRouteRegistrar";
+import "./presentation/http/hono/registrars/UserHonoApiRouteRegistrar";
+import "./presentation/http/hono/registrars/WebhookHonoApiRouteRegistrar";
+import "./presentation/http/hono/registrars/WhitelabelHonoApiRouteRegistrar";
+import "./presentation/http/hono/registrars/WorkflowHonoApiRouteRegistrar";
+import "./presentation/http/routeHandlers/BinaryHttpRouteHandlerFactory";
+import "./presentation/http/routeHandlers/CredentialHttpRouteHandler";
+import "./presentation/http/routeHandlers/OAuth2HttpRouteHandlerFactory";
+import "./presentation/http/routeHandlers/RunHttpRouteHandler";
+import "./presentation/http/routeHandlers/UserHttpRouteHandlerFactory";
+import "./presentation/http/routeHandlers/WebhookHttpRouteHandler";
+import "./presentation/http/routeHandlers/WorkflowHttpRouteHandler";
+import { logLevelPolicyFactory } from "./infrastructure/logging/LogLevelPolicyFactory";
+import { FrameworkBuiltinCredentialTypesRegistrar } from "./infrastructure/credentials/FrameworkBuiltinCredentialTypesRegistrar";
+import { OpenAiApiKeyCredentialHealthTester } from "./infrastructure/credentials/OpenAiApiKeyCredentialHealthTester";
+import { OpenAiApiKeyCredentialTypeFactory } from "./infrastructure/credentials/OpenAiApiKeyCredentialTypeFactory";
+import { CodemationPluginRegistrar } from "./infrastructure/config/CodemationPluginRegistrar";
+import type { CredentialType } from "./domain/credentials/CredentialServices";
+import { CredentialTypeRegistryImpl } from "./domain/credentials/CredentialServices";
+import type { CodemationAuthConfig } from "./presentation/config/CodemationAuthConfig";
+import type { CodemationApplicationRuntimeConfig, CodemationConfig } from "./presentation/config/CodemationConfig";
+import type { NormalizedCodemationConfig } from "./presentation/config/CodemationConfigNormalizer";
+import { CodemationConfigNormalizer } from "./presentation/config/CodemationConfigNormalizer";
+import type { CodemationPlugin } from "./presentation/config/CodemationPlugin";
+import type { CodemationWhitelabelConfig } from "./presentation/config/CodemationWhitelabelConfig";
+import { WorkflowWebsocketServer } from "./presentation/websocket/WorkflowWebsocketServer";
+import { ApplicationTokens } from "./applicationTokens";
+import { CodemationBootstrapRequest } from "./bootstrap/CodemationBootstrapRequest";
+import type { CodemationContainerRegistration } from "./bootstrap/CodemationContainerRegistration";
+import { CodemationFrontendBootstrapRequest } from "./bootstrap/CodemationFrontendBootstrapRequest";
+import { PreparedCodemationRuntime } from "./bootstrap/PreparedCodemationRuntime";
+import { PreparedCodemationRuntimeFactory } from "./bootstrap/PreparedCodemationRuntimeFactory";
+import { CodemationContainerFactory } from "./bootstrap/CodemationContainerFactory";
+import { CodemationWorkerBootstrapRequest } from "./bootstrap/CodemationWorkerBootstrapRequest";
+import { AppConfigFactory } from "./bootstrap/runtime/AppConfigFactory";
+import { CliRuntimeBootService } from "./bootstrap/boot/CliRuntimeBootService";
+import { FrontendRuntimeBootService } from "./bootstrap/boot/FrontendRuntimeBootService";
+import { WorkerRuntimeBootService } from "./bootstrap/boot/WorkerRuntimeBootService";
+
+type StopHandle = Readonly<{ stop: () => Promise<void> }>;
+
+export type CodemationStopHandle = StopHandle;
+
+export type CodemationApplicationConfig = CodemationConfig;
+
+export class CodemationApplication {
+  private readonly pluginRegistrar: CodemationPluginRegistrar;
+  private readonly containerFactory: CodemationContainerFactory;
+  private readonly preparedRuntimeFactory: PreparedCodemationRuntimeFactory;
+  private readonly configNormalizer: CodemationConfigNormalizer;
+  private readonly appConfigFactory: AppConfigFactory;
+  private readonly cliRuntimeBootService: CliRuntimeBootService;
+  private readonly frontendRuntimeBootService: FrontendRuntimeBootService;
+  private readonly workerRuntimeBootService: WorkerRuntimeBootService;
+
+  private configuredContainer: Container | null = null;
+  private preparedRuntime: PreparedCodemationRuntime | null = null;
+  private workflows: WorkflowDefinition[] = [];
+  private runtimeConfig: CodemationApplicationRuntimeConfig = {};
+  private containerRegistrations: ReadonlyArray<CodemationContainerRegistration<unknown>> = [];
+  private hasConfiguredCredentialSessionServiceRegistration = false;
+  private plugins: ReadonlyArray<CodemationPlugin> = [];
+  private sharedWorkflowWebsocketServer: WorkflowWebsocketServer | null = null;
+  private applicationAuthConfig: CodemationAuthConfig | undefined;
+  private whitelabelConfig: CodemationWhitelabelConfig = {};
+  private frameworkBuiltinCredentialTypesRegistered = false;
+  private credentialTypes: Array<CredentialType<any, any, unknown>> = [];
+
+  constructor(
+    pluginRegistrar: CodemationPluginRegistrar = new CodemationPluginRegistrar(),
+    containerFactory: CodemationContainerFactory = new CodemationContainerFactory(),
+    preparedRuntimeFactory: PreparedCodemationRuntimeFactory = new PreparedCodemationRuntimeFactory(),
+    configNormalizer: CodemationConfigNormalizer = new CodemationConfigNormalizer(),
+    appConfigFactory: AppConfigFactory = new AppConfigFactory(),
+    cliRuntimeBootService: CliRuntimeBootService = new CliRuntimeBootService(),
+    frontendRuntimeBootService: FrontendRuntimeBootService = new FrontendRuntimeBootService(),
+    workerRuntimeBootService: WorkerRuntimeBootService = new WorkerRuntimeBootService(),
+  ) {
+    this.pluginRegistrar = pluginRegistrar;
+    this.containerFactory = containerFactory;
+    this.preparedRuntimeFactory = preparedRuntimeFactory;
+    this.configNormalizer = configNormalizer;
+    this.appConfigFactory = appConfigFactory;
+    this.cliRuntimeBootService = cliRuntimeBootService;
+    this.frontendRuntimeBootService = frontendRuntimeBootService;
+    this.workerRuntimeBootService = workerRuntimeBootService;
+  }
+
+  useConfig(config: CodemationApplicationConfig): this {
+    const normalizedConfig: NormalizedCodemationConfig = this.configNormalizer.normalize(config);
+    logLevelPolicyFactory.create().applyCodemationLogConfig(normalizedConfig.log);
+    if (normalizedConfig.workflows) {
+      this.useWorkflows(normalizedConfig.workflows);
+    }
+    this.useContainerRegistrations(normalizedConfig.containerRegistrations);
+    if (!this.frameworkBuiltinCredentialTypesRegistered) {
+      new FrameworkBuiltinCredentialTypesRegistrar(
+        new OpenAiApiKeyCredentialTypeFactory(new OpenAiApiKeyCredentialHealthTester(globalThis.fetch)),
+      ).register(this, normalizedConfig);
+      this.frameworkBuiltinCredentialTypesRegistered = true;
+    }
+    if (normalizedConfig.credentialTypes) {
+      for (const credentialType of normalizedConfig.credentialTypes) {
+        this.registerCredentialType(credentialType);
+      }
+    }
+    if (normalizedConfig.plugins) {
+      this.usePlugins(normalizedConfig.plugins);
+    }
+    if (normalizedConfig.runtime) {
+      this.useRuntimeConfig(normalizedConfig.runtime);
+    }
+    if (normalizedConfig.auth !== undefined) {
+      this.applicationAuthConfig = normalizedConfig.auth;
+    }
+    this.whitelabelConfig = normalizedConfig.whitelabel ?? {};
+    return this;
+  }
+
+  useWorkflows(workflows: ReadonlyArray<WorkflowDefinition>): this {
+    this.workflows = [...workflows];
+    this.invalidatePreparedState();
+    return this;
+  }
+
+  useRuntimeConfig(runtimeConfig: CodemationApplicationRuntimeConfig): this {
+    this.runtimeConfig = {
+      ...this.runtimeConfig,
+      ...runtimeConfig,
+      ...(runtimeConfig.engineExecutionLimits !== undefined
+        ? {
+            engineExecutionLimits: {
+              ...this.runtimeConfig.engineExecutionLimits,
+              ...runtimeConfig.engineExecutionLimits,
+            },
+          }
+        : {}),
+    };
+    this.invalidatePreparedState();
+    return this;
+  }
+
+  private useContainerRegistrations(registrations: ReadonlyArray<CodemationContainerRegistration<unknown>>): this {
+    this.containerRegistrations = [...registrations];
+    this.hasConfiguredCredentialSessionServiceRegistration = registrations.some(
+      (entry) => entry.token === CoreTokens.CredentialSessionService,
+    );
+    this.invalidatePreparedState();
+    return this;
+  }
+
+  usePlugins(plugins: ReadonlyArray<CodemationPlugin>): this {
+    this.plugins = [...plugins];
+    return this;
+  }
+
+  useSharedWorkflowWebsocketServer(workflowWebsocketServer: WorkflowWebsocketServer): this {
+    this.sharedWorkflowWebsocketServer = workflowWebsocketServer;
+    if (this.configuredContainer) {
+      this.configuredContainer.registerInstance(WorkflowWebsocketServer, workflowWebsocketServer);
+      this.configuredContainer.registerInstance(ApplicationTokens.WorkflowWebsocketPublisher, workflowWebsocketServer);
+    }
+    return this;
+  }
+
+  getRuntimeConfig(): CodemationApplicationRuntimeConfig {
+    return { ...this.runtimeConfig };
+  }
+
+  getWorkflows(): ReadonlyArray<WorkflowDefinition> {
+    return [...this.workflows];
+  }
+
+  getContainer(): Container {
+    return this.ensureConfiguredContainer();
+  }
+
+  getBootRuntimeSummary(): BootRuntimeSummary | null {
+    return this.preparedRuntime?.runtimeSummary ?? null;
+  }
+
+  registerCredentialType(type: CredentialType<any, any, unknown>): void {
+    if (this.credentialTypes.some((entry) => entry.definition.typeId === type.definition.typeId)) {
+      return;
+    }
+    this.credentialTypes.push(type);
+    if (this.configuredContainer) {
+      this.configuredContainer.resolve(CredentialTypeRegistryImpl).register(type);
+    }
+  }
+
+  async applyPlugins(request: CodemationBootstrapRequest): Promise<void> {
+    const container = this.ensureConfiguredContainer();
+    const env = request.resolveEnvironment();
+    await this.pluginRegistrar.apply({
+      plugins: this.plugins,
+      container,
+      appConfig: this.appConfigFactory.create({
+        repoRoot: request.repoRoot,
+        consumerRoot: request.consumerRoot,
+        env,
+        workflowSources: request.workflowSources,
+        runtimeConfig: this.runtimeConfig,
+        authConfig: this.applicationAuthConfig,
+        whitelabelConfig: this.whitelabelConfig,
+      }),
+      registerCredentialType: (type) => this.registerCredentialType(type),
+      loggerFactory: container.resolve(ApplicationTokens.LoggerFactory),
+    });
+  }
+
+  async prepareContainer(request: CodemationBootstrapRequest): Promise<PreparedCodemationRuntime> {
+    if (this.preparedRuntime) {
+      return this.preparedRuntime;
+    }
+    const env = request.resolveEnvironment();
+    this.preparedRuntime = await this.preparedRuntimeFactory.prepare({
+      container: this.ensureConfiguredContainer(),
+      repoRoot: request.repoRoot,
+      consumerRoot: request.consumerRoot,
+      env,
+      workflowSources: request.workflowSources,
+      runtimeConfig: this.runtimeConfig,
+      applicationAuthConfig: this.applicationAuthConfig,
+      whitelabelConfig: this.whitelabelConfig,
+      hasConfiguredCredentialSessionServiceRegistration: this.hasConfiguredCredentialSessionServiceRegistration,
+    });
+    return this.preparedRuntime;
+  }
+
+  async bootCli(request: CodemationBootstrapRequest): Promise<PreparedCodemationRuntime> {
+    const preparedRuntime = await this.prepareContainer(request);
+    await this.cliRuntimeBootService.boot({ preparedRuntime });
+    return preparedRuntime;
+  }
+
+  async bootFrontend(request: CodemationFrontendBootstrapRequest): Promise<PreparedCodemationRuntime> {
+    const preparedRuntime = await this.prepareContainer(request.bootstrap);
+    await this.frontendRuntimeBootService.boot({
+      preparedRuntime,
+      skipPresentationServers: request.skipPresentationServers,
+    });
+    return preparedRuntime;
+  }
+
+  async bootWorker(request: CodemationWorkerBootstrapRequest): Promise<CodemationStopHandle> {
+    const preparedRuntime = await this.prepareContainer(request.bootstrap);
+    void request.bootstrapSource;
+    return await this.workerRuntimeBootService.boot({
+      preparedRuntime,
+      queues: request.queues,
+    });
+  }
+
+  async stop(args?: Readonly<{ stopWebsocketServer?: boolean }>): Promise<void> {
+    if (!this.preparedRuntime) {
+      return;
+    }
+    await this.preparedRuntime.stop(args);
+  }
+
+  private ensureConfiguredContainer(): Container {
+    if (this.configuredContainer) {
+      return this.configuredContainer;
+    }
+    this.configuredContainer = this.containerFactory.create({
+      application: this,
+      registrations: this.containerRegistrations,
+      runtimeConfig: this.runtimeConfig,
+      workflows: this.workflows,
+      credentialTypes: this.credentialTypes,
+      sharedWorkflowWebsocketServer: this.sharedWorkflowWebsocketServer,
+    });
+    return this.configuredContainer;
+  }
+
+  private invalidatePreparedState(): void {
+    this.configuredContainer = null;
+    this.preparedRuntime = null;
+  }
+}

package/src/consumer.ts

@@ -0,0 +1,4 @@
+export { CodemationConsumerAppResolver } from "./presentation/server/CodemationConsumerAppResolver";
+export type { CodemationConsumerApp } from "./presentation/server/CodemationConsumerAppResolver";
+export { CodemationConsumerConfigLoader } from "./presentation/server/CodemationConsumerConfigLoader";
+export type { CodemationConsumerConfigResolution } from "./presentation/server/CodemationConsumerConfigLoader";

package/src/credentials.ts

@@ -0,0 +1,24 @@
+import type { AnyCredentialType } from "./domain/credentials/CredentialServices";
+import { OpenAiApiKeyCredentialHealthTester } from "./infrastructure/credentials/OpenAiApiKeyCredentialHealthTester";
+import { OpenAiApiKeyCredentialTypeFactory } from "./infrastructure/credentials/OpenAiApiKeyCredentialTypeFactory";
+
+export { CredentialBindingService, CredentialInstanceService } from "./domain/credentials/CredentialServices";
+export type {
+  AnyCredentialType,
+  CredentialSessionFactoryArgs,
+  CredentialType,
+} from "./domain/credentials/CredentialServices";
+export { OpenAiApiKeyCredentialHealthTester } from "./infrastructure/credentials/OpenAiApiKeyCredentialHealthTester";
+export { OpenAiApiKeyCredentialTypeFactory } from "./infrastructure/credentials/OpenAiApiKeyCredentialTypeFactory";
+export type {
+  OpenAiApiKeyMaterial,
+  OpenAiApiKeyPublicConfig,
+  OpenAiApiKeySession,
+} from "./infrastructure/credentials/OpenAiApiKeyCredentialShapes.types";
+
+const defaultOpenAiApiKeyCredentialTypeFactory = new OpenAiApiKeyCredentialTypeFactory(
+  new OpenAiApiKeyCredentialHealthTester(globalThis.fetch),
+);
+
+export const openAiApiKeyCredentialType: AnyCredentialType =
+  defaultOpenAiApiKeyCredentialTypeFactory.createCredentialType();

package/src/devServerSidecar.ts

@@ -0,0 +1,10 @@
+/**
+ * Narrow entry for dev/runtime tooling (Next host, runtime-dev) without pulling the full
+ * server barrel (e.g. CodemationConsumerConfigLoader → tsx) into the Next bundle.
+ */
+export { CodemationTsyringeParamInfoReader } from "./presentation/server/CodemationTsyringeParamInfoReader";
+export { CodemationTsyringeTypeInfoRegistrar } from "./presentation/server/CodemationTsyringeTypeInfoRegistrar";
+export {
+  DevelopmentRuntimeRouteGuard,
+  type DevelopmentRuntimeSignal,
+} from "./presentation/server/DevelopmentRuntimeRouteGuard";

package/src/domain/credentials/CredentialBindingService.ts

@@ -0,0 +1,139 @@
+import type {
+  CredentialBinding,
+  CredentialBindingKey,
+  CredentialInstanceId,
+  CredentialRequirement,
+  WorkflowDefinition,
+  WorkflowRepository,
+} from "@codemation/core";
+
+import { CoreTokens, inject, injectable } from "@codemation/core";
+
+import { ApplicationRequestError } from "../../application/ApplicationRequestError";
+
+import type {
+  WorkflowCredentialHealthDto,
+  WorkflowCredentialHealthSlotDto,
+} from "../../application/contracts/CredentialContractsRegistry";
+
+import { ApplicationTokens } from "../../applicationTokens";
+
+import { WorkflowCredentialNodeResolver } from "./WorkflowCredentialNodeResolver";
+import { CredentialInstanceService } from "./CredentialInstanceService";
+import type { CredentialStore, MutableCredentialSessionService } from "./CredentialServices";
+
+@injectable()
+export class CredentialBindingService {
+  constructor(
+    @inject(ApplicationTokens.CredentialStore)
+    private readonly credentialStore: CredentialStore,
+    @inject(CredentialInstanceService)
+    private readonly credentialInstanceService: CredentialInstanceService,
+    @inject(CoreTokens.WorkflowRepository)
+    private readonly workflowRepository: WorkflowRepository,
+    @inject(CoreTokens.CredentialSessionService)
+    private readonly credentialSessionService: MutableCredentialSessionService,
+    @inject(WorkflowCredentialNodeResolver)
+    private readonly workflowCredentialNodeResolver: WorkflowCredentialNodeResolver,
+  ) {}
+
+  async upsertBinding(
+    args: Readonly<{ workflowId: string; nodeId: string; slotKey: string; instanceId: CredentialInstanceId }>,
+  ): Promise<CredentialBinding> {
+    const workflow = this.requireWorkflow(args.workflowId);
+    const requirement = this.requireRequirement(workflow, args.nodeId, args.slotKey);
+    const instance = await this.credentialInstanceService.requireInstance(args.instanceId);
+    if (!requirement.acceptedTypes.includes(instance.typeId)) {
+      throw new ApplicationRequestError(
+        400,
+        `Credential instance ${instance.instanceId} (${instance.typeId}) is not compatible with slot ${args.slotKey}. Accepted types: ${requirement.acceptedTypes.join(", ")}`,
+      );
+    }
+    const binding: CredentialBinding = {
+      key: {
+        workflowId: args.workflowId,
+        nodeId: args.nodeId,
+        slotKey: args.slotKey,
+      },
+      instanceId: args.instanceId,
+      updatedAt: new Date().toISOString(),
+    };
+    await this.credentialStore.upsertBinding(binding);
+    this.credentialSessionService.evictBinding(binding.key);
+    return binding;
+  }
+
+  async listWorkflowHealth(workflowId: string): Promise<WorkflowCredentialHealthDto> {
+    const workflow = this.requireWorkflow(workflowId);
+    const bindings = await this.credentialStore.listBindingsByWorkflowId(workflowId);
+    const bindingsByKey = new Map(bindings.map((binding) => [this.toBindingKeyString(binding.key), binding] as const));
+    const slots: WorkflowCredentialHealthSlotDto[] = [];
+    for (const slotRef of this.workflowCredentialNodeResolver.listSlots(workflow)) {
+      const requirement = slotRef.requirement;
+      const bindingKey = {
+        workflowId,
+        nodeId: slotRef.nodeId,
+        slotKey: requirement.slotKey,
+      } satisfies CredentialBindingKey;
+      const binding = bindingsByKey.get(this.toBindingKeyString(bindingKey));
+      if (!binding) {
+        slots.push({
+          workflowId,
+          nodeId: slotRef.nodeId,
+          nodeName: slotRef.nodeName,
+          requirement,
+          health: {
+            status: requirement.optional ? "optional-unbound" : "unbound",
+          },
+        });
+        continue;
+      }
+      const instance = await this.credentialInstanceService.requireInstance(binding.instanceId);
+      const latestTestResult = await this.credentialStore.getLatestTestResult(instance.instanceId);
+      slots.push({
+        workflowId,
+        nodeId: slotRef.nodeId,
+        nodeName: slotRef.nodeName,
+        requirement,
+        instance: {
+          instanceId: instance.instanceId,
+          typeId: instance.typeId,
+          displayName: instance.displayName,
+          setupStatus: instance.setupStatus,
+        },
+        health: {
+          status: latestTestResult?.health.status ?? "unknown",
+          message: latestTestResult?.health.message,
+          testedAt: latestTestResult?.health.testedAt,
+        },
+      });
+    }
+    return {
+      workflowId,
+      slots,
+    };
+  }
+
+  private requireWorkflow(workflowId: string): WorkflowDefinition {
+    const workflow = this.workflowRepository.get(decodeURIComponent(workflowId));
+    if (!workflow) {
+      throw new ApplicationRequestError(404, `Unknown workflowId: ${workflowId}`);
+    }
+    return workflow;
+  }
+
+  private requireRequirement(workflow: WorkflowDefinition, nodeId: string, slotKey: string): CredentialRequirement {
+    const resolved = this.workflowCredentialNodeResolver.findRequirement(workflow, nodeId, slotKey);
+    if (!resolved) {
+      if (!this.workflowCredentialNodeResolver.isCredentialNodeIdInWorkflow(workflow, nodeId)) {
+        throw new ApplicationRequestError(404, `Unknown workflow node: ${nodeId}`);
+      }
+      throw new ApplicationRequestError(400, `Node ${nodeId} does not declare credential slot ${slotKey}.`);
+    }
+    return resolved.requirement;
+  }
+
+  private toBindingKeyString(bindingKey: CredentialBindingKey): string {
+    return `${bindingKey.workflowId}:${bindingKey.nodeId}:${bindingKey.slotKey}`;
+  }
+}

package/src/domain/credentials/CredentialFieldEnvOverlayService.ts

@@ -0,0 +1,60 @@
+import type { CredentialFieldSchema, CredentialTypeDefinition } from "@codemation/core";
+import { inject, injectable } from "@codemation/core";
+
+import { ApplicationTokens } from "../../applicationTokens";
+import type { AppConfig } from "../../presentation/config/AppConfig";
+
+import type { JsonRecord } from "./CredentialServices";
+
+@injectable()
+export class CredentialFieldEnvOverlayService {
+  constructor(
+    @inject(ApplicationTokens.AppConfig)
+    private readonly appConfig: AppConfig,
+  ) {}
+
+  /** True when the field declares an env var and process.env has a non-empty string for it. */
+  isFieldResolvedFromEnv(field: CredentialFieldSchema): boolean {
+    const name = field.envVarName?.trim();
+    if (!name) {
+      return false;
+    }
+    const v = this.appConfig.env[name];
+    return typeof v === "string" && v.length > 0;
+  }
+
+  apply(
+    args: Readonly<{
+      definition: CredentialTypeDefinition;
+      publicConfig: JsonRecord;
+      material: JsonRecord;
+    }>,
+  ): Readonly<{ resolvedPublicConfig: JsonRecord; resolvedMaterial: JsonRecord }> {
+    const pub: Record<string, unknown> = { ...args.publicConfig };
+    const mat: Record<string, unknown> = { ...args.material };
+    for (const field of args.definition.publicFields ?? []) {
+      const name = field.envVarName?.trim();
+      if (!name) {
+        continue;
+      }
+      const v = this.appConfig.env[name];
+      if (typeof v === "string" && v.length > 0) {
+        pub[field.key] = v;
+      }
+    }
+    for (const field of args.definition.secretFields ?? []) {
+      const name = field.envVarName?.trim();
+      if (!name) {
+        continue;
+      }
+      const v = this.appConfig.env[name];
+      if (typeof v === "string" && v.length > 0) {
+        mat[field.key] = v;
+      }
+    }
+    return Object.freeze({
+      resolvedPublicConfig: Object.freeze(pub),
+      resolvedMaterial: Object.freeze(mat),
+    });
+  }
+}