@celilo/cli 0.1.0

package/src/variables/declarative-derivation.test.ts

@@ -0,0 +1,743 @@
+import { describe, expect, test } from 'bun:test';
+import type { ModuleManifest, VariableDeclare } from '../manifest/schema';
+import {
+  applyDeclarativeDerivations,
+  resolveDeclarativeDerivation,
+} from './declarative-derivation';
+import type { ResolutionContext } from './types';
+
+describe('resolveDeclarativeDerivation', () => {
+  describe('system config references', () => {
+    test('resolves $system:key pattern', () => {
+      const variable: VariableDeclare = {
+        name: 'primary_domain',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: '$system:primary_domain',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: { primary_domain: 'example.com' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      const result = resolveDeclarativeDerivation(variable, context);
+      expect(result).toBe('example.com');
+    });
+
+    test('resolves nested system config with dots', () => {
+      const variable: VariableDeclare = {
+        name: 'dmz_subnet',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: '$system:network.dmz.subnet',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: { 'network.dmz.subnet': '10.0.10.0/24' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      const result = resolveDeclarativeDerivation(variable, context);
+      expect(result).toBe('10.0.10.0/24');
+    });
+
+    test('throws on missing system config', () => {
+      const variable: VariableDeclare = {
+        name: 'primary_domain',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: '$system:primary_domain',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      expect(() => resolveDeclarativeDerivation(variable, context)).toThrow(
+        "Missing system config: primary_domain (required by variable 'primary_domain')",
+      );
+    });
+  });
+
+  describe('variable interpolation', () => {
+    test('resolves {variable} pattern', () => {
+      const variable: VariableDeclare = {
+        name: 'vps_hostname',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: '{hostname}.example.com',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: { hostname: 'dns-ext' },
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      const result = resolveDeclarativeDerivation(variable, context);
+      expect(result).toBe('dns-ext.example.com');
+    });
+
+    test('resolves multiple variable interpolations', () => {
+      const variable: VariableDeclare = {
+        name: 'vps_hostname',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: '{hostname}.{primary_domain}',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: { hostname: 'dns-ext', primary_domain: 'example.com' },
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      const result = resolveDeclarativeDerivation(variable, context);
+      expect(result).toBe('dns-ext.example.com');
+    });
+
+    test('throws on missing variable', () => {
+      const variable: VariableDeclare = {
+        name: 'vps_hostname',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: '{hostname}.{primary_domain}',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: { hostname: 'dns-ext' }, // missing primary_domain
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      expect(() => resolveDeclarativeDerivation(variable, context)).toThrow(
+        "Missing variable: primary_domain (required by variable 'vps_hostname')",
+      );
+    });
+  });
+
+  describe('capability references', () => {
+    test('resolves $capability:name.path pattern', () => {
+      const variable: VariableDeclare = {
+        name: 'dns_server_ip',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: '$capability:dns_external.server.ip',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {
+          dns_external: {
+            server: {
+              ip: '188.166.157.2',
+            },
+          },
+        },
+      };
+
+      const result = resolveDeclarativeDerivation(variable, context);
+      expect(result).toBe('188.166.157.2');
+    });
+
+    test('resolves nested capability path', () => {
+      const variable: VariableDeclare = {
+        name: 'dns_primary',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: '$capability:dns_external.server.ip.primary',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {
+          dns_external: {
+            server: {
+              ip: {
+                primary: '188.166.157.2',
+                secondary: '188.166.157.3',
+              },
+            },
+          },
+        },
+      };
+
+      const result = resolveDeclarativeDerivation(variable, context);
+      expect(result).toBe('188.166.157.2');
+    });
+
+    test('throws on missing capability', () => {
+      const variable: VariableDeclare = {
+        name: 'dns_server_ip',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: '$capability:dns_external.server.ip',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      expect(() => resolveDeclarativeDerivation(variable, context)).toThrow(
+        "Missing capability: dns_external (required by variable 'dns_server_ip')",
+      );
+    });
+
+    test('throws on missing capability field', () => {
+      const variable: VariableDeclare = {
+        name: 'dns_server_ip',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: '$capability:dns_external.server.ip',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {
+          dns_external: {
+            server: {}, // missing ip field
+          },
+        },
+      };
+
+      expect(() => resolveDeclarativeDerivation(variable, context)).toThrow(
+        "Missing capability field: dns_external.server.ip (required by variable 'dns_server_ip')",
+      );
+    });
+  });
+
+  describe('nested variable resolution', () => {
+    test('resolves $system: references within capability values', () => {
+      const variable: VariableDeclare = {
+        name: 'auth_url',
+        type: 'string',
+        required: false,
+        source: 'capability',
+        derive_from: '$capability:idp.auth_url',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: { primary_domain: 'example.com' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {
+          idp: {
+            auth_url: 'https://auth.${system:primary_domain}',
+          },
+        },
+      };
+
+      const result = resolveDeclarativeDerivation(variable, context);
+      expect(result).toBe('https://auth.example.com');
+    });
+
+    test('resolves $system: references (unbraced) within capability values', () => {
+      const variable: VariableDeclare = {
+        name: 'api_url',
+        type: 'string',
+        required: false,
+        source: 'capability',
+        derive_from: '$capability:idp.api_url',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: { primary_domain: 'example.com' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {
+          idp: {
+            api_url: 'https://auth.$system:primary_domain/api',
+          },
+        },
+      };
+
+      const result = resolveDeclarativeDerivation(variable, context);
+      expect(result).toBe('https://auth.example.com/api');
+    });
+  });
+
+  describe('mixed patterns', () => {
+    test('combines system config and variable interpolation', () => {
+      const variable: VariableDeclare = {
+        name: 'full_url',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: 'https://{hostname}.$system:primary_domain',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: { hostname: 'www' },
+        systemConfig: { primary_domain: 'example.com' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      const result = resolveDeclarativeDerivation(variable, context);
+      expect(result).toBe('https://www.example.com');
+    });
+
+    test('combines all three pattern types', () => {
+      const variable: VariableDeclare = {
+        name: 'acme_dns',
+        type: 'string',
+        required: false,
+        source: 'user',
+        derive_from: '{hostname}.$system:primary_domain@$capability:dns_external.server.ip',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: { hostname: 'caddy' },
+        systemConfig: { primary_domain: 'example.com' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {
+          dns_external: {
+            server: { ip: '188.166.157.2' },
+          },
+        },
+      };
+
+      const result = resolveDeclarativeDerivation(variable, context);
+      expect(result).toBe('caddy.example.com@188.166.157.2');
+    });
+  });
+
+  describe('no derivation', () => {
+    test('returns undefined when derive_from is not set', () => {
+      const variable: VariableDeclare = {
+        name: 'hostname',
+        type: 'string',
+        required: false,
+        source: 'user',
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      const result = resolveDeclarativeDerivation(variable, context);
+      expect(result).toBeUndefined();
+    });
+  });
+});
+
+describe('applyDeclarativeDerivations', () => {
+  describe('basic derivations', () => {
+    test('applies single derivation', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'primary_domain',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: '$system:primary_domain',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: { primary_domain: 'example.com' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      expect(context.selfConfig.primary_domain).toBe('example.com');
+    });
+
+    test('applies multiple derivations in order', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'primary_domain',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: '$system:primary_domain',
+            },
+            {
+              name: 'vps_hostname',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: '{hostname}.{primary_domain}',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: { hostname: 'dns-ext' },
+        systemConfig: { primary_domain: 'example.com' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      expect(context.selfConfig.primary_domain).toBe('example.com');
+      expect(context.selfConfig.vps_hostname).toBe('dns-ext.example.com');
+    });
+  });
+
+  describe('user config precedence', () => {
+    test('does not overwrite user-provided values', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'primary_domain',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: '$system:primary_domain',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: { primary_domain: 'custom.com' }, // User provided
+        systemConfig: { primary_domain: 'example.com' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      // Should keep user value
+      expect(context.selfConfig.primary_domain).toBe('custom.com');
+    });
+  });
+
+  describe('dependency resolution', () => {
+    test('resolves dependencies in declaration order', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            // First: derive primary_domain from system
+            {
+              name: 'primary_domain',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: '$system:primary_domain',
+            },
+            // Second: derive vps_hostname using primary_domain
+            {
+              name: 'vps_hostname',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: '{hostname}.{primary_domain}',
+            },
+            // Third: derive full_url using vps_hostname
+            {
+              name: 'full_url',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: 'https://{vps_hostname}',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: { hostname: 'dns-ext' },
+        systemConfig: { primary_domain: 'example.com' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      expect(context.selfConfig.primary_domain).toBe('example.com');
+      expect(context.selfConfig.vps_hostname).toBe('dns-ext.example.com');
+      expect(context.selfConfig.full_url).toBe('https://dns-ext.example.com');
+    });
+  });
+
+  describe('error handling', () => {
+    test('throws error for required variable with missing dependency', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'primary_domain',
+              type: 'string',
+              required: true, // Required!
+              source: 'user',
+              derive_from: '$system:primary_domain',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {}, // Missing primary_domain
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      expect(() => applyDeclarativeDerivations(manifest, context)).toThrow(
+        "Missing system config: primary_domain (required by variable 'primary_domain')",
+      );
+    });
+
+    test('silently skips optional variable with missing dependency', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'primary_domain',
+              type: 'string',
+              required: false, // Optional
+              source: 'user',
+              derive_from: '$system:primary_domain',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {}, // Missing primary_domain
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      // Should not throw
+      applyDeclarativeDerivations(manifest, context);
+
+      // Variable remains unset
+      expect(context.selfConfig.primary_domain).toBeUndefined();
+    });
+
+    test('skips non-string types (handled by config interview instead)', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'port',
+              type: 'number',
+              required: false,
+              source: 'user',
+              derive_from: '$system:port',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: { port: '8080' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      // Non-string variable is skipped — port remains unset
+      expect(context.selfConfig.port).toBeUndefined();
+    });
+  });
+
+  describe('skips', () => {
+    test('skips variables without derive_from', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'hostname',
+              type: 'string',
+              required: true,
+              source: 'user',
+              // No derive_from
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      // Should not throw or modify context
+      applyDeclarativeDerivations(manifest, context);
+
+      expect(context.selfConfig.hostname).toBeUndefined();
+    });
+
+    test('handles manifest with no variables', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: { owns: [], imports: [] },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      // Should not throw
+      applyDeclarativeDerivations(manifest, context);
+
+      expect(context.selfConfig).toEqual({});
+    });
+  });
+});