@kadi.build/deploy-ability 0.0.1

package/dist/utils/registry/manager.d.ts

@@ -0,0 +1,319 @@
+/**
+ * Temporary Container Registry Manager
+ *
+ * Manages a temporary container registry for making local Docker images accessible
+ * to Akash providers during deployment. Wraps the TunneledContainerRegistry from
+ * @kadi.build/container-registry-ability with deployment-specific logic.
+ *
+ * **Core Responsibilities:**
+ * - Start/stop temporary registry with public tunnel
+ * - Detect which images exist locally vs remotely
+ * - Push local images to temporary registry
+ * - Track image → registry URL mappings
+ * - Provide credentials for SDL generation
+ *
+ * @module utils/registry/manager
+ */
+import type { DeploymentLogger } from '../../types/common.js';
+import type { AkashDeploymentProfile } from '../../types/profiles.js';
+import type { RegistryCredentials, RegistryOptions } from './types.js';
+/**
+ * Temporary Container Registry Manager
+ *
+ * Manages the lifecycle of a temporary container registry that makes local images
+ * accessible to Akash providers. This class handles starting the registry, detecting
+ * local images, pushing them, and tracking URL transformations.
+ *
+ * **Typical Workflow:**
+ * ```typescript
+ * const manager = new TemporaryContainerRegistryManager(logger);
+ *
+ * // 1. Start registry
+ * await manager.startTemporaryRegistry({
+ *   tunnelService: 'serveo',
+ *   containerEngine: 'docker'
+ * });
+ *
+ * // 2. Add local images from profile
+ * await manager.addLocalImagesToTemporaryRegistry(profile, 'docker');
+ *
+ * // 3. Get transformed image URLs
+ * const url = manager.getPublicImageUrl('frontend', 'my-app:latest');
+ *
+ * // 4. Get credentials for SDL
+ * const creds = manager.getRegistryCredentials();
+ *
+ * // 5. Stop registry when done
+ * await manager.stopTemporaryRegistry();
+ * ```
+ */
+export declare class TemporaryContainerRegistryManager {
+    private logger;
+    private registry;
+    private registryInfo;
+    /**
+     * Maps original image names to their public registry URLs
+     *
+     * Key: Original image name (e.g., "my-app:latest")
+     * Value: Container mapping with registry URL and metadata
+     */
+    private containerMappings;
+    /**
+     * Create a new registry manager
+     *
+     * @param logger - Logger for progress and error messages
+     */
+    constructor(logger: DeploymentLogger);
+    /**
+     * Start temporary registry with public tunnel
+     *
+     * Creates a local container registry on the specified port and exposes it publicly
+     * via a tunnel service (ngrok, serveo, or bore). The registry is used to make
+     * local Docker images accessible to Akash providers during deployment.
+     *
+     * **What This Does:**
+     * 1. Loads environment variables (.env) for tunnel configuration
+     * 2. Starts local registry container on specified port
+     * 3. Creates public tunnel (ngrok/serveo/bore)
+     * 4. Generates authentication credentials
+     * 5. Returns when registry is accessible
+     *
+     * **Tunnel Services:**
+     * - **ngrok**: Most reliable, requires auth token (NGROK_AUTH_TOKEN env var)
+     * - **serveo**: Free SSH-based tunnel, no signup required
+     * - **bore**: Modern alternative using bore.pub
+     *
+     * @param options - Configuration options for registry and tunnel
+     * @throws Error if registry fails to start or tunnel cannot be established
+     *
+     * @example
+     * ```typescript
+     * await manager.startTemporaryRegistry({
+     *   port: 3000,
+     *   tunnelService: 'serveo',
+     *   containerEngine: 'docker',
+     *   registryDuration: 600000, // 10 minutes
+     *   autoShutdown: false
+     * });
+     * ```
+     */
+    startTemporaryRegistry(options: RegistryOptions): Promise<void>;
+    /**
+     * Display registry access information including domain and credentials
+     *
+     * Logs registry connection details for debugging purposes.
+     * Only logs if debug logging is enabled (DEBUG=deploy-ability:registry).
+     */
+    private displayRegistryAccessInformation;
+    /**
+     * Check if a container image exists locally
+     *
+     * Uses `docker images -q` or `podman images -q` to check if an image exists
+     * in the local container engine. This is the ground truth for whether we need
+     * to add an image to the temporary registry.
+     *
+     * **Why This Works:**
+     * - Returns image hash if image exists locally
+     * - Returns empty string if image doesn't exist
+     * - Works for both tagged and untagged images
+     * - Handles shorthand names correctly (e.g., "nginx" vs "docker.io/library/nginx")
+     *
+     * **Reality-Based Detection:**
+     * Instead of guessing based on image name patterns (checking for "/" in the name),
+     * we check the actual state of the local container engine. This prevents false
+     * positives and false negatives.
+     *
+     * @param imageName - Full image name with tag (e.g., "my-app:latest")
+     * @param engine - Container engine to use
+     * @returns True if image exists locally, false otherwise
+     */
+    private checkImageExistsLocally;
+    /**
+     * Add local images from deployment profile to the temporary registry
+     *
+     * **Simplified Logic (Reality-Based Detection):**
+     *
+     * Instead of guessing if an image is "local" based on name patterns (like checking
+     * if it has "/" in the name), we simply check if the image actually exists locally
+     * using `docker images -q <image>`.
+     *
+     * **This approach:**
+     * 1. Is more accurate (checks reality, not heuristics)
+     * 2. Is simpler (one check instead of multiple conditions)
+     * 3. Handles edge cases automatically:
+     *    - Docker Hub shorthand ("nginx" → exists remotely, not locally)
+     *    - Custom registries with default namespaces
+     *    - Images that "look local" but are actually remote
+     *
+     * **Decision Flow:**
+     * - Image exists locally → Add to temporary registry and make publicly accessible
+     * - Image doesn't exist locally → Treat as remote reference (don't add to registry)
+     *
+     * **Why This Works:**
+     * The temporary registry is ONLY needed for images that exist locally but need to
+     * be made publicly accessible to Akash providers. If an image doesn't exist locally,
+     * either:
+     * - It's a remote image (providers can pull it directly)
+     * - It doesn't exist anywhere (deployment will fail later with clear error)
+     *
+     * @param profile - Deployment profile containing services with images
+     * @param containerEngine - Container engine to use for operations
+     * @throws Error if a required local image cannot be added to registry
+     *
+     * @example
+     * ```typescript
+     * await manager.addLocalImagesToTemporaryRegistry(profile, 'docker');
+     * // Checks each service image, adds local ones to registry
+     * ```
+     */
+    addLocalImagesToTemporaryRegistry(profile: AkashDeploymentProfile, containerEngine: 'docker' | 'podman'): Promise<void>;
+    /**
+     * Intelligent container addition with fallback strategies
+     *
+     * Tries multiple strategies to add a container image to the registry:
+     * 1. **Strategy 1**: Load from tar file (from kadi-build export cache)
+     * 2. **Strategy 2**: Load from container engine (docker/podman)
+     * 3. **Failure**: Show helpful error with suggestions
+     *
+     * **Why Multiple Strategies:**
+     * - Tar files are faster and don't require container engine running
+     * - Container engine is the fallback if tar file not available
+     * - Provides clear guidance if both fail
+     *
+     * @param imageName - Full image name with tag
+     * @param serviceName - Service name from profile
+     * @param containerEngine - Container engine to use
+     * @returns Container mapping with registry URL
+     * @throws Error if image cannot be added with any strategy
+     */
+    private addContainerIntelligently;
+    /**
+     * Create container mapping for registry URLs
+     *
+     * Transforms a local image reference into a complete registry URL mapping
+     * that can be used in SDL generation. Includes service name tracking for
+     * better debugging and error messages.
+     *
+     * @param originalImage - Original image name from agent.json (e.g., "my-app")
+     * @param serviceName - Service name from profile (e.g., "frontend")
+     * @param containerInfo - Container info from registry with alias
+     * @param repoName - Repository name extracted from image
+     * @param imageTag - Image tag (e.g., "latest")
+     * @returns Complete container mapping with registry URL
+     */
+    private createContainerMapping;
+    /**
+     * Get public image URL for a specific service
+     *
+     * This is the key method that SDL generator calls to get the transformed
+     * registry URL for a local image.
+     *
+     * **Returns null if:**
+     * - Image is not local (no mapping exists)
+     * - Image wasn't added to registry
+     * - Service name doesn't match
+     *
+     * @param serviceName - Service name from profile
+     * @param originalImage - Original image name from profile
+     * @returns Public registry URL or null if not a local image
+     *
+     * @example
+     * ```typescript
+     * const url = manager.getPublicImageUrl('frontend', 'my-app:latest');
+     * // Returns: "abc123.serveo.net/my-app:latest" or null
+     * ```
+     */
+    getPublicImageUrl(serviceName: string, originalImage: string): string | null;
+    /**
+     * Get registry credentials for SDL generation
+     *
+     * Returns authentication credentials that should be added to the SDL services
+     * section so Akash providers can authenticate with the temporary registry.
+     *
+     * @returns Registry credentials or null if not available
+     *
+     * @example
+     * ```typescript
+     * const creds = manager.getRegistryCredentials();
+     * // Use in SDL: { host: "abc123.serveo.net", username: "...", password: "..." }
+     * ```
+     */
+    getRegistryCredentials(): RegistryCredentials | null;
+    /**
+     * Find tar file from kadi-build export directory
+     *
+     * Searches for container tar files exported by kadi-build in common locations:
+     * 1. ~/.kadi/tmp/container-registry-exports/containers/ (primary)
+     * 2. ./container-exports/ (backup)
+     * 3. /tmp/container-registry-exports/containers/ (fallback)
+     *
+     * **Why This Matters:**
+     * Tar files are faster to load and don't require the container engine to be running.
+     *
+     * @param imageName - Image name to search for (e.g., "my-app:0.0.1")
+     * @returns Path to tar file or null if not found
+     */
+    private findKadiBuildTarFile;
+    /**
+     * Show helpful suggestion to run kadi-build
+     *
+     * Displays actionable suggestions when a container cannot be found or added.
+     * Helps users understand what went wrong and how to fix it.
+     *
+     * @param imageName - Image that couldn't be added
+     * @param containerType - Container engine used
+     */
+    private showKadiBuildSuggestion;
+    /**
+     * Verify container is accessible in the registry
+     *
+     * Checks that a container with the given alias is present in the registry.
+     * Logs a warning if not found and shows available containers for debugging.
+     *
+     * @param actualAlias - Container alias to verify
+     */
+    private verifyContainerInRegistry;
+    /**
+     * Get the registry domain (without protocol)
+     *
+     * Returns the domain to use in image URLs. Prefers tunnel domain over local.
+     *
+     * @returns Registry domain (e.g., "abc123.serveo.net" or "localhost:3000")
+     */
+    private getRegistryDomain;
+    /**
+     * Get registry URL components including local and tunnel endpoints
+     *
+     * @returns Registry URLs with both local and tunnel information
+     */
+    private getRegistryUrls;
+    /**
+     * Get the preferred domain (tunnel if available, otherwise local)
+     *
+     * @returns Domain without protocol
+     */
+    private getPreferredDomain;
+    /**
+     * Check if registry is running
+     *
+     * @returns True if registry is started and accessible
+     */
+    isRunning(): boolean;
+    /**
+     * Display container mappings for debugging
+     *
+     * Shows how original image names were transformed to registry URLs.
+     * Useful for troubleshooting deployment issues.
+     */
+    displayContainerMappings(): Promise<void>;
+    /**
+     * Stop the temporary registry and cleanup resources
+     *
+     * Shuts down the registry container and tunnel. Should be called after
+     * deployment completes and providers have pulled all images.
+     *
+     * **Safe to call multiple times** - idempotent operation.
+     */
+    stopTemporaryRegistry(): Promise<void>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/utils/registry/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/utils/registry/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EAEV,mBAAmB,EAInB,eAAe,EAChB,MAAM,YAAY,CAAC;AAYpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,iCAAiC;IAC5C,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,QAAQ,CAAiD;IACjE,OAAO,CAAC,YAAY,CAA6B;IAEjD;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB,CAAuC;IAEhE;;;;OAIG;gBACS,MAAM,EAAE,gBAAgB;IAIpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,sBAAsB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAkFrE;;;;;OAKG;YACW,gCAAgC;IAgC9C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,uBAAuB;IAgB/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACG,iCAAiC,CACrC,OAAO,EAAE,sBAAsB,EAC/B,eAAe,EAAE,QAAQ,GAAG,QAAQ,GACnC,OAAO,CAAC,IAAI,CAAC;IA0ChB;;;;;;;;;;;;;;;;;;OAkBG;YACW,yBAAyB;IA4EvC;;;;;;;;;;;;;OAaG;YACW,sBAAsB;IA4BpC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAU5E;;;;;;;;;;;;;OAaG;IACH,sBAAsB,IAAI,mBAAmB,GAAG,IAAI;IA8BpD;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,oBAAoB;IAmC5B;;;;;;;;OAQG;IACH,OAAO,CAAC,uBAAuB;IA6B/B;;;;;;;OAOG;IACH,OAAO,CAAC,yBAAyB;IAsBjC;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAyBzB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAK1B;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;;OAKG;IACG,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB/C;;;;;;;OAOG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;CAqB7C"}