@kadi.build/deploy-ability 0.0.1

package/dist/targets/local/engine-manager.js

@@ -0,0 +1,250 @@
+/**
+ * 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 debug from 'debug';
+import { success, failure, } from '../../types/index.js';
+import { DeploymentError } from '../../errors/index.js';
+import { runCommand } from '../../utils/command-runner.js';
+/**
+ * Debug logger for engine operations
+ */
+const log = debug('deploy-ability:local:engine');
+/**
+ * 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 async function checkEngineRunning(engine, options = {}) {
+    const { timeout = 30_000, commandOptions } = options;
+    log('Checking if %s is running', engine);
+    const infoCommand = `${engine} info --format json`;
+    const result = await runCommand(infoCommand, {
+        ...commandOptions,
+        timeout,
+        silent: true,
+    });
+    if (!result.success) {
+        log('%s is not running: %s', engine, result.error.message);
+        return failure(new DeploymentError(`${engine} is not running or not accessible`, 'ENGINE_NOT_RUNNING', {
+            engine,
+            command: infoCommand,
+            error: result.error.message,
+        }, true, engine === 'docker'
+            ? 'Start Docker Desktop or run "dockerd" manually, then retry'
+            : 'Run "podman machine start" manually, then retry', 'error', result.error));
+    }
+    log('%s is running', engine);
+    // Parse version and platform from info output
+    let version;
+    let platform;
+    try {
+        const info = JSON.parse(result.data.stdout);
+        version = info.version?.Version || info.Version;
+        platform = info.host?.os || info.host?.arch || process.platform;
+    }
+    catch {
+        // Ignore parsing errors - version/platform are optional
+        log('Could not parse engine info JSON');
+    }
+    return success({
+        engine,
+        running: true,
+        version,
+        platform,
+        autoStarted: false,
+    });
+}
+/**
+ * Attempts to start a Podman VM
+ *
+ * On macOS and Windows, Podman runs inside a VM that must be started
+ * before the engine can be used. This function handles the startup
+ * process and waits for the VM to become ready.
+ *
+ * @param options - Command execution options
+ * @returns Result indicating success or failure
+ *
+ * @internal
+ */
+async function startPodmanVM(options = {}) {
+    const { timeout = 60_000, commandOptions } = options;
+    log('Attempting to start Podman VM');
+    const startResult = await runCommand('podman machine start', {
+        ...commandOptions,
+        timeout,
+        silent: false,
+    });
+    if (!startResult.success) {
+        log('Failed to start Podman VM: %s', startResult.error.message);
+        return failure(new DeploymentError('Podman VM could not be started', 'PODMAN_VM_START_FAILED', {
+            command: 'podman machine start',
+            error: startResult.error.message,
+        }, true, 'Run "podman machine init" (first time only) and "podman machine start" manually', 'error', startResult.error));
+    }
+    log('Podman VM start command completed');
+    // Wait for socket to become available
+    log('Waiting for Podman socket to become available');
+    const checkResult = await runCommand('podman info --format json', {
+        ...commandOptions,
+        timeout: 30_000,
+        silent: true,
+    });
+    if (!checkResult.success) {
+        log('Podman socket did not become available: %s', checkResult.error.message);
+        return failure(new DeploymentError('Podman VM started but socket is not available', 'PODMAN_SOCKET_UNAVAILABLE', {
+            error: checkResult.error.message,
+        }, true, 'Wait a few seconds and retry, or run "podman machine stop && podman machine start"', 'error', checkResult.error));
+    }
+    log('Podman socket is now available');
+    return success(undefined);
+}
+/**
+ * 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 async function ensureEngineRunning(engine, options = {}) {
+    const { autoStart = true } = options;
+    log('Ensuring %s is running (autoStart: %s)', engine, autoStart);
+    // Fast path: check if engine is already running
+    const checkResult = await checkEngineRunning(engine, options);
+    if (checkResult.success) {
+        log('%s is already running', engine);
+        return checkResult;
+    }
+    // Engine not running - check if we can auto-start
+    if (!autoStart) {
+        log('Auto-start disabled, returning error');
+        return checkResult;
+    }
+    // Docker cannot be auto-started (platform-specific, complex)
+    if (engine === 'docker') {
+        log('Cannot auto-start Docker, returning error');
+        return checkResult;
+    }
+    // For Podman, check if this is a connection error we can fix
+    const errorMessage = checkResult.error.context.error;
+    const isConnectionError = /cannot connect to podman|unable to connect|dial unix/i.test(errorMessage);
+    if (!isConnectionError) {
+        log('Not a connection error, cannot auto-start: %s', errorMessage);
+        return checkResult;
+    }
+    // Attempt to auto-start Podman VM
+    log('Attempting auto-start of Podman VM');
+    const startResult = await startPodmanVM(options);
+    if (!startResult.success) {
+        log('Auto-start failed');
+        return failure(startResult.error);
+    }
+    log('Auto-start succeeded, verifying engine is running');
+    // Verify engine is now running
+    const verifyResult = await checkEngineRunning(engine, options);
+    if (verifyResult.success) {
+        log('Engine verified running after auto-start');
+        return success({
+            ...verifyResult.data,
+            autoStarted: true,
+        });
+    }
+    log('Engine still not running after auto-start');
+    return verifyResult;
+}
+/**
+ * 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 async function getEngineVersion(engine, options = {}) {
+    const result = await checkEngineRunning(engine, options);
+    if (!result.success) {
+        return failure(result.error);
+    }
+    if (!result.data.version) {
+        return failure(new DeploymentError('Could not determine engine version', 'ENGINE_VERSION_UNKNOWN', { engine }, false, undefined, 'warning'));
+    }
+    return success(result.data.version);
+}
+//# sourceMappingURL=engine-manager.js.map

package/dist/targets/local/engine-manager.js.map

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

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

@@ -0,0 +1,40 @@
+/**
+ * Local Deployment Target - Public API
+ *
+ * Main entry point for local Docker/Podman deployments.
+ * Re-exports all public APIs and types for the local target.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { deployToLocal } from 'deploy-ability/local';
+ *
+ * const result = await deployToLocal({
+ *   projectRoot: '/path/to/project',
+ *   profile: 'local-dev'
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Deployed!', result.data.endpoints);
+ * }
+ * ```
+ *
+ * @example With Progress Tracking
+ * ```typescript
+ * import { deployToLocal } from 'deploy-ability/local';
+ *
+ * const result = await deployToLocal({
+ *   projectRoot: process.cwd(),
+ *   onProgress: (event) => {
+ *     console.log(`[${event.phase}] ${event.message}`);
+ *   }
+ * });
+ * ```
+ *
+ * @module targets/local
+ */
+export { deployLocal as deployToLocal } from './deployer.js';
+export { ensureEngineRunning, checkEngineRunning, getEngineVersion, type EngineInfo, type EngineCheckOptions, } from './engine-manager.js';
+export { ensureNetwork, networkExists, getNetworkInfo, removeNetwork, type NetworkOptions, type CreateNetworkOptions, } from './network-manager.js';
+export { generateComposeFile, generateComposeYAML, composeFileToYAML, convertEnvArrayToObject, convertPortsToComposeFormat, type ServiceInput, type ComposeGenerationOptions, } from './compose-generator.js';
+export type { ComposeFile, ComposeService, ComposeNetwork, PortMapping, RestartPolicy, NetworkMode, ContainerStatus, ContainerInfo, NetworkInfo, ServiceDependency, Healthcheck, VolumeMount, ServiceValidationError, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/targets/local/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,WAAW,IAAI,aAAa,EAAE,MAAM,eAAe,CAAC;AAG7D,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,uBAAuB,EACvB,2BAA2B,EAC3B,KAAK,YAAY,EACjB,KAAK,wBAAwB,GAC9B,MAAM,wBAAwB,CAAC;AAGhC,YAAY,EACV,WAAW,EACX,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/targets/local/index.js

@@ -0,0 +1,43 @@
+/**
+ * Local Deployment Target - Public API
+ *
+ * Main entry point for local Docker/Podman deployments.
+ * Re-exports all public APIs and types for the local target.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { deployToLocal } from 'deploy-ability/local';
+ *
+ * const result = await deployToLocal({
+ *   projectRoot: '/path/to/project',
+ *   profile: 'local-dev'
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Deployed!', result.data.endpoints);
+ * }
+ * ```
+ *
+ * @example With Progress Tracking
+ * ```typescript
+ * import { deployToLocal } from 'deploy-ability/local';
+ *
+ * const result = await deployToLocal({
+ *   projectRoot: process.cwd(),
+ *   onProgress: (event) => {
+ *     console.log(`[${event.phase}] ${event.message}`);
+ *   }
+ * });
+ * ```
+ *
+ * @module targets/local
+ */
+// Main deployment function
+export { deployLocal as deployToLocal } from './deployer.js';
+// Engine management
+export { ensureEngineRunning, checkEngineRunning, getEngineVersion, } from './engine-manager.js';
+// Network management
+export { ensureNetwork, networkExists, getNetworkInfo, removeNetwork, } from './network-manager.js';
+// Compose generation
+export { generateComposeFile, generateComposeYAML, composeFileToYAML, convertEnvArrayToObject, convertPortsToComposeFormat, } from './compose-generator.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/targets/local/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,2BAA2B;AAC3B,OAAO,EAAE,WAAW,IAAI,aAAa,EAAE,MAAM,eAAe,CAAC;AAE7D,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,GAGjB,MAAM,qBAAqB,CAAC;AAE7B,qBAAqB;AACrB,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,aAAa,GAGd,MAAM,sBAAsB,CAAC;AAE9B,qBAAqB;AACrB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,uBAAuB,EACvB,2BAA2B,GAG5B,MAAM,wBAAwB,CAAC"}

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

@@ -0,0 +1,160 @@
+/**
+ * Docker Network Management Module
+ *
+ * Manages Docker/Podman networks for KADI deployments, ensuring
+ * required networks exist and are properly configured for inter-service
+ * communication.
+ *
+ * Key Features:
+ * - Network creation with idempotency (safe to call multiple times)
+ * - Network inspection and validation
+ * - Automatic conflict resolution
+ * - Type-safe Result returns
+ *
+ * @module targets/local/network-manager
+ */
+import { type Result, type ContainerEngine } from '../../types/index.js';
+import { DeploymentError } from '../../errors/index.js';
+import { type CommandOptions } from '../../utils/command-runner.js';
+import type { NetworkInfo } from './types.js';
+/**
+ * Options for network operations
+ */
+export interface NetworkOptions {
+    /**
+     * Timeout for network operations in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    readonly timeout?: number;
+    /**
+     * Command execution options
+     */
+    readonly commandOptions?: CommandOptions;
+}
+/**
+ * Network creation options
+ */
+export interface CreateNetworkOptions extends NetworkOptions {
+    /**
+     * Network driver to use
+     * @default 'bridge'
+     */
+    readonly driver?: 'bridge' | 'host' | 'overlay' | 'macvlan' | 'none' | string;
+    /**
+     * Enable IPv6
+     * @default false
+     */
+    readonly ipv6?: boolean;
+    /**
+     * Additional driver options
+     */
+    readonly driverOpts?: Record<string, string>;
+}
+/**
+ * Checks if a Docker network exists
+ *
+ * Queries the container engine to verify if a network with the given
+ * name exists. Returns true if it exists, false otherwise.
+ *
+ * @param engine - Container engine to use
+ * @param networkName - Name of the network to check
+ * @param options - Network operation options
+ * @returns Result with boolean indicating existence
+ *
+ * @example
+ * ```typescript
+ * const result = await networkExists('docker', 'kadi-net');
+ *
+ * if (result.success && result.data) {
+ *   console.log('Network exists');
+ * } else if (result.success && !result.data) {
+ *   console.log('Network does not exist');
+ * } else {
+ *   console.error('Error checking network:', result.error.message);
+ * }
+ * ```
+ */
+export declare function networkExists(engine: ContainerEngine, networkName: string, options?: NetworkOptions): Promise<Result<boolean, DeploymentError>>;
+/**
+ * Gets detailed information about a Docker network
+ *
+ * Retrieves and parses network information including driver, scope,
+ * and whether the network was created externally.
+ *
+ * @param engine - Container engine to use
+ * @param networkName - Name of the network to inspect
+ * @param options - Network operation options
+ * @returns Result with network information
+ *
+ * @example
+ * ```typescript
+ * const result = await getNetworkInfo('docker', 'kadi-net');
+ *
+ * if (result.success) {
+ *   console.log('Network ID:', result.data.id);
+ *   console.log('Driver:', result.data.driver);
+ *   console.log('Pre-existing:', result.data.preexisting);
+ * }
+ * ```
+ */
+export declare function getNetworkInfo(engine: ContainerEngine, networkName: string, options?: NetworkOptions): Promise<Result<NetworkInfo, DeploymentError>>;
+/**
+ * Creates a Docker network if it doesn't already exist
+ *
+ * This function is idempotent - safe to call multiple times. If the
+ * network already exists, it will return success with `preexisting: true`.
+ *
+ * Handles the common "already exists" error gracefully and returns
+ * structured network information.
+ *
+ * @param engine - Container engine to use
+ * @param networkName - Name of the network to create
+ * @param options - Network creation options
+ * @returns Result with network information
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const result = await ensureNetwork('docker', 'kadi-net');
+ *
+ * if (result.success) {
+ *   if (result.data.preexisting) {
+ *     console.log('Network already existed');
+ *   } else {
+ *     console.log('Network created:', result.data.id);
+ *   }
+ * }
+ * ```
+ *
+ * @example With Custom Driver
+ * ```typescript
+ * const result = await ensureNetwork('docker', 'my-overlay-net', {
+ *   driver: 'overlay',
+ *   ipv6: true
+ * });
+ * ```
+ */
+export declare function ensureNetwork(engine: ContainerEngine, networkName: string, options?: CreateNetworkOptions): Promise<Result<NetworkInfo, DeploymentError>>;
+/**
+ * Removes a Docker network
+ *
+ * Deletes the specified network. Will fail if containers are still
+ * attached to the network.
+ *
+ * @param engine - Container engine to use
+ * @param networkName - Name of the network to remove
+ * @param options - Network operation options
+ * @returns Result indicating success or failure
+ *
+ * @example
+ * ```typescript
+ * const result = await removeNetwork('docker', 'kadi-net');
+ *
+ * if (result.success) {
+ *   console.log('Network removed');
+ * } else if (result.error.code === 'NETWORK_IN_USE') {
+ *   console.log('Network still has containers attached');
+ * }
+ * ```
+ */
+export declare function removeNetwork(engine: ContainerEngine, networkName: string, options?: NetworkOptions): Promise<Result<void, DeploymentError>>;
+//# sourceMappingURL=network-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"network-manager.d.ts","sourceRoot":"","sources":["../../../src/targets/local/network-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;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;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAO9C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAE9E;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CA8C3C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC,CA0F/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC,CA8I/C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,CAmExC"}