@wildo-ai/platform-config-lib 1.0.1

package/src/credentials/credential-generator.service.ts

@@ -0,0 +1,39 @@
+import { generateKeyPairSync, randomBytes } from 'crypto';
+
+const ALPHANUMERIC = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+const PASSWORD_CHARS = ALPHANUMERIC + '_+-';
+
+
+export class CredentialGenerator {
+
+  static generateECKeyPair(): { privateKey: string; publicKey: string } {
+    const { publicKey, privateKey } = generateKeyPairSync('ec', {
+      namedCurve: 'prime256v1',
+      publicKeyEncoding: { type: 'spki', format: 'pem' },
+      privateKeyEncoding: { type: 'sec1', format: 'pem' },
+    });
+    return { privateKey: privateKey.trim(), publicKey: publicKey.trim() };
+  }
+
+  static generatePassword(length: number = 24): string {
+    return this.generateFromCharset(length, PASSWORD_CHARS);
+  }
+
+  static generateSecret(length: number = 48): string {
+    return this.generateFromCharset(length, ALPHANUMERIC);
+  }
+
+  static generateErlangCookie(): string {
+    return this.generateFromCharset(32, ALPHANUMERIC);
+  }
+
+  static generateFromCharset(length: number, charset: string): string {
+    const bytes = randomBytes(length);
+    let result = '';
+    for (let i = 0; i < length; i++) {
+      result += charset[bytes[i] % charset.length];
+    }
+    return result;
+  }
+
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from './project-config';
+export * from './workspace-scope';
+export * from './credentials/credential-generator.service';
+
+export * from './schemas/platform-application-config.schemas';
+export * from './schemas/platform-application-secrets.schemas';
+export * from './schemas/platform-config.schemas';
+export * from './schemas/framework-info.schemas';
+export * from './schemas/framework-secrets.schemas';
+export * from './release/framework-release.constants';
+export * from './bootstrap/bootstrap.schemas';
+export * from './bootstrap/bootstrap.contracts';
+export * from './bootstrap/bootstrap-planner';
+export * from './bootstrap/application-backend-env.contracts';
+export * from './bootstrap/platform-runtime-env.contracts';
+export * from './bootstrap/runtime-topology.contracts';

package/src/project-config/__tests__/application-modules.utils.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getDeclaredApplicationModuleIds,
+  getServiceBoundApplicationModuleIds,
+  resolveDeclaredApplicationModules,
+  resolveServiceBoundApplicationModules,
+} from '../shared/application-modules.utils';
+
+describe('application module utilities', () => {
+  const modules = {
+    'tasks-manager': {
+      services: ['backendApi', 'app'],
+    },
+    'admin-tools': {
+      services: ['backendApi'],
+    },
+  };
+
+  it('lists declared module ids in declaration order', () => {
+    expect(getDeclaredApplicationModuleIds(modules)).toEqual(['tasks-manager', 'admin-tools']);
+  });
+
+  it('filters module ids by declared service key', () => {
+    expect(getServiceBoundApplicationModuleIds(modules, 'app')).toEqual(['tasks-manager']);
+    expect(getServiceBoundApplicationModuleIds(modules, 'backendApi')).toEqual([
+      'tasks-manager',
+      'admin-tools',
+    ]);
+  });
+
+  it('resolves declared modules against a local registry map', () => {
+    const declaredModulesById = {
+      'tasks-manager': 'shared.tasks',
+      'admin-tools': 'shared.admin',
+    };
+
+    expect(resolveDeclaredApplicationModules(modules, declaredModulesById, 'test consumer')).toEqual([
+      'shared.tasks',
+      'shared.admin',
+    ]);
+  });
+
+  it('fails when a declared module is missing from the local registry map', () => {
+    expect(() => resolveServiceBoundApplicationModules(
+      modules,
+      'backendApi',
+      { 'tasks-manager': 'backend.tasks' },
+      'backend service "backendApi"',
+    )).toThrow(
+      'Application modules [admin-tools] are declared for backend service "backendApi" in wildo.saas.config.ts but no matching implementation was registered.',
+    );
+  });
+});

package/src/project-config/__tests__/define-framework-config.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { defineFrameworkConfig } from '../define-framework-config';
+
+describe('defineFrameworkConfig', () => {
+  it('accepts the framework release contract', () => {
+    const parsed = defineFrameworkConfig({
+      version: 1,
+      frameworkVersion: '0.2.0',
+      minCliVersion: '0.2.0',
+      publish: {
+        npm: {
+          scope: '@wildo-ai',
+          packages: ['@wildo-ai/saas-models'],
+        },
+        docker: {
+          namespace: 'wildoai',
+          images: ['wildo-platform'],
+        },
+      },
+    });
+
+    expect(parsed.publish.npm.scope).toBe('@wildo-ai');
+    expect(parsed.publish.docker.namespace).toBe('wildoai');
+  });
+
+  it('rejects an invalid npm scope', () => {
+    expect(() => defineFrameworkConfig({
+      version: 1,
+      frameworkVersion: '0.2.0',
+      minCliVersion: '0.2.0',
+      publish: {
+        npm: {
+          scope: 'wildo-ai',
+          packages: [],
+        },
+        docker: {
+          namespace: 'wildoai',
+          images: [],
+        },
+      },
+    })).toThrow('npm scope must look like @scope or @scope/name');
+  });
+});

package/src/project-config/__tests__/define-saas-config.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from 'vitest';
+import { ExternalProvider_ExchangeProtocol_Kind } from '@wildo-ai/external-connectors-models';
+import { AppFrontendType } from '../shared/service-definitions.schemas';
+import { defineSaasConfig } from '../define-saas-config';
+
+describe('defineSaasConfig', () => {
+  it('accepts sparse external provider protocol maps', () => {
+    const parsed = defineSaasConfig({
+      version: 1,
+      name: 'wonder-todos',
+      slug: 'wonder-todos',
+      displayName: 'Wonder Todos',
+      type: 'saas',
+      services: {
+        app: {
+          path: './app',
+          serviceName: 'wonder-todos-app',
+          defaultPort: 4242,
+          frontendType: AppFrontendType.SAAS_APP,
+        },
+      },
+      externalProvidersConfigurations: {
+        anthropic: {
+          [ExternalProvider_ExchangeProtocol_Kind.CLI_RUNTIME]: {
+            enabled: true,
+            executionProfiles: {},
+          },
+        },
+      },
+      features: {
+        organizations: false,
+        billing: false,
+        multiLanguage: false,
+      },
+      bootstrap: {
+        firstAdmin: {
+          userTypes: ['member'],
+        },
+      },
+      dataServices: {
+        mongodb: {
+          databasePrefix: 'wonder-todos',
+        },
+        redis: {
+          keyPrefix: 'wonder-todos:',
+        },
+        rabbitmq: {
+          vhost: 'wonder-todos',
+        },
+        s3: {
+          bucketPrefix: 'wonder-todos',
+        },
+      },
+    });
+
+    expect(parsed.externalProvidersConfigurations.anthropic?.cli_runtime?.enabled).toBe(true);
+    expect(parsed.externalProvidersConfigurations.anthropic?.llm_provider).toBeUndefined();
+    expect(parsed.bootstrap?.firstAdmin?.userTypes).toEqual(['member']);
+  });
+
+  it('accepts module service bindings declared with service keys only', () => {
+    const parsed = defineSaasConfig({
+      version: 1,
+      name: 'wonder-todos',
+      slug: 'wonder-todos',
+      displayName: 'Wonder Todos',
+      type: 'saas',
+      services: {
+        backendApi: {
+          path: './backend-api',
+          serviceName: 'wonder-todos-backend-api',
+        },
+        app: {
+          path: './app',
+          serviceName: 'wonder-todos-app',
+          frontendType: AppFrontendType.SAAS_APP,
+        },
+      },
+      modules: {
+        'tasks-manager': {
+          services: ['backendApi', 'app'],
+        },
+      },
+      externalProvidersConfigurations: {},
+      features: {
+        organizations: false,
+        billing: false,
+        multiLanguage: false,
+      },
+      dataServices: {
+        mongodb: {
+          databasePrefix: 'wonder-todos',
+        },
+        redis: {
+          keyPrefix: 'wonder-todos:',
+        },
+        rabbitmq: {
+          vhost: 'wonder-todos',
+        },
+        s3: {
+          bucketPrefix: 'wonder-todos',
+        },
+      },
+    });
+
+    expect(parsed.modules?.['tasks-manager']?.services).toEqual(['backendApi', 'app']);
+  });
+
+  it('rejects module bindings that reference unknown services', () => {
+    try {
+      defineSaasConfig({
+        version: 1,
+        name: 'wonder-todos',
+        slug: 'wonder-todos',
+        displayName: 'Wonder Todos',
+        type: 'saas',
+        services: {
+          backendApi: {
+            path: './backend-api',
+            serviceName: 'wonder-todos-backend-api',
+          },
+        },
+        modules: {
+          'tasks-manager': {
+            services: ['backendApi', 'app'],
+          },
+        },
+        externalProvidersConfigurations: {},
+        features: {
+          organizations: false,
+          billing: false,
+          multiLanguage: false,
+        },
+        dataServices: {
+          mongodb: {
+            databasePrefix: 'wonder-todos',
+          },
+          redis: {
+            keyPrefix: 'wonder-todos:',
+          },
+          rabbitmq: {
+            vhost: 'wonder-todos',
+          },
+          s3: {
+            bucketPrefix: 'wonder-todos',
+          },
+        },
+      });
+      throw new Error('Expected defineSaasConfig to reject unknown service bindings.');
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toContain(
+        'Module \\"tasks-manager\\" references unknown service \\"app\\".',
+      );
+    }
+  });
+
+  it('rejects companion-only metadata on service declarations', () => {
+    try {
+      defineSaasConfig({
+        version: 1,
+        name: 'wonder-todos',
+        slug: 'wonder-todos',
+        displayName: 'Wonder Todos',
+        type: 'saas',
+        services: {
+          backendApi: {
+            path: './backend-api',
+            serviceName: 'wonder-todos-backend-api',
+            companionIntrospection: {
+              targets: {},
+              behaviors: {},
+            },
+          } as unknown as {
+            path: string;
+            serviceName: string;
+            defaultPort?: number | undefined;
+            frontendType?: AppFrontendType | undefined;
+          },
+        },
+        modules: {},
+        externalProvidersConfigurations: {},
+        features: {
+          organizations: false,
+          billing: false,
+          multiLanguage: false,
+        },
+        dataServices: {
+          mongodb: {
+            databasePrefix: 'wonder-todos',
+          },
+          redis: {
+            keyPrefix: 'wonder-todos:',
+          },
+          rabbitmq: {
+            vhost: 'wonder-todos',
+          },
+          s3: {
+            bucketPrefix: 'wonder-todos',
+          },
+        },
+      });
+      throw new Error('Expected defineSaasConfig to reject companion-only service metadata.');
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toContain('companionIntrospection');
+      expect((error as Error).message).toContain('unrecognized_keys');
+    }
+  });
+});

package/src/project-config/__tests__/loader.test.ts

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { ConfigArtifactsZone, WORKSPACE_CONFIG_NAMES } from '../../workspace-scope/workspace-scope.schemas';
+import { loadConfig, loadFrameworkConfig, loadPackageCompanionExport } from '../loader';
+
+const tempDirs: string[] = [];
+
+describe('loadConfig', () => {
+  afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('writes sibling platform config artifacts into the project-owned dist zone', async () => {
+    const sandboxRoot = mkdtempSync(join(tmpdir(), 'platform-config-lib-loader-'));
+    tempDirs.push(sandboxRoot);
+
+    const projectRoot = join(sandboxRoot, 'project');
+    const platformRoot = join(sandboxRoot, 'shared-platform', 'remotes', 'staging');
+    mkdirSync(projectRoot, { recursive: true });
+    mkdirSync(platformRoot, { recursive: true });
+
+    writeFileSync(join(projectRoot, WORKSPACE_CONFIG_NAMES.PROJECT), 'export default {};', 'utf8');
+    writeFileSync(
+      join(platformRoot, 'wildo.infra.staging.saas.config.ts'),
+      'export default { deployment: { branch: "staging" } };',
+      'utf8',
+    );
+
+    const config = await loadConfig<{ deployment: { branch: string } }>(
+      join(platformRoot, 'wildo.infra.staging.saas.config.ts'),
+      {
+        artifactLocation: {
+          zone: ConfigArtifactsZone.PLATFORM,
+          ownerRoot: projectRoot,
+        },
+      },
+    );
+
+    expect(config.deployment.branch).toBe('staging');
+    expect(existsSync(join(projectRoot, '.wildo-project', 'dist', 'config-loader', 'platform'))).toBe(true);
+    expect(existsSync(join(platformRoot, 'dist'))).toBe(false);
+    expect(existsSync(join(platformRoot, '.swc'))).toBe(false);
+  });
+
+  it('writes framework config artifacts into the framework-owned dist zone', async () => {
+    const sandboxRoot = mkdtempSync(join(tmpdir(), 'platform-config-lib-framework-loader-'));
+    tempDirs.push(sandboxRoot);
+
+    const frameworkRoot = join(sandboxRoot, 'wildo-ai');
+    const frameworkConfigRoot = join(frameworkRoot, WORKSPACE_CONFIG_NAMES.FRAMEWORK_DIR);
+    mkdirSync(frameworkConfigRoot, { recursive: true });
+
+    writeFileSync(join(frameworkRoot, 'wildo-framework.info.json'), '{"version":"0.2.0","minCliVersion":"0.2.0"}', 'utf8');
+    writeFileSync(
+      join(frameworkConfigRoot, 'wildo.framework.config.ts'),
+      [
+        "import { defineFrameworkConfig } from '@wildo-ai/platform-config-lib';",
+        'export default defineFrameworkConfig({',
+        "  frameworkVersion: '0.2.0',",
+        "  minCliVersion: '0.2.0',",
+        '  publish: {',
+        "    npm: { scope: '@wildo-ai', packages: [] },",
+        "    docker: { namespace: 'wildoai', images: [] },",
+        '  },',
+        '});',
+      ].join('\n'),
+      'utf8',
+    );
+
+    const config = await loadFrameworkConfig(frameworkRoot);
+
+    expect(config?.publish.npm.scope).toBe('@wildo-ai');
+    expect(existsSync(join(frameworkRoot, '.wildo-framework', 'dist', 'config-loader', 'framework'))).toBe(true);
+  });
+
+  it('loads a companion export from the source fallback when dist export is unavailable', async () => {
+    const sandboxRoot = mkdtempSync(join(tmpdir(), 'platform-config-lib-companion-loader-'));
+    tempDirs.push(sandboxRoot);
+
+    writeFileSync(
+      join(sandboxRoot, 'package.json'),
+      JSON.stringify({ name: '@test/app', type: 'module', exports: { './companion': { import: './dist/library/companion-exports.js' } } }, null, 2),
+      'utf8',
+    );
+    mkdirSync(join(sandboxRoot, 'src'), { recursive: true });
+    writeFileSync(
+      join(sandboxRoot, 'src', 'companion-exports.ts'),
+      'export default { designSystemConfig: { chartPalette: "rose,amber" } };',
+      'utf8',
+    );
+
+    const exports = await loadPackageCompanionExport<{ designSystemConfig: { chartPalette: string } }>(sandboxRoot);
+
+    expect(exports.designSystemConfig.chartPalette).toBe('rose,amber');
+  });
+});

package/src/project-config/define-framework-config.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import {
+  FRAMEWORK_RELEASE_DOCKER_NAMESPACE,
+  FRAMEWORK_RELEASE_NPM_SCOPE,
+} from '../release/framework-release.constants';
+
+const SimpleSemverSchema = z.string().regex(
+  /^\d+\.\d+\.\d+$/,
+  'must be a simple semver string in the form x.y.z',
+);
+
+export const WildoFrameworkReleaseNpmConfigSchema = z.object({
+  scope: z.literal(FRAMEWORK_RELEASE_NPM_SCOPE),
+  packages: z.array(z.string().min(1)).default([]),
+});
+export type WildoFrameworkReleaseNpmConfig = z.infer<typeof WildoFrameworkReleaseNpmConfigSchema>;
+
+export const WildoFrameworkReleaseDockerConfigSchema = z.object({
+  namespace: z.literal(FRAMEWORK_RELEASE_DOCKER_NAMESPACE),
+  images: z.array(z.string().min(1)).default([]),
+});
+export type WildoFrameworkReleaseDockerConfig = z.infer<typeof WildoFrameworkReleaseDockerConfigSchema>;
+
+export const WildoFrameworkConfigSchema = z.object({
+  version: z.number().int().positive().default(1),
+  frameworkVersion: SimpleSemverSchema,
+  minCliVersion: SimpleSemverSchema,
+  publish: z.object({
+    npm: WildoFrameworkReleaseNpmConfigSchema,
+    docker: WildoFrameworkReleaseDockerConfigSchema,
+  }),
+});
+export type WildoFrameworkConfig = z.infer<typeof WildoFrameworkConfigSchema>;
+export type WildoFrameworkConfigInput = z.input<typeof WildoFrameworkConfigSchema>;
+
+/**
+ * Define framework-scoped release configuration.
+ *
+ * This is the author-owned source of truth for framework release metadata that
+ * later materializes into `wildo-framework.info.json` and the CLI publish flow.
+ */
+export function defineFrameworkConfig(config: WildoFrameworkConfigInput): WildoFrameworkConfig {
+  return WildoFrameworkConfigSchema.parse(config);
+}

package/src/project-config/define-infra-config.ts

@@ -0,0 +1,168 @@
+import { z } from 'zod';
+import {
+  WildoEnvironmentIdSchema,
+  WildoDeploymentRuntime,
+  WildoDeploymentConfigSchema,
+  WildoImageTagStrategy,
+} from './shared/environment.schemas';
+
+// ============================================================================
+// Service Schemas — runtime-specific shapes
+// ============================================================================
+
+/**
+ * Addressing config for local or Docker Compose services.
+ * Describes how to reach a service (host, port, URL override).
+ */
+export const InfraServiceAddressingSchema = z.object({
+  host: z.string().optional(),
+  port: z.number().int().positive().optional(),
+  url: z.string().optional(),
+});
+export type InfraServiceAddressing = z.infer<typeof InfraServiceAddressingSchema>;
+
+/**
+ * Scaling config for Kubernetes-deployed services.
+ * Controls replica count per service in K8s Deployment manifests.
+ */
+export const InfraServiceK8sSchema = z.object({
+  replicas: z.number().int().positive().optional(),
+});
+export type InfraServiceK8s = z.infer<typeof InfraServiceK8sSchema>;
+
+/**
+ * Internal union schema for Zod parsing — accepts all fields,
+ * runtime validation in `superRefine` enforces per-runtime constraints.
+ */
+const InfraServiceSchema = z.object({
+  host: z.string().optional(),
+  port: z.number().int().positive().optional(),
+  url: z.string().optional(),
+  replicas: z.number().int().positive().optional(),
+});
+
+// ============================================================================
+// Infra Config Schema
+// ============================================================================
+
+export const WildoInfraConfigSchema = z.object({
+  version: z.number().int().positive().default(1),
+  environment: WildoEnvironmentIdSchema,
+
+  deployment: WildoDeploymentConfigSchema.optional(),
+
+  database: z.object({
+    name: z.string().min(1).optional(),
+    host: z.string().optional(),
+    port: z.number().int().positive().optional(),
+  }).optional(),
+
+  cache: z.object({
+    host: z.string().optional(),
+    port: z.number().int().positive().optional(),
+    database: z.number().int().nonnegative().optional(),
+  }).optional(),
+
+  queue: z.object({
+    host: z.string().optional(),
+    port: z.number().int().positive().optional(),
+    vhost: z.string().optional(),
+  }).optional(),
+
+  storage: z.object({
+    bucket: z.string().min(1).optional(),
+    endpoint: z.string().optional(),
+  }).optional(),
+
+  services: z.record(z.string(), InfraServiceSchema).optional(),
+  domain: z.string().optional(),
+}).superRefine((data, ctx) => {
+  const runtime = data.deployment?.runtime;
+  const services = data.services;
+  if (!services) return;
+
+  for (const [name, svc] of Object.entries(services)) {
+    if (runtime !== WildoDeploymentRuntime.KUBERNETES && svc.replicas !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['services', name, 'replicas'],
+        message: `"replicas" is only valid when deployment.runtime is "${WildoDeploymentRuntime.KUBERNETES}". Docker Compose always runs 1 container per service.`,
+      });
+    }
+
+    if (runtime === WildoDeploymentRuntime.KUBERNETES) {
+      if (svc.host !== undefined || svc.port !== undefined || svc.url !== undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['services', name],
+          message: `"host"/"port"/"url" are not used in Kubernetes runtime — service discovery handles addressing.`,
+        });
+      }
+    }
+  }
+});
+
+export type WildoInfraConfig = z.infer<typeof WildoInfraConfigSchema>;
+export type WildoInfraConfigInput = z.input<typeof WildoInfraConfigSchema>;
+
+// ============================================================================
+// Typed input interfaces for compile-time enforcement
+// ============================================================================
+
+interface InfraConfigBase {
+  version?: number;
+  environment: string;
+  database?: { name?: string; host?: string; port?: number };
+  cache?: { host?: string; port?: number; database?: number };
+  queue?: { host?: string; port?: number; vhost?: string };
+  storage?: { bucket?: string; endpoint?: string };
+  domain?: string;
+}
+
+/** Input shape when no deployment is configured (local environment). */
+interface InfraConfigLocal extends InfraConfigBase {
+  deployment?: undefined;
+  services?: Record<string, InfraServiceAddressing>;
+}
+
+/** Input shape for Docker Compose runtime. */
+interface InfraConfigDockerCompose extends InfraConfigBase {
+  deployment: {
+    branch: string;
+    runtime: WildoDeploymentRuntime.DOCKER_COMPOSE;
+    imageTagStrategy?: WildoImageTagStrategy | `${WildoImageTagStrategy}`;
+  };
+  services?: Record<string, InfraServiceAddressing>;
+}
+
+/** Input shape for Kubernetes runtime — services support `replicas`. */
+interface InfraConfigKubernetes extends InfraConfigBase {
+  deployment: {
+    branch: string;
+    runtime: WildoDeploymentRuntime.KUBERNETES;
+    registry?: string;
+    namespace?: string;
+    imageTagStrategy?: WildoImageTagStrategy | `${WildoImageTagStrategy}`;
+  };
+  services?: Record<string, InfraServiceK8s>;
+}
+
+/**
+ * Define per-environment infrastructure configuration for a SaaS app.
+ *
+ * The function is overloaded to enforce runtime-specific constraints at
+ * compile time:
+ * - **No deployment / Docker Compose**: services accept `host`, `port`, `url`
+ * - **Kubernetes**: services accept `replicas`
+ *
+ * Additional runtime validation via Zod `superRefine` catches mismatches
+ * that TypeScript inference might not catch (e.g., generic `WildoInfraConfigInput`).
+ */
+export function defineInfraConfig(config: InfraConfigLocal): WildoInfraConfig;
+export function defineInfraConfig(config: InfraConfigDockerCompose): WildoInfraConfig;
+export function defineInfraConfig(config: InfraConfigKubernetes): WildoInfraConfig;
+export function defineInfraConfig(
+  config: InfraConfigLocal | InfraConfigDockerCompose | InfraConfigKubernetes,
+): WildoInfraConfig {
+  return WildoInfraConfigSchema.parse(config as WildoInfraConfigInput);
+}