@celilo/cli 0.1.0

package/src/hooks/types.ts

@@ -0,0 +1,89 @@
+/**
+ * Hook type definitions
+ *
+ * Types for the module lifecycle hook system.
+ * Hooks allow modules to execute custom logic at deployment milestones
+ * (e.g., container_created triggers web automation for API key creation).
+ */
+
+/**
+ * Hook definition from module manifest.
+ *
+ * Inputs and outputs are no longer carried by the manifest — they live in the
+ * contract registry (see `apps/celilo/src/manifest/contracts/v1.ts`),
+ * keyed by the manifest's `celilo_contract` version. The executor resolves
+ * the signature at runtime.
+ */
+export interface HookDefinition {
+  /** Path to hook script relative to module directory */
+  script: string;
+  /** Total timeout in milliseconds (default: 60000) */
+  timeout?: number;
+  /** If true, hook needs interactive terminal (no FuelGauge wrapping) */
+  interactive?: boolean;
+}
+
+/**
+ * Logger interface provided to hook scripts
+ */
+export interface HookLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  success(message: string): void;
+}
+
+/**
+ * Context passed to hook scripts
+ */
+export interface HookContext {
+  /** Module configuration values */
+  config: Record<string, unknown>;
+  /** Module secret values (decrypted) */
+  secrets: Record<string, string>;
+  /** Logger for reporting progress */
+  logger: HookLogger;
+  /** Run in debug mode (e.g., Playwright headless: false) */
+  debug: boolean;
+  /** Directory for saving screenshots on failure */
+  screenshotDir: string;
+  /** Capability function interfaces from provider modules (e.g., context.capabilities.dns_registrar) */
+  capabilities: Record<string, unknown>;
+  /** Dynamic inputs specified in manifest (e.g., vps_ip) */
+  [key: string]: unknown;
+}
+
+/**
+ * Result returned from hook execution
+ */
+export interface HookResult {
+  success: boolean;
+  outputs: Record<string, unknown>;
+  error?: string;
+  /** Path to failure screenshot, if captured */
+  screenshotPath?: string;
+  /** Duration in milliseconds */
+  duration: number;
+}
+
+/**
+ * Supported lifecycle hook names.
+ *
+ * Must stay in sync with the canonical hook list in
+ * `apps/celilo/src/manifest/contracts/v1.ts` and with the schema's
+ * `hooks` block in `apps/celilo/src/manifest/schema.ts`.
+ */
+export type HookName =
+  | 'container_created'
+  | 'on_install'
+  | 'on_uninstall'
+  | 'health_check'
+  | 'validate_config'
+  | 'on_backup'
+  | 'on_backup_analyze'
+  | 'on_restore';
+
+/**
+ * Hook manifest section - maps hook names to definitions
+ */
+export type HookManifest = Partial<Record<HookName, HookDefinition>>;

package/src/infrastructure/property-extractor.test.ts

@@ -0,0 +1,194 @@
+import { describe, expect, test } from 'bun:test';
+import type { Machine } from '@/types/infrastructure';
+import {
+  type ProxmoxProviderConfig,
+  extractMachineProperties,
+  extractProxmoxProperties,
+  extractTerraformProperties,
+} from './property-extractor';
+
+// Test fixture for Proxmox provider config
+const mockProxmoxConfig: ProxmoxProviderConfig = {
+  default_target_node: 'node2',
+  lxc_template: 'local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst',
+  storage: 'local-lvm',
+};
+
+describe('extractMachineProperties', () => {
+  test('extracts properties from machine record', () => {
+    const machine: Machine = {
+      id: 'machine-123',
+      hostname: 'dns-ext',
+      ipAddress: '203.0.113.42',
+      sshUser: 'root',
+      sshKeyEncrypted: 'encrypted-key',
+      hardware: { cpu_cores: 2, memory_mb: 2048, disk_gb: 20 },
+      zone: 'external',
+      role: 'host',
+      interfaces: [],
+      assignedModuleIds: [],
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    const properties = extractMachineProperties(machine);
+
+    expect(properties).toEqual({
+      'ip.primary': '203.0.113.42',
+      hostname: 'dns-ext',
+      id: 'machine-123',
+    });
+  });
+
+  test('translates from camelCase to dot notation', () => {
+    const machine: Machine = {
+      id: 'machine-456',
+      hostname: 'test-host',
+      ipAddress: '192.168.1.100', // camelCase in code
+      sshUser: 'ubuntu',
+      sshKeyEncrypted: 'encrypted',
+      hardware: { cpu_cores: 1, memory_mb: 1024, disk_gb: 10 },
+      zone: 'internal',
+      role: 'host',
+      interfaces: [],
+      assignedModuleIds: [],
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+
+    const properties = extractMachineProperties(machine);
+
+    // Verify camelCase → dot notation translation
+    expect(properties['ip.primary']).toBe('192.168.1.100');
+    expect(properties.ipAddress).toBeUndefined(); // Should not have camelCase key
+  });
+});
+
+describe('extractProxmoxProperties', () => {
+  test('extracts properties from IPAM allocation', () => {
+    const properties = extractProxmoxProperties(100, '10.0.10.5', 'homebridge', mockProxmoxConfig);
+
+    expect(properties).toEqual({
+      'ip.primary': '10.0.10.5',
+      hostname: 'homebridge',
+      id: '100',
+      target_node: 'node2',
+      lxc_template: 'local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst',
+      storage: 'local-lvm',
+    });
+  });
+
+  test('converts vmid number to string', () => {
+    const properties = extractProxmoxProperties(12345, '10.0.20.15', 'caddy', mockProxmoxConfig);
+
+    expect(properties.id).toBe('12345');
+    expect(typeof properties.id).toBe('string');
+  });
+
+  test('uses container IP as primary IP', () => {
+    const properties = extractProxmoxProperties(100, '10.0.10.5', 'test', mockProxmoxConfig);
+
+    // Container IP (from IPAM) becomes the primary IP
+    expect(properties['ip.primary']).toBe('10.0.10.5');
+  });
+
+  test('includes provider config properties', () => {
+    const properties = extractProxmoxProperties(100, '10.0.10.5', 'test', mockProxmoxConfig);
+
+    expect(properties.target_node).toBe('node2');
+    expect(properties.lxc_template).toBe(
+      'local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst',
+    );
+    expect(properties.storage).toBe('local-lvm');
+  });
+});
+
+describe('extractTerraformProperties', () => {
+  test('extracts properties from unwrapped Terraform output', () => {
+    const terraformOutputs = {
+      droplet_ip: '203.0.113.42',
+      droplet_id: '123456789',
+    };
+
+    const properties = extractTerraformProperties(terraformOutputs, 'dns-external');
+
+    expect(properties).toEqual({
+      'ip.primary': '203.0.113.42',
+      hostname: 'dns-external',
+      id: '123456789',
+    });
+  });
+
+  test('extracts properties from wrapped Terraform output format', () => {
+    // Terraform output -json format wraps values in objects
+    const terraformOutputs = {
+      droplet_ip: {
+        value: '198.51.100.50',
+        type: 'string',
+        sensitive: false,
+      },
+      droplet_id: {
+        value: '987654321',
+        type: 'string',
+        sensitive: false,
+      },
+    };
+
+    const properties = extractTerraformProperties(terraformOutputs, 'web-server');
+
+    expect(properties).toEqual({
+      'ip.primary': '198.51.100.50',
+      hostname: 'web-server',
+      id: '987654321',
+    });
+  });
+
+  test('handles numeric droplet ID', () => {
+    const terraformOutputs = {
+      droplet_ip: '203.0.113.42',
+      droplet_id: {
+        value: 123456789, // Number instead of string
+        type: 'number',
+        sensitive: false,
+      },
+    };
+
+    const properties = extractTerraformProperties(terraformOutputs, 'test');
+
+    expect(properties.id).toBe('123456789');
+    expect(typeof properties.id).toBe('string');
+  });
+
+  test('throws on missing droplet_ip', () => {
+    const terraformOutputs = {
+      droplet_id: '123456789',
+      // droplet_ip missing
+    };
+
+    expect(() => extractTerraformProperties(terraformOutputs, 'test')).toThrow(
+      'Missing required Terraform outputs',
+    );
+  });
+
+  test('throws on missing droplet_id', () => {
+    const terraformOutputs = {
+      droplet_ip: '203.0.113.42',
+      // droplet_id missing
+    };
+
+    expect(() => extractTerraformProperties(terraformOutputs, 'test')).toThrow(
+      'Missing required Terraform outputs',
+    );
+  });
+
+  test('throws on invalid output format', () => {
+    const terraformOutputs = {
+      droplet_ip: { invalid: 'format' }, // Missing 'value' key
+      droplet_id: '123456789',
+    };
+
+    expect(() => extractTerraformProperties(terraformOutputs, 'test')).toThrow(
+      'Invalid Terraform output format',
+    );
+  });
+});

package/src/infrastructure/property-extractor.ts

@@ -0,0 +1,151 @@
+import type { Machine } from '@/types/infrastructure';
+import { z } from 'zod';
+
+/**
+ * Zod schema for Terraform output values
+ * Terraform can return plain values or wrapped in { value, type, sensitive }
+ * Validates external data from terraform output -json (Rule 3.7)
+ */
+const TerraformOutputValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.object({
+    value: z.union([z.string(), z.number()]),
+    type: z.string().optional(),
+    sensitive: z.boolean().optional(),
+  }),
+]);
+
+/**
+ * Zod schema for Digital Ocean Terraform outputs
+ * Expects droplet_ip and droplet_id outputs from Terraform
+ */
+const DigitalOceanOutputSchema = z.object({
+  droplet_ip: TerraformOutputValueSchema,
+  droplet_id: TerraformOutputValueSchema,
+});
+
+/**
+ * Extract infrastructure properties from a machine.
+ * Translates from TypeScript camelCase to dot notation user-facing format.
+ *
+ * @param machine - Machine record from database
+ * @returns Infrastructure properties with dot notation keys
+ */
+export function extractMachineProperties(machine: Machine): Record<string, string> {
+  return {
+    'ip.primary': machine.ipAddress,
+    hostname: machine.hostname,
+    id: machine.id,
+  };
+}
+
+/**
+ * Proxmox provider configuration shape
+ */
+export interface ProxmoxProviderConfig {
+  default_target_node: string;
+  lxc_template: string;
+  storage: string;
+}
+
+/**
+ * Extract infrastructure properties from IPAM allocation (Proxmox).
+ * Used when container service allocates IP via IPAM before Terraform runs.
+ *
+ * @param vmid - Proxmox VMID allocated by IPAM
+ * @param containerIp - Container IP allocated by IPAM
+ * @param hostname - Container hostname
+ * @param providerConfig - Proxmox provider configuration from container service
+ * @returns Infrastructure properties with dot notation keys
+ */
+export function extractProxmoxProperties(
+  vmid: number,
+  containerIp: string,
+  hostname: string,
+  providerConfig: ProxmoxProviderConfig,
+): Record<string, string> {
+  return {
+    'ip.primary': containerIp,
+    hostname: hostname,
+    id: vmid.toString(),
+    target_node: providerConfig.default_target_node,
+    lxc_template: providerConfig.lxc_template,
+    storage: providerConfig.storage,
+  };
+}
+
+/**
+ * Extract infrastructure properties from Terraform outputs (Digital Ocean).
+ * Parses Terraform's JSON output format which can wrap values in objects.
+ * Validates output structure before extraction (Rule 3.7).
+ *
+ * @param outputs - Terraform output JSON (from `terraform output -json`)
+ * @param hostname - Container hostname
+ * @returns Infrastructure properties with dot notation keys
+ */
+export function extractTerraformProperties(
+  outputs: Record<string, unknown>,
+  hostname: string,
+): Record<string, string> {
+  // Validate structure matches Digital Ocean expectations
+  let validated: z.infer<typeof DigitalOceanOutputSchema>;
+  try {
+    validated = DigitalOceanOutputSchema.parse(outputs);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      // Check for missing top-level fields (completely absent from outputs)
+      const topLevelErrors = error.errors.filter((e) => e.path.length === 1);
+      const hasUndefinedFields = topLevelErrors.some((e) => {
+        if (e.code === 'invalid_union') {
+          // For union errors, check if the field is actually undefined
+          const fieldName = e.path[0] as string;
+          return !(fieldName in outputs); // Field is truly missing
+        }
+        return e.code === 'invalid_type' && e.received === 'undefined';
+      });
+
+      if (hasUndefinedFields) {
+        throw new Error(
+          'Missing required Terraform outputs: droplet_ip and droplet_id must be defined',
+        );
+      }
+
+      // Invalid format (field exists but doesn't match expected types)
+      throw new Error(`Invalid Terraform output format: ${JSON.stringify(outputs)}`);
+    }
+    throw error;
+  }
+
+  // Terraform output format can be:
+  // { "droplet_ip": "203.0.113.42" } OR
+  // { "droplet_ip": { "value": "203.0.113.42", "type": "string", "sensitive": false } }
+
+  const unwrapOutput = (value: unknown): string => {
+    if (typeof value === 'string') {
+      return value;
+    }
+    if (typeof value === 'number') {
+      return value.toString();
+    }
+    if (typeof value === 'object' && value !== null && 'value' in value) {
+      const wrapped = value as { value: unknown };
+      if (typeof wrapped.value === 'string') {
+        return wrapped.value;
+      }
+      if (typeof wrapped.value === 'number') {
+        return wrapped.value.toString();
+      }
+    }
+    throw new Error(`Invalid Terraform output format: ${JSON.stringify(value)}`);
+  };
+
+  const dropletIp = unwrapOutput(validated.droplet_ip);
+  const dropletId = unwrapOutput(validated.droplet_id);
+
+  return {
+    'ip.primary': dropletIp,
+    hostname: hostname,
+    id: dropletId,
+  };
+}