kadi-deploy 0.19.0

package/src/enhanced-registry-manager.ts

@@ -0,0 +1,892 @@
+/**
+ * Enhanced Temporary Container Registry Manager - TypeScript Version
+ *
+ * This builds on the excellent logic from registry-manager.js but adapts it
+ * for the new registry-aware SDL generation flow.
+ */
+
+import type { AkashProfile } from './schemas/profiles.js';
+import type { IKadiLogger } from './types/external.js';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'child_process';
+import debug from 'debug';
+
+import { TunneledContainerRegistry } from '@kadi.build/container-registry-ability';
+
+// @ts-ignore - config resolver from tunnel-services (JavaScript)
+import { resolveTunnelConfig } from '@kadi.build/tunnel-services';
+
+/**
+ * Debug logger for registry operations
+ */
+const log = debug('kadi:registry');
+
+/**
+ * Container mapping that tracks original image to registry URL transformation
+ */
+interface ContainerMapping {
+  originalImage: string; // e.g., "my-app" or "localhost/my-app"
+  serviceName: string; // e.g., "frontend"
+  registryUrl: string; // e.g., "temp-registry.serveo.net/my-app:latest"
+  repoName: string; // e.g., "my-app"
+  imageTag: string; // e.g., "latest"
+  actualAlias: string; // e.g., "my-app" (sanitized for registry)
+}
+
+/**
+ * Registry credentials for SDL generation
+ */
+interface RegistryCredentials {
+  host: string; // e.g., "temp-registry.serveo.net"
+  username: string; // e.g., access key
+  password: string; // e.g., secret key
+}
+
+/**
+ * Registry information for container registry instance
+ *
+ * Aligned with @kadi.build/container-registry-ability RegistryInfo type.
+ */
+import type {
+  RegistryInfo as CRARegistryInfo,
+  ContainerInfo as CRAContainerInfo,
+} from '@kadi.build/container-registry-ability';
+
+type RegistryInfo = CRARegistryInfo;
+
+/**
+ * Registry URL components including local and tunnel endpoints
+ */
+interface RegistryUrls {
+  localUrl: string; // e.g., "http://localhost:3000"
+  localDomain: string; // e.g., "localhost:3000"
+  tunnelUrl: string | null; // e.g., "https://abc123.serveo.net" or null
+  tunnelDomain: string | null; // e.g., "abc123.serveo.net" or null
+}
+
+/**
+ * Configuration options for starting the temporary registry
+ *
+ * Controls registry server, tunnel service, and lifecycle behavior.
+ */
+interface RegistryOptions {
+  /** Port number for the local registry server (default: 3000) */
+  port?: number;
+
+  /** Tunnel service to expose registry publicly ('kadi', 'ngrok', 'serveo', or 'localtunnel') */
+  tunnelService?: 'kadi' | 'ngrok' | 'serveo' | 'localtunnel';
+
+  /** Container engine to use for loading images ('docker' or 'podman') */
+  containerEngine?: 'docker' | 'podman';
+
+  /** Duration in milliseconds before auto-shutdown (default: 600000 = 10 minutes) */
+  durationMs?: number;
+
+  /** Enable automatic shutdown after downloads complete (default: true) */
+  autoShutdown?: boolean;
+
+  /** Authentication token for tunnel service (required for some services like ngrok) */
+  tunnelAuthToken?: string;
+
+  /** Region for tunnel service (e.g., 'us', 'eu', 'ap') */
+  tunnelRegion?: string;
+
+  /** Protocol for tunnel service ('http' or 'https') */
+  tunnelProtocol?: string;
+
+  /** Custom subdomain for tunnel (may require paid plan) */
+  tunnelSubdomain?: string;
+}
+
+/**
+ * Container information returned by the registry
+ *
+ * Represents a container that has been added to the temporary registry.
+ * The alias is the sanitized name used to reference the container in the registry.
+ */
+interface ContainerInfo {
+  /** Sanitized container alias used in the registry (e.g., "my-app") */
+  alias: string;
+}
+
+export class TemporaryContainerRegistryManager {
+  private logger: IKadiLogger;
+  private registry: TunneledContainerRegistry | null = null;
+  private registryInfo: RegistryInfo | null = null;
+
+  // Core data: maps original image names to their registry URLs
+  private containerMappings = new Map<string, ContainerMapping>();
+
+  constructor(logger: IKadiLogger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Start temporary registry using TunneledContainerRegistry
+   *
+   * Creates a local container registry on the specified port and exposes it publicly
+   * via a tunnel service (kadi, ngrok, serveo, or localtunnel). The registry is used to make
+   * local Docker images accessible to Akash providers during deployment.
+   *
+   * @param options - Configuration options for registry and tunnel
+   * @returns Promise that resolves when registry is running and accessible
+   * @throws Error if registry fails to start or tunnel cannot be established
+   *
+   * @example
+   * ```typescript
+   * await manager.startTemporaryRegistry({
+   *   port: 3000,
+   *   tunnelService: 'serveo',
+   *   containerEngine: 'docker',
+   *   durationMs: 600000,
+   *   autoShutdown: false
+   * });
+   * ```
+   */
+  async startTemporaryRegistry(options: RegistryOptions): Promise<void> {
+    if (this.registry) {
+      log('Temporary registry already running');
+      return;
+    }
+
+    log('Starting temporary container registry...');
+
+    try {
+      // ----------------------------------------------------------------
+      // Resolve tunnel configuration using config.yml walk-up + vault
+      // + .env fallback + process.env overrides.
+      //
+      // This replaces the previous dotenv-based loading. The tunnel
+      // config resolver (from @kadi.build/tunnel-services) handles:
+      //   1. config.yml "tunnel" section (non-secret settings)
+      //   2. secrets.toml vault "tunnel" for tokens (via secret-ability)
+      //   3. .env file walk-up (fallback when no vault found)
+      //   4. process.env overrides (always win)
+      // ----------------------------------------------------------------
+      const tunnelResolved = await resolveTunnelConfig();
+      const { config: tunnelCfg, secrets: tunnelSecrets } = tunnelResolved;
+
+      const resolvedTunnelService = options.tunnelService || tunnelCfg.default_service || 'kadi';
+
+      // Determine tunnel auth token: explicit option > vault > process.env fallback
+      const resolvedAuthToken =
+        options.tunnelAuthToken ||
+        tunnelSecrets.kadi_token ||
+        tunnelSecrets.ngrok_token;
+
+      const envNgrokRegion = tunnelCfg.ngrok_region || tunnelCfg.region || process.env.NGROK_REGION || undefined;
+      const envNgrokProtocol = tunnelCfg.ngrok_protocol || process.env.NGROK_PROTOCOL || undefined;
+
+      // Warn if kadi tunnel is selected but no token found
+      if (resolvedTunnelService === 'kadi' && !resolvedAuthToken) {
+        this.logger.log(`   ⚠ KADI_TUNNEL_TOKEN not set — kadi tunnel (frpc) requires a token`);
+        this.logger.log(`     Set via: kadi secret set -v tunnel KADI_TUNNEL_TOKEN`);
+      }
+
+      // ----------------------------------------------------------------
+      // CRITICAL: Force-write resolved tunnel values into process.env.
+      //
+      // Some downstream packages (CRA → S3HttpServer → FileSharingServer)
+      // may still reference process.env for tunnel config during the
+      // transition period. We propagate resolved values to ensure
+      // compatibility.
+      //
+      // INFRASTRUCTURE DEFAULTS:
+      // The kadi tunnel architecture is WSS-only (no direct TCP on port
+      // 7000). We ensure transport/wssControlHost defaults are always set.
+      // ----------------------------------------------------------------
+      const KADI_DEFAULTS = {
+        KADI_TUNNEL_SERVER:    'broker.kadi.build',
+        KADI_TUNNEL_DOMAIN:    'tunnel.kadi.build',
+        KADI_TUNNEL_MODE:      'frpc',
+        KADI_TUNNEL_TRANSPORT: 'wss',
+        KADI_TUNNEL_WSS_HOST:  'tunnel-control.kadi.build',
+        KADI_TUNNEL_PORT:      '7000',
+        KADI_TUNNEL_SSH_PORT:  '2200',
+        KADI_AGENT_ID:         'kadi',
+      };
+
+      const envVarsToPropagate: Record<string, string | undefined> = {
+        KADI_TUNNEL_TOKEN:     resolvedAuthToken,
+        KADI_TUNNEL_SERVER:    tunnelCfg.server_addr      || process.env.KADI_TUNNEL_SERVER    || KADI_DEFAULTS.KADI_TUNNEL_SERVER,
+        KADI_TUNNEL_DOMAIN:    tunnelCfg.tunnel_domain     || process.env.KADI_TUNNEL_DOMAIN    || KADI_DEFAULTS.KADI_TUNNEL_DOMAIN,
+        KADI_TUNNEL_MODE:      tunnelCfg.mode              || process.env.KADI_TUNNEL_MODE      || KADI_DEFAULTS.KADI_TUNNEL_MODE,
+        KADI_TUNNEL_TRANSPORT: tunnelCfg.transport         || process.env.KADI_TUNNEL_TRANSPORT || KADI_DEFAULTS.KADI_TUNNEL_TRANSPORT,
+        KADI_TUNNEL_WSS_HOST:  tunnelCfg.wss_control_host  || process.env.KADI_TUNNEL_WSS_HOST  || KADI_DEFAULTS.KADI_TUNNEL_WSS_HOST,
+        KADI_TUNNEL_PORT:      tunnelCfg.server_port?.toString() || process.env.KADI_TUNNEL_PORT || KADI_DEFAULTS.KADI_TUNNEL_PORT,
+        KADI_TUNNEL_SSH_PORT:  tunnelCfg.ssh_port?.toString()    || process.env.KADI_TUNNEL_SSH_PORT || KADI_DEFAULTS.KADI_TUNNEL_SSH_PORT,
+        KADI_AGENT_ID:         tunnelCfg.agent_id          || process.env.KADI_AGENT_ID         || KADI_DEFAULTS.KADI_AGENT_ID,
+        NGROK_AUTH_TOKEN:      tunnelSecrets.ngrok_token,
+        NGROK_REGION:          envNgrokRegion as string | undefined,
+        NGROK_PROTOCOL:        envNgrokProtocol as string | undefined,
+      };
+
+      for (const [key, value] of Object.entries(envVarsToPropagate)) {
+        if (value) {
+          process.env[key] = value;
+          log('Env set: %s=%s', key, key.includes('TOKEN') ? '***' : value);
+        }
+      }
+
+      log('Tunnel env: server=%s domain=%s mode=%s transport=%s wssHost=%s',
+        process.env.KADI_TUNNEL_SERVER, process.env.KADI_TUNNEL_DOMAIN,
+        process.env.KADI_TUNNEL_MODE, process.env.KADI_TUNNEL_TRANSPORT,
+        process.env.KADI_TUNNEL_WSS_HOST);
+
+      // Create TunneledContainerRegistry instance
+      this.registry = new TunneledContainerRegistry({
+        port: options.port || 3000,
+        tunnelService: resolvedTunnelService,
+        tunnelOptions: {
+          // Allow CLI options to override env if provided
+          authToken: resolvedAuthToken,
+          region: options.tunnelRegion || envNgrokRegion,
+          protocol: options.tunnelProtocol || envNgrokProtocol,
+          subdomain: options.tunnelSubdomain,
+          // Control fallback order: kadi (primary) → ngrok → localtunnel → pinggy → localhost.run → serveo
+          managerOptions: {
+            fallbackServices: process.env.TUNNEL_FALLBACK_SERVICES || 'ngrok,localtunnel,pinggy,localhost.run,serveo'
+          }
+        },
+        enableMonitoring: false,
+        // Disable verbose logging - only show errors
+        // User can enable with DEBUG=kadi:* environment variable if needed
+        enableLogging: false,
+        logLevel: 'error',
+        // Enable auto-shutdown by default to cleanup resources after deployment completes
+        // Can be disabled by passing options.autoShutdown = false
+        autoShutdown: options.autoShutdown ?? true,
+        containerType: options.containerEngine,
+        duration: options.durationMs
+      });
+
+      // Start the registry (includes tunnel establishment)
+      await this.registry.start();
+      this.registryInfo = this.registry.getRegistryInfo();
+
+      // Ensure we got valid registry info
+      if (!this.registryInfo) {
+        throw new Error(
+          'Failed to get registry information after starting registry'
+        );
+      }
+
+      // Ensure at minimum we have a local URL (tunnel URL is optional)
+      if (!this.registryInfo.localUrl) {
+        throw new Error('Registry started but no local URL available');
+      }
+
+      // Report tunnel status to user
+      if (this.registryInfo.tunnelUrl) {
+        this.logger.log(`   ✓ Tunnel connected: ${this.registryInfo.tunnelUrl}`);
+
+        // Detect if kadi tunnel was requested but a fallback service was used
+        const tunnelUrl = this.registryInfo.tunnelUrl;
+        const isKadiFallback = resolvedTunnelService === 'kadi' && (
+          tunnelUrl.includes('serveo') ||
+          tunnelUrl.includes('ngrok') ||
+          tunnelUrl.includes('localtunnel') ||
+          tunnelUrl.includes('pinggy')
+        );
+        if (isKadiFallback) {
+          this.logger.log(`   ⚠ KADI tunnel failed — fell back to alternate service`);
+          this.logger.log(`     This usually means frpc is not installed or couldn't connect.`);
+          this.logger.log(`     Install frpc: brew install frpc (macOS) or see https://github.com/fatedier/frp/releases`);
+          this.logger.log(`     Run with DEBUG=kadi:* for full tunnel diagnostics.`);
+          log('KADI tunnel fallback detected. Requested: %s, actual URL: %s', resolvedTunnelService, tunnelUrl);
+        }
+      } else {
+        this.logger.log(`   ⚠ No tunnel URL — registry only accessible locally at ${this.registryInfo.localUrl}`);
+        this.logger.log(`     Akash providers will NOT be able to pull images!`);
+      }
+
+      // Determine the primary registry URL (prefer tunnel over local)
+      const primaryRegistryUrl =
+        this.registryInfo.tunnelUrl || this.registryInfo.localUrl;
+      log('Registry started at: %s', primaryRegistryUrl);
+
+      await this.displayRegistryAccessInformation();
+    } catch (error) {
+      await this.stopTemporaryRegistry();
+      throw new Error(`Failed to start temporary registry: ${error}`);
+    }
+  }
+
+  /**
+   * Display registry access information including domain and credentials
+   *
+   * Reused from temporary-container-registry.ts with the same fallback logic
+   */
+  private async displayRegistryAccessInformation(): Promise<void> {
+    if (!this.registryInfo) {
+      return;
+    }
+
+    try {
+      // Try to get and display command help (same as temporary-container-registry.ts)
+      const commandHelp = await this.registry!.generateCommandHelp();
+
+      const registryDomain =
+        commandHelp?.registry?.registryDomain ||
+        (this.registryInfo.tunnelUrl || this.registryInfo.localUrl).replace(
+          /^https?:\/\//,
+          ''
+        );
+
+      log('Registry domain: %s', registryDomain);
+
+      if (this.registryInfo.credentials) {
+        log('Access key: %s', this.registryInfo.credentials.accessKey);
+        log('Secret key: [hidden]');
+      }
+    } catch (error) {
+      // Fallback display if command generation fails (same as temporary-container-registry.ts)
+      if (this.registryInfo.credentials) {
+        log('Registry credentials available');
+        log('Username: %s', this.registryInfo.credentials.accessKey);
+        log('Password: [hidden]');
+      }
+    }
+  }
+
+  /**
+   * 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. 
+   *
+   * - `docker images -q <image>` returns the image hash if it exists
+   * - 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")
+   *
+   * @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(
+    imageName: string,
+    engine: 'docker' | 'podman'
+  ): boolean {
+    try {
+      const result = execSync(`${engine} images -q ${imageName}`, {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'] // Suppress stderr
+      });
+      return result.trim().length > 0;
+    } catch (error) {
+      // Command failed (engine not available or other error)
+      return false;
+    }
+  }
+
+  /**
+   * Add local images from AkashProfile 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)
+   *
+   * This prevents us from starting unnecessary infrastructure (tunnel, S3 server)
+   * and provides better error messages.
+   */
+  async addLocalImagesToTemporaryRegistry(
+    loadedProfile: AkashProfile,
+    containerEngine: 'docker' | 'podman'
+  ): Promise<void> {
+    log('Checking which service images exist locally...');
+
+    const serviceEntries = Object.entries(loadedProfile.services);
+    let localCount = 0;
+
+    for (const [serviceName, serviceConfig] of serviceEntries) {
+      // Type assertion: Zod validates this is AkashService
+      const typedService = serviceConfig as { image: string };
+      const imageName = typedService.image;
+
+      // Check if image exists locally (reality-based, not name-based)
+      if (this.checkImageExistsLocally(imageName, containerEngine)) {
+        localCount++;
+        // Image exists locally → add to temporary registry
+        this.logger.log(`   📦 ${serviceName}: ${imageName} (local → pushing to registry)`);
+        log('Image found locally for service %s: %s', serviceName, imageName);
+
+        try {
+          // Use the intelligent fallback strategy from registry-manager.js
+          const mapping = await this.addContainerIntelligently(
+            imageName,
+            serviceName,
+            containerEngine
+          );
+
+          // Store the mapping for later SDL generation
+          this.containerMappings.set(imageName, mapping);
+        } catch (error) {
+          this.logger.error(
+            `❌ Failed to add local image '${imageName}' for service '${serviceName}': ${(error as Error).message}`
+          );
+          throw error; // Stop deployment if we can't host a required local image
+        }
+      } else {
+        // Image doesn't exist locally → treat as remote
+        log(`Skipping remote image: ${serviceName}: ${imageName}`);
+        log('Image not found locally, treating as remote for service %s: %s', serviceName, imageName);
+      }
+    }
+
+    if (localCount > 0) {
+      this.logger.log(`   ✓ ${localCount} local image(s) pushed to registry`);
+    }
+    log('Successfully processed %d local images', this.containerMappings.size);
+  }
+
+  /**
+   * Intelligent container addition with fallback strategies
+   *
+   * Adapted from registry-manager.js addContainerIntelligently but enhanced
+   * for TypeScript and our new flow.
+   */
+  private async addContainerIntelligently(
+    imageName: string,
+    serviceName: string,
+    containerEngine: 'docker' | 'podman'
+  ): Promise<ContainerMapping> {
+    // Parse image name (reuse logic from registry-manager.js)
+    const repoName = imageName.includes(':')
+      ? imageName.split(':')[0]
+      : imageName;
+    const imageTag = imageName.includes(':')
+      ? imageName.split(':')[1]
+      : 'latest';
+
+    log('Attempting to add container: %s', imageName);
+
+    // Strategy 1: Try to find and use tar file from kadi-build
+    // (Reuse findKadiBuildTarFile logic from registry-manager.js)
+    const tarPath = this.findKadiBuildTarFile(imageName);
+    if (tarPath) {
+      try {
+        log('Loading container from tar file: %s', tarPath);
+
+        const containerInfo = await this.registry!.addContainer({
+          type: 'tar',
+          name: repoName,
+          path: tarPath
+        });
+
+        log('Container loaded from tar file with alias: %s', containerInfo.alias);
+
+        return this.createContainerMapping(
+          imageName,
+          serviceName,
+          containerInfo,
+          repoName,
+          imageTag
+        );
+      } catch (error) {
+        log('Failed to load from tar file: %s', (error as Error).message);
+        log('Falling back to container engine...');
+      }
+    }
+
+    // Strategy 2: Try to add from container engine (docker/podman)
+    // (Reuse logic from registry-manager.js)
+    try {
+      log('Attempting to add from %s engine: %s', containerEngine, imageName);
+
+      const containerInfo = await this.registry!.addContainer({
+        type: containerEngine,
+        name: repoName,
+        image: imageName
+      });
+
+      log('Container loaded from %s with alias: %s', containerEngine, containerInfo.alias);
+
+      return this.createContainerMapping(
+        imageName,
+        serviceName,
+        containerInfo,
+        repoName,
+        imageTag
+      );
+    } catch (error) {
+      log('Failed to load from %s: %s', containerEngine, (error as Error).message);
+    }
+
+    // Strategy 3: Show helpful error message (reuse from registry-manager.js)
+    this.showKadiBuildSuggestion(imageName, containerEngine);
+    throw new Error(
+      `Could not add container ${imageName}. See suggestions above.`
+    );
+  }
+
+  /**
+   * 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 async createContainerMapping(
+    originalImage: string,
+    serviceName: string,
+    containerInfo: ContainerInfo,
+    repoName: string,
+    imageTag: string
+  ): Promise<ContainerMapping> {
+    const actualAlias = containerInfo.alias;
+    const registryUrls = await this.registry!.getRegistryUrls();
+    const registryDomain = this.getPreferredDomain();
+    const registryImageUrl = `${registryDomain}/${actualAlias}:${imageTag}`;
+
+    const mapping: ContainerMapping = {
+      originalImage,
+      serviceName,
+      registryUrl: registryImageUrl,
+      repoName,
+      imageTag,
+      actualAlias
+    };
+
+    log('Container available at: %s', registryImageUrl);
+
+    // Verify container is accessible (reuse verification logic)
+    this.verifyContainerInRegistry(actualAlias);
+
+    return mapping;
+  }
+
+  /**
+   * NEW METHOD: Get public image URL for a specific service
+   *
+   * This is the key method that SDL generator will call:
+   * "What's the registry URL I should use for this image?"
+   */
+  getPublicImageUrl(serviceName: string, originalImage: string): string | null {
+    // Look for mapping by original image name
+    const mapping = this.containerMappings.get(originalImage);
+
+    if (mapping && mapping.serviceName === serviceName) {
+      // Debug logging - could make this conditional in the future
+      // this.logger.log(`🔍 Found registry URL for ${serviceName}:${originalImage} → ${mapping.registryUrl}`);
+      return mapping.registryUrl;
+    }
+
+    // Debug logging - could make this conditional in the future
+    // this.logger.log(`🔍 No registry URL found for ${serviceName}:${originalImage} (not a local image or not processed)`);
+    return null;
+  }
+
+  /**
+   * Get registry credentials for SDL generation
+   *
+   * The SDL generator calls this to get credentials for local images
+   */
+  getRegistryCredentials(): RegistryCredentials | null {
+    if (!this.registryInfo?.credentials) {
+      log('No registry credentials available');
+      return null;
+    }
+
+    log('Registry info - tunnel: %s, local: %s',
+      this.registryInfo.tunnelUrl,
+      this.registryInfo.localUrl
+    );
+
+    const host = this.getRegistryDomain();
+
+    // Convert to the format expected by SDL generation
+    const credentials = {
+      host: host,
+      username: this.registryInfo.credentials.accessKey,
+      password: this.registryInfo.credentials.secretKey
+    };
+
+    log('Returning registry credentials - host: %s, username: %s',
+      credentials.host,
+      credentials.username
+    );
+
+    return credentials;
+  }
+
+  /**
+   * Check if an image is local (reuse from existing code)
+   */
+  private isLocalImage(image: string): boolean {
+    if (!image) return false;
+
+    // Local images don't contain registry domains or start with localhost
+    return (
+      !image.includes('/') ||
+      image.startsWith('localhost/') ||
+      image.startsWith('127.0.0.1/')
+    );
+  }
+
+  /**
+   * Find tar file from kadi-build export directory
+   *
+   * Reused from temporary-container-registry.ts - excellent implementation
+   * that searches for container tar files exported by kadi-build in common locations.
+   */
+  private findKadiBuildTarFile(imageName: string): string | null {
+    // Generate the expected filename pattern
+    // Example: "agent-a:0.0.1" -> "agent-a-0.0.1.tar"
+    const expectedFilename = `${imageName.replace(/[^a-zA-Z0-9.-]/g, '-')}.tar`;
+
+    // Common locations where kadi-build saves tar files
+    const possiblePaths: string[] = [
+      // User's home directory .kadi cache (primary location)
+      path.join(
+        os.homedir(),
+        '.kadi',
+        'tmp',
+        'container-registry-exports',
+        'containers'
+      ),
+      // Current working directory exports (backup location)
+      path.join(process.cwd(), 'container-exports'),
+      // Temporary directory exports (fallback location)
+      path.join(os.tmpdir(), 'container-registry-exports', 'containers')
+    ];
+
+    for (const basePath of possiblePaths) {
+      const fullPath = path.join(basePath, expectedFilename);
+
+      if (fs.existsSync(fullPath)) {
+        log('Found tar file for %s: %s', imageName, fullPath);
+        return fullPath;
+      }
+
+      log('Checked: %s - not found', fullPath);
+    }
+
+    // Debug: this.logger.log(`❌ No tar file found for ${imageName}`);
+    // Debug: this.logger.log(`   Expected filename: ${expectedFilename}`);
+    // Debug: this.logger.log(`   Searched in: ${possiblePaths.join(', ')}`);
+    return null;
+  }
+
+  /**
+   * Show helpful suggestion to run kadi-build
+   *
+   * Adapted from registry-manager.js showKadiBuildSuggestion method
+   */
+  private showKadiBuildSuggestion(
+    imageName: string,
+    containerType: string
+  ): void {
+    this.logger.log(`\n🔧 CONTAINER NOT FOUND: ${imageName}`);
+    this.logger.log(`\nThis could mean:`);
+    this.logger.log(`  • The container hasn't been built yet`);
+    this.logger.log(`  • The container name doesn't match what's available`);
+    this.logger.log(`  • The container was built with a different tool`);
+
+    this.logger.log(`\n💡 SUGGESTED SOLUTIONS:`);
+    this.logger.log(`\n1. Build the container first:`);
+    this.logger.log(
+      `   kadi build --tag ${imageName} --engine ${containerType}`
+    );
+
+    this.logger.log(`\n2. Check available containers:`);
+    this.logger.log(
+      `   ${containerType} images | grep ${imageName.split(':')[0]}`
+    );
+
+    this.logger.log(
+      `\n3. Verify the image name in your agent.json matches the built container`
+    );
+
+    this.logger.log(`\n4. If using a different tag, ensure it exists:`);
+    this.logger.log(`   ${containerType} images ${imageName.split(':')[0]}`);
+  }
+
+  /**
+   * 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(actualAlias: string): void {
+    try {
+      const containers = this.registry!.listContainers();
+      const foundContainer = containers.find(
+        (c) => c.alias === actualAlias
+      );
+
+      if (foundContainer) {
+        log('Verified container in registry with alias: %s', foundContainer.alias);
+      } else {
+        this.logger.warn(
+          `   ⚠️  Warning: Container not found in registry with alias: ${actualAlias}`
+        );
+        this.logger.log(
+          `   Available containers: ${containers.map((c) => c.alias ?? c.name).join(', ')}`
+        );
+      }
+    } catch (error) {
+      // Silently ignore verification errors - registry might not support listing
+    }
+  }
+
+  /**
+   * Get the registry domain (without protocol)
+   *
+   * Reused from registry-manager.js with fallback logic
+   */
+  private getRegistryDomain(): string {
+    // First try to get from our own getRegistryUrls() method
+    try {
+      const preferredDomain = this.getPreferredDomain();
+      if (preferredDomain) {
+        log('Registry domain from getRegistryUrls: %s', preferredDomain);
+        return preferredDomain;
+      }
+    } catch (error) {
+      log('Could not get registry URLs: %s', error);
+    }
+
+    // Fallback to parsing from registry info
+    if (this.registryInfo) {
+      const url = this.registryInfo.tunnelUrl || this.registryInfo.localUrl;
+      if (url) {
+        const domain = url.replace(/^https?:\/\//, '');
+        log('Registry domain from registryInfo: %s', domain);
+        return domain;
+      }
+    }
+
+    this.logger.error('❌ Could not determine registry domain!');
+    return '';
+  }
+
+  /**
+   * Get registry URL components including local and tunnel endpoints
+   */
+  private getRegistryUrls(): RegistryUrls {
+    if (!this.registryInfo) {
+      throw new Error('Registry not started');
+    }
+
+    const localUrl = this.registryInfo.localUrl;
+    const tunnelUrl = this.registryInfo.tunnelUrl || null;
+
+    // Extract domains (remove protocol)
+    const localDomain = localUrl.replace(/^https?:\/\//, '');
+    const tunnelDomain = tunnelUrl
+      ? tunnelUrl.replace(/^https?:\/\//, '')
+      : null;
+
+    return {
+      localUrl,
+      localDomain,
+      tunnelUrl,
+      tunnelDomain
+    };
+  }
+
+  /**
+   * Get the preferred URL (tunnel if available, otherwise local)
+   */
+  private getPreferredUrl(): string {
+    const urls = this.getRegistryUrls();
+    return urls.tunnelUrl || urls.localUrl;
+  }
+
+  /**
+   * Get the preferred domain (tunnel if available, otherwise local)
+   */
+  private getPreferredDomain(): string {
+    const urls = this.getRegistryUrls();
+    return urls.tunnelDomain || urls.localDomain;
+  }
+
+  /**
+   * Check if registry is running
+   */
+  isRunning(): boolean {
+    return this.registry !== null && this.registryInfo !== null;
+  }
+
+  /**
+   * Display container mappings for debugging
+   *
+   * Enhanced version that shows the new mapping structure
+   */
+  async displayContainerMappings(): Promise<void> {
+    this.logger.log('\n🔍 Container image mappings:');
+
+    if (this.containerMappings.size === 0) {
+      this.logger.log('  No local images processed');
+      return;
+    }
+
+    for (const [originalImage, mapping] of this.containerMappings) {
+      this.logger.log(`  ${mapping.serviceName}:`);
+      this.logger.log(`    Original: ${originalImage}`);
+      this.logger.log(`    Registry: ${mapping.registryUrl}`);
+      this.logger.log(`    Alias: ${mapping.actualAlias}`);
+    }
+  }
+
+  /**
+   * Stop the temporary registry and cleanup resources
+   *
+   * Reused from temporary-container-registry.ts with proper cleanup
+   */
+  async stopTemporaryRegistry(): Promise<void> {
+    if (!this.registry) {
+      return;
+    }
+
+    log('Stopping temporary registry...');
+
+    try {
+      // Stop the registry instance
+      await this.registry.stop();
+
+      // Clear state
+      this.registry = null;
+      this.registryInfo = null;
+      this.containerMappings.clear();
+
+      log('Temporary registry stopped and cleaned up');
+    } catch (error) {
+      this.logger.warn(`⚠️  Error during registry cleanup: ${error}`);
+    }
+  }
+}