@celilo/cli 0.1.5 → 0.1.7

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,5 +1,11 @@
 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', () => {
@@ -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();
+  });
 });

package/src/variables/parser.ts

@@ -9,13 +9,19 @@ import type { VariableReference } from './types';
  * Examples:
  * - $self:container_ip
  * - ${self:disk}G
+ * - $self:domains[0]              ← array indexing on $self: refs
  * - $capability:dns_registrar.primary_domain
  * - ${system:base_url}/api
  *
- * Path must start with letter or underscore, not digit
+ * Path must start with letter or underscore, not digit. An optional
+ * [N] suffix indexes into an array variable (currently only
+ * meaningful on $self: refs whose target is `type: array` — e.g.
+ * namecheap's `domains` declared as an array; the manifest's
+ * capability data block can then read `$self:domains[0]` as a
+ * computed alias for the canonical default).
  */
 const VARIABLE_PATTERN =
-  /\$\{(self|system|system_secret|secret|capability):([a-zA-Z_][a-zA-Z0-9_.-]*)\}|\$(self|system|system_secret|secret|capability):([a-zA-Z_][a-zA-Z0-9_.-]*)/g;
+  /\$\{(self|system|system_secret|secret|capability):([a-zA-Z_][a-zA-Z0-9_.-]*(?:\[\d+\])?)\}|\$(self|system|system_secret|secret|capability):([a-zA-Z_][a-zA-Z0-9_.-]*(?:\[\d+\])?)/g;
 
 /**
  * Parse template content to extract variable references
@@ -56,8 +62,9 @@ export function parseVariables(content: string): VariableReference[] {
  */
 export function hasVariables(content: string): boolean {
   // Create new regex without state to avoid issues with global flag
-  // Matches both ${type:path} and $type:path
-  const pattern = /\$\{?(self|system|system_secret|secret|capability):([a-zA-Z_][a-zA-Z0-9_.-]*)/;
+  // Matches both ${type:path} and $type:path (with optional [N] index)
+  const pattern =
+    /\$\{?(self|system|system_secret|secret|capability):([a-zA-Z_][a-zA-Z0-9_.-]*(?:\[\d+\])?)/;
   return pattern.test(content);
 }
 
@@ -69,8 +76,42 @@ export function hasVariables(content: string): boolean {
  */
 export function isValidVariableFormat(variable: string): boolean {
   // Path must start with letter or underscore, not digit
-  // Accepts both ${type:path} and $type:path
+  // Accepts both ${type:path} and $type:path with optional [N] indexing
   const pattern =
-    /^(?:\$\{(self|system|system_secret|secret|capability):[a-zA-Z_][a-zA-Z0-9_.-]*\}|\$(self|system|system_secret|secret|capability):[a-zA-Z_][a-zA-Z0-9_.-]*)$/;
+    /^(?:\$\{(self|system|system_secret|secret|capability):[a-zA-Z_][a-zA-Z0-9_.-]*(?:\[\d+\])?\}|\$(self|system|system_secret|secret|capability):[a-zA-Z_][a-zA-Z0-9_.-]*(?:\[\d+\])?)$/;
   return pattern.test(variable);
 }
+
+/**
+ * Split a variable path into its base name and optional array index.
+ *
+ * Examples:
+ *   parsePath("domains")     → { name: "domains" }
+ *   parsePath("domains[0]")  → { name: "domains", index: 0 }
+ *   parsePath("a.b.c[2]")    → { name: "a.b.c", index: 2 }
+ *
+ * Pure helper used wherever `$self:NAME[N]` semantics need to be
+ * applied to a resolved value (currently the capability-data
+ * resolver in `context.ts` and the lazy-resolution path in
+ * `resolver.ts`).
+ */
+export function parsePath(path: string): { name: string; index?: number } {
+  const match = /^(.+)\[(\d+)\]$/.exec(path);
+  if (!match) return { name: path };
+  return { name: match[1], index: Number.parseInt(match[2], 10) };
+}
+
+/**
+ * Apply an optional `[N]` index to a value. Used by the variable
+ * resolver after looking up a name like `domains` in a config map —
+ * if the original path had `[N]`, we drill into the array.
+ *
+ * Returns `undefined` for out-of-bounds indexes or when an index is
+ * applied to a non-array. Callers turn that into a resolver error.
+ */
+export function applyIndex(value: unknown, index: number | undefined): unknown {
+  if (index === undefined) return value;
+  if (!Array.isArray(value)) return undefined;
+  if (index < 0 || index >= value.length) return undefined;
+  return value[index];
+}

package/src/variables/resolver.ts

@@ -1,4 +1,4 @@
-import { parseVariables } from './parser';
+import { applyIndex, parsePath, parseVariables } from './parser';
 import type {
   ResolutionContext,
   ResolveResult,
@@ -173,8 +173,11 @@ export async function resolveVariable(
 
       // Check if value contains unresolved $self: variable (lazy resolution)
       if (typeof value === 'string' && value.startsWith('$self:')) {
-        // Get provider module's config to resolve the variable
-        const selfVarPath = value.substring(6); // Remove "$self:" prefix
+        // Get provider module's config to resolve the variable.
+        // The path can be a plain key ("primary_domain") or include
+        // an array index ("domains[0]") — see parsePath/applyIndex
+        // and the syntax note in the multi-domain DDNS design doc.
+        const { name, index } = parsePath(value.substring(6));
 
         // Get provider module ID
         const providerQuery = db.$client.prepare(
@@ -193,23 +196,38 @@ export async function resolveVariable(
           };
         }
 
-        // Get provider module's config value
+        // Fetch both `value` and `value_json` so we can index into
+        // arrays when the path contained `[N]`.
         const configQuery = db.$client.prepare(
-          'SELECT value FROM module_configs WHERE module_id = ? AND key = ?',
+          'SELECT value, value_json FROM module_configs WHERE module_id = ? AND key = ?',
         );
-        const configResult = configQuery.get(providerResult.id, selfVarPath) as
-          | { value: string }
+        const configResult = configQuery.get(providerResult.id, name) as
+          | { value: string; value_json: string | null }
           | undefined;
 
         if (!configResult) {
           return {
             success: false,
             variable: variable.raw,
-            error: `Provider module '${providerResult.id}' has not configured '${selfVarPath}' (required by capability '${capabilityName}')`,
+            error: `Provider module '${providerResult.id}' has not configured '${name}' (required by capability '${capabilityName}')`,
           };
         }
 
-        return { success: true, value: configResult.value };
+        const rawValue: unknown = configResult.value_json
+          ? JSON.parse(configResult.value_json)
+          : configResult.value;
+        const indexed = applyIndex(rawValue, index);
+        if (indexed === undefined) {
+          return {
+            success: false,
+            variable: variable.raw,
+            error:
+              index === undefined
+                ? `Provider module '${providerResult.id}' has not configured '${name}'`
+                : `'$self:${name}[${index}]' is out of bounds or '${name}' is not an array on '${providerResult.id}'`,
+          };
+        }
+        return { success: true, value: typeof indexed === 'string' ? indexed : String(indexed) };
       }
 
       // Convert value to string

package/tsconfig.json

@@ -4,6 +4,7 @@
     "module": "ESNext",
     "lib": ["ESNext"],
     "moduleResolution": "bundler",
+    "jsx": "react-jsx",
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,