@kadi.build/deploy-ability 0.0.1

package/dist/targets/local/deployer.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Local Deployment Orchestrator
+ *
+ * Main orchestration logic for local Docker/Podman deployments.
+ * Coordinates engine management, network setup, compose generation,
+ * and container orchestration.
+ *
+ * This module ties together all the local deployment components:
+ * - Engine verification and startup
+ * - Network creation
+ * - Compose file generation
+ * - Container deployment
+ *
+ * @module targets/local/deployer
+ */
+import { type LocalDeploymentOptions, type LocalDeploymentResult } from '../../types/index.js';
+/**
+ * Performs a local deployment using Docker or Podman Compose
+ *
+ * This is the main orchestration function that executes a complete
+ * local deployment workflow:
+ *
+ * 1. **Profile Loading** - Load and validate deployment profile from agent.json
+ * 2. **Engine Verification** - Ensure container engine is running (auto-start Podman if needed)
+ * 3. **Network Setup** - Create required Docker network for inter-service communication
+ * 4. **Compose Generation** - Generate docker-compose.yml from service configurations
+ * 5. **File Writing** - Write compose file to disk
+ * 6. **Container Deployment** - Execute `docker compose up -d` to start services
+ *
+ * **Dry Run Mode:**
+ * When `dryRun: true` is set, all validation and generation steps are performed,
+ * but no actual deployment occurs. The generated compose file is returned in the
+ * result for inspection.
+ *
+ * **Progress Tracking:**
+ * Provide an `onProgress` callback to receive real-time updates about deployment
+ * progress. Events include phase, message, and optional metadata.
+ *
+ * @param options - Local deployment options
+ * @returns Result with deployment information or error
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const result = await deployLocal({
+ *   projectRoot: '/path/to/project',
+ *   profile: 'local-dev'
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Deployed services:', result.data.services);
+ *   console.log('Endpoints:', result.data.endpoints);
+ * } else {
+ *   console.error('Deployment failed:', result.error.getUserMessage());
+ * }
+ * ```
+ *
+ * @example With Progress Tracking
+ * ```typescript
+ * const result = await deployLocal({
+ *   projectRoot: process.cwd(),
+ *   profile: 'production-local',
+ *   onProgress: (event) => {
+ *     console.log(`[${event.phase}] ${event.message}`);
+ *   }
+ * });
+ * ```
+ *
+ * @example Dry Run
+ * ```typescript
+ * const result = await deployLocal({
+ *   projectRoot: process.cwd(),
+ *   dryRun: true
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Generated compose file:');
+ *   console.log(result.data.composeFile);
+ * }
+ * ```
+ */
+export declare function deployLocal(options: LocalDeploymentOptions): Promise<LocalDeploymentResult>;
+//# sourceMappingURL=deployer.d.ts.map

package/dist/targets/local/deployer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployer.d.ts","sourceRoot":"","sources":["../../../src/targets/local/deployer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,sBAAsB,CAAC;AAqF9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CA0UhC"}

package/dist/targets/local/deployer.js

@@ -0,0 +1,367 @@
+/**
+ * Local Deployment Orchestrator
+ *
+ * Main orchestration logic for local Docker/Podman deployments.
+ * Coordinates engine management, network setup, compose generation,
+ * and container orchestration.
+ *
+ * This module ties together all the local deployment components:
+ * - Engine verification and startup
+ * - Network creation
+ * - Compose file generation
+ * - Container deployment
+ *
+ * @module targets/local/deployer
+ */
+import debug from 'debug';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { success, failure, } from '../../types/index.js';
+import { DeploymentError } from '../../errors/index.js';
+import { loadProfile } from '../../utils/profile-loader.js';
+import { runCommand } from '../../utils/command-runner.js';
+import { ensureEngineRunning } from './engine-manager.js';
+import { ensureNetwork } from './network-manager.js';
+import { generateComposeYAML, } from './compose-generator.js';
+/**
+ * Debug logger for deployment orchestration
+ */
+const log = debug('deploy-ability:local:deploy');
+/**
+ * Default network name for KADI deployments
+ */
+const DEFAULT_NETWORK = 'kadi-net';
+/**
+ * Default compose file name
+ */
+const DEFAULT_COMPOSE_FILE = 'docker-compose.yml';
+/**
+ * Maps local deployment phase to general deployment phase
+ *
+ * @param phase - Local deployment phase
+ * @returns General deployment phase
+ *
+ * @internal
+ */
+function mapLocalPhaseToDeploymentPhase(phase) {
+    switch (phase) {
+        case 'profile':
+            return 'loading-profile';
+        case 'engine':
+        case 'network':
+            return 'initializing';
+        case 'compose':
+        case 'deploy':
+            return 'creating-deployment';
+        case 'complete':
+            return 'completed';
+    }
+}
+/**
+ * Emits a progress event if onProgress callback is provided
+ *
+ * Converts local deployment phases to general deployment phases
+ * for compatibility with the common progress callback interface.
+ *
+ * @param options - Deployment options
+ * @param phase - Local deployment phase
+ * @param message - Progress message
+ * @param progress - Optional progress percentage (0-100)
+ *
+ * @internal
+ */
+function emitProgress(options, phase, message, progress) {
+    if (options.onProgress) {
+        log('Progress: %s - %s', phase, message);
+        options.onProgress({
+            phase: mapLocalPhaseToDeploymentPhase(phase),
+            message,
+            progress,
+            data: {
+                localPhase: phase,
+            },
+        });
+    }
+}
+/**
+ * Performs a local deployment using Docker or Podman Compose
+ *
+ * This is the main orchestration function that executes a complete
+ * local deployment workflow:
+ *
+ * 1. **Profile Loading** - Load and validate deployment profile from agent.json
+ * 2. **Engine Verification** - Ensure container engine is running (auto-start Podman if needed)
+ * 3. **Network Setup** - Create required Docker network for inter-service communication
+ * 4. **Compose Generation** - Generate docker-compose.yml from service configurations
+ * 5. **File Writing** - Write compose file to disk
+ * 6. **Container Deployment** - Execute `docker compose up -d` to start services
+ *
+ * **Dry Run Mode:**
+ * When `dryRun: true` is set, all validation and generation steps are performed,
+ * but no actual deployment occurs. The generated compose file is returned in the
+ * result for inspection.
+ *
+ * **Progress Tracking:**
+ * Provide an `onProgress` callback to receive real-time updates about deployment
+ * progress. Events include phase, message, and optional metadata.
+ *
+ * @param options - Local deployment options
+ * @returns Result with deployment information or error
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const result = await deployLocal({
+ *   projectRoot: '/path/to/project',
+ *   profile: 'local-dev'
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Deployed services:', result.data.services);
+ *   console.log('Endpoints:', result.data.endpoints);
+ * } else {
+ *   console.error('Deployment failed:', result.error.getUserMessage());
+ * }
+ * ```
+ *
+ * @example With Progress Tracking
+ * ```typescript
+ * const result = await deployLocal({
+ *   projectRoot: process.cwd(),
+ *   profile: 'production-local',
+ *   onProgress: (event) => {
+ *     console.log(`[${event.phase}] ${event.message}`);
+ *   }
+ * });
+ * ```
+ *
+ * @example Dry Run
+ * ```typescript
+ * const result = await deployLocal({
+ *   projectRoot: process.cwd(),
+ *   dryRun: true
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Generated compose file:');
+ *   console.log(result.data.composeFile);
+ * }
+ * ```
+ */
+export async function deployLocal(options) {
+    const { projectRoot, profile: profileName, engine: engineOverride, network: networkOverride, composeOutputPath: composePathOverride, dryRun = false, verbose = false, logger, } = options;
+    log('Starting local deployment');
+    log('Project root: %s', projectRoot);
+    log('Profile: %s', profileName || '(default)');
+    log('Dry run: %s', dryRun);
+    // -------------------------------------------------------------------------
+    // Phase 1: Load and validate deployment profile
+    // -------------------------------------------------------------------------
+    emitProgress(options, 'profile', 'Loading deployment profile');
+    let loadedProfile;
+    try {
+        loadedProfile = await loadProfile(projectRoot, profileName, logger);
+    }
+    catch (error) {
+        log('Profile loading failed: %s', error.message);
+        return failure(new DeploymentError(`Failed to load deployment profile: ${error.message}`, 'PROFILE_LOAD_ERROR', {
+            projectRoot,
+            profileName,
+            error: error.message,
+        }, true, 'Check that agent.json exists and has valid deploy configuration', 'error', error));
+    }
+    const { name: selectedProfileName, profile } = loadedProfile;
+    // Validate this is a local profile
+    if (profile.target !== 'local') {
+        log('Profile is not a local target: %s', profile.target);
+        return failure(new DeploymentError(`Profile "${selectedProfileName}" is not a local deployment profile (target: "${profile.target}")`, 'PROFILE_INVALID', {
+            profileName: selectedProfileName,
+            target: profile.target,
+        }, true, 'Select a profile with target: "local"', 'error'));
+    }
+    // Extract configuration with overrides
+    const engine = engineOverride ?? profile.engine ?? 'docker';
+    const networkName = networkOverride ?? profile.network ?? DEFAULT_NETWORK;
+    const composePath = composePathOverride ?? path.join(projectRoot, DEFAULT_COMPOSE_FILE);
+    log('Configuration: engine=%s network=%s', engine, networkName);
+    const serviceNames = Object.keys(profile.services);
+    log('Services to deploy: %s', serviceNames.join(', '));
+    // -------------------------------------------------------------------------
+    // Phase 2: Dry run - preview without executing
+    // -------------------------------------------------------------------------
+    if (dryRun) {
+        log('Dry run mode - generating preview');
+        emitProgress(options, 'compose', 'Generating compose file (dry run)');
+        const composeResult = generateComposeYAML(profile.services, {
+            networkName,
+            containerPrefix: 'kadi',
+        });
+        if (!composeResult.success) {
+            log('Compose generation failed: %s', composeResult.error.message);
+            return failure(composeResult.error);
+        }
+        log('Dry run complete - returning preview data');
+        return success({
+            dryRun: true,
+            profile: selectedProfileName,
+            engine,
+            services: serviceNames,
+            composeFile: composeResult.data,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Phase 3: Ensure container engine is running
+    // -------------------------------------------------------------------------
+    emitProgress(options, 'engine', `Ensuring ${engine} is running`);
+    const engineResult = await ensureEngineRunning(engine, {
+        timeout: 60_000,
+        autoStart: true,
+    });
+    if (!engineResult.success) {
+        log('Engine check failed: %s', engineResult.error.message);
+        logger?.error(`❌ ${engine} is not available`);
+        return failure(engineResult.error);
+    }
+    log('Engine ready (autoStarted=%s)', engineResult.data.autoStarted);
+    // -------------------------------------------------------------------------
+    // Phase 4: Create or verify network
+    // -------------------------------------------------------------------------
+    emitProgress(options, 'network', `Setting up network: ${networkName}`);
+    const networkResult = await ensureNetwork(engine, networkName, {
+        timeout: 30_000,
+        driver: 'bridge',
+    });
+    if (!networkResult.success) {
+        log('Network setup failed: %s', networkResult.error.message);
+        logger?.error(`❌ Failed to create network ${networkName}`);
+        return failure(networkResult.error);
+    }
+    log('Network ready (preexisting=%s)', networkResult.data.preexisting);
+    // -------------------------------------------------------------------------
+    // Phase 5: Generate Docker Compose file
+    // -------------------------------------------------------------------------
+    emitProgress(options, 'compose', 'Generating docker-compose.yml');
+    const composeOptions = {
+        version: '3.9',
+        networkName,
+        containerPrefix: 'kadi',
+        tty: true,
+        stdinOpen: true,
+    };
+    const composeResult = generateComposeYAML(profile.services, composeOptions);
+    if (!composeResult.success) {
+        log('Compose generation failed: %s', composeResult.error.message);
+        logger?.error('❌ Failed to generate docker-compose.yml');
+        return failure(composeResult.error);
+    }
+    log('Compose file generated: %d bytes', composeResult.data.length);
+    // -------------------------------------------------------------------------
+    // Phase 6: Write compose file to disk
+    // -------------------------------------------------------------------------
+    emitProgress(options, 'compose', `Writing compose file to ${composePath}`);
+    try {
+        await fs.writeFile(composePath, composeResult.data, 'utf8');
+        log('Compose file written to: %s', composePath);
+    }
+    catch (error) {
+        log('Failed to write compose file: %s', error.message);
+        return failure(new DeploymentError(`Failed to write docker-compose.yml to ${composePath}`, 'FILE_WRITE_ERROR', {
+            path: composePath,
+            error: error.message,
+        }, true, 'Check file permissions and disk space', 'error', error));
+    }
+    // -------------------------------------------------------------------------
+    // Phase 7: Deploy services with docker compose
+    // -------------------------------------------------------------------------
+    emitProgress(options, 'deploy', 'Starting services');
+    // Use -d flag for detached mode (background)
+    const composeUpCommand = `${engine} compose up -d`;
+    log('Executing: %s', composeUpCommand);
+    const deployResult = await runCommand(composeUpCommand, {
+        cwd: projectRoot,
+        timeout: 300_000, // 5 minutes for container pulls
+        silent: !verbose,
+    });
+    if (!deployResult.success) {
+        log('Deployment failed: %s', deployResult.error.message);
+        logger?.error('❌ Deployment failed');
+        return failure(new DeploymentError('Failed to start services with docker compose', 'COMPOSE_UP_FAILED', {
+            engine,
+            command: composeUpCommand,
+            error: deployResult.error.message,
+            exitCode: deployResult.error.context.exitCode,
+        }, true, 'Check docker compose output for errors, ensure images exist', 'error', deployResult.error));
+    }
+    log('Deployment completed successfully');
+    // -------------------------------------------------------------------------
+    // Phase 8: Extract container information
+    // -------------------------------------------------------------------------
+    emitProgress(options, 'complete', 'Getting container information');
+    // Get container IDs from docker compose ps
+    const psCommand = `${engine} compose ps --quiet`;
+    log('Getting container IDs: %s', psCommand);
+    const psResult = await runCommand(psCommand, {
+        cwd: projectRoot,
+        timeout: 30_000,
+        silent: true,
+    });
+    const containersMap = {};
+    if (psResult.success) {
+        const containerIds = psResult.data.stdout.trim().split('\n').filter(id => id);
+        log('Found %d containers', containerIds.length);
+        // Map container IDs to service names
+        // Get full container info to match names
+        for (const containerId of containerIds) {
+            const inspectCmd = `${engine} inspect ${containerId} --format '{{.Name}}'`;
+            const inspectResult = await runCommand(inspectCmd, {
+                timeout: 10_000,
+                silent: true,
+            });
+            if (inspectResult.success) {
+                const containerName = inspectResult.data.stdout.trim().replace(/^\//, ''); // Remove leading /
+                // Match container name to service name
+                // Container names are typically: kadi-{serviceName} or {project}_{serviceName}_1
+                for (const serviceName of serviceNames) {
+                    if (containerName.includes(serviceName)) {
+                        containersMap[serviceName] = containerId.substring(0, 12); // Short ID
+                        log('Mapped service %s to container %s', serviceName, containerId.substring(0, 12));
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    else {
+        log('Failed to get container IDs: %s', psResult.error.message);
+        // Non-fatal - continue without container IDs
+    }
+    // -------------------------------------------------------------------------
+    // Phase 9: Build endpoint information
+    // -------------------------------------------------------------------------
+    // Extract endpoints from service configurations
+    const endpointsMap = {};
+    for (const [serviceName, serviceConfig] of Object.entries(profile.services)) {
+        const config = serviceConfig;
+        if (config.expose) {
+            for (const portConfig of config.expose) {
+                const externalPort = portConfig.as ?? portConfig.port;
+                // Use first exposed port as primary endpoint for this service
+                if (!endpointsMap[serviceName]) {
+                    endpointsMap[serviceName] = `http://localhost:${externalPort}`;
+                }
+            }
+        }
+    }
+    log('Endpoints: %o', endpointsMap);
+    log('Containers: %o', containersMap);
+    return success({
+        profile: selectedProfileName,
+        engine,
+        network: networkResult.data.name,
+        services: serviceNames,
+        containers: containersMap,
+        endpoints: endpointsMap,
+        composePath,
+        deployedAt: new Date(),
+    });
+}
+//# sourceMappingURL=deployer.js.map

package/dist/targets/local/deployer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployer.js","sourceRoot":"","sources":["../../../src/targets/local/deployer.ts"],"names":[],"mappings":"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"}

package/dist/targets/local/engine-manager.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Container Engine Management Module
+ *
+ * Manages Docker and Podman container engine lifecycle, ensuring engines
+ * are running and accessible before deployment operations.
+ *
+ * Key Features:
+ * - Automatic Podman VM startup on macOS/Windows
+ * - Health checks and connectivity verification
+ * - Structured error handling with recovery suggestions
+ * - Type-safe Result returns (no throwing)
+ *
+ * @module targets/local/engine-manager
+ */
+import { type Result, type ContainerEngine } from '../../types/index.js';
+import { DeploymentError } from '../../errors/index.js';
+import { type CommandOptions } from '../../utils/command-runner.js';
+/**
+ * Container engine information
+ *
+ * Returned after successful engine verification, providing
+ * structured data about the running engine.
+ */
+export interface EngineInfo {
+    /**
+     * Engine type
+     */
+    readonly engine: ContainerEngine;
+    /**
+     * Whether engine is running
+     */
+    readonly running: boolean;
+    /**
+     * Engine version string
+     */
+    readonly version?: string;
+    /**
+     * Whether this engine was auto-started by us
+     */
+    readonly autoStarted: boolean;
+    /**
+     * Platform the engine is running on
+     */
+    readonly platform?: string;
+}
+/**
+ * Options for engine verification
+ */
+export interface EngineCheckOptions {
+    /**
+     * Timeout for engine operations in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    readonly timeout?: number;
+    /**
+     * Whether to attempt auto-starting the engine
+     * @default true
+     */
+    readonly autoStart?: boolean;
+    /**
+     * Command execution options
+     */
+    readonly commandOptions?: CommandOptions;
+}
+/**
+ * Checks if a container engine is running and accessible
+ *
+ * Performs a health check by running `docker info` or `podman info`.
+ * Returns structured engine information if successful.
+ *
+ * **Does NOT auto-start the engine** - use `ensureEngineRunning` for that.
+ *
+ * @param engine - Container engine to check
+ * @param options - Check options
+ * @returns Result with engine info or error
+ *
+ * @example
+ * ```typescript
+ * const result = await checkEngineRunning('docker');
+ *
+ * if (result.success) {
+ *   console.log(`Docker is running: v${result.data.version}`);
+ * } else {
+ *   console.error('Docker not available:', result.error.message);
+ * }
+ * ```
+ */
+export declare function checkEngineRunning(engine: ContainerEngine, options?: EngineCheckOptions): Promise<Result<EngineInfo, DeploymentError>>;
+/**
+ * Ensures a container engine is running and accessible
+ *
+ * This is the main entry point for engine management. It will:
+ *
+ * **For Docker:**
+ * - Check if Docker daemon is running
+ * - Return error if not (cannot auto-start Docker)
+ * - Provide clear instructions for manual startup
+ *
+ * **For Podman:**
+ * - Check if Podman socket is available
+ * - Automatically start Podman VM if not running (macOS/Windows)
+ * - Wait for VM to become ready
+ * - Return error if auto-start fails
+ *
+ * This eliminates common "connection refused" errors and provides
+ * a better developer experience, especially with Podman's VM architecture.
+ *
+ * @param engine - Container engine to ensure is running
+ * @param options - Engine check options
+ * @returns Result with engine info or error
+ *
+ * @example
+ * ```typescript
+ * const result = await ensureEngineRunning('podman', { autoStart: true });
+ *
+ * if (result.success) {
+ *   console.log('Engine ready:', result.data);
+ *   if (result.data.autoStarted) {
+ *     console.log('Podman VM was automatically started');
+ *   }
+ * } else {
+ *   console.error('Engine error:', result.error.getUserMessage());
+ *   console.error('Suggestion:', result.error.suggestion);
+ * }
+ * ```
+ *
+ * @example With custom timeout
+ * ```typescript
+ * const result = await ensureEngineRunning('docker', {
+ *   timeout: 10_000,
+ *   autoStart: false
+ * });
+ * ```
+ */
+export declare function ensureEngineRunning(engine: ContainerEngine, options?: EngineCheckOptions): Promise<Result<EngineInfo, DeploymentError>>;
+/**
+ * Gets version information for a container engine
+ *
+ * Convenience function to extract just the version string from an engine.
+ *
+ * @param engine - Container engine to check
+ * @param options - Check options
+ * @returns Result with version string or error
+ *
+ * @example
+ * ```typescript
+ * const result = await getEngineVersion('docker');
+ *
+ * if (result.success) {
+ *   console.log('Docker version:', result.data);
+ * }
+ * ```
+ */
+export declare function getEngineVersion(engine: ContainerEngine, options?: EngineCheckOptions): Promise<Result<string, DeploymentError>>;
+//# sourceMappingURL=engine-manager.d.ts.map

package/dist/targets/local/engine-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-manager.d.ts","sourceRoot":"","sources":["../../../src/targets/local/engine-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EACL,KAAK,MAAM,EAGX,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAOhF;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC,CAyD9C;AA+ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC,CA4D9C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAqB1C"}