kadi-deploy 0.19.0

package/src/types/akash.ts

@@ -0,0 +1,116 @@
+/**
+ * Akash Network Profile Types
+ *
+ * Type definitions for Akash deployment profiles and service configurations.
+ * These types represent the profile structure AFTER loading from agent.json
+ * but BEFORE passing to deploy-ability.
+ */
+
+import type { ResourceConfig } from '../types.js';
+
+/**
+ * Port exposure configuration for Akash SDL
+ */
+export interface AkashPortExpose {
+  port: number;
+  as?: number;
+  to?: string[];
+  proto?: 'tcp' | 'udp';
+  global?: boolean;
+  accept?: string[];
+}
+
+/**
+ * Container registry credentials for private images
+ */
+export interface AkashRegistryCredentials {
+  host: string;
+  username: string;
+  password: string;
+}
+
+/**
+ * Pricing configuration for Akash bidding
+ */
+export interface AkashPricing {
+  denom: string; // e.g., "uakt"
+  amount: number | string;
+}
+
+/**
+ * Placement requirements for Akash providers
+ */
+export interface AkashPlacement {
+  signedBy?: {
+    allOf?: string[];
+    anyOf?: string[];
+  };
+  attributes?: Record<string, any>;
+}
+
+/**
+ * Service definition for Akash deployment
+ *
+ * Represents a single service in the deployment profile.
+ * Includes container image, runtime config, resources, and pricing.
+ */
+export interface AkashServiceDefinition {
+  /** Container image (e.g., "nginx:latest" or "my-app:1.0") */
+  image: string;
+
+  /** Optional command override */
+  command?: string[];
+
+  /** Environment variables (array or object format) */
+  env?: string[] | Record<string, string>;
+
+  /** Port exposures */
+  expose?: AkashPortExpose[];
+
+  /** Registry credentials for private images */
+  credentials?: AkashRegistryCredentials;
+
+  /** Resource requirements (CPU, memory, storage, GPU) */
+  resources?: ResourceConfig;
+
+  /** Pricing configuration for bidding */
+  pricing?: AkashPricing;
+
+  /** Number of instances to deploy */
+  count?: number;
+}
+
+/**
+ * Loaded Akash deployment profile
+ *
+ * Complete Akash profile structure after loading from agent.json.
+ * Contains all services and global placement/pricing settings.
+ */
+export interface LoadedAkashProfile {
+  /** Profile name */
+  selectedProfileName: string;
+
+  /** Deployment target (always 'akash') */
+  target: 'akash';
+
+  /** Network to deploy to */
+  network: 'mainnet' | 'testnet';
+
+  /** Container engine to use for local operations */
+  engine?: 'docker' | 'podman';
+
+  /** Service definitions */
+  services: Record<string, AkashServiceDefinition>;
+
+  /** Placement requirements (auditors, attributes) */
+  placement?: AkashPlacement;
+
+  /** WalletConnect project ID for mobile wallet connection */
+  walletConnectProjectId?: string;
+
+  /** Other profile options */
+  verbose?: boolean;
+  showCommands?: boolean;
+  yes?: boolean;
+  dryRun?: boolean;
+}

package/src/types/container-registry-ability.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Ambient type declarations for @kadi.build/container-registry-ability
+ *
+ * The package ships with types at src/types/index.d.ts but doesn't have a
+ * "types" field in package.json or a .d.ts for the main entry point.
+ * This declaration bridges that gap so we get proper type checking.
+ *
+ * Based on container-registry-ability v0.0.6 API surface.
+ */
+declare module '@kadi.build/container-registry-ability' {
+  export interface TunnelOptions {
+    subdomain?: string;
+    region?: string;
+    authtoken?: string;
+    authToken?: string;
+    host?: string;
+    port?: number;
+    protocol?: string;
+    /** Pass-through options for TunnelManager (e.g. fallbackServices) */
+    managerOptions?: Record<string, unknown>;
+  }
+
+  export interface RegistryUrls {
+    localUrl: string;
+    localDomain: string;
+    tunnelUrl: string | null;
+    tunnelDomain: string | null;
+    preferredUrl: string;
+    preferredDomain: string;
+  }
+
+  export interface Credentials {
+    accessKey: string;
+    secretKey: string;
+    expiry: Date;
+  }
+
+  export interface Container {
+    id: string;
+    name: string;
+    alias?: string;
+    tags: string[];
+    size: number;
+    addedAt: Date;
+  }
+
+  export interface ContainerSpec {
+    source?: string;
+    type?: 'docker' | 'podman' | 'tar' | 'mock';
+    name: string;
+    image?: string;
+    path?: string;
+    alias?: string;
+    tags?: string[];
+  }
+
+  export interface ContainerInfo {
+    id: string;
+    name: string;
+    alias: string;
+    tags: string[];
+    size: number;
+    addedAt: Date;
+    source: string;
+  }
+
+  export interface RegistryInfo {
+    status: string;
+    serverId: string;
+    localUrl: string;
+    tunnelUrl: string | null;
+    credentials: Credentials;
+    startTime: Date;
+    containers: Container[];
+  }
+
+  export interface TunneledContainerRegistryOptions {
+    port?: number;
+    serverName?: string;
+    tunnelService?: string;
+    tunnelOptions?: TunnelOptions;
+    credentials?: {
+      expiry?: number;
+      permissions?: string[];
+      customKey?: string;
+      customSecret?: string;
+    };
+    autoShutdown?: boolean;
+    shutdownOptions?: {
+      onCompletion?: boolean;
+      completionDelay?: number;
+      maxIdleTime?: number;
+      maxTotalTime?: number;
+    };
+    enableMonitoring?: boolean;
+    monitoringOptions?: {
+      updateInterval?: number;
+      enableDashboard?: boolean;
+      enableLogging?: boolean;
+    };
+    preferredEngine?: string;
+    containerType?: string;
+    engineOptions?: {
+      dockerSocket?: string;
+      podmanSocket?: string;
+    };
+    registryOptions?: {
+      enableCatalog?: boolean;
+      enableHealthCheck?: boolean;
+      customHeaders?: object;
+    };
+    enableLogging?: boolean;
+    logLevel?: string;
+    duration?: number;
+  }
+
+  export class TunneledContainerRegistry {
+    constructor(options?: TunneledContainerRegistryOptions);
+
+    // Core lifecycle
+    start(): Promise<RegistryInfo>;
+    stop(): Promise<void>;
+
+    // Container management
+    addContainer(containerSpec: ContainerSpec): Promise<ContainerInfo>;
+    addContainers(containerSpecs: ContainerSpec[]): Promise<ContainerInfo[]>;
+    removeContainer(nameOrId: string): Promise<void>;
+    listContainers(): Container[];
+
+    // Information
+    getRegistryInfo(): RegistryInfo;
+    getRegistryUrls(): Promise<RegistryUrls>;
+    getAccessCredentials(): Promise<Credentials>;
+    getDockerCommands(containerName?: string): Promise<object>;
+    getPodmanCommands(containerName?: string): Promise<object>;
+    getContainerCommands(containerName?: string): Promise<object>;
+    generateCommandHelp(options?: object): Promise<any>;
+
+    // Statistics
+    getStats(): object;
+    getRegistryStats(): object;
+    getContainerStats(nameOrId: string): object | null;
+
+    // Configuration
+    updateConfig(newConfig: Partial<TunneledContainerRegistryOptions>): Promise<void>;
+    refreshCredentials(options?: { expiry?: number }): Promise<Credentials>;
+
+    // Utility
+    healthCheck(): Promise<object>;
+    autoDiscoverContainers(options?: object): Promise<ContainerInfo[]>;
+    exportRegistryConfig(): Promise<object>;
+
+    // Event emitter
+    on(event: string, listener: (...args: any[]) => void): this;
+    once(event: string, listener: (...args: any[]) => void): this;
+    emit(event: string, ...args: any[]): boolean;
+  }
+}

package/src/types/external.ts

@@ -0,0 +1,49 @@
+// src/types/external.ts
+
+// Commander.js types
+export interface ICommander {
+  command(name: string): ICommand;
+  parse(argv?: string[]): void;
+  opts(): Record<string, unknown>;
+}
+
+export interface ICommand {
+  alias(alias: string): ICommand;
+  description(desc: string): ICommand;
+  // Register a subcommand on this command
+  command(name: string, opts?: { isDefault?: boolean }): ICommand;
+  // Overload for option without default value
+  option(flags: string, description: string): ICommand;
+  // Overload for option with default value but no parser function
+  option(flags: string, description: string, defaultValue: string | number | boolean): ICommand;
+  // Overload for option with parser function and optional default
+  option(
+    flags: string,
+    description: string,
+    fn: ((value: string, previous: unknown) => unknown) | RegExp,
+    defaultValue?: unknown
+  ): ICommand;
+  action(fn: (...args: unknown[]) => void | Promise<void>): ICommand;
+  addHelpText(position: string, text: string): ICommand;
+}
+
+// Logger types
+export interface IKadiLogger {
+  log(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  debug(message: string, ...args: unknown[]): void;
+  verbose(message: string, ...args: unknown[]): void;
+}
+
+// Core types
+export interface IKadiCore {
+  version: string;
+  config: Record<string, unknown>;
+  utils: {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+  };
+}

package/src/types.ts

@@ -0,0 +1,211 @@
+/**
+ * Core TypeScript interfaces for the KADI deploy profile system
+ *
+ * This file defines the type system for the profile-based deployment configuration
+ * that replaces the previous flag-based CLI approach. The system follows a three-tier
+ * precedence model: CLI flags > Profile settings > System defaults
+ */
+
+import type { ICommander, IKadiLogger, IKadiCore } from './types/external.js';
+
+/**
+ * DeployOptions represents raw CLI input before profile resolution
+ *
+ * This captures what the user provided via command-line flags. All fields are
+ * optional because users might rely on profile defaults or system defaults.
+ * The profile field indicates which profile to load from agent.json.
+ */
+export interface DeployOptions {
+  // Profile selection
+  profile?: string; // Name of the profile to use from agent.json
+
+  // CLI overrides - these take precedence over profile settings
+  target?: string;
+  network?: string;
+  engine?: string;
+  cert?: string;
+  useRemoteRegistry?: boolean;
+  registryDuration?: number;
+  tunnelService?: string; // Tunnel service (validated at runtime: kadi, ngrok, serveo, localtunnel)
+  interactive?: boolean;
+  dryRun?: boolean;
+  verbose?: boolean;
+  yes?: boolean;
+  showCommands?: boolean;
+  project?: string; // Path to project directory (defaults to cwd)
+
+  // Secrets injection options
+  secretTimeout?: number; // Timeout (ms) for waiting for agent to request secrets
+  autoApproveSecrets?: boolean; // Auto-approve secret requests without prompting
+
+  // Autonomous deployment options
+  autonomous?: boolean; // Enable fully autonomous deployment (no human interaction)
+  bidStrategy?: 'cheapest' | 'most-reliable' | 'balanced'; // Bid selection strategy for autonomous mode
+  bidMaxPrice?: number; // Maximum price per block in uAKT for bid filtering
+  requireAudited?: boolean; // Only accept bids from audited providers
+  secretsVault?: string; // Override vault name for secrets (default: from profile)
+
+  // Multi-instance deployment options
+  label?: string; // Human-readable label for this deployment instance (e.g. "broker-us-east")
+  instance?: string; // Target a specific deployment instance by ID
+}
+
+/**
+ * ResolvedDeployOptions represents the final configuration after merging
+ * CLI flags, profile settings, and system defaults
+ *
+ * This is what gets passed to deployment targets. All required fields have
+ * been resolved to concrete values, eliminating the need for target modules
+ * to handle undefined values or complex fallback logic.
+ */
+export interface ResolvedDeployOptions {
+  // Required fields - always have concrete values after resolution
+  target: 'local' | 'akash';
+  network: 'mainnet' | 'testnet';
+  engine: 'docker' | 'podman';
+  useRemoteRegistry: boolean;
+  registryDuration: number;
+  tunnelService: string;
+  interactive: boolean;
+  dryRun: boolean;
+  verbose: boolean;
+  yes: boolean;
+  showCommands: boolean;
+  project: string;
+
+  // Optional fields - may remain undefined if not specified anywhere
+  cert?: string; // Only defined if user provided cert path
+  profile?: string; // Profile name that was used (if any)
+
+  // Secrets injection options
+  secretTimeout?: number; // Timeout (ms) for waiting for agent to request secrets
+  autoApproveSecrets?: boolean; // Auto-approve secret requests without prompting
+
+  // Autonomous deployment options
+  autonomous?: boolean; // Enable fully autonomous deployment (no human interaction)
+  bidStrategy?: 'cheapest' | 'most-reliable' | 'balanced'; // Bid selection strategy for autonomous mode
+  bidMaxPrice?: number; // Maximum price per block in uAKT for bid filtering
+  requireAudited?: boolean; // Only accept bids from audited providers
+  secretsVault?: string; // Override vault name for secrets (default: from profile)
+
+  // Multi-instance deployment options
+  label?: string; // Human-readable label for this deployment instance
+  instance?: string; // Target a specific deployment instance by ID
+}
+
+/**
+ * Resource configuration for Akash deployments
+ * // DO I neeD THIS?
+ *
+ * Defines compute resources needed for the deployment. These get translated
+ * into Akash SDL (Stack Definition Language) resource requirements.
+ */
+/**
+ * Persistent volume specification for Akash Network
+ */
+export interface PersistentVolumeSpec {
+  /** Volume name (must be unique within service) */
+  name: string;
+  /** Volume size (e.g., "10Gi") */
+  size: string;
+  /** Container mount path (e.g., "/data") */
+  mount: string;
+  /** Storage class: beta1 (HDD), beta2 (SSD), beta3 (NVMe), ram */
+  class?: 'beta1' | 'beta2' | 'beta3' | 'ram';
+}
+
+/**
+ * Storage specification - supports both legacy and persistent formats
+ *
+ * **Legacy format (string):**
+ * Simple ephemeral storage that's wiped on restart
+ * Example: "2Gi"
+ *
+ * **Array format (persistent volumes):**
+ * First element: ephemeral storage size (required)
+ * Additional elements: named persistent volumes (optional)
+ * Example: ["512Mi", { name: "data", size: "10Gi", mount: "/data", class: "beta2" }]
+ */
+export type StorageSpec = string | [string, ...PersistentVolumeSpec[]];
+
+export interface ResourceConfig {
+  cpu?: number; // CPU units (e.g., 0.5 for half a CPU)
+  memory?: string; // Memory with units (e.g., "512Mi", "2Gi")
+  storage?: StorageSpec; // Storage: simple string or array with persistent volumes
+  gpu?: {
+    units: number; // Number of GPU units
+    attributes: {
+      vendor?: string; // GPU vendor (e.g., "nvidia", "amd")
+      model?: string; // GPU model (e.g., "rtx3060", "a100")
+    };
+  };
+}
+
+/**
+ * Complete agent configuration structure (agent.json)
+ *
+ * This represents the full agent.json file structure with support for both
+ * traditional service-based configuration and the new profile-based system.
+ * Variable interpolation is supported for ${name} and ${version} placeholders.
+ */
+export interface AgentConfig {
+  // Basic agent metadata
+  name: string; // Agent name (used for ${name} interpolation)
+  version: string; // Agent version (used for ${version} interpolation)
+  license?: string; // License identifier (e.g., "MIT")
+  description?: string; // Human-readable description
+
+  // Abilities configuration - defines what capabilities this agent has
+  abilities?: Record<string, string>; // Map of ability name to version (e.g., "data-processor": "1.2.0")
+
+  // Scripts configuration - lifecycle hooks for the agent
+  scripts?: Record<string, string>; // Map of script name to command (e.g., "setup": "npm install")
+
+  // Build configuration - compatibility with kadi-build profiles
+  build?: Record<string, any>; // Build profiles from kadi-build system
+
+  // Deploy configuration - the heart of the deploy profile system
+  // Raw JSON profiles - each target loads and validates its own profile format
+  deploy?: Record<string, any>;
+
+  // Broker configuration - WebSocket URLs for KADI broker connections
+  // Used for secrets injection to share secrets with deployed agents
+  brokers?: Record<string, string>; // Map of broker name to WebSocket URL (e.g., "default": "ws://localhost:8080/kadi")
+}
+
+/**
+ * KADI CLI context interface
+ *
+ * Provides access to core KADI CLI functionality like command registration,
+ * logging, and core utilities. Passed to all KADI plugins and modules.
+ */
+export interface IKadiContext {
+  commander: ICommander; // Commander.js instance for CLI registration
+  logger: IKadiLogger; // KADI logging utilities
+  core: IKadiCore; // Core KADI functionality and utilities
+}
+
+/**
+ * Deployment context passed to target modules
+ *
+ * This is the complete context that deployment targets (local.js, akash.js)
+ * receive. It includes the original KADI context plus deployment-specific
+ * information like the resolved configuration and agent metadata.
+ */
+export interface DeploymentContext extends IKadiContext {
+  projectRoot: string; // Absolute path to the project being deployed
+  agent: AgentConfig; // Parsed agent.json configuration
+  flags: ResolvedDeployOptions; // Final deployment configuration after resolution
+}
+
+/**
+ * Target module interface
+ *
+ * All deployment targets must implement this interface. The deploy method
+ * receives a complete DeploymentContext and is responsible for executing
+ * the deployment according to the resolved configuration.
+ */
+export interface DeployTarget {
+  description: string;
+  deploy(ctx: DeploymentContext): Promise<void>;
+}

package/src/utils/akt-price.ts

@@ -0,0 +1,74 @@
+/**
+ * AKT Price Fetcher
+ *
+ * Utility for fetching current AKT token price in USD from CoinGecko API.
+ * Used for displaying USD pricing in bid selection and deployment summaries.
+ *
+ * @module utils/akt-price
+ */
+
+/**
+ * Fetch current AKT price in USD from CoinGecko
+ *
+ * Makes a request to CoinGecko's public API to get the current market price
+ * of Akash Network (AKT) token in USD.
+ *
+ * **API Details:**
+ * - Endpoint: https://api.coingecko.com/api/v3/simple/price
+ * - No API key required for basic usage
+ * - Rate limit: ~10-50 requests/minute (free tier)
+ * - Response format: { "akash-network": { "usd": 0.45 } }
+ *
+ * **Error Handling:**
+ * Returns undefined if the fetch fails for any reason (network error, API down, etc.)
+ * This allows the caller to gracefully degrade to showing only AKT pricing.
+ *
+ * @returns Promise resolving to USD price per AKT, or undefined if unavailable
+ *
+ * @example Basic usage
+ * ```typescript
+ * const aktPrice = await fetchAktPriceUSD();
+ * if (aktPrice) {
+ *   console.log(`1 AKT = $${aktPrice.toFixed(2)}`);
+ * } else {
+ *   console.log('AKT price unavailable');
+ * }
+ * ```
+ *
+ * @example With bid selector
+ * ```typescript
+ * const aktPrice = await fetchAktPriceUSD();
+ * const selected = await selectBidInteractively(bids, aktPrice);
+ * ```
+ */
+export async function fetchAktPriceUSD(): Promise<number | undefined> {
+  try {
+    const response = await fetch(
+      'https://api.coingecko.com/api/v3/simple/price?ids=akash-network&vs_currencies=usd',
+      {
+        // 5 second timeout
+        signal: AbortSignal.timeout(5000),
+        headers: {
+          'Accept': 'application/json',
+        }
+      }
+    );
+
+    if (!response.ok) {
+      return undefined;
+    }
+
+    const data = await response.json();
+    const price = data?.['akash-network']?.['usd'];
+
+    // Validate price is a positive number
+    if (typeof price === 'number' && price > 0 && Number.isFinite(price)) {
+      return price;
+    }
+
+    return undefined;
+  } catch (error) {
+    // Silent failure - caller can handle missing price gracefully
+    return undefined;
+  }
+}