@celilo/cli 0.1.4 → 0.1.6

package/src/variables/context.ts

@@ -15,6 +15,7 @@ import type { ModuleManifest } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { applyDeclarativeDerivations } from './declarative-derivation';
+import { applyIndex, parsePath } from './parser';
 import type { ResolutionContext } from './types';
 
 /**
@@ -92,7 +93,7 @@ async function autoAssignFromWellKnown(
  * Policy function - checks manifest and config
  *
  * A module needs IPAM if:
- * 1. It declares vmid and container_ip variables (container-based), AND
+ * 1. It declares vmid and target_ip variables (container-based), AND
  * 2. These values are not already set in module config
  *
  * @param manifest - Module manifest
@@ -106,16 +107,16 @@ function needsIpamAllocation(
   const variables = manifest.variables?.owns ?? [];
 
   const hasVmid = variables.some((v) => v.name === 'vmid');
-  const hasContainerIp = variables.some((v) => v.name === 'container_ip');
+  const hasTargetIp = variables.some((v) => v.name === 'target_ip');
 
-  // Module must declare both vmid and container_ip to be container-based
-  if (!hasVmid || !hasContainerIp) {
+  // Module must declare both vmid and target_ip to be container-based
+  if (!hasVmid || !hasTargetIp) {
     return false;
   }
 
   // Check if already allocated (both must be present)
   const vmidSet = selfConfig.vmid !== undefined && selfConfig.vmid !== '';
-  const ipSet = selfConfig.container_ip !== undefined && selfConfig.container_ip !== '';
+  const ipSet = selfConfig.target_ip !== undefined && selfConfig.target_ip !== '';
 
   // Need allocation if either is missing
   return !vmidSet || !ipSet;
@@ -162,7 +163,7 @@ function determineModuleZone(
  *
  * These variables are automatically available in Ansible templates:
  * - inventory.hostname: Derived from hostname variable
- * - inventory.ansible_host: Derived from container_ip (strips CIDR) or vps_ip
+ * - inventory.ansible_host: Derived from target_ip (strips CIDR) or vps_ip
  * - inventory.ansible_user: Defaults to "root"
  * - inventory.groups: Derived from module ID
  *
@@ -181,9 +182,9 @@ function autoDeriveInventoryVariables(
     derived['inventory.hostname'] = selfConfig.hostname;
   }
 
-  // Auto-derive ansible_host from container_ip (strips CIDR) or vps_ip
-  if (selfConfig.container_ip) {
-    derived['inventory.ansible_host'] = stripCidr(selfConfig.container_ip);
+  // Auto-derive ansible_host from target_ip (strips CIDR) or vps_ip
+  if (selfConfig.target_ip) {
+    derived['inventory.ansible_host'] = stripCidr(selfConfig.target_ip);
   } else if (selfConfig.vps_ip) {
     // VPS-based modules use vps_ip directly (no CIDR to strip)
     derived['inventory.ansible_host'] = selfConfig.vps_ip;
@@ -202,6 +203,34 @@ function autoDeriveInventoryVariables(
   return derived;
 }
 
+/**
+ * Recursively resolve "$self:key" strings in a capability data object
+ * using the provider module's actual config values. Supports the
+ * optional `[N]` array-index suffix (e.g. `$self:domains[0]`) so a
+ * provider can declare computed aliases — `primary_domain:
+ * $self:domains[0]` — without the framework storing the alias as a
+ * separate value. Non-string values and strings that don't start
+ * with "$self:" are returned unchanged.
+ */
+function resolveSelfRefsInObject(
+  obj: Record<string, unknown>,
+  providerConfig: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (typeof value === 'string' && value.startsWith('$self:')) {
+      const { name, index } = parsePath(value.slice(6));
+      const resolved = applyIndex(providerConfig[name], index);
+      result[key] = resolved !== undefined ? resolved : value;
+    } else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      result[key] = resolveSelfRefsInObject(value as Record<string, unknown>, providerConfig);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 /**
  * Build resolution context for a module
  *
@@ -329,7 +358,7 @@ export async function buildResolutionContext(
   }
 
   // IPAM auto-allocation
-  // If module declares vmid/container_ip but they're not configured, allocate automatically
+  // If module declares vmid/target_ip but they're not configured, allocate automatically
   if (module?.manifestData) {
     const manifest = module.manifestData as ModuleManifest;
 
@@ -342,17 +371,17 @@ export async function buildResolutionContext(
         const existing = await getAllocation(moduleId, tx);
 
         let vmid: number;
-        let containerIp: string;
+        let allocatedIp: string;
 
         if (existing) {
           // Use existing allocation
           vmid = existing.vmid;
-          containerIp = existing.containerIp;
+          allocatedIp = existing.containerIp;
         } else {
           // Allocate new resources (persists to ipAllocations)
           const allocation = await allocateResources(moduleId, zone, tx);
           vmid = allocation.vmid;
-          containerIp = allocation.containerIp;
+          allocatedIp = allocation.containerIp;
         }
 
         // Ensure values are in module config (upsert to handle existing keys)
@@ -366,15 +395,15 @@ export async function buildResolutionContext(
 
         await tx
           .insert(moduleConfigs)
-          .values({ moduleId, key: 'container_ip', value: containerIp })
+          .values({ moduleId, key: 'target_ip', value: allocatedIp })
           .onConflictDoUpdate({
             target: [moduleConfigs.moduleId, moduleConfigs.key],
-            set: { value: containerIp },
+            set: { value: allocatedIp },
           });
 
         // Update selfConfig with allocated values
         selfConfig.vmid = String(vmid);
-        selfConfig.container_ip = containerIp;
+        selfConfig.target_ip = allocatedIp;
       });
     }
   }
@@ -418,7 +447,26 @@ export async function buildResolutionContext(
     } else {
       data = row.data;
     }
-    capabilitiesMap[row.capabilityName] = data as Record<string, unknown>;
+
+    // Lazily resolve $self: references in capability data using the provider
+    // module's actual config values. Capability data is stored with unresolved
+    // $self: references (e.g. namecheap stores primary_domain: "$self:primary_domain")
+    // because the real value isn't known at import time. We resolve them here so
+    // consuming modules see the actual values (e.g. "iamtheinternet.org") rather
+    // than the raw template strings.
+    const providerConfigs = db
+      .select()
+      .from(moduleConfigs)
+      .where(eq(moduleConfigs.moduleId, row.moduleId))
+      .all();
+    const providerConfigMap: Record<string, unknown> = {};
+    for (const c of providerConfigs) {
+      providerConfigMap[c.key] = c.valueJson ? JSON.parse(c.valueJson) : c.value;
+    }
+    capabilitiesMap[row.capabilityName] = resolveSelfRefsInObject(
+      data as Record<string, unknown>,
+      providerConfigMap,
+    );
   }
 
   // Fetch system configuration (for $system: variables)

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

@@ -676,6 +676,312 @@ describe('applyDeclarativeDerivations', () => {
     });
   });
 
+  describe('capability data with unresolved $self: refs', () => {
+    // This is the real-world scenario: namecheap's dns_registrar capability is stored
+    // in the DB with raw {primary_domain: "$self:primary_domain"} by buildCapabilityData.
+    // When lunacycle's primary_domain derives from $capability:dns_registrar.primary_domain,
+    // it receives the string "$self:primary_domain" — which can't be resolved in lunacycle's
+    // context. The key must remain unset rather than being poisoned with the raw template.
+    test('does not set selfConfig when capability value still contains $self: ref', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'lunacycle',
+        name: 'Lunacycle',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'primary_domain',
+              type: 'string',
+              required: false,
+              source: 'capability',
+              derive_from: '$capability:dns_registrar.primary_domain',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'lunacycle',
+        selfConfig: {}, // primary_domain not set yet
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {
+          // Raw capability data as stored by buildCapabilityData — $self: unresolved
+          dns_registrar: { primary_domain: '$self:primary_domain' },
+        },
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      // Must NOT be set to '$self:primary_domain' — that poisons downstream code
+      expect(context.selfConfig.primary_domain).toBeUndefined();
+    });
+
+    test('uses existing selfConfig value when capability returns unresolved $self: ref', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'lunacycle',
+        name: 'Lunacycle',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'primary_domain',
+              type: 'string',
+              required: false,
+              source: 'capability',
+              derive_from: '$capability:dns_registrar.primary_domain',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'lunacycle',
+        selfConfig: { primary_domain: 'iamtheinternet.org' }, // Previously resolved value
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {
+          dns_registrar: { primary_domain: '$self:primary_domain' }, // Raw, unresolved
+        },
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      // Should keep the existing resolved value
+      expect(context.selfConfig.primary_domain).toBe('iamtheinternet.org');
+    });
+  });
+
+  describe('capability data with unresolved $secret: refs', () => {
+    // $secret: is not handled by substituteVariables (only $system:, {var}, $capability:
+    // are resolved). So if a capability stores "$secret:api_key", it passes through
+    // all 5 resolution passes unchanged and must be skipped.
+    test('does not set selfConfig when capability value contains $secret: ref', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'consumer',
+        name: 'Consumer',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'api_key',
+              type: 'string',
+              required: false,
+              source: 'capability',
+              derive_from: '$capability:provider.api_key',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'consumer',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {
+          provider: { api_key: '$secret:provider_api_key' },
+        },
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      expect(context.selfConfig.api_key).toBeUndefined();
+    });
+  });
+
+  describe('two-level resolution via capability', () => {
+    // Capability data contains $system: refs — the multi-pass loop in
+    // resolveDeclarativeDerivation resolves them. This tests applyDeclarativeDerivations
+    // end-to-end, not just resolveDeclarativeDerivation in isolation.
+    test('resolves $system: ref inside capability value', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'caddy',
+        name: 'Caddy',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'auth_url',
+              type: 'string',
+              required: false,
+              source: 'capability',
+              derive_from: '$capability:idp.auth_url',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'caddy',
+        selfConfig: {},
+        systemConfig: { primary_domain: 'example.com' },
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {
+          // Capability data uses $system: — this CAN be resolved in the consumer's context
+          idp: { auth_url: 'https://auth.$system:primary_domain' },
+        },
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      expect(context.selfConfig.auth_url).toBe('https://auth.example.com');
+    });
+  });
+
+  describe('circular variable references', () => {
+    // Both optional variables reference each other — each throws "Missing variable"
+    // on first pass (the other isn't set yet). Both should remain unset.
+    test('silently skips both optional variables in a circular reference', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'foo',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: '{bar}',
+            },
+            {
+              name: 'bar',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: '{foo}',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      expect(context.selfConfig.foo).toBeUndefined();
+      expect(context.selfConfig.bar).toBeUndefined();
+    });
+
+    test('throws when either circular variable is required', () => {
+      const manifest: ModuleManifest = {
+        celilo_contract: '1.0',
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        requires: { capabilities: [] },
+        provides: { capabilities: [] },
+        variables: {
+          owns: [
+            {
+              name: 'foo',
+              type: 'string',
+              required: true, // Required — must throw
+              source: 'user',
+              derive_from: '{bar}',
+            },
+            {
+              name: 'bar',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: '{foo}',
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: {},
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      expect(() => applyDeclarativeDerivations(manifest, context)).toThrow(
+        "Missing variable: bar (required by variable 'foo')",
+      );
+    });
+  });
+
+  describe('$self: directly in derive_from', () => {
+    // $self: in derive_from is a manifest authoring error — substituteVariables
+    // does not handle $self:, so it passes through all resolution passes unchanged.
+    // The hasUnresolved check must prevent it from poisoning selfConfig.
+    test('does not set selfConfig when derive_from contains $self: directly', () => {
+      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_copy',
+              type: 'string',
+              required: false,
+              source: 'user',
+              derive_from: '$self:hostname', // Wrong syntax — $self: is not supported in derive_from
+            },
+          ],
+          imports: [],
+        },
+      };
+
+      const context: ResolutionContext = {
+        moduleId: 'test-module',
+        selfConfig: { hostname: 'my-host' },
+        systemConfig: {},
+        systemSecrets: {},
+        secrets: {},
+        capabilities: {},
+      };
+
+      applyDeclarativeDerivations(manifest, context);
+
+      // $self: passes through unresolved; must not poison selfConfig
+      expect(context.selfConfig.hostname_copy).toBeUndefined();
+    });
+  });
+
   describe('skips', () => {
     test('skips variables without derive_from', () => {
       const manifest: ModuleManifest = {

package/src/variables/declarative-derivation.ts

@@ -182,8 +182,10 @@ export function applyDeclarativeDerivations(
           derived.includes('$system:') ||
           derived.includes('$capability:') ||
           derived.includes('$secret:');
-        if (hasUnresolved && context.selfConfig[variable.name] !== undefined) {
-          // Keep the existing (user-set or previously-resolved) value
+        if (hasUnresolved) {
+          // Don't store a value that still contains unresolved template refs.
+          // This happens when a capability's data contains $self: refs that
+          // resolve in the provider's context, not the consumer's.
           continue;
         }
         context.selfConfig[variable.name] = derived;

package/src/variables/parser.test.ts

@@ -1,16 +1,22 @@
 import { describe, expect, test } from 'bun:test';
-import { hasVariables, isValidVariableFormat, parseVariables } from './parser';
+import {
+  applyIndex,
+  hasVariables,
+  isValidVariableFormat,
+  parsePath,
+  parseVariables,
+} from './parser';
 
 describe('parseVariables', () => {
   test('should parse self variables', () => {
-    const content = 'ip: $self:container_ip';
+    const content = 'ip: $self:target_ip';
     const variables = parseVariables(content);
 
     expect(variables).toHaveLength(1);
     expect(variables[0]).toEqual({
       type: 'self',
-      path: 'container_ip',
-      raw: '$self:container_ip',
+      path: 'target_ip',
+      raw: '$self:target_ip',
     });
   });
 
@@ -52,7 +58,7 @@ describe('parseVariables', () => {
 
   test('should parse multiple variables in same content', () => {
     const content = `
-      ip: $self:container_ip
+      ip: $self:target_ip
       dns: $capability:dns_external.nameserver
       key: $secret:api_key
     `;
@@ -101,7 +107,7 @@ resource "proxmox_lxc" "homebridge" {
   cores    = $self:cores
   memory   = $self:memory
   network {
-    ip = "$self:container_ip/24"
+    ip = "$self:target_ip/24"
     gw = "$system:management.ip"
   }
 }
@@ -189,7 +195,7 @@ resource "proxmox_lxc" "homebridge" {
 
 describe('hasVariables', () => {
   test('should return true for content with variables', () => {
-    expect(hasVariables('ip: $self:container_ip')).toBe(true);
+    expect(hasVariables('ip: $self:target_ip')).toBe(true);
     expect(hasVariables('$secret:key')).toBe(true);
   });
 
@@ -206,7 +212,7 @@ describe('hasVariables', () => {
 
 describe('isValidVariableFormat', () => {
   test('should validate correct variable formats', () => {
-    expect(isValidVariableFormat('$self:container_ip')).toBe(true);
+    expect(isValidVariableFormat('$self:target_ip')).toBe(true);
     expect(isValidVariableFormat('$system:management.ip')).toBe(true);
     expect(isValidVariableFormat('$secret:api_key')).toBe(true);
     expect(isValidVariableFormat('$capability:dns_external.nameserver')).toBe(true);
@@ -219,7 +225,7 @@ describe('isValidVariableFormat', () => {
   });
 
   test('should reject invalid variable formats', () => {
-    expect(isValidVariableFormat('self:container_ip')).toBe(false); // missing $
+    expect(isValidVariableFormat('self:target_ip')).toBe(false); // missing $
     expect(isValidVariableFormat('$unknown:value')).toBe(false); // invalid type
     expect(isValidVariableFormat('$self:')).toBe(false); // missing path
     expect(isValidVariableFormat('$self')).toBe(false); // missing colon and path
@@ -228,4 +234,53 @@ describe('isValidVariableFormat', () => {
     expect(isValidVariableFormat('${self:test')).toBe(false); // missing closing brace
     expect(isValidVariableFormat('$self:test}')).toBe(false); // mismatched brace
   });
+
+  test('should accept [N] array-index suffix on $self:', () => {
+    expect(isValidVariableFormat('$self:domains[0]')).toBe(true);
+    expect(isValidVariableFormat('$self:domains[42]')).toBe(true);
+    expect(isValidVariableFormat('${self:domains[0]}')).toBe(true);
+  });
+
+  test('should reject malformed [N] indexes', () => {
+    expect(isValidVariableFormat('$self:domains[]')).toBe(false);
+    expect(isValidVariableFormat('$self:domains[a]')).toBe(false);
+    expect(isValidVariableFormat('$self:domains[-1]')).toBe(false);
+    expect(isValidVariableFormat('$self:domains[0')).toBe(false);
+  });
+});
+
+describe('parsePath', () => {
+  test('returns name without index when no brackets', () => {
+    expect(parsePath('domains')).toEqual({ name: 'domains' });
+    expect(parsePath('a.b.c')).toEqual({ name: 'a.b.c' });
+  });
+
+  test('separates trailing [N] into index field', () => {
+    expect(parsePath('domains[0]')).toEqual({ name: 'domains', index: 0 });
+    expect(parsePath('domains[7]')).toEqual({ name: 'domains', index: 7 });
+    expect(parsePath('a.b.c[2]')).toEqual({ name: 'a.b.c', index: 2 });
+  });
+});
+
+describe('applyIndex', () => {
+  test('returns the value unchanged when index is undefined', () => {
+    expect(applyIndex('hello', undefined)).toBe('hello');
+    expect(applyIndex(['a', 'b'], undefined)).toEqual(['a', 'b']);
+  });
+
+  test('drills into array at the given index', () => {
+    expect(applyIndex(['a', 'b', 'c'], 0)).toBe('a');
+    expect(applyIndex(['a', 'b', 'c'], 2)).toBe('c');
+  });
+
+  test('returns undefined for out-of-bounds indexes', () => {
+    expect(applyIndex(['a'], 5)).toBeUndefined();
+    expect(applyIndex([], 0)).toBeUndefined();
+  });
+
+  test('returns undefined when applying an index to a non-array', () => {
+    expect(applyIndex('not an array', 0)).toBeUndefined();
+    expect(applyIndex(42, 0)).toBeUndefined();
+    expect(applyIndex(null, 0)).toBeUndefined();
+  });
 });