@wildo-ai/platform-config-lib 1.0.1

package/src/project-config/shared/application-modules.utils.ts

@@ -0,0 +1,65 @@
+import type { ApplicationModules } from './application-modules.schemas';
+
+function resolveModuleIds(
+  modules: ApplicationModules | undefined,
+  predicate: (serviceKeys: string[]) => boolean,
+): string[] {
+  return Object.entries(modules ?? {})
+    .filter(([, binding]) => predicate(binding.services))
+    .map(([moduleId]) => moduleId);
+}
+
+function pickApplicationModules<T>(
+  moduleIds: string[],
+  declaredModulesById: Record<string, T>,
+  consumerLabel: string,
+): T[] {
+  const missingModuleIds = moduleIds.filter((moduleId) => !(moduleId in declaredModulesById));
+
+  if (missingModuleIds.length > 0) {
+    throw new Error(
+      `Application modules [${missingModuleIds.join(', ')}] are declared for ${consumerLabel} ` +
+      'in wildo.saas.config.ts but no matching implementation was registered.',
+    );
+  }
+
+  return moduleIds.map((moduleId) => declaredModulesById[moduleId]!);
+}
+
+export function getDeclaredApplicationModuleIds(
+  modules: ApplicationModules | undefined,
+): string[] {
+  return resolveModuleIds(modules, () => true);
+}
+
+export function getServiceBoundApplicationModuleIds(
+  modules: ApplicationModules | undefined,
+  serviceKey: string,
+): string[] {
+  return resolveModuleIds(modules, (serviceKeys) => serviceKeys.includes(serviceKey));
+}
+
+export function resolveDeclaredApplicationModules<T>(
+  modules: ApplicationModules | undefined,
+  declaredModulesById: Record<string, T>,
+  consumerLabel: string,
+): T[] {
+  return pickApplicationModules(
+    getDeclaredApplicationModuleIds(modules),
+    declaredModulesById,
+    consumerLabel,
+  );
+}
+
+export function resolveServiceBoundApplicationModules<T>(
+  modules: ApplicationModules | undefined,
+  serviceKey: string,
+  declaredModulesById: Record<string, T>,
+  consumerLabel = `service "${serviceKey}"`,
+): T[] {
+  return pickApplicationModules(
+    getServiceBoundApplicationModuleIds(modules, serviceKey),
+    declaredModulesById,
+    consumerLabel,
+  );
+}

package/src/project-config/shared/backing-services.schemas.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+
+export enum BackingServiceKind {
+  MONGODB = 'mongodb',
+  REDIS = 'redis',
+  RABBITMQ = 'rabbitmq',
+  S3 = 's3',
+  POSTGRESQL = 'postgresql',
+  GOTENBERG = 'gotenberg',
+  CLAMAV = 'clamav',
+}
+
+/**
+ * Source of a backing service instance.
+ * - `self`: self-hosted container (Docker/K8s), managed by the platform
+ * - `atlas`: MongoDB Atlas (managed cloud)
+ * - `managed`: other managed cloud provider
+ */
+export enum BackingServiceSource {
+  SELF = 'self',
+  ATLAS = 'atlas',
+  MANAGED = 'managed',
+}
+
+export const BackingServiceToggleSchema = z.object({
+  enabled: z.boolean(),
+});
+export type BackingServiceToggle = z.infer<typeof BackingServiceToggleSchema>;
+
+export const BackingServiceEnvConfigSchema = z.object({
+  source: z.enum(BackingServiceSource),
+  provider: z.string().min(1).optional(),
+});
+export type BackingServiceEnvConfig = z.infer<typeof BackingServiceEnvConfigSchema>;
+
+/**
+ * Platform-level backing services declaration (which services are available).
+ * Used in `wildo.platform.config.ts`.
+ */
+export const BackingServicesDeclarationSchema = z.object({
+  [BackingServiceKind.MONGODB]: BackingServiceToggleSchema.optional(),
+  [BackingServiceKind.REDIS]: BackingServiceToggleSchema.optional(),
+  [BackingServiceKind.RABBITMQ]: BackingServiceToggleSchema.optional(),
+  [BackingServiceKind.S3]: BackingServiceToggleSchema.optional(),
+  [BackingServiceKind.POSTGRESQL]: BackingServiceToggleSchema.optional(),
+  [BackingServiceKind.GOTENBERG]: BackingServiceToggleSchema.optional(),
+  [BackingServiceKind.CLAMAV]: BackingServiceToggleSchema.optional(),
+});
+export type BackingServicesDeclaration = z.infer<typeof BackingServicesDeclarationSchema>;
+
+/**
+ * Per-environment backing services config (source for each service).
+ * Used in `wildo.platform.config.{env}.ts`.
+ */
+export const BackingServicesEnvConfigSchema = z.record(
+  z.enum(BackingServiceKind),
+  BackingServiceEnvConfigSchema,
+);
+export type BackingServicesEnvConfig = z.infer<typeof BackingServicesEnvConfigSchema>;

package/src/project-config/shared/data-services.schemas.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+
+const AppDatabaseBackedServiceSchema = z.object({
+  databasePrefix: z.string().min(1),
+});
+
+/**
+ * App-level data service configuration.
+ * Declares how the app uses each backing service (prefixes, vhosts, etc.).
+ * Used in `wildo.saas.config.ts`.
+ */
+export const AppDataServicesSchema = z.object({
+  mongodb: AppDatabaseBackedServiceSchema.optional(),
+  redis: z.object({
+    keyPrefix: z.string().min(1),
+  }).optional(),
+  rabbitmq: z.object({
+    vhost: z.string().min(1),
+  }).optional(),
+  s3: z.object({
+    bucketPrefix: z.string().min(1),
+  }).optional(),
+  postgresql: AppDatabaseBackedServiceSchema.optional(),
+});
+export type AppDataServices = z.infer<typeof AppDataServicesSchema>;
+
+/**
+ * Resolve the canonical application database name across supported database engines.
+ *
+ * Framework semantics treat the application database name as a cross-engine concept,
+ * not a MongoDB-only field. When multiple database engines are configured, they must
+ * agree on the same prefix or the runtime target would become ambiguous.
+ */
+export function deriveAppDatabaseName(
+  dataServices: AppDataServices | undefined,
+): string | undefined {
+  if (!dataServices) {
+    return undefined;
+  }
+
+  const configuredPrefixes = [
+    dataServices.mongodb?.databasePrefix,
+    dataServices.postgresql?.databasePrefix,
+  ].filter((value): value is string => value !== undefined);
+
+  const uniquePrefixes = [...new Set(configuredPrefixes)];
+  if (uniquePrefixes.length === 0) {
+    return undefined;
+  }
+
+  if (uniquePrefixes.length > 1) {
+    throw new Error(
+      `Application database prefixes must match across configured database engines. Received: ${uniquePrefixes.join(', ')}`,
+    );
+  }
+
+  return uniquePrefixes[0];
+}

package/src/project-config/shared/env-example-defaults.ts

@@ -0,0 +1,50 @@
+/**
+ * Default context values for the app-backend-env.example.hbs template.
+ * Provides fake/placeholder data derived from infrastructure defaults.
+ */
+
+import { INFRA_DEFAULT_PORTS, PLATFORM_DEFAULT_PORTS } from './infrastructure-defaults.schemas';
+
+export interface AppBackendEnvExampleContext {
+  APPLICATION_ID: string;
+  PLATFORM_APPLICATION_PRIMARY_SECRET: string;
+  PLATFORM_APPS_MANAGER_URL: string;
+  APPLICATION_ENV: string;
+  SERVICE_NAME: string;
+  PLATFORM_FILE_GENERATOR_URL: string;
+  PLATFORM_CRONTABS_BATCHES_MANAGER_URL: string;
+  MONGODB_HOST: string;
+  MONGODB_DATABASE: string;
+  MONGODB_PROTOCOL: string;
+  REDIS_HOST: string;
+  REDIS_PORT: number;
+  RABBITMQ_HOST: string;
+  RABBITMQ_PORT: number;
+}
+
+/**
+ * Build the default template context for the app backend .env example.
+ * All values are placeholder/local defaults — real values come from
+ * secrets.json + config.json via `wildo config sync`.
+ */
+export function buildAppBackendEnvExampleDefaults(
+  overrides?: Partial<AppBackendEnvExampleContext>,
+): AppBackendEnvExampleContext {
+  return {
+    APPLICATION_ID: 'your-app-id-from-platform',
+    PLATFORM_APPLICATION_PRIMARY_SECRET: 'your-super-secure-platform-secret-at-least-32-characters-long',
+    PLATFORM_APPS_MANAGER_URL: `http://localhost:${PLATFORM_DEFAULT_PORTS.APPS_MANAGER}`,
+    APPLICATION_ENV: 'development',
+    SERVICE_NAME: 'your-service-name',
+    PLATFORM_FILE_GENERATOR_URL: `http://localhost:${PLATFORM_DEFAULT_PORTS.FILE_GENERATOR}`,
+    PLATFORM_CRONTABS_BATCHES_MANAGER_URL: `http://localhost:${PLATFORM_DEFAULT_PORTS.CRONTABS_BATCHES_MANAGER}`,
+    MONGODB_HOST: `localhost:${INFRA_DEFAULT_PORTS.MONGODB}`,
+    MONGODB_DATABASE: 'wildo_app',
+    MONGODB_PROTOCOL: 'mongodb',
+    REDIS_HOST: 'localhost',
+    REDIS_PORT: INFRA_DEFAULT_PORTS.VALKEY,
+    RABBITMQ_HOST: 'localhost',
+    RABBITMQ_PORT: INFRA_DEFAULT_PORTS.RABBITMQ,
+    ...overrides,
+  };
+}

package/src/project-config/shared/environment.schemas.ts

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+
+/**
+ * Convenience environment ids kept for common local/staging/production setups.
+ *
+ * The project model is no longer limited to a fixed environment set: remote
+ * environment ids can be any slug-like value. Use `WildoEnvironmentIdSchema`
+ * for authoritative validation.
+ */
+export enum WildoEnvironment {
+  LOCAL = 'local',
+  STAGING = 'staging',
+  PRODUCTION = 'production',
+}
+
+export const WildoEnvironmentIdSchema = z
+  .string()
+  .min(1)
+  .regex(
+    /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+    'environment ids must be lowercase alphanumeric with optional hyphen-separated segments',
+  );
+export type WildoEnvironmentId = z.infer<typeof WildoEnvironmentIdSchema>;
+
+/**
+ * Deployment runtime targets for CI/CD workflows and infra config.
+ *
+ * Single source of truth for deployment runtime targets, used by both
+ * platform-config-lib (developer-facing config) and wildo-cli (operational).
+ */
+export enum WildoDeploymentRuntime {
+  DOCKER_COMPOSE = 'docker-compose',
+  KUBERNETES = 'kubernetes',
+}
+
+export enum WildoLocationType {
+  LOCAL = 'local',
+  REMOTE = 'remote',
+}
+
+export function isLocalEnvironmentId(environmentId: string): boolean {
+  return environmentId === WildoEnvironment.LOCAL;
+}
+
+export const WildoKubernetesConfigSchema = z.object({
+  namespace: z.string().min(1),
+  baseDomain: z.string().min(1),
+  ingressClass: z.string().min(1).optional(),
+});
+export type WildoKubernetesConfig = z.infer<typeof WildoKubernetesConfigSchema>;
+
+export const WildoRemoteProviderSchema = z.object({
+  provider: z.string().min(1),
+  registryEndpoint: z.string().min(1),
+  region: z.string().min(1).optional(),
+});
+export type WildoRemoteProvider = z.infer<typeof WildoRemoteProviderSchema>;
+
+export const WildoLoggingConfigSchema = z.object({
+  level: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  formattedConsoleErrors: z.boolean().optional(),
+});
+export type WildoLoggingConfig = z.infer<typeof WildoLoggingConfigSchema>;
+
+export enum DatabaseEngine {
+  MONGODB = 'mongodb',
+  POSTGRESQL = 'postgresql',
+}
+
+export enum WildoImageTagStrategy {
+  COMMIT_SHA = 'commit-sha',
+  BRANCH_NAME = 'branch-name',
+  SEMVER = 'semver',
+}
+
+/**
+ * Docker Compose deployment — no scaling, no K8s-specific fields.
+ */
+export const DockerComposeDeploymentSchema = z.object({
+  branch: z.string().min(1),
+  runtime: z.literal(WildoDeploymentRuntime.DOCKER_COMPOSE),
+  imageTagStrategy: z.enum(WildoImageTagStrategy).default(WildoImageTagStrategy.COMMIT_SHA),
+});
+
+/**
+ * Kubernetes deployment — includes registry, namespace, and scaling support.
+ */
+export const KubernetesDeploymentSchema = z.object({
+  branch: z.string().min(1),
+  runtime: z.literal(WildoDeploymentRuntime.KUBERNETES),
+  registry: z.string().min(1).optional(),
+  namespace: z.string().min(1).optional(),
+  imageTagStrategy: z.enum(WildoImageTagStrategy).default(WildoImageTagStrategy.COMMIT_SHA),
+});
+
+/**
+ * Deployment configuration for CI/CD pipeline integration.
+ * Discriminated on `runtime`: K8s-specific fields (`registry`, `namespace`)
+ * are only available when `runtime` is `KUBERNETES`.
+ */
+export const WildoDeploymentConfigSchema = z.discriminatedUnion('runtime', [
+  DockerComposeDeploymentSchema,
+  KubernetesDeploymentSchema,
+]);
+export type WildoDeploymentConfig = z.infer<typeof WildoDeploymentConfigSchema>;
+
+/**
+ * Canonical namespace derivation for platform-managed application resources.
+ *
+ * Environment ids are part of the namespace because local and arbitrary remote
+ * deployments must be isolated through generated names instead of hand-authored
+ * checked-in values.
+ */
+export function buildApplicationNamespace(
+  appSlug: string,
+  environmentId: string,
+): string {
+  const normalizedAppSlug = appSlug.trim();
+  const normalizedEnvironmentId = environmentId.trim();
+
+  if (!normalizedAppSlug) {
+    throw new Error('appSlug is required to derive an application namespace');
+  }
+  if (!normalizedEnvironmentId) {
+    throw new Error('environmentId is required to derive an application namespace');
+  }
+
+  return `${normalizedAppSlug}-${normalizedEnvironmentId}`;
+}
+
+export function buildApplicationDatabaseUsername(
+  appSlug: string,
+  environmentId: string,
+): string {
+  return `${buildApplicationNamespace(appSlug, environmentId)}_user`;
+}

package/src/project-config/shared/infrastructure-defaults.schemas.ts

@@ -0,0 +1,47 @@
+/**
+ * Infrastructure default ports and constants.
+ * Single source of truth — CLI catalogs, apps-manager env schemas,
+ * and generated manifests all derive from these values.
+ */
+
+export const INFRA_DEFAULT_PORTS = {
+  MONGODB: 27017,
+  VALKEY: 6379,
+  RABBITMQ: 5672,
+  RABBITMQ_MANAGEMENT: 15672,
+  MINIO: 9000,
+  POSTGRESQL: 5432,
+  GOTENBERG: 3100,
+  GOTENBERG_INTERNAL: 3000,
+} as const;
+
+export const PLATFORM_DEFAULT_PORTS = {
+  APPS_MANAGER: 5151,
+  CRONTABS_BATCHES_MANAGER: 5152,
+  FILE_GENERATOR: 5153,
+} as const;
+
+export const K8S_LOCAL_DEFAULTS = {
+  NAMESPACE: 'wildo-local',
+  BASE_DOMAIN: 'local.wildo.ai',
+} as const;
+
+export const KIND_CLUSTER_DEFAULTS = {
+  CLUSTER_NAME: 'dev',
+  KUBECTL_CONTEXT: 'kind-dev',
+  REGISTRY_NAME: 'kind-registry',
+  REGISTRY_PORT: 5001,
+} as const;
+
+export const STORAGE_DEFAULTS = {
+  BUCKET: 'wildo-files',
+  PROVIDER: 'minio',
+} as const;
+
+/**
+ * Platform MongoDB database name.
+ * This is the database used by apps-manager and platform services for
+ * all platform-scoped collections (wildoApplication, platformApplications, etc.).
+ * Aligned with PostgreSQL naming (`wildo_platform`).
+ */
+export const PLATFORM_MONGO_DATABASE = 'wildo_platform' as const;

package/src/project-config/shared/k8s-utils.ts

@@ -0,0 +1,56 @@
+/**
+ * Kubernetes URL builders and naming conventions.
+ * Single source of truth for constructing K8s-style addresses and resource names.
+ *
+ * Used by CLI (ServiceAddressResolver, K8s manifest gen) and apps-manager
+ * (application lifecycle) to ensure consistent URL/naming patterns.
+ */
+
+/**
+ * Builds a K8s cluster-internal URL: `http://<service>.<namespace>.svc.cluster.local:<port>`
+ */
+export function buildK8sInternalUrl(service: string, port: number, namespace: string): string {
+  return `http://${service}.${namespace}.svc.cluster.local:${port}`;
+}
+
+/**
+ * Builds a K8s cluster-internal hostname (without scheme/port).
+ */
+export function buildK8sInternalHost(service: string, namespace: string): string {
+  return `${service}.${namespace}.svc.cluster.local`;
+}
+
+/**
+ * Builds an ingress-based public URL: `https://<service>.<baseDomain>`
+ */
+export function buildK8sPublicUrl(service: string, baseDomain: string): string {
+  return `https://${service}.${baseDomain}`;
+}
+
+/**
+ * K8s Secret name for a platform service: `<service>-secret`
+ */
+export function k8sServiceSecretName(service: string): string {
+  return `${service}-secret`;
+}
+
+/**
+ * K8s ConfigMap name for a platform service: `<service>-config`
+ */
+export function k8sServiceConfigMapName(service: string): string {
+  return `${service}-config`;
+}
+
+/**
+ * K8s Secret name for an app backend: `app-<serviceName>-secret`
+ */
+export function k8sAppBackendSecretName(serviceName: string): string {
+  return `app-${serviceName}-secret`;
+}
+
+/**
+ * K8s ConfigMap name for an app backend: `app-<serviceName>-config`
+ */
+export function k8sAppBackendConfigMapName(serviceName: string): string {
+  return `app-${serviceName}-config`;
+}

package/src/project-config/shared/platform-services.schemas.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+/**
+ * Platform microservices. All use the same Docker image (wildo-platform)
+ * differentiated at runtime via PLATFORM_SERVICE env var.
+ *
+ * For app developers: deployed as Docker containers.
+ * For framework developers: run natively from source (hot-reload).
+ */
+export enum PlatformWildoServices {
+  PLATFORM_INIT = 'platform-init',
+  APPS_MANAGER = 'platform-apps-manager',
+  CRONTABS_BATCHES_MANAGER = 'platform-crontabs-batches-manager',
+  FILE_GENERATOR = 'platform-file-generator',
+}
+
+export enum AppsManagerMode {
+  NORMAL = 'normal',
+  INIT = 'init',
+  MAINT = 'maint',
+}
+
+export const PlatformServiceConfigSchema = z.object({
+  serviceName: z.string().min(1),
+  enabled: z.boolean().default(true),
+});
+export type PlatformServiceConfig = z.infer<typeof PlatformServiceConfigSchema>;
+
+export const PlatformServicesDeclarationSchema = z.record(
+  z.string(),
+  PlatformServiceConfigSchema,
+);
+export type PlatformServicesDeclaration = z.infer<typeof PlatformServicesDeclarationSchema>;

package/src/project-config/shared/service-definitions.schemas.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+
+export enum AppFrontendType {
+  SAAS_APP = 'saas-app',
+  STATIC_WEBSITE = 'static-website',
+}
+
+export const AppServiceDefinitionSchema = z.object({
+  path: z.string().min(1),
+  serviceName: z.string().min(1),
+  defaultPort: z.number().int().positive().optional(),
+  frontendType: z.enum(AppFrontendType).optional(),
+}).strict()
+export type AppServiceDefinition = z.infer<typeof AppServiceDefinitionSchema>;
+
+export const WorkerRuntimeSchema = z.object({
+  type: z.string().min(1),
+  language: z.string().min(1),
+});
+export type WorkerRuntime = z.infer<typeof WorkerRuntimeSchema>;
+
+export const ResourceLimitsSchema = z.object({
+  cpu: z.string().min(1).optional(),
+  memory: z.string().min(1).optional(),
+});
+export type ResourceLimits = z.infer<typeof ResourceLimitsSchema>;
+
+export const DataAccessSchema = z.object({
+  database: z.enum(['read-only', 'read-write', 'none']).optional(),
+  cache: z.boolean().optional(),
+  queue: z.enum(['consumer', 'producer', 'both', 'none']).optional(),
+});
+export type DataAccess = z.infer<typeof DataAccessSchema>;
+
+export const AppRefSchema = z.object({
+  path: z.string().min(1),
+});
+export type AppRef = z.infer<typeof AppRefSchema>;