kadi-deploy 0.19.0

package/src/index.ts

@@ -0,0 +1,307 @@
+/**
+ * KADI Deploy - Main Entry Point
+ *
+ * Profile-based deployment system for KADI agents using deploy-ability library.
+ * Supports deployment to Akash Network and local Docker/Podman.
+ *
+ * This implementation uses deploy-ability as a library for all deployment operations.
+ *
+ * @module index
+ */
+
+import path from 'node:path';
+import type { IKadiContext, DeployOptions, ResolvedDeployOptions, DeploymentContext } from './types.js';
+import { loadAgentConfig, getFirstProfile, hasProfile, getProfile } from './config/agent-loader.js';
+import { executeAkashDeployment } from './commands/deploy.js';
+import { executeLocalDeployment } from './commands/deploy-local.js';
+import { executeDown } from './commands/down.js';
+import { validateSecretsOrFail } from './secrets/index.js';
+
+/**
+ * Register the "deploy" command with the Kadi CLI
+ *
+ * Uses Commander subcommands:
+ *   kadi deploy [up]   — Deploy agents (default, backward compatible)
+ *   kadi deploy down   — Tear down an active deployment
+ *
+ * @param ctx - Plugin context injected by the Kadi CLI
+ */
+export default function registerDeploy(ctx: IKadiContext) {
+  const { commander, logger } = ctx;
+
+  // Parent command — `kadi deploy`
+  const deploy = commander
+    .command('deploy')
+    .alias('d')
+    .description(
+      'Deploy agents to Akash Network or locally, or tear them down'
+    );
+
+  // ─────────────────────────────────────────────────────────────────
+  // Subcommand: deploy up (default — runs when bare `kadi deploy` is used)
+  // ─────────────────────────────────────────────────────────────────
+  deploy
+    .command('up', { isDefault: true })
+    .description(
+      'Deploy agents to Akash Network or locally using profiles from agent.json'
+    )
+
+    // Profile selection
+    .option(
+      '--profile <profile>',
+      'Deploy profile to use from agent.json (if not specified, uses first available profile)'
+    )
+
+    // Project configuration
+    .option(
+      '-p, --project <path>',
+      'Path to folder containing agent.json'
+    )
+
+    // Deployment options
+    .option('--dry-run', "Preview deployment without executing")
+    .option('--yes, -y', 'Skip confirmation prompts')
+    .option('--verbose, -v', 'Verbose logging')
+
+    // Network/engine overrides
+    .option('--network <network>', 'Akash network (mainnet|testnet)')
+    .option('--engine <engine>', 'Container engine (docker|podman)')
+
+    // Certificate (Akash only)
+    .option('--cert <path>', 'Path to existing TLS certificate')
+
+    // Autonomous deployment (agent-controlled, no human interaction)
+    .option('--autonomous', 'Fully autonomous deployment with no human interaction (uses secrets vault for wallet)')
+    .option('--bid-strategy <strategy>', 'Bid selection strategy for autonomous mode (cheapest|most-reliable|balanced)', 'cheapest')
+    .option('--bid-max-price <uakt>', 'Maximum bid price per block in uAKT (autonomous mode)')
+    .option('--require-audited', 'Only accept bids from audited providers (autonomous mode)')
+    .option('--secrets-vault <vault>', 'Vault for wallet mnemonic (default: "global"). Deployment secrets always use the profile\'s secrets.vault')
+    .option('--auto-approve-secrets', 'Auto-approve secret sharing without prompting')
+    .option('--secret-timeout <ms>', 'Timeout (ms) for waiting for agent to request secrets')
+    .option('--label <label>', 'Human-readable label for this deployment instance (e.g. "broker-east")')
+
+    // Help text
+    .addHelpText(
+      'after',
+      `
+Profile Examples:
+  kadi deploy                           # Use first available profile
+  kadi deploy --profile production      # Use production profile
+  kadi deploy --profile akash-mainnet   # Deploy to Akash mainnet
+  kadi deploy --profile local-dev       # Deploy locally
+
+Autonomous Deployment (no human interaction):
+  kadi deploy --autonomous              # Auto-deploy using secrets vault
+  kadi deploy --autonomous --bid-strategy most-reliable
+  kadi deploy --autonomous --bid-max-price 1000 --require-audited
+  kadi deploy --autonomous --auto-approve-secrets
+
+Teardown:
+  kadi deploy down                      # Tear down the active deployment
+  kadi deploy down --autonomous         # Fully non-interactive (skips confirmation + QR)
+  kadi deploy down --autonomous --profile prod  # Required when multiple deployments active
+  kadi deploy down --yes                # Skip confirmation (interactive mode)
+
+Configuration:
+  Profiles are defined in agent.json under the "deploy" field.
+  CLI flags override profile settings.
+
+  For autonomous mode, store your wallet mnemonic in the secrets vault:
+    kadi secrets set --vault global --key AKASH_WALLET --value "your mnemonic"
+
+Supported Targets:
+  • akash - Deploy to Akash Network (decentralized cloud)
+  • local - Deploy to local Docker/Podman
+    `
+    )
+
+    .action(async (...args: unknown[]) => {
+      // Commander passes flags as first argument
+      const flags = args[0] as Record<string, unknown>;
+
+      // Set default project path if not provided
+      const deployFlags = {
+        ...flags,
+        project: (flags.project as string) || process.cwd(),
+        bidMaxPrice: flags.bidMaxPrice ? parseInt(flags.bidMaxPrice as string, 10) : undefined,
+        secretTimeout: flags.secretTimeout ? parseInt(flags.secretTimeout as string, 10) : undefined,
+      } as DeployOptions;
+
+      try {
+        await deployWithDeployAbility(ctx, deployFlags);
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        logger.error(`Deploy failed: ${errorMessage}`);
+
+        if (deployFlags.verbose) {
+          logger.error('Full error details:');
+          console.error(error);
+        }
+
+        process.exitCode = 1;
+      }
+    });
+
+  // ─────────────────────────────────────────────────────────────────
+  // Subcommand: deploy down — tear down an active deployment
+  // ─────────────────────────────────────────────────────────────────
+  deploy
+    .command('down')
+    .description(
+      'Tear down an active deployment (reads .kadi-deploy.lock)'
+    )
+    .option(
+      '-p, --project <path>',
+      'Path to project with agent.json / .kadi-deploy.lock'
+    )
+    .option('--profile <profile>', 'Profile name to tear down (prompts if multiple active)')
+    .option('--instance <id>', 'Instance ID to tear down (4-char hex from deploy output)')
+    .option('--all', 'Tear down all active deployments')
+    .option('--engine <engine>', 'Override container engine (docker|podman)')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .option('--verbose, -v', 'Verbose output')
+    .option('--autonomous', 'Autonomous Akash teardown (wallet from secrets vault, no QR)')
+    .option('--secrets-vault <vault>', 'Vault name for wallet mnemonic (default: "global")')
+    .option('--network <network>', 'Override Akash network (mainnet|testnet)')
+    .action(async (...args: unknown[]) => {
+      const flags = args[0] as Record<string, unknown>;
+
+      try {
+        await executeDown(ctx, {
+          project: (flags.project as string) || process.cwd(),
+          profile: flags.profile as string | undefined,
+          instance: flags.instance as string | undefined,
+          all: flags.all as boolean | undefined,
+          engine: flags.engine as string | undefined,
+          yes: flags.yes as boolean | undefined,
+          verbose: flags.verbose as boolean | undefined,
+          autonomous: flags.autonomous as boolean | undefined,
+          secretsVault: flags.secretsVault as string | undefined,
+          network: flags.network as string | undefined,
+        });
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        logger.error(`Teardown failed: ${errorMessage}`);
+
+        if (flags.verbose) {
+          logger.error('Full error details:');
+          console.error(error);
+        }
+
+        process.exitCode = 1;
+      }
+    });
+}
+
+/**
+ * Main deployment logic using deploy-ability library
+ *
+ * This function:
+ * 1. Loads agent.json
+ * 2. Resolves profile
+ * 3. Routes to appropriate command (Akash or local)
+ *
+ * @param ctx - KADI CLI context
+ * @param options - Raw CLI options
+ */
+async function deployWithDeployAbility(ctx: IKadiContext, options: DeployOptions) {
+  const { logger } = ctx;
+  const projectRoot = path.resolve(options.project || process.cwd());
+
+  // ----------------------------------------------------------------
+  // 1. Load agent.json
+  // ----------------------------------------------------------------
+  let agentConfig;
+  try {
+    agentConfig = await loadAgentConfig(projectRoot);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.error(
+      `Unable to load agent.json from ${projectRoot}: ${errorMessage}`
+    );
+    return;
+  }
+
+  // ----------------------------------------------------------------
+  // 2. Resolve profile
+  // ----------------------------------------------------------------
+  let selectedProfile = options.profile;
+
+  if (options.profile) {
+    // User explicitly requested a profile - validate it exists
+    if (!hasProfile(agentConfig, options.profile)) {
+      logger.error(
+        `Deploy profile '${options.profile}' not found in agent.json`
+      );
+      return;
+    }
+  } else {
+    // No profile specified - use first one
+    selectedProfile = getFirstProfile(agentConfig);
+
+    if (!selectedProfile) {
+      logger.error('No deploy profiles found in agent.json');
+      logger.log('Add a deploy profile under the "deploy" field in agent.json');
+      return;
+    }
+  }
+
+  // Get profile configuration
+  if (!selectedProfile) {
+    logger.error('No deploy profiles available');
+    return;
+  }
+
+  // Get and validate profile structure (Zod validation)
+  const profile = getProfile(agentConfig, selectedProfile);
+  if (!profile) {
+    logger.error(`Profile "${selectedProfile}" not found in agent.json`);
+    return;
+  }
+
+  // ----------------------------------------------------------------
+  // 2.5. Validate secrets exist before deployment
+  // ----------------------------------------------------------------
+  // Check that all required secrets are available in the local vault.
+  // This shells out to `kadi secret list --json` and compares against
+  // the profile's secrets.required array. Fails fast with helpful error
+  // if any required secrets are missing.
+  try {
+    validateSecretsOrFail(profile, projectRoot, logger);
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err);
+    logger.error(errorMessage);
+    return;
+  }
+
+  const target = profile.target;
+
+  // ----------------------------------------------------------------
+  // 3. Build deployment context
+  // ----------------------------------------------------------------
+  const deployCtx: DeploymentContext = {
+    ...ctx,
+    projectRoot,
+    agent: agentConfig,
+    flags: {
+      ...options,
+      profile: selectedProfile,
+      target,
+      project: projectRoot
+    } as ResolvedDeployOptions
+  };
+
+  // ----------------------------------------------------------------
+  // 4. Route to appropriate deployment command
+  // ----------------------------------------------------------------
+  if (target === 'akash') {
+    await executeAkashDeployment(deployCtx);
+  } else if (target === 'local') {
+    await executeLocalDeployment(deployCtx);
+  } else {
+    logger.error(`Unknown deployment target: ${target}`);
+    logger.log('Supported targets: akash, local');
+  }
+}

package/src/infrastructure/registry.ts

@@ -0,0 +1,269 @@
+/**
+ * Registry Infrastructure Module
+ *
+ * Handles temporary container registry for local images.
+ *
+ * **Problem**: Akash providers can't pull local images like "my-app"
+ * **Solution**:
+ *   1. Start temporary registry on localhost:3000
+ *   2. Push local images to it
+ *   3. Expose publicly via tunnel (kadi/ngrok/serveo/localtunnel)
+ *   4. Rewrite profile to use public registry URLs
+ *   5. Providers can now pull images during deployment
+ *
+ * @module infrastructure/registry
+ */
+
+import { TemporaryContainerRegistryManager } from '../enhanced-registry-manager.js';
+import type { IKadiLogger } from '../types/external.js';
+import type { AkashDeploymentData } from '@kadi.build/deploy-ability/types';
+import type { AkashProfile } from '../schemas/profiles.js';
+import { execSync } from 'node:child_process';
+
+/**
+ * Registry context returned by setupRegistryIfNeeded
+ */
+export interface RegistryContext {
+  /**
+   * Profile ready for deployment to Akash
+   *
+   * Local images have been replaced with public registry URLs.
+   * For example:
+   *   - Original: { image: "my-app" }
+   *   - Deployable: { image: "abc123.serveo.net/my-app:latest", credentials: {...} }
+   */
+  deployableProfile: AkashProfile;
+
+  /**
+   * Cleanup function to call after deployment
+   *
+   * Waits for containers to be running on provider, then shuts down
+   * the temporary registry (no longer needed once containers pulled images).
+   */
+  cleanup: () => Promise<void>;
+}
+
+/**
+ * Sets up temporary registry infrastructure if profile uses local images
+ *
+ * @param profile - Original profile from agent.json
+ * @param logger - Logger instance
+ * @param options - Registry configuration options
+ * @returns Registry context with deployable profile and cleanup function
+ *
+ * @example No local images
+ * ```typescript
+ * // Profile uses remote images only (docker.io/nginx)
+ * const ctx = await setupRegistryIfNeeded(profile, logger)
+ * // ctx.deployableProfile === profile (unchanged)
+ * // ctx.cleanup() is a no-op
+ * ```
+ *
+ * @example Local images present
+ * ```typescript
+ * // Profile uses local images (my-app, my-api)
+ * const ctx = await setupRegistryIfNeeded(profile, logger)
+ * // ctx.deployableProfile has images rewritten to public URLs
+ * // ctx.cleanup() waits for containers and shuts down registry
+ * ```
+ */
+export async function setupRegistryIfNeeded(
+  profile: AkashProfile,
+  logger: IKadiLogger,
+  options: {
+    useRemoteRegistry?: boolean;
+    registryDuration?: number;
+    tunnelService?: 'kadi' | 'ngrok' | 'serveo' | 'localtunnel';
+    containerEngine?: 'docker' | 'podman';
+  } = {}
+): Promise<RegistryContext> {
+  // User explicitly wants to use remote registry
+  if (options.useRemoteRegistry) {
+    logger.log('📡 Using remote registry (local registry disabled)');
+    logger.log('⚠️  Ensure all images are pushed to a remote registry!');
+
+    return {
+      deployableProfile: profile,
+      cleanup: async () => {} // No cleanup needed
+    };
+  }
+
+  // Check if any services use local images
+  if (!hasLocalImages(profile)) {
+    // All images are remote (docker.io/nginx, ghcr.io/owner/repo, etc.)
+    // No registry needed - providers can pull directly
+    return {
+      deployableProfile: profile,
+      cleanup: async () => {} // No cleanup needed
+    };
+  }
+
+  // Profile has local images - start registry infrastructure
+  const resolvedTunnel = options.tunnelService || 'kadi';
+  const resolvedEngine = options.containerEngine || 'docker';
+  logger.log(`🔧 Local images detected — setting up temporary registry (${resolvedTunnel} tunnel)...`);
+
+  const manager = new TemporaryContainerRegistryManager(logger);
+
+  try {
+    await manager.startTemporaryRegistry({
+      port: 3000,
+      tunnelService: resolvedTunnel,
+      containerEngine: resolvedEngine,
+      durationMs: options.registryDuration || 600000, // 10 minutes default
+      autoShutdown: false // We'll shutdown manually after containers are running
+    });
+  } catch (err) {
+    const msg = (err as Error).message || String(err);
+    logger.error(`❌ Registry startup failed: ${msg}`);
+    if (resolvedTunnel === 'kadi' && (msg.includes('token') || msg.includes('auth') || msg.includes('KADI_TUNNEL'))) {
+      logger.error(``);
+      logger.error(`   The kadi tunnel (frpc) requires a token.`);
+      logger.error(`   Ensure your .env file contains KADI_TUNNEL_TOKEN and is`);
+      logger.error(`   placed in the kadi-deploy plugin root (next to package.json).`);
+    }
+    throw err;
+  }
+
+  // Push local images to registry
+  logger.log(`📦 Pushing local images to temporary registry...`);
+  await manager.addLocalImagesToTemporaryRegistry(
+    profile,
+    resolvedEngine
+  );
+
+  // Transform profile: "my-app" → "abc123.serveo.net/my-app:latest"
+  const deployableProfile = transformProfileWithRegistry(profile, manager);
+
+  return {
+    deployableProfile,
+    cleanup: async () => {
+      if (manager.isRunning()) {
+        logger.log('🛑 Shutting down temporary registry...');
+        await manager.stopTemporaryRegistry();
+        logger.log('✅ Temporary registry shut down');
+      }
+    }
+  };
+}
+
+/**
+ * Checks if profile contains any local container images
+ *
+ * **Reality-Based Detection:**
+ * Instead of guessing based on image name patterns, we check if images
+ * actually exist locally using `docker images -q <image>`.
+ *
+ * This is more accurate because:
+ * - "nginx" might look local but exists only remotely (Docker Hub)
+ * - "my-app" might be on local machine and needs our temporary registry
+ * - We avoid false positives from name heuristics
+ *
+ * **Why this matters:**
+ * If this returns true, we start the temporary registry infrastructure
+ * (tunnel, S3 server). We should only do this when there are ACTUAL local
+ * images that need to be made publicly accessible.
+ *
+ * @param profile - Profile to check
+ * @param engine - Container engine to use for checking (default: 'docker')
+ * @returns True if profile has any images that exist locally
+ */
+export function hasLocalImages(profile: AkashProfile, engine: 'docker' | 'podman' = 'docker'): boolean {
+  if (!profile.services) return false;
+
+  return Object.values(profile.services).some((service) => {
+    const image = service.image;
+    if (!image) return false;
+
+    try {
+      // Check if image exists locally
+      const result = execSync(`${engine} images -q ${image}`, {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'] // Suppress stderr
+      });
+      return result.trim().length > 0;
+    } catch (error) {
+      // Image doesn't exist locally or engine unavailable
+      return false;
+    }
+  });
+}
+
+/**
+ * Transforms profile to use registry URLs for local images
+ *
+ * Creates a new profile object with:
+ * - Local images replaced with public registry URLs
+ * - Registry credentials added to each service
+ *
+ * @param profile - Original profile
+ * @param manager - Running registry manager
+ * @returns Transformed profile ready for deployment
+ */
+function transformProfileWithRegistry(
+  profile: AkashProfile,
+  manager: TemporaryContainerRegistryManager
+): AkashProfile {
+  // Deep clone to avoid mutating original
+  const transformed = JSON.parse(JSON.stringify(profile)) as AkashProfile;
+
+  // Get registry credentials
+  const credentials = manager.getRegistryCredentials();
+
+  // Transform each service
+  for (const [serviceName, service] of Object.entries(transformed.services)) {
+    // Service is typed from Zod schema
+    const originalImage = service.image;
+
+    // Check if this is a local image
+    const isLocal =
+      !originalImage.includes('/') ||
+      originalImage.startsWith('localhost/') ||
+      originalImage.startsWith('127.0.0.1/');
+
+    if (isLocal) {
+      // Get public registry URL for this image
+      const registryUrl = manager.getPublicImageUrl(serviceName, originalImage);
+
+      if (registryUrl) {
+        // Replace image with registry URL
+        service.image = registryUrl;
+
+        // Add registry credentials
+        if (credentials) {
+          service.credentials = {
+            host: credentials.host,
+            username: credentials.username,
+            password: credentials.password
+          };
+        }
+      }
+    }
+  }
+
+  return transformed;
+}
+
+/**
+ * Wait for containers to be running on Akash provider before shutting down registry
+ *
+ * This is called by the cleanup function to ensure providers have pulled images
+ * before we shut down the temporary registry.
+ *
+ * @param deploymentData - Deployment result from deploy-ability
+ * @param logger - Logger instance
+ * @param timeoutMs - How long to wait (default: 5 minutes)
+ */
+export async function waitForContainersRunning(
+  deploymentData: AkashDeploymentData,
+  logger: IKadiLogger,
+  timeoutMs: number = 300000
+): Promise<void> {
+  logger.log('⏳ Waiting for containers to be running on provider...');
+
+  // TODO: Use deploy-ability's waitForContainersRunning if available
+  // For now, just wait a bit to let providers pull images
+  await new Promise(resolve => setTimeout(resolve, 30000)); // 30 seconds
+
+  logger.log('✅ Containers should be running (or pulling images)');
+}