@wildo-ai/platform-config-lib 1.0.1

package/src/bootstrap/application-backend-env.contracts.ts

@@ -0,0 +1,17 @@
+export {
+  APPLICATION_BACKEND_BOOTSTRAP_ENV_KEY_LIST,
+  APPLICATION_BACKEND_DATA_ENV_KEY_LIST,
+  APPLICATION_BACKEND_ENV_KEY_LIST,
+  APPLICATION_BACKEND_PLATFORM_URL_ENV_KEY_LIST,
+  APPLICATION_BACKEND_RUNTIME_ENV_KEY_LIST,
+  APPLICATION_BACKEND_SENSITIVE_ENV_KEYS,
+  ApplicationBackendBootstrapEnvKey,
+  ApplicationBackendBootstrapEnvKeys,
+  ApplicationBackendDataEnvKey,
+  ApplicationBackendDataEnvKeys,
+  type ApplicationBackendEnvKey,
+  ApplicationBackendPlatformUrlEnvKey,
+  ApplicationBackendPlatformUrlEnvKeys,
+  ApplicationBackendRuntimeEnvKey,
+  ApplicationBackendRuntimeEnvKeys,
+} from '@wildo-ai/platform-core-shared';

package/src/bootstrap/bootstrap-planner.ts

@@ -0,0 +1,46 @@
+import { BootstrapExecutorKind, BootstrapStepId } from './bootstrap.schemas';
+
+export interface BootstrapPlanInput {
+  executor: BootstrapExecutorKind;
+  initializePlatform?: boolean;
+  ensureApplication?: boolean;
+  fetchBootstrapCredentials?: boolean;
+  generateRuntimeArtifacts?: boolean;
+  startLocalRuntime?: boolean;
+}
+
+export interface BootstrapPlanStep {
+  id: BootstrapStepId;
+  required: boolean;
+}
+
+/**
+ * Build a semantic bootstrap plan independent of the concrete executor.
+ * Executors (CLI local processes, CI/CD remote jobs, HTTP workflows) can interpret
+ * the same ordered steps differently while keeping one shared core behavior.
+ */
+export function buildBootstrapPlan(input: BootstrapPlanInput): BootstrapPlanStep[] {
+  const steps: BootstrapPlanStep[] = [];
+
+  if (input.initializePlatform) {
+    steps.push({ id: BootstrapStepId.INITIALIZE_PLATFORM, required: true });
+  }
+
+  if (input.ensureApplication) {
+    steps.push({ id: BootstrapStepId.ENSURE_APPLICATION, required: true });
+  }
+
+  if (input.fetchBootstrapCredentials) {
+    steps.push({ id: BootstrapStepId.FETCH_BOOTSTRAP_CREDENTIALS, required: true });
+  }
+
+  if (input.generateRuntimeArtifacts) {
+    steps.push({ id: BootstrapStepId.GENERATE_RUNTIME_ARTIFACTS, required: true });
+  }
+
+  if (input.executor === BootstrapExecutorKind.LOCAL && input.startLocalRuntime) {
+    steps.push({ id: BootstrapStepId.START_LOCAL_RUNTIME, required: true });
+  }
+
+  return steps;
+}

package/src/bootstrap/bootstrap.contracts.ts

@@ -0,0 +1,251 @@
+import { RuntimeEnvironment } from '@wildo-ai/saas-models';
+import type { ApplicationModules } from '../project-config/shared/application-modules.schemas';
+import {
+  getDeclaredApplicationModuleIds,
+  getServiceBoundApplicationModuleIds,
+} from '../project-config/shared/application-modules.utils';
+import type { AppDataServices } from '../project-config/shared/data-services.schemas';
+import { deriveAppDatabaseName } from '../project-config/shared/data-services.schemas';
+import type {
+  CapabilityBindingInput,
+  ExternalProvidersConfigurationsInput,
+} from '../project-config/define-saas-config';
+import {
+  AdminAppManagedDeclarationSchema,
+  AppBootstrapCredentialsResponseSchema,
+  type AppBootstrapCredentialsResponse,
+  type AppBootstrapFirstAdminSeed,
+  type AdminAppManagedDeclaration,
+  type AdminAppInitializeRequest,
+} from './bootstrap.schemas';
+
+export interface BuildAppBootstrapCredentialsResponseInput {
+  appSlug: string;
+  environment: RuntimeEnvironment;
+  applicationId: string;
+  primarySecret: string;
+  appsManagerUrl: string;
+}
+
+/**
+ * apps-manager control-plane bootstrap protocol details shared by CLI callers
+ * and apps-manager producers.
+ */
+export const APPS_MANAGER_ADMIN_SECRET_HEADER = 'X-Admin-Secret';
+export const APPS_MANAGER_API_PREFIX = '/api/v1';
+
+export function buildAdminInitializeApplicationPath(appSlug: string): string {
+  return `/admin/apps/${encodeURIComponent(appSlug)}/initialize`;
+}
+
+export function buildAppBootstrapCredentialsPath(
+  appSlug: string,
+  environment: RuntimeEnvironment,
+): string {
+  return `/admin/apps/${encodeURIComponent(appSlug)}/credentials/${environment}`;
+}
+
+/**
+ * Build and validate the shared bootstrap credentials response envelope.
+ * This keeps the response contract identical across apps-manager producers and CLI consumers.
+ */
+export function buildAppBootstrapCredentialsResponse(
+  input: BuildAppBootstrapCredentialsResponseInput,
+): AppBootstrapCredentialsResponse {
+  return AppBootstrapCredentialsResponseSchema.parse({
+    success: true,
+    appSlug: input.appSlug,
+    environment: input.environment,
+    credentials: {
+      APPLICATION_ID: input.applicationId,
+      PLATFORM_APPLICATION_PRIMARY_SECRET: input.primarySecret,
+      PLATFORM_APPS_MANAGER_URL: input.appsManagerUrl,
+      APPLICATION_ENV: input.environment,
+    },
+  });
+}
+
+/**
+ * Small shared semantic descriptor for already-loaded app config.
+ * Filesystem/path-bearing adapter data should stay in the CLI layer.
+ */
+export interface NormalizedProjectAppDescriptor {
+  appKey: string;
+  appPath: string;
+  appType: 'saas';
+}
+
+export function normalizeProjectApps(input: {
+  apps: Record<string, { path: string; type: 'saas' }>;
+}): NormalizedProjectAppDescriptor[] {
+  return Object.entries(input.apps).map(([appKey, app]) => ({
+    appKey,
+    appPath: app.path,
+    appType: app.type,
+  }));
+}
+
+export interface NormalizedSaasBackendServiceDescriptor {
+  key: string;
+  path: string;
+  serviceName: string;
+  defaultPort?: number | undefined;
+}
+
+export interface NormalizedSaasFrontendServiceDescriptor {
+  key: string;
+  path: string;
+  serviceName: string;
+  defaultPort?: number | undefined;
+  frontendType: string;
+}
+
+export interface NormalizedSaasRuntimeDescriptor {
+  appSlug: string;
+  appDisplayName: string;
+  appDatabaseName?: string | undefined;
+  backendServices: NormalizedSaasBackendServiceDescriptor[];
+  frontendServices: NormalizedSaasFrontendServiceDescriptor[];
+  managedDeclaration: AdminAppManagedDeclaration;
+  firstAdminSeed?: AppBootstrapFirstAdminSeed | undefined;
+  declaredModules: NonNullable<ApplicationModules>;
+  moduleIds: string[];
+  moduleIdsByService: Record<string, string[]>;
+}
+
+export interface NormalizedLocalServiceAddressingDescriptor {
+  host?: string | undefined;
+  port?: number | undefined;
+  url?: string | undefined;
+}
+
+export function normalizeSaasModuleBindings(input: {
+  services: Record<string, { serviceName: string }>;
+  modules?: ApplicationModules | undefined;
+}) {
+  const declaredModules = input.modules ?? {};
+
+  return {
+    declaredModules,
+    moduleIds: getDeclaredApplicationModuleIds(declaredModules),
+    moduleIdsByService: Object.fromEntries(
+      Object.keys(input.services).map((serviceKey) => [
+        serviceKey,
+        getServiceBoundApplicationModuleIds(declaredModules, serviceKey),
+      ]),
+    ),
+  };
+}
+
+export function buildAdminAppManagedDeclaration(input: {
+  name: string;
+  slug: string;
+  displayName: string;
+  description?: string | undefined;
+  type: 'saas';
+  services: Record<
+    string,
+    {
+      serviceName: string;
+      frontendType?: string | undefined;
+    }
+  >;
+  capabilities?: Record<string, CapabilityBindingInput> | undefined;
+  externalProvidersConfigurations?: ExternalProvidersConfigurationsInput | undefined;
+}): AdminAppManagedDeclaration {
+  return AdminAppManagedDeclarationSchema.parse({
+    app: {
+      name: input.name,
+      slug: input.slug,
+      displayName: input.displayName,
+      description: input.description,
+      type: input.type,
+    },
+    frontendServices: Object.values(input.services)
+      .filter((service) => service.frontendType !== undefined)
+      .map((service) => ({
+        serviceName: service.serviceName,
+        frontendType: service.frontendType,
+      })),
+    capabilities: input.capabilities,
+    externalProvidersConfigurations: input.externalProvidersConfigurations,
+  });
+}
+
+export function normalizeSaasRuntimeDescriptor(input: {
+  projectAppKey?: string | undefined;
+  name: string;
+  slug: string;
+  displayName: string;
+  description?: string | undefined;
+  type: 'saas';
+  services: Record<
+    string,
+    {
+      path: string;
+      serviceName: string;
+      defaultPort?: number | undefined;
+      frontendType?: string | undefined;
+    }
+  >;
+  capabilities?: Record<string, CapabilityBindingInput> | undefined;
+  externalProvidersConfigurations?: ExternalProvidersConfigurationsInput | undefined;
+  dataServices?: AppDataServices | undefined;
+  modules?: ApplicationModules | undefined;
+  bootstrap?: {
+    firstAdmin?: AppBootstrapFirstAdminSeed | undefined;
+  } | undefined;
+}): NormalizedSaasRuntimeDescriptor {
+  if (input.projectAppKey && input.projectAppKey !== input.slug) {
+    throw new Error(
+      `Project app key "${input.projectAppKey}" must match SaaS slug "${input.slug}" for coherent app identity`,
+    );
+  }
+
+  const backendServices = Object.entries(input.services)
+    .filter(([, service]) => service.frontendType === undefined)
+    .map(([key, service]) => ({
+      key,
+      path: service.path,
+      serviceName: service.serviceName,
+      defaultPort: service.defaultPort,
+    }));
+
+  const frontendServices = Object.entries(input.services)
+    .filter(([, service]) => service.frontendType !== undefined)
+    .map(([key, service]) => ({
+      key,
+      path: service.path,
+      serviceName: service.serviceName,
+      defaultPort: service.defaultPort,
+      frontendType: service.frontendType!,
+    }));
+  const normalizedModuleBindings = normalizeSaasModuleBindings({
+    services: input.services,
+    modules: input.modules,
+  });
+
+  return {
+    appSlug: input.slug,
+    appDisplayName: input.displayName,
+    appDatabaseName: deriveAppDatabaseName(input.dataServices),
+    backendServices,
+    frontendServices,
+    managedDeclaration: buildAdminAppManagedDeclaration({
+      name: input.name,
+      slug: input.slug,
+      displayName: input.displayName,
+      description: input.description,
+      type: input.type,
+      services: input.services,
+      capabilities: input.capabilities,
+      externalProvidersConfigurations: input.externalProvidersConfigurations,
+    }),
+    firstAdminSeed: input.bootstrap?.firstAdmin,
+    declaredModules: normalizedModuleBindings.declaredModules,
+    moduleIds: normalizedModuleBindings.moduleIds,
+    moduleIdsByService: normalizedModuleBindings.moduleIdsByService,
+  };
+}
+
+export type { AdminAppInitializeRequest };

package/src/bootstrap/bootstrap.schemas.ts

@@ -0,0 +1,164 @@
+import {
+  AppConfiguration_Shared_AppIdentity_Schema,
+  CapabilityBindingsPolicySchema,
+  EngineCapability,
+  FrontendServicesConfigSchema,
+  RuntimeEnvironment,
+} from '@wildo-ai/saas-models';
+import { z } from 'zod';
+import {
+  CapabilityBindingSchema,
+  ExternalProvidersConfigurationsSchema,
+} from '../project-config/define-saas-config';
+import { AppFrontendType } from '../project-config/shared/service-definitions.schemas';
+
+/**
+ * Shared bootstrap execution mode.
+ * The workflow semantics stay the same; only the executor differs.
+ */
+export enum BootstrapExecutorKind {
+  LOCAL = 'local',
+  REMOTE = 'remote',
+}
+
+/**
+ * Shared bootstrap step identifiers.
+ * These represent semantic workflow stages, not package-specific implementation details.
+ */
+export enum BootstrapStepId {
+  INITIALIZE_PLATFORM = 'initialize-platform',
+  ENSURE_APPLICATION = 'ensure-application',
+  FETCH_BOOTSTRAP_CREDENTIALS = 'fetch-bootstrap-credentials',
+  GENERATE_RUNTIME_ARTIFACTS = 'generate-runtime-artifacts',
+  START_LOCAL_RUNTIME = 'start-local-runtime',
+}
+
+/**
+ * Minimum bootstrap credentials required for an application backend to authenticate
+ * with apps-manager and fetch its full runtime configuration.
+ */
+export const AppBootstrapCredentialsSchema = z.object({
+  APPLICATION_ID: z.string().min(1),
+  PLATFORM_APPLICATION_PRIMARY_SECRET: z.string().min(1),
+  PLATFORM_APPS_MANAGER_URL: z.url(),
+  APPLICATION_ENV: z.nativeEnum(RuntimeEnvironment),
+});
+
+/**
+ * Shared response envelope returned by apps-manager when bootstrap credentials are requested.
+ * Both apps-manager and CLI should rely on this same contract.
+ * `environment` / `APPLICATION_ENV` describe runtime semantics for the
+ * bootstrapped application process, not the project-level remote environment id.
+ */
+export const AppBootstrapCredentialsResponseSchema = z.object({
+  success: z.literal(true),
+  appSlug: z.string().min(1),
+  environment: z.nativeEnum(RuntimeEnvironment),
+  credentials: AppBootstrapCredentialsSchema,
+});
+
+export const AdminAppManagedDeclarationSchema = z.object({
+  app: z.object({
+    name: z.string().min(1),
+    slug: z.string().min(1),
+    displayName: z.string().min(1),
+    description: z.string().optional(),
+    type: z.literal('saas'),
+  }),
+  frontendServices: z.array(z.object({
+    serviceName: z.string().min(1),
+    frontendType: z.enum(AppFrontendType),
+  })).default([]),
+  capabilities: z.partialRecord(
+    z.enum(EngineCapability),
+    CapabilityBindingSchema,
+  ).optional(),
+  externalProvidersConfigurations: ExternalProvidersConfigurationsSchema,
+});
+
+export const AppBootstrapFirstAdminSeedSchema = z.object({
+  userTypes: z.array(z.string().min(1)).min(1),
+});
+
+const AppBootstrapRotatedPublicKeyEntrySchema = z.object({
+  kid: z.string().min(1),
+  publicKey: z.string().min(1),
+});
+
+export const AppBootstrapConfigMetadataResponseSchema = z.object({
+  appSlug: z.string().min(1),
+  appIdentity: AppConfiguration_Shared_AppIdentity_Schema.optional(),
+  frontendServices: FrontendServicesConfigSchema.optional(),
+  capabilities: CapabilityBindingsPolicySchema.optional(),
+  email: z.object({
+    isTransactionalWildoManaged: z.boolean(),
+    isMarketingWildoManaged: z.boolean(),
+  }).optional(),
+  externalProvidersConfigurations: ExternalProvidersConfigurationsSchema,
+  jwt: z.object({
+    publicKey: z.record(z.string(), z.string()),
+    rotatedPublicKeys: z.record(
+      z.string(),
+      z.array(AppBootstrapRotatedPublicKeyEntrySchema),
+    ).optional(),
+  }).optional(),
+});
+
+/**
+ * Shared admin request payload for a single app initialization.
+ * This describes the control-plane contract, independently of whether the caller
+ * is the CLI or a future CI/CD executor.
+ */
+export const AdminAppInitializeRequestSchema = z.object({
+  name: z.string().min(1).optional(),
+  appDatabaseName: z.string().min(1).optional(),
+  override: z.boolean().optional(),
+  userEmail: z.string().email().optional(),
+  userFirstName: z.string().min(1).optional(),
+  userLastName: z.string().min(1).optional(),
+  userPassword: z.string().min(1).optional(),
+  managedDeclaration: AdminAppManagedDeclarationSchema.optional(),
+  firstAdminSeed: AppBootstrapFirstAdminSeedSchema.optional(),
+});
+
+export const AdminAppInitializeTargetSchema = z.object({
+  slug: z.string().min(1),
+  name: z.string().min(1).optional(),
+  appDatabaseName: z.string().min(1).optional(),
+  managedDeclaration: AdminAppManagedDeclarationSchema.optional(),
+  firstAdminSeed: AppBootstrapFirstAdminSeedSchema.optional(),
+});
+
+export const AdminAppsInitializeBatchRequestSchema = z.object({
+  override: z.boolean().optional(),
+  userEmail: z.string().email().optional(),
+  userFirstName: z.string().min(1).optional(),
+  userLastName: z.string().min(1).optional(),
+  userPassword: z.string().min(1).optional(),
+  targets: z.array(AdminAppInitializeTargetSchema).min(1),
+});
+
+/**
+ * Shared success response for a single app initialization request.
+ */
+export const AdminAppInitializeResponseSchema = z.object({
+  success: z.literal(true),
+  application: z.object({
+    name: z.string().min(1),
+    slug: z.string().min(1),
+  }),
+  credentials: z.object({
+    email: z.string().email(),
+    password: z.string().min(1),
+  }),
+});
+
+export type AppBootstrapCredentials = z.infer<typeof AppBootstrapCredentialsSchema>;
+export type AppBootstrapCredentialsResponse = z.infer<typeof AppBootstrapCredentialsResponseSchema>;
+export type AdminAppManagedDeclaration = z.infer<typeof AdminAppManagedDeclarationSchema>;
+export type AppBootstrapFirstAdminSeed = z.infer<typeof AppBootstrapFirstAdminSeedSchema>;
+export type AppBootstrapConfigMetadataResponse = z.infer<typeof AppBootstrapConfigMetadataResponseSchema>;
+export type AdminAppInitializeRequest = z.infer<typeof AdminAppInitializeRequestSchema>;
+export type AdminAppInitializeTarget = z.infer<typeof AdminAppInitializeTargetSchema>;
+export type AdminAppsInitializeBatchRequest = z.infer<typeof AdminAppsInitializeBatchRequestSchema>;
+export type AdminAppInitializeResponse = z.infer<typeof AdminAppInitializeResponseSchema>;

package/src/bootstrap/platform-runtime-env.contracts.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared environment contract for platform runtime processes.
+ *
+ * This captures the canonical env-var vocabulary used by CLI-generated platform
+ * `.env` material and by platform services such as apps-manager at runtime.
+ * Keep these keys declarative and cross-executor: the contract owns names and
+ * sensitivity classification, while writers/readers own behavior.
+ */
+
+export enum PlatformProcessEnvKey {
+  HOST = 'HOST',
+  PORT = 'PORT',
+  SERVICE_NAME = 'SERVICE_NAME',
+  PLATFORM_ENVIRONMENT_ID = 'PLATFORM_ENVIRONMENT_ID',
+  APPLICATION_ENV = 'APPLICATION_ENV',
+  APPS_MANAGER_MODE = 'APPS_MANAGER_MODE',
+}
+
+export enum PlatformServiceUrlEnvKey {
+  PLATFORM_APPS_MANAGER_URL = 'PLATFORM_APPS_MANAGER_URL',
+  PLATFORM_FILE_GENERATOR_URL = 'PLATFORM_FILE_GENERATOR_URL',
+  PLATFORM_CRONTABS_BATCHES_MANAGER_URL = 'PLATFORM_CRONTABS_BATCHES_MANAGER_URL',
+}
+
+export enum PlatformInfrastructureEnvKey {
+  MONGO_CONNECT_URL = 'MONGO_CONNECT_URL',
+  MONGO_PLATFORM_URL = 'MONGO_PLATFORM_URL',
+  BASE_MONGO_SERVER_URL = 'BASE_MONGO_SERVER_URL',
+  REDIS_HOST = 'REDIS_HOST',
+  REDIS_PORT = 'REDIS_PORT',
+  REDIS_ADMIN_USER = 'REDIS_ADMIN_USER',
+  REDIS_ADMIN_PASSWORD = 'REDIS_ADMIN_PASSWORD',
+  RABBITMQ_HOST = 'RABBITMQ_HOST',
+  RABBITMQ_PORT = 'RABBITMQ_PORT',
+  RABBITMQ_MANAGEMENT_PORT = 'RABBITMQ_MANAGEMENT_PORT',
+  RABBITMQ_ADMIN_USERNAME = 'RABBITMQ_ADMIN_USERNAME',
+  RABBITMQ_ADMIN_PASSWORD = 'RABBITMQ_ADMIN_PASSWORD',
+  STORAGE_PROVIDER = 'STORAGE_PROVIDER',
+  STORAGE_ENDPOINT = 'STORAGE_ENDPOINT',
+  STORAGE_PORT = 'STORAGE_PORT',
+  STORAGE_USE_SSL = 'STORAGE_USE_SSL',
+  STORAGE_BUCKET = 'STORAGE_BUCKET',
+  STORAGE_ACCESS_KEY = 'STORAGE_ACCESS_KEY',
+  STORAGE_SECRET_KEY = 'STORAGE_SECRET_KEY',
+  GOTENBERG_URL = 'GOTENBERG_URL',
+  PG_HOST = 'PG_HOST',
+  PG_PORT = 'PG_PORT',
+  PG_ADMIN_USER = 'PG_ADMIN_USER',
+  PG_ADMIN_PASSWORD = 'PG_ADMIN_PASSWORD',
+  PG_ADMIN_DATABASE = 'PG_ADMIN_DATABASE',
+  PG_SSL_MODE = 'PG_SSL_MODE',
+}
+
+export enum PlatformSecurityEnvKey {
+  PLATFORM_APPS_MANAGER_PRIVATE_KEY = 'PLATFORM_APPS_MANAGER_PRIVATE_KEY',
+  PLATFORM_APPS_MANAGER_PUBLIC_KEY = 'PLATFORM_APPS_MANAGER_PUBLIC_KEY',
+  PLATFORM_APPLICATION_PRIMARY_SECRET = 'PLATFORM_APPLICATION_PRIMARY_SECRET',
+  PLATFORM_ADMIN_SECRET = 'PLATFORM_ADMIN_SECRET',
+}
+
+export enum PlatformAdminEnvKey {
+  ADMIN_EMAIL = 'ADMIN_EMAIL',
+  ADMIN_PASSWORD = 'ADMIN_PASSWORD',
+  ADMIN_FIRST_NAME = 'ADMIN_FIRST_NAME',
+  ADMIN_LAST_NAME = 'ADMIN_LAST_NAME',
+  GITHUB_WILDO_APPS_DEFAULT_ORG_URL = 'GITHUB_WILDO_APPS_DEFAULT_ORG_URL',
+  GITHUB_WILDO_APPS_ADMIN_USER = 'GITHUB_WILDO_APPS_ADMIN_USER',
+  GITHUB_WILDO_APPS_ADMIN_TOKEN = 'GITHUB_WILDO_APPS_ADMIN_TOKEN',
+  GITHUB_WILDO_APPS_ADMIN_SSH_SK = 'GITHUB_WILDO_APPS_ADMIN_SSH_SK',
+}
+
+export enum PlatformKubernetesEnvKey {
+  K8S_NAMESPACE = 'K8S_NAMESPACE',
+  K8S_EXTERNAL_BASE_DOMAIN = 'K8S_EXTERNAL_BASE_DOMAIN',
+  K8S_IMAGE_REGISTRY = 'K8S_IMAGE_REGISTRY',
+}
+
+export const PlatformProcessEnvKeys = PlatformProcessEnvKey;
+export const PlatformServiceUrlEnvKeys = PlatformServiceUrlEnvKey;
+export const PlatformInfrastructureEnvKeys = PlatformInfrastructureEnvKey;
+export const PlatformSecurityEnvKeys = PlatformSecurityEnvKey;
+export const PlatformAdminEnvKeys = PlatformAdminEnvKey;
+export const PlatformKubernetesEnvKeys = PlatformKubernetesEnvKey;
+
+export const PLATFORM_RUNTIME_SENSITIVE_ENV_KEYS = new Set<string>([
+  PlatformInfrastructureEnvKey.MONGO_CONNECT_URL,
+  PlatformInfrastructureEnvKey.MONGO_PLATFORM_URL,
+  PlatformInfrastructureEnvKey.REDIS_ADMIN_PASSWORD,
+  PlatformInfrastructureEnvKey.RABBITMQ_ADMIN_PASSWORD,
+  PlatformInfrastructureEnvKey.STORAGE_ACCESS_KEY,
+  PlatformInfrastructureEnvKey.STORAGE_SECRET_KEY,
+  PlatformInfrastructureEnvKey.PG_ADMIN_PASSWORD,
+  PlatformSecurityEnvKey.PLATFORM_APPS_MANAGER_PRIVATE_KEY,
+  PlatformSecurityEnvKey.PLATFORM_APPS_MANAGER_PUBLIC_KEY,
+  PlatformSecurityEnvKey.PLATFORM_APPLICATION_PRIMARY_SECRET,
+  PlatformSecurityEnvKey.PLATFORM_ADMIN_SECRET,
+  PlatformAdminEnvKey.ADMIN_PASSWORD,
+  PlatformAdminEnvKey.GITHUB_WILDO_APPS_ADMIN_TOKEN,
+]);

package/src/bootstrap/runtime-topology.contracts.ts

@@ -0,0 +1,102 @@
+import {
+  buildApplicationRuntimeEndpoints,
+  buildPlatformRuntimeEndpoints,
+  type RuntimeEndpointUrls,
+} from '@wildo-ai/platform-core-shared';
+import {
+  buildK8sInternalUrl,
+  buildK8sPublicUrl,
+} from '../project-config/shared/k8s-utils';
+import { PLATFORM_DEFAULT_PORTS } from '../project-config/shared/infrastructure-defaults.schemas';
+
+export {
+  buildApplicationRuntimeEndpoints,
+  buildPlatformRuntimeEndpoints,
+  parseRuntimeEndpointsRecord,
+  PlatformApplicationType,
+  PlatformRuntimeEndpointKey,
+  serializeRuntimeEndpointsRecord,
+} from '@wildo-ai/platform-core-shared';
+
+export type {
+  ApplicationRuntimeEndpointsInput,
+  PlatformRuntimeEndpointsInput,
+  RuntimeEndpointUrls,
+} from '@wildo-ai/platform-core-shared';
+
+export function buildLocalhostPlatformRuntimeEndpoints(
+  host: string = 'localhost',
+): Record<string, RuntimeEndpointUrls> {
+  const buildUrl = (port: number): RuntimeEndpointUrls => ({
+    publicUrl: `http://${host}:${port}`,
+    internalUrl: `http://${host}:${port}`,
+  });
+
+  return buildPlatformRuntimeEndpoints({
+    appsManager: buildUrl(PLATFORM_DEFAULT_PORTS.APPS_MANAGER),
+    crontabsBatchesManager: buildUrl(PLATFORM_DEFAULT_PORTS.CRONTABS_BATCHES_MANAGER),
+    fileGenerator: buildUrl(PLATFORM_DEFAULT_PORTS.FILE_GENERATOR),
+  });
+}
+
+export interface LocalhostApplicationRuntimeEndpointsInput {
+  mainBackendApiPort?: number | undefined;
+  frontendApplicationPorts?: Record<string, number> | undefined;
+  websitePort?: number | undefined;
+  technicalDocumentationPort?: number | undefined;
+  host?: string | undefined;
+}
+
+export function buildLocalhostApplicationRuntimeEndpoints(
+  input: LocalhostApplicationRuntimeEndpointsInput,
+): Record<string, RuntimeEndpointUrls> {
+  const host = input.host ?? 'localhost';
+  const buildUrl = (port: number): RuntimeEndpointUrls => ({
+    publicUrl: `http://${host}:${port}`,
+    internalUrl: `http://${host}:${port}`,
+  });
+
+  return buildApplicationRuntimeEndpoints({
+    frontendApplications: input.frontendApplicationPorts
+      ? Object.fromEntries(
+          Object.entries(input.frontendApplicationPorts).map(([frontendServiceName, port]) => [
+            frontendServiceName,
+            buildUrl(port),
+          ]),
+        )
+      : undefined,
+    ...(input.websitePort ? { website: buildUrl(input.websitePort) } : {}),
+    ...(input.technicalDocumentationPort
+      ? { technicalDocumentation: buildUrl(input.technicalDocumentationPort) }
+      : {}),
+    ...(input.mainBackendApiPort
+      ? {
+          mainBackendApi: buildUrl(input.mainBackendApiPort),
+          healthCheckApi: buildUrl(input.mainBackendApiPort - 1),
+          mainWebhookApi: buildUrl(input.mainBackendApiPort - 2),
+          oauth2ProviderApi: buildUrl(input.mainBackendApiPort - 3),
+          mcpApi: buildUrl(input.mainBackendApiPort - 4),
+        }
+      : {}),
+  });
+}
+
+export function buildK8sPlatformRuntimeEndpoints(input: {
+  baseDomain: string;
+  namespace: string;
+}): Record<string, RuntimeEndpointUrls> {
+  return buildPlatformRuntimeEndpoints({
+    appsManager: {
+      publicUrl: buildK8sPublicUrl('platform-apps-manager', input.baseDomain),
+      internalUrl: buildK8sInternalUrl('platform-apps-manager', PLATFORM_DEFAULT_PORTS.APPS_MANAGER, input.namespace),
+    },
+    crontabsBatchesManager: {
+      publicUrl: buildK8sPublicUrl('platform-crontabs-batches-manager', input.baseDomain),
+      internalUrl: buildK8sInternalUrl('platform-crontabs-batches-manager', PLATFORM_DEFAULT_PORTS.CRONTABS_BATCHES_MANAGER, input.namespace),
+    },
+    fileGenerator: {
+      publicUrl: buildK8sPublicUrl('platform-file-generator', input.baseDomain),
+      internalUrl: buildK8sInternalUrl('platform-file-generator', PLATFORM_DEFAULT_PORTS.FILE_GENERATOR, input.namespace),
+    },
+  });
+}