@celilo/cli 0.1.0

package/src/variables/declarative-derivation.ts

@@ -0,0 +1,200 @@
+import type { ModuleManifest, VariableDeclare } from '../manifest/schema';
+import type { ResolutionContext } from './types';
+
+/**
+ * Get nested property from object using dot notation
+ *
+ * Policy function - pure navigation
+ *
+ * @param obj - Object to navigate
+ * @param path - Dot-separated path (e.g., "server.ip.primary")
+ * @returns Value at path or undefined if not found
+ */
+function getNestedProperty(obj: Record<string, unknown>, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (current && typeof current === 'object' && part in (current as Record<string, unknown>)) {
+      current = (current as Record<string, unknown>)[part];
+    } else {
+      return undefined;
+    }
+  }
+
+  return current;
+}
+
+/**
+ * Resolve declarative variable derivation from manifest
+ *
+ * Policy function - pure template substitution
+ *
+ * Supports the following template patterns:
+ * - $system:key - System config value (e.g., $system:primary_domain)
+ * - {variable} - Module's own variable (e.g., {hostname})
+ * - $capability:name.path - Capability data (e.g., $capability:dns_registrar.primary_domain)
+ *
+ * @param variable - Variable declaration with derive_from field
+ * @param context - Resolution context (selfConfig, systemConfig, etc.)
+ * @returns Derived value or undefined if dependencies missing
+ * @throws Error if required dependencies are missing
+ */
+/**
+ * Pattern that matches any unresolved variable reference.
+ * Used to detect whether another resolution pass is needed.
+ */
+const UNRESOLVED_PATTERN = /\$\{?(?:system|self|capability|secret|system_secret):/;
+
+/**
+ * Run one pass of variable substitution on a string.
+ */
+function substituteVariables(
+  input: string,
+  variableName: string,
+  context: ResolutionContext,
+): string {
+  let result = input;
+
+  // Replace $system:key patterns (both $system:key and ${system:key} forms)
+  result = result.replace(/\$\{?system:([a-zA-Z0-9_.]+)\}?/g, (_match, key) => {
+    const value = context.systemConfig[key];
+    if (value === undefined) {
+      throw new Error(`Missing system config: ${key} (required by variable '${variableName}')`);
+    }
+    return value;
+  });
+
+  // Replace {variable_name} patterns
+  result = result.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, varName) => {
+    const value = context.selfConfig[varName];
+    if (value === undefined) {
+      throw new Error(`Missing variable: ${varName} (required by variable '${variableName}')`);
+    }
+    return value;
+  });
+
+  // Replace $capability:name.path patterns
+  result = result.replace(
+    /\$capability:([a-zA-Z0-9_]+)\.([a-zA-Z0-9_.]+)/g,
+    (_match, capName, path) => {
+      const capData = context.capabilities[capName];
+      if (!capData) {
+        throw new Error(`Missing capability: ${capName} (required by variable '${variableName}')`);
+      }
+
+      const value = getNestedProperty(capData, path);
+      if (value === undefined) {
+        throw new Error(
+          `Missing capability field: ${capName}.${path} (required by variable '${variableName}')`,
+        );
+      }
+      return String(value);
+    },
+  );
+
+  return result;
+}
+
+export function resolveDeclarativeDerivation(
+  variable: VariableDeclare,
+  context: ResolutionContext,
+): string | undefined {
+  if (!variable.derive_from) {
+    return undefined;
+  }
+
+  const template = variable.derive_from;
+
+  // $machine: derivations are handled by the config interview, not template resolution
+  if (template.startsWith('$machine:')) {
+    return undefined;
+  }
+
+  // Resolve variables iteratively — capability values may contain $system: or
+  // other references that need a second pass to fully resolve.
+  let result = template;
+  const maxPasses = 5;
+  for (let i = 0; i < maxPasses; i++) {
+    const resolved = substituteVariables(result, variable.name, context);
+    if (resolved === result) break; // Stable — no more substitutions possible
+    result = resolved;
+    if (!UNRESOLVED_PATTERN.test(result)) break; // Fully resolved
+  }
+
+  return result;
+}
+
+/**
+ * Apply all declarative derivations from manifest
+ *
+ * Planning function - processes variable declarations in order
+ *
+ * Rules:
+ * 1. User-provided values always take precedence (not overwritten)
+ * 2. Variables are resolved in declaration order
+ * 3. Only works for type: string variables
+ * 4. If derivation fails for optional variable, silently skip
+ * 5. If derivation fails for required variable, throw error
+ *
+ * @param manifest - Module manifest with variable declarations
+ * @param context - Resolution context (will be mutated with derived values)
+ */
+export function applyDeclarativeDerivations(
+  manifest: ModuleManifest,
+  context: ResolutionContext,
+): void {
+  const variables = manifest.variables?.owns ?? [];
+
+  for (const variable of variables) {
+    // Re-derive capability-sourced and infrastructure-sourced variables every time,
+    // since the upstream data may have changed. User-provided values take precedence
+    // only for user-sourced variables.
+    const shouldRederive = variable.source === 'capability' || variable.source === 'infrastructure';
+    if (!shouldRederive && context.selfConfig[variable.name] !== undefined) {
+      continue;
+    }
+
+    // Skip if no derivation defined
+    if (!variable.derive_from) {
+      continue;
+    }
+
+    // Declarative derivation only resolves string template expressions.
+    // Non-string types (arrays, objects) with derive_from are handled by
+    // the config interview system instead.
+    if (variable.type !== 'string') {
+      continue;
+    }
+
+    try {
+      const derived = resolveDeclarativeDerivation(variable, context);
+      if (derived !== undefined) {
+        // Don't overwrite with a value that still contains unresolved
+        // template references ($self:, $system:, $capability:). This
+        // happens when capability data contains template strings that
+        // can't be fully resolved in the consuming module's context —
+        // e.g. $capability:dns_registrar.primary_domain resolves to
+        // namecheap's "$self:primary_domain", but $self: in that
+        // context is namecheap, not the consumer.
+        const hasUnresolved =
+          derived.includes('$self:') ||
+          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
+          continue;
+        }
+        context.selfConfig[variable.name] = derived;
+      }
+    } catch (error) {
+      // If derivation fails due to missing dependencies, handle based on required flag
+      if (variable.required) {
+        // Required variable - propagate error
+        throw error;
+      }
+      // Optional variable - silently skip (will use default or remain unset)
+    }
+  }
+}

package/src/variables/parser.test.ts

@@ -0,0 +1,231 @@
+import { describe, expect, test } from 'bun:test';
+import { hasVariables, isValidVariableFormat, parseVariables } from './parser';
+
+describe('parseVariables', () => {
+  test('should parse self variables', () => {
+    const content = 'ip: $self:container_ip';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(1);
+    expect(variables[0]).toEqual({
+      type: 'self',
+      path: 'container_ip',
+      raw: '$self:container_ip',
+    });
+  });
+
+  test('should parse system variables', () => {
+    const content = 'server: $system:management.ip';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(1);
+    expect(variables[0]).toEqual({
+      type: 'system',
+      path: 'management.ip',
+      raw: '$system:management.ip',
+    });
+  });
+
+  test('should parse secret variables', () => {
+    const content = 'key: $secret:api_key';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(1);
+    expect(variables[0]).toEqual({
+      type: 'secret',
+      path: 'api_key',
+      raw: '$secret:api_key',
+    });
+  });
+
+  test('should parse capability variables', () => {
+    const content = 'dns: $capability:dns_external.nameserver';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(1);
+    expect(variables[0]).toEqual({
+      type: 'capability',
+      path: 'dns_external.nameserver',
+      raw: '$capability:dns_external.nameserver',
+    });
+  });
+
+  test('should parse multiple variables in same content', () => {
+    const content = `
+      ip: $self:container_ip
+      dns: $capability:dns_external.nameserver
+      key: $secret:api_key
+    `;
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(3);
+    expect(variables[0]?.type).toBe('self');
+    expect(variables[1]?.type).toBe('capability');
+    expect(variables[2]?.type).toBe('secret');
+  });
+
+  test('should handle nested paths in capability variables', () => {
+    const content = '$capability:dns_external.config.primary.nameserver';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(1);
+    expect(variables[0]?.path).toBe('dns_external.config.primary.nameserver');
+  });
+
+  test('should handle underscores and numbers in paths', () => {
+    const content = '$self:vlan_id_10';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(1);
+    expect(variables[0]?.path).toBe('vlan_id_10');
+  });
+
+  test('should not parse paths starting with numbers', () => {
+    const content = '$self:123invalid';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(0);
+  });
+
+  test('should return empty array for content without variables', () => {
+    const content = 'no variables here';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(0);
+  });
+
+  test('should handle variables in complex template', () => {
+    const content = `
+resource "proxmox_lxc" "homebridge" {
+  hostname = "$self:hostname"
+  cores    = $self:cores
+  memory   = $self:memory
+  network {
+    ip = "$self:container_ip/24"
+    gw = "$system:management.ip"
+  }
+}
+    `;
+    const variables = parseVariables(content);
+
+    expect(variables.length).toBeGreaterThan(3);
+  });
+
+  test('should parse braced variables for concatenation', () => {
+    const content = 'size = "${self:disk}G"';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(1);
+    expect(variables[0]).toEqual({
+      type: 'self',
+      path: 'disk',
+      raw: '${self:disk}',
+    });
+  });
+
+  test('should parse multiple braced variables', () => {
+    const content = 'url = "${system:protocol}://${system:host}:${system:port}"';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(3);
+    expect(variables[0]?.raw).toBe('${system:protocol}');
+    expect(variables[1]?.raw).toBe('${system:host}');
+    expect(variables[2]?.raw).toBe('${system:port}');
+  });
+
+  test('should handle mix of braced and simple variables', () => {
+    const content = 'size = "${self:disk}G" and vmid = $self:vmid';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(2);
+    expect(variables[0]?.raw).toBe('${self:disk}');
+    expect(variables[1]?.raw).toBe('$self:vmid');
+  });
+
+  test('should handle braced variables with nested paths', () => {
+    const content = 'api = "${capability:auth.endpoint.url}/v1"';
+    const variables = parseVariables(content);
+
+    expect(variables).toHaveLength(1);
+    expect(variables[0]).toEqual({
+      type: 'capability',
+      path: 'auth.endpoint.url',
+      raw: '${capability:auth.endpoint.url}',
+    });
+  });
+
+  test('should NOT match Terraform variables (no colon after type)', () => {
+    const content = `
+      hostname = "\${var.hostname}"
+      ip = "\${local.ip_address}"
+      id = "\${proxmox_lxc.caddy.id}"
+      cidr = "\${var.network.cidr}"
+    `;
+    const variables = parseVariables(content);
+
+    // Should find zero variables because Terraform uses dots, not colons
+    expect(variables).toHaveLength(0);
+  });
+
+  test('should match our syntax but not Terraform syntax in same file', () => {
+    const content = `
+      # Our syntax (with colon)
+      size = "\${self:disk}G"
+
+      # Terraform syntax (with dots)
+      hostname = "\${var.hostname}"
+
+      # Our syntax again
+      vmid = $self:vmid
+    `;
+    const variables = parseVariables(content);
+
+    // Should only find our 2 variables
+    expect(variables).toHaveLength(2);
+    expect(variables[0]?.raw).toBe('${self:disk}');
+    expect(variables[1]?.raw).toBe('$self:vmid');
+  });
+});
+
+describe('hasVariables', () => {
+  test('should return true for content with variables', () => {
+    expect(hasVariables('ip: $self:container_ip')).toBe(true);
+    expect(hasVariables('$secret:key')).toBe(true);
+  });
+
+  test('should return true for content with braced variables', () => {
+    expect(hasVariables('size: "${self:disk}G"')).toBe(true);
+    expect(hasVariables('${system:url}')).toBe(true);
+  });
+
+  test('should return false for content without variables', () => {
+    expect(hasVariables('no variables')).toBe(false);
+    expect(hasVariables('dollar sign $ but not a variable')).toBe(false);
+  });
+});
+
+describe('isValidVariableFormat', () => {
+  test('should validate correct variable formats', () => {
+    expect(isValidVariableFormat('$self:container_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);
+  });
+
+  test('should validate correct braced variable formats', () => {
+    expect(isValidVariableFormat('${self:disk}')).toBe(true);
+    expect(isValidVariableFormat('${system:url}')).toBe(true);
+    expect(isValidVariableFormat('${capability:auth.endpoint}')).toBe(true);
+  });
+
+  test('should reject invalid variable formats', () => {
+    expect(isValidVariableFormat('self:container_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
+    expect(isValidVariableFormat('$self:123')).toBe(false); // path starts with number
+    expect(isValidVariableFormat('$self:path with spaces')).toBe(false); // spaces not allowed
+    expect(isValidVariableFormat('${self:test')).toBe(false); // missing closing brace
+    expect(isValidVariableFormat('$self:test}')).toBe(false); // mismatched brace
+  });
+});

package/src/variables/parser.ts

@@ -0,0 +1,76 @@
+import type { VariableReference } from './types';
+
+/**
+ * Regular expression to match variable references
+ * Supports two syntaxes:
+ * 1. ${type:path.to.value} - Explicit braces for concatenation (e.g., "${self:disk}G")
+ * 2. $type:path.to.value - Simple syntax for standalone variables (e.g., "vmid = $self:vmid")
+ *
+ * Examples:
+ * - $self:container_ip
+ * - ${self:disk}G
+ * - $capability:dns_registrar.primary_domain
+ * - ${system:base_url}/api
+ *
+ * Path must start with letter or underscore, not digit
+ */
+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;
+
+/**
+ * Parse template content to extract variable references
+ *
+ * Policy function (Rule 10.1) - parses only, no side effects
+ *
+ * @param content - Template content
+ * @returns Array of variable references found in template
+ */
+export function parseVariables(content: string): VariableReference[] {
+  const variables: VariableReference[] = [];
+  const matches = content.matchAll(VARIABLE_PATTERN);
+
+  for (const match of matches) {
+    const [raw, bracedType, bracedPath, simpleType, simplePath] = match;
+
+    // Check which syntax matched (braced vs simple)
+    const type = bracedType || simpleType;
+    const path = bracedPath || simplePath;
+
+    if (type && path) {
+      variables.push({
+        type: type as VariableReference['type'],
+        path,
+        raw,
+      });
+    }
+  }
+
+  return variables;
+}
+
+/**
+ * Check if a string contains any variable references
+ *
+ * @param content - String to check
+ * @returns True if content contains variables
+ */
+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_.-]*)/;
+  return pattern.test(content);
+}
+
+/**
+ * Validate variable reference format
+ *
+ * @param variable - Variable string to validate
+ * @returns True if format is valid
+ */
+export function isValidVariableFormat(variable: string): boolean {
+  // Path must start with letter or underscore, not digit
+  // Accepts both ${type:path} and $type:path
+  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_.-]*)$/;
+  return pattern.test(variable);
+}