@celilo/cli 0.1.0

package/src/variables/context.ts

@@ -0,0 +1,624 @@
+import { eq } from 'drizzle-orm';
+import { getWellKnownCapability, isWellKnown } from '../capabilities/well-known';
+import { getDb } from '../db/client';
+import type { DbClient } from '../db/client';
+import {
+  capabilities,
+  moduleConfigs,
+  modules,
+  secrets,
+  systemConfig,
+  systemSecrets,
+} from '../db/schema';
+import { allocateResources, getAllocation } from '../ipam/allocator';
+import type { ModuleManifest } from '../manifest/schema';
+import { decryptSecret } from '../secrets/encryption';
+import { getOrCreateMasterKey } from '../secrets/master-key';
+import { applyDeclarativeDerivations } from './declarative-derivation';
+import type { ResolutionContext } from './types';
+
+/**
+ * Strip CIDR notation from IP address
+ * Policy function - pure string manipulation
+ *
+ * @param ipWithCidr - IP address with optional CIDR (e.g., "10.0.10.10/24")
+ * @returns IP address without CIDR (e.g., "10.0.10.10")
+ */
+function stripCidr(ipWithCidr: string): string {
+  const slashIndex = ipWithCidr.indexOf('/');
+  if (slashIndex === -1) {
+    return ipWithCidr;
+  }
+  return ipWithCidr.slice(0, slashIndex);
+}
+
+/**
+ * Auto-assign hostname and zone from well-known capabilities
+ * Policy function - derives values from capability registry
+ *
+ * Zero-config systems
+ * If module provides a well-known capability, auto-assign:
+ * - hostname from canonical_hostname
+ * - zone from required_zone
+ *
+ * Only assigns if not already set (explicit config wins)
+ *
+ * @param manifest - Module manifest
+ * @param selfConfig - Current module configuration
+ * @param db - Database client for hostname conflict detection
+ * @returns Object with assigned hostname and zone (if any)
+ * @throws Error if hostname conflict or zone enforcement fails
+ */
+async function autoAssignFromWellKnown(
+  manifest: ModuleManifest,
+  selfConfig: Record<string, string>,
+  _moduleId: string,
+  _db: DbClient,
+): Promise<{ hostname?: string; zone?: string }> {
+  const providedCapabilities = manifest.provides?.capabilities ?? [];
+  const result: { hostname?: string; zone?: string } = {};
+
+  // Find first well-known capability (priority order)
+  // Note: Capability uniqueness and zone enforcement are validated at import time
+  for (const capability of providedCapabilities) {
+    if (!isWellKnown(capability.name)) {
+      continue;
+    }
+
+    const wellKnown = getWellKnownCapability(capability.name);
+
+    // Determine current zone (from config or manifest)
+    const currentZone = selfConfig.zone || manifest.requires?.machine?.zone;
+
+    // Auto-assign hostname if not already set
+    if (!selfConfig.hostname) {
+      result.hostname = wellKnown.canonical_hostname;
+    }
+
+    // Auto-assign zone if not already set (in config or manifest)
+    if (!currentZone) {
+      result.zone = wellKnown.required_zone;
+    }
+
+    // Only process first well-known capability (deterministic)
+    break;
+  }
+
+  return result;
+}
+
+/**
+ * Determine if module needs IPAM auto-allocation
+ * Policy function - checks manifest and config
+ *
+ * A module needs IPAM if:
+ * 1. It declares vmid and container_ip variables (container-based), AND
+ * 2. These values are not already set in module config
+ *
+ * @param manifest - Module manifest
+ * @param selfConfig - Current module configuration
+ * @returns true if IPAM allocation needed
+ */
+function needsIpamAllocation(
+  manifest: ModuleManifest,
+  selfConfig: Record<string, string>,
+): boolean {
+  const variables = manifest.variables?.owns ?? [];
+
+  const hasVmid = variables.some((v) => v.name === 'vmid');
+  const hasContainerIp = variables.some((v) => v.name === 'container_ip');
+
+  // Module must declare both vmid and container_ip to be container-based
+  if (!hasVmid || !hasContainerIp) {
+    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 !== '';
+
+  // Need allocation if either is missing
+  return !vmidSet || !ipSet;
+}
+
+/**
+ * Determine network zone for module
+ * Policy function - extracts zone from manifest or config
+ *
+ * Zone determination priority:
+ * 1. Explicit zone in module config (user override)
+ * 2. VM resources zone in manifest
+ * 3. Default to 'dmz'
+ *
+ * @param manifest - Module manifest
+ * @param selfConfig - Current module configuration
+ * @returns Network zone ('dmz', 'app', 'secure', or 'internal')
+ */
+function determineModuleZone(
+  manifest: ModuleManifest,
+  selfConfig: Record<string, string>,
+): 'dmz' | 'app' | 'secure' | 'internal' {
+  // Priority 1: Explicit zone in config
+  if (selfConfig.zone) {
+    const zone = selfConfig.zone;
+    if (zone === 'dmz' || zone === 'app' || zone === 'secure' || zone === 'internal') {
+      return zone;
+    }
+  }
+
+  // Priority 2: VM resources zone in manifest
+  const vmZone = manifest.requires?.machine?.zone;
+  if (vmZone === 'dmz' || vmZone === 'app' || vmZone === 'secure' || vmZone === 'internal') {
+    return vmZone;
+  }
+
+  // Default: dmz (public-facing services)
+  return 'dmz';
+}
+
+/**
+ * Auto-derive inventory variables from module configuration
+ * Policy function - derives values from existing config
+ *
+ * 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_user: Defaults to "root"
+ * - inventory.groups: Derived from module ID
+ *
+ * @param moduleId - Module ID
+ * @param selfConfig - Module configuration
+ * @returns Additional derived variables to merge into selfConfig
+ */
+function autoDeriveInventoryVariables(
+  moduleId: string,
+  selfConfig: Record<string, string>,
+): Record<string, string> {
+  const derived: Record<string, string> = {};
+
+  // Auto-derive hostname from hostname variable
+  if (selfConfig.hostname) {
+    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);
+  } else if (selfConfig.vps_ip) {
+    // VPS-based modules use vps_ip directly (no CIDR to strip)
+    derived['inventory.ansible_host'] = selfConfig.vps_ip;
+  }
+
+  // Auto-derive ansible_user (default: root)
+  // Can be overridden by module config
+  if (!selfConfig['inventory.ansible_user']) {
+    derived['inventory.ansible_user'] = 'root';
+  }
+
+  // Auto-derive groups from module ID
+  // Format: module ID becomes the primary group
+  derived['inventory.groups'] = moduleId;
+
+  return derived;
+}
+
+/**
+ * Build resolution context for a module
+ *
+ * Execution function (Rule 10.1) - performs database queries
+ *
+ * @param moduleId - Module to build context for
+ * @param db - Database client (optional, for testing)
+ * @returns Resolution context with all data sources
+ */
+export async function buildResolutionContext(
+  moduleId: string,
+  db = getDb(),
+): Promise<ResolutionContext> {
+  // Fetch module manifest for VM resources
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+
+  // Fetch module configuration (self)
+  const configRows = db
+    .select()
+    .from(moduleConfigs)
+    .where(eq(moduleConfigs.moduleId, moduleId))
+    .all();
+
+  const selfConfig: Record<string, string> = {};
+  for (const row of configRows) {
+    // Handle complex types (stored in valueJson)
+    if (row.valueJson) {
+      selfConfig[row.key] = row.valueJson; // Store JSON string
+    } else {
+      selfConfig[row.key] = row.value;
+    }
+  }
+
+  // Well-known capability auto-assignment
+  // Auto-assign hostname and zone if module provides well-known capability
+  if (module?.manifestData) {
+    const manifest = module.manifestData as ModuleManifest;
+    const assigned = await autoAssignFromWellKnown(manifest, selfConfig, moduleId, db);
+
+    // Store assigned values in module config
+    if (assigned.hostname) {
+      await db
+        .insert(moduleConfigs)
+        .values({ moduleId, key: 'hostname', value: assigned.hostname })
+        .onConflictDoUpdate({
+          target: [moduleConfigs.moduleId, moduleConfigs.key],
+          set: { value: assigned.hostname },
+        });
+      selfConfig.hostname = assigned.hostname;
+    }
+
+    if (assigned.zone) {
+      await db
+        .insert(moduleConfigs)
+        .values({ moduleId, key: 'zone', value: assigned.zone })
+        .onConflictDoUpdate({
+          target: [moduleConfigs.moduleId, moduleConfigs.key],
+          set: { value: assigned.zone },
+        });
+      selfConfig.zone = assigned.zone;
+    }
+  }
+
+  // Variable defaults
+  // Auto-apply default values from variable declarations if not already configured
+  if (module?.manifestData) {
+    const manifest = module.manifestData as ModuleManifest;
+    const variables = manifest.variables?.owns ?? [];
+
+    for (const variable of variables) {
+      // Only apply if variable has a default and config doesn't already have it
+      if (variable.default !== undefined && !selfConfig[variable.name]) {
+        const valueStr = String(variable.default);
+
+        await db
+          .insert(moduleConfigs)
+          .values({ moduleId, key: variable.name, value: valueStr })
+          .onConflictDoUpdate({
+            target: [moduleConfigs.moduleId, moduleConfigs.key],
+            set: { value: valueStr },
+          });
+
+        selfConfig[variable.name] = valueStr;
+      }
+    }
+  }
+
+  // VM resource defaults
+  // Auto-apply VM resource defaults from manifest if not already configured
+  if (module?.manifestData) {
+    const manifest = module.manifestData as ModuleManifest;
+    const machineResources = manifest.requires?.machine;
+
+    if (machineResources) {
+      // Map manifest fields to module variable names and apply defaults
+      const resourceMappings: Array<{
+        manifestKey: keyof typeof machineResources;
+        configKey: string;
+      }> = [
+        { manifestKey: 'cpu', configKey: 'cores' }, // manifest.requires.machine.cpu → cores variable
+        { manifestKey: 'memory', configKey: 'memory' },
+        { manifestKey: 'disk', configKey: 'disk' },
+        { manifestKey: 'storage', configKey: 'storage' },
+      ];
+
+      for (const { manifestKey, configKey } of resourceMappings) {
+        const value = machineResources[manifestKey];
+
+        // Only apply if manifest specifies a value and config doesn't already have it
+        if (value !== undefined && !selfConfig[configKey]) {
+          const valueStr = String(value);
+
+          await db
+            .insert(moduleConfigs)
+            .values({ moduleId, key: configKey, value: valueStr })
+            .onConflictDoUpdate({
+              target: [moduleConfigs.moduleId, moduleConfigs.key],
+              set: { value: valueStr },
+            });
+
+          selfConfig[configKey] = valueStr;
+        }
+      }
+    }
+  }
+
+  // IPAM auto-allocation
+  // If module declares vmid/container_ip but they're not configured, allocate automatically
+  if (module?.manifestData) {
+    const manifest = module.manifestData as ModuleManifest;
+
+    if (needsIpamAllocation(manifest, selfConfig)) {
+      const zone = determineModuleZone(manifest, selfConfig);
+
+      // Use transaction to ensure atomicity
+      await db.transaction(async (tx) => {
+        // Check if allocation already exists in ipAllocations table
+        const existing = await getAllocation(moduleId, tx);
+
+        let vmid: number;
+        let containerIp: string;
+
+        if (existing) {
+          // Use existing allocation
+          vmid = existing.vmid;
+          containerIp = existing.containerIp;
+        } else {
+          // Allocate new resources (persists to ipAllocations)
+          const allocation = await allocateResources(moduleId, zone, tx);
+          vmid = allocation.vmid;
+          containerIp = allocation.containerIp;
+        }
+
+        // Ensure values are in module config (upsert to handle existing keys)
+        await tx
+          .insert(moduleConfigs)
+          .values({ moduleId, key: 'vmid', value: String(vmid) })
+          .onConflictDoUpdate({
+            target: [moduleConfigs.moduleId, moduleConfigs.key],
+            set: { value: String(vmid) },
+          });
+
+        await tx
+          .insert(moduleConfigs)
+          .values({ moduleId, key: 'container_ip', value: containerIp })
+          .onConflictDoUpdate({
+            target: [moduleConfigs.moduleId, moduleConfigs.key],
+            set: { value: containerIp },
+          });
+
+        // Update selfConfig with allocated values
+        selfConfig.vmid = String(vmid);
+        selfConfig.container_ip = containerIp;
+      });
+    }
+  }
+
+  // Add machine requirements from manifest to selfConfig so templates can
+  // reference them via $self:requires.machine.<field>
+  if (module?.manifestData) {
+    const manifest = module.manifestData as Record<string, unknown>;
+    const requires = manifest.requires as Record<string, unknown> | undefined;
+    if (requires?.machine) {
+      const machineRequires = requires.machine as Record<string, unknown>;
+      for (const [key, value] of Object.entries(machineRequires)) {
+        selfConfig[`requires.machine.${key}`] = String(value);
+      }
+    }
+  }
+
+  // Fetch secrets (encrypted values should be decrypted by caller)
+  const secretRows = db.select().from(secrets).where(eq(secrets.moduleId, moduleId)).all();
+
+  const secretsMap: Record<string, string> = {};
+  for (const row of secretRows) {
+    secretsMap[row.name] = row.encryptedValue;
+  }
+
+  // Fetch all capabilities (for capability variables)
+  const capabilityRows = db.select().from(capabilities).all();
+
+  const capabilitiesMap: Record<string, Record<string, unknown>> = {};
+  for (const row of capabilityRows) {
+    // Parse JSON data if it's a string
+    let data: unknown;
+    if (typeof row.data === 'string') {
+      try {
+        data = JSON.parse(row.data);
+      } catch (error) {
+        throw new Error(
+          `Failed to parse capability data for ${row.capabilityName}: ${error instanceof Error ? error.message : 'Invalid JSON'}`,
+        );
+      }
+    } else {
+      data = row.data;
+    }
+    capabilitiesMap[row.capabilityName] = data as Record<string, unknown>;
+  }
+
+  // Fetch system configuration (for $system: variables)
+  const systemConfigRows = db.select().from(systemConfig).all();
+
+  const systemConfigMap: Record<string, string> = {};
+  for (const row of systemConfigRows) {
+    systemConfigMap[row.key] = row.value;
+  }
+
+  // Fetch system secrets (for $system_secret: variables)
+  const systemSecretsMap: Record<string, string> = {};
+  try {
+    const systemSecretRows = db.select().from(systemSecrets).all();
+
+    if (systemSecretRows.length > 0) {
+      // Get master key for decryption
+      const masterKey = await getOrCreateMasterKey();
+
+      for (const row of systemSecretRows) {
+        try {
+          const decrypted = decryptSecret(
+            {
+              encryptedValue: row.encryptedValue,
+              iv: row.iv,
+              authTag: row.authTag,
+            },
+            masterKey,
+          );
+          systemSecretsMap[row.key] = decrypted;
+        } catch (err) {
+          // Log error but continue with other secrets
+          console.error(`Failed to decrypt system secret ${row.key}:`, err);
+        }
+      }
+    }
+  } catch (_err) {
+    // Table might not exist in test/old databases - that's okay
+    // System secrets are optional
+  }
+
+  // Zone-based networking
+  // Auto-derive network config from zone (gateway, vlan, subnet, bridge)
+  if (module?.manifestData) {
+    const manifest = module.manifestData as ModuleManifest;
+    const zone = selfConfig.zone || manifest.requires?.machine?.zone;
+
+    // If zone from manifest but not in selfConfig, store it as first-class config
+    if (zone && !selfConfig.zone) {
+      await db
+        .insert(moduleConfigs)
+        .values({ moduleId, key: 'zone', value: zone })
+        .onConflictDoUpdate({
+          target: [moduleConfigs.moduleId, moduleConfigs.key],
+          set: { value: zone },
+        });
+      selfConfig.zone = zone;
+    }
+
+    // Only apply for container-based zones (not external/VPS)
+    if (zone && zone !== 'external') {
+      const networkFields = ['gateway', 'vlan', 'subnet', 'bridge'];
+
+      for (const field of networkFields) {
+        // Only apply if not already configured by user
+        if (!selfConfig[field]) {
+          const systemConfigKey = `network.${zone}.${field}`;
+          const value = systemConfigMap[systemConfigKey];
+
+          if (value) {
+            await db
+              .insert(moduleConfigs)
+              .values({ moduleId, key: field, value })
+              .onConflictDoUpdate({
+                target: [moduleConfigs.moduleId, moduleConfigs.key],
+                set: { value },
+              });
+
+            selfConfig[field] = value;
+          }
+        }
+      }
+    }
+  }
+
+  // Declarative variable derivation
+  // Apply template-based derivations from manifest
+  if (module?.manifestData) {
+    const manifest = module.manifestData as ModuleManifest;
+    const context: ResolutionContext = {
+      moduleId,
+      selfConfig,
+      systemConfig: systemConfigMap,
+      systemSecrets: systemSecretsMap,
+      secrets: secretsMap,
+      capabilities: capabilitiesMap,
+    };
+
+    // Snapshot values before derivation so we can detect changes
+    const preDeriveValues: Record<string, string> = { ...selfConfig };
+
+    // Apply declarative derivations from manifest
+    applyDeclarativeDerivations(manifest, context);
+
+    // Persist derived values to database
+    // For capability/infrastructure-sourced variables, always update since
+    // the upstream value may have changed.
+    const rederivableSources = new Set(['capability', 'infrastructure']);
+    const declaredVars = manifest.variables?.owns ?? [];
+
+    for (const [key, value] of Object.entries(context.selfConfig)) {
+      const decl = declaredVars.find((v) => v.name === key);
+      const isNew = preDeriveValues[key] === undefined;
+      const isChanged =
+        decl?.source && rederivableSources.has(decl.source) && preDeriveValues[key] !== value;
+
+      // Don't persist values that still contain unresolved template
+      // variables ($self:, $system:, $capability:). This happens when
+      // capability data contains template references that can't be
+      // fully resolved in the consuming module's context — e.g.,
+      // $capability:dns_registrar.primary_domain resolves to
+      // namecheap's capability data "$self:primary_domain", but
+      // $self: in that context refers to namecheap, not the consumer.
+      // Persisting the raw template would poison the config with an
+      // unresolvable string. Keep the user-set value (if any) instead.
+      if (
+        typeof value === 'string' &&
+        (value.includes('$self:') ||
+          value.includes('$system:') ||
+          value.includes('$capability:') ||
+          value.includes('$secret:'))
+      ) {
+        continue;
+      }
+
+      if (isNew || isChanged) {
+        await db
+          .insert(moduleConfigs)
+          .values({ moduleId, key, value })
+          .onConflictDoUpdate({
+            target: [moduleConfigs.moduleId, moduleConfigs.key],
+            set: { value },
+          });
+
+        selfConfig[key] = value;
+      }
+    }
+  }
+
+  // Auto-derive inventory variables
+  const derivedVars = autoDeriveInventoryVariables(moduleId, selfConfig);
+
+  // Merge derived variables into selfConfig
+  // Explicit config takes precedence over derived values
+  const finalSelfConfig = { ...derivedVars, ...selfConfig };
+
+  return {
+    moduleId,
+    selfConfig: finalSelfConfig,
+    systemConfig: systemConfigMap,
+    systemSecrets: systemSecretsMap,
+    secrets: secretsMap,
+    capabilities: capabilitiesMap,
+  };
+}
+
+/**
+ * Build resolution context from explicit data (for testing)
+ *
+ * Policy function - no database access
+ *
+ * @param moduleId - Module ID
+ * @param data - Explicit data sources
+ * @returns Resolution context
+ */
+export function buildContextFromData(
+  moduleId: string,
+  data: {
+    selfConfig?: Record<string, string>;
+    systemConfig?: Record<string, string>;
+    systemSecrets?: Record<string, string>;
+    secrets?: Record<string, string>;
+    capabilities?: Record<string, Record<string, unknown>>;
+  } = {},
+): ResolutionContext {
+  const selfConfig = data.selfConfig ?? {};
+
+  // Auto-derive inventory variables (same as buildResolutionContext)
+  const derivedVars = autoDeriveInventoryVariables(moduleId, selfConfig);
+
+  // Merge derived variables into selfConfig
+  // Explicit config takes precedence over derived values
+  const finalSelfConfig = { ...derivedVars, ...selfConfig };
+
+  return {
+    moduleId,
+    selfConfig: finalSelfConfig,
+    systemConfig: data.systemConfig ?? {},
+    systemSecrets: data.systemSecrets ?? {},
+    secrets: data.secrets ?? {},
+    capabilities: data.capabilities ?? {},
+  };
+}