@kadi.build/deploy-ability 0.0.5 → 0.0.6

package/docs/PIPELINE_BUILDER_DESIGN.md

@@ -1,1149 +0,0 @@
-# Pipeline Builder Pattern Design Proposal
-
-> **Status**: Draft Proposal
-> **Author**: Design discussion with Claude Code
-> **Date**: 2025-11-18
-> **Target**: deploy-ability v0.1.0
-
----
-
-## Table of Contents
-
-1. [Executive Summary](#executive-summary)
-2. [Current Design & Problems](#current-design--problems)
-3. [Proposed Solution: Pipeline Builder](#proposed-solution-pipeline-builder)
-4. [API Design](#api-design)
-5. [Before/After Comparison](#beforeafter-comparison)
-6. [Implementation Plan](#implementation-plan)
-7. [Migration Strategy](#migration-strategy)
-8. [Benefits & Trade-offs](#benefits--trade-offs)
-
----
-
-## Executive Summary
-
-**Problem**: The current deploy-ability API has excellent separation of concerns but poor discoverability and error-prone usage patterns. Users must manually orchestrate registry setup, profile transformation, and cleanup - leading to easy mistakes and confusing errors.
-
-**Solution**: Introduce a fluent Pipeline Builder API that makes deployment steps explicit, discoverable, and safe by default. The pipeline handles orchestration, lifecycle management, and automatic cleanup while preserving the underlying composable primitives.
-
-**Impact**:
-- **Users**: Simpler, safer API that's hard to misuse
-- **Library**: Backward compatible - builder is new, primitives remain unchanged
-- **Code Quality**: Reduced boilerplate, automatic resource cleanup, better error messages
-
----
-
-## Current Design & Problems
-
-### How It Works Today
-
-The current design separates concerns across multiple layers:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ Layer 1: kadi-deploy (CLI Orchestration)                   │
-│                                                             │
-│ 1. Load profile from agent.json                            │
-│ 2. Call setupRegistryIfNeeded() → returns transformed      │
-│ 3. Call deployToAkash() with transformed profile           │
-│ 4. Remember to call cleanup() in finally block             │
-└─────────────────────────────────────────────────────────────┘
-                           ↓
-┌─────────────────────────────────────────────────────────────┐
-│ Layer 2: deploy-ability (Library Primitives)               │
-│                                                             │
-│ • setupRegistryIfNeeded() - Optional pre-processing        │
-│ • deployToAkash() - Core deployment logic                  │
-│ • loadProfile() - Profile loading                          │
-│ • generateAkashSdl() - SDL generation                      │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Current Usage Pattern (kadi-deploy)
-
-```typescript
-// File: kadi-deploy/src/targets/akash/akash.ts
-
-export async function deployToAkash(ctx: DeploymentContext) {
-  const { profile, wallet, certificate, logger } = ctx;
-
-  // Step 1: Manually setup registry (easy to forget!)
-  const registryCtx = await setupRegistryIfNeeded(
-    profile,
-    logger,
-    {
-      containerEngine: 'docker',
-      tunnelService: 'serveo'
-    }
-  );
-
-  // Step 2: Remember the cleanup function for later
-  const cleanup = registryCtx.cleanup;
-
-  try {
-    // Step 3: Call deployment with transformed profile
-    const result = await deployToAkash({
-      loadedProfile: {
-        profile: registryCtx.deployableProfile  // ← Transformed!
-      },
-      wallet,
-      certificate,
-      bidSelector: selectCheapestBid,
-      logger
-    });
-
-    if (!result.success) {
-      throw new Error(result.error.message);
-    }
-
-    return result.data;
-
-  } finally {
-    // Step 4: Manual cleanup (easy to forget or get wrong!)
-    await cleanup();
-  }
-}
-```
-
-### Problems with Current Design
-
-#### 1. **Discoverability Problem**
-
-Looking at `deployToAkash()` signature, there's NO indication that local images require special handling:
-
-```typescript
-// What the signature shows:
-export async function deployToAkash(
-  params: AkashDeploymentExecution
-): Promise<AkashDeploymentResult>
-
-// What it DOESN'T show:
-// ⚠️  If your profile uses local images, call setupRegistryIfNeeded() first!
-// ⚠️  Don't forget to call the cleanup function!
-// ⚠️  Use a try-finally block to ensure cleanup happens!
-```
-
-**Result**: New users (or even experienced ones in a hurry) will write:
-
-```typescript
-// This looks right but FAILS at runtime! ❌
-const result = await deployToAkash({
-  projectRoot: './',
-  profile: 'my-profile',  // Contains "image": "my-app:latest"
-  wallet,
-  certificate,
-  bidSelector: selectCheapestBid
-});
-
-// Error (on Akash provider, minutes later):
-// "Failed to pull image: my-app:latest - not found"
-```
-
-The error happens **remotely** on the Akash provider, not locally where you can catch it early.
-
-#### 2. **Manual Lifecycle Management**
-
-Users must remember to:
-- Call `setupRegistryIfNeeded()` before deployment
-- Store the `cleanup` function
-- Call `cleanup()` in a finally block
-- Handle cleanup errors gracefully
-
-**This is error-prone**:
-
-```typescript
-// What if deployment throws before cleanup is set up?
-const registryCtx = await setupRegistryIfNeeded(...);
-const cleanup = registryCtx.cleanup;  // ← Not in try block yet!
-
-// What if user forgets finally block?
-try {
-  await deployToAkash(...);
-} catch (error) {
-  console.error(error);
-  return;  // ← Forgot cleanup! Registry keeps running!
-}
-
-// What if cleanup throws?
-finally {
-  await cleanup();  // ← Could throw and mask deployment errors
-}
-```
-
-#### 3. **Split Brain Problem**
-
-To understand the complete deployment flow, you need to know about:
-- **deploy-ability**: The core primitives (`deployToAkash`, `setupRegistryIfNeeded`)
-- **kadi-deploy**: The orchestration logic (how primitives are combined)
-
-There's no single place that shows the "canonical way" to deploy with local images.
-
-#### 4. **TypeScript Can't Help**
-
-The type system doesn't encode the relationship between local images and registry setup:
-
-```typescript
-// TypeScript is happy with this, but it's wrong at runtime:
-const profile: AkashDeploymentProfile = {
-  target: 'akash',
-  services: {
-    app: {
-      image: 'my-local-image:latest'  // ← Local image!
-    }
-  }
-};
-
-// TypeScript doesn't warn you about this:
-await deployToAkash({
-  loadedProfile: { profile },  // ← Missing registry setup!
-  wallet,
-  certificate
-});
-```
-
-#### 5. **Verbose Boilerplate**
-
-Every consumer of deploy-ability needs to write the same orchestration logic:
-
-```typescript
-// This pattern repeats in every deployment tool:
-const registryCtx = await setupRegistryIfNeeded(...);
-try {
-  const result = await deployToAkash({
-    loadedProfile: { profile: registryCtx.deployableProfile },
-    ...
-  });
-  return result;
-} finally {
-  await registryCtx.cleanup();
-}
-```
-
----
-
-## Proposed Solution: Pipeline Builder
-
-### Core Concept
-
-Introduce a **fluent builder API** that:
-1. Makes deployment steps **explicit** and **discoverable**
-2. Handles **lifecycle management** automatically
-3. Provides **clear error messages** for missing steps
-4. Remains **backward compatible** (keeps existing primitives)
-
-### Mental Model
-
-Think of deployment as building a pipeline with stages:
-
-```
-Profile Loading → Registry Setup → Wallet → Certificate → Execution → Cleanup
-    (Stage 1)       (Stage 2)     (Stage 3)  (Stage 4)   (Stage 5)   (Auto)
-```
-
-Each stage:
-- Is **explicit** (you call a method to add it)
-- Is **validated** (builder checks you didn't skip required steps)
-- Is **typed** (TypeScript guides you through the steps)
-- Is **automatic** (lifecycle handled for you)
-
-### Key Design Principles
-
-1. **Fluent & Discoverable**: Chaining methods makes steps obvious
-2. **Safe by Default**: Can't execute without required stages
-3. **Automatic Cleanup**: Resources freed via RAII pattern
-4. **Backward Compatible**: Original functions still work
-5. **Progressive Disclosure**: Simple by default, powerful when needed
-
----
-
-## API Design
-
-### Basic Usage
-
-```typescript
-import { DeploymentPipeline } from '@kadi.build/deploy-ability/akash';
-
-// Simple deployment with local images
-const result = await DeploymentPipeline
-  .create({ projectRoot: './', profile: 'production' })
-  .withLocalImageSupport({ tunnelService: 'serveo' })
-  .withWallet(wallet)
-  .withCertificate(certificate)
-  .execute();
-
-// Cleanup happens automatically!
-```
-
-### Advanced Usage
-
-```typescript
-// Full control with custom bid selection
-const result = await DeploymentPipeline
-  .create({
-    projectRoot: './',
-    profile: 'production',
-    network: 'mainnet'
-  })
-  .withLocalImageSupport({
-    tunnelService: 'ngrok',
-    tunnelAuthToken: process.env.NGROK_TOKEN
-  })
-  .withWallet(wallet)
-  .withCertificate(certificate)
-  .withBidSelector((bids) => {
-    const filtered = filterBids(bids, {
-      maxPricePerMonth: { usd: 50, aktPrice: 0.45 },
-      minUptime: { value: 0.95, period: '7d' }
-    });
-    return selectCheapestBid(filtered);
-  })
-  .withLogger(customLogger)
-  .execute();
-```
-
-### Conditional Registry Setup
-
-```typescript
-// Automatic detection - registry only starts if needed
-const result = await DeploymentPipeline
-  .create({ projectRoot: './', profile: 'production' })
-  .withLocalImageSupport()  // ← Auto-detects, no-op if all remote
-  .withWallet(wallet)
-  .withCertificate(certificate)
-  .execute();
-```
-
-### Pre-loaded Profile (Advanced)
-
-```typescript
-// When you already have a transformed profile
-const result = await DeploymentPipeline
-  .createFromProfile(transformedProfile, 'production')
-  .withWallet(wallet)
-  .withCertificate(certificate)
-  .execute();
-```
-
-### Dry Run Mode
-
-```typescript
-// Generate SDL without deploying
-const result = await DeploymentPipeline
-  .create({ projectRoot: './', profile: 'production' })
-  .dryRun();
-
-console.log('SDL:', result.data.sdl);
-```
-
-### Error Handling
-
-```typescript
-try {
-  const result = await DeploymentPipeline
-    .create({ projectRoot: './', profile: 'production' })
-    .withWallet(wallet)
-    .execute();  // ← Missing certificate!
-
-} catch (error) {
-  if (error instanceof PipelineValidationError) {
-    console.error('Pipeline not configured correctly:', error.message);
-    // "Certificate is required. Call .withCertificate() before .execute()"
-  }
-}
-```
-
-### Monitoring & Callbacks
-
-```typescript
-const result = await DeploymentPipeline
-  .create({ projectRoot: './', profile: 'production' })
-  .withLocalImageSupport()
-  .withWallet(wallet)
-  .withCertificate(certificate)
-  .onRegistryStarted((info) => {
-    console.log(`Registry available at: ${info.tunnelUrl}`);
-  })
-  .onBidsReceived((bids) => {
-    console.log(`Received ${bids.length} bids`);
-  })
-  .onLeaseCreated((lease) => {
-    console.log(`Lease created with ${lease.provider}`);
-  })
-  .execute();
-```
-
----
-
-## Before/After Comparison
-
-### Consumer: kadi-deploy CLI
-
-#### Before (Current Design)
-
-```typescript
-// File: kadi-deploy/src/targets/akash/akash.ts
-
-import {
-  deployToAkash,
-  setupRegistryIfNeeded,
-  selectCheapestBid
-} from '@kadi.build/deploy-ability/akash';
-
-export async function deployAkashProfile(ctx: DeploymentContext) {
-  const { profile, wallet, certificate, logger } = ctx;
-
-  // Manual orchestration
-  logger.log('Setting up registry for local images...');
-  const registryCtx = await setupRegistryIfNeeded(
-    profile,
-    logger,
-    {
-      containerEngine: 'docker',
-      tunnelService: 'serveo'
-    }
-  );
-
-  const cleanup = registryCtx.cleanup;
-
-  try {
-    logger.log('Deploying to Akash...');
-
-    const result = await deployToAkash({
-      loadedProfile: {
-        profile: registryCtx.deployableProfile
-      },
-      wallet,
-      certificate,
-      bidSelector: selectCheapestBid,
-      logger
-    });
-
-    if (!result.success) {
-      throw new Error(result.error.message);
-    }
-
-    logger.log('✅ Deployment successful!');
-    return result.data;
-
-  } catch (error) {
-    logger.error('❌ Deployment failed:', error);
-    throw error;
-
-  } finally {
-    logger.log('Cleaning up registry...');
-    try {
-      await cleanup();
-    } catch (cleanupError) {
-      logger.warn('Warning: Registry cleanup failed:', cleanupError);
-    }
-  }
-}
-```
-
-**Issues**:
-- 48 lines of boilerplate
-- Manual lifecycle management
-- Nested try-catch for cleanup errors
-- Easy to forget steps
-
-#### After (Pipeline Builder)
-
-```typescript
-// File: kadi-deploy/src/targets/akash/akash.ts
-
-import {
-  DeploymentPipeline,
-  selectCheapestBid
-} from '@kadi.build/deploy-ability/akash';
-
-export async function deployAkashProfile(ctx: DeploymentContext) {
-  const { profile, wallet, certificate, logger } = ctx;
-
-  // Pipeline handles orchestration
-  const result = await DeploymentPipeline
-    .createFromProfile(profile, ctx.profileName)
-    .withLocalImageSupport({ tunnelService: 'serveo' })
-    .withWallet(wallet)
-    .withCertificate(certificate)
-    .withBidSelector(selectCheapestBid)
-    .withLogger(logger)
-    .execute();
-
-  if (!result.success) {
-    throw new Error(result.error.message);
-  }
-
-  return result.data;
-}
-```
-
-**Improvements**:
-- 19 lines (60% reduction)
-- No manual lifecycle management
-- Automatic cleanup (even on errors)
-- Clear, readable flow
-
-### Consumer: Custom Deployment Script
-
-#### Before (Current Design)
-
-```typescript
-// deploy.ts - User's custom deployment script
-
-import {
-  deployToAkash,
-  setupRegistryIfNeeded,
-  connectWallet,
-  ensureCertificate,
-  createSigningClient,
-  selectCheapestBid
-} from '@kadi.build/deploy-ability/akash';
-
-async function deploy() {
-  // Step 1: Connect wallet
-  const walletResult = await connectWallet({ network: 'mainnet' });
-  if (!walletResult.success) throw walletResult.error;
-
-  // Step 2: Ensure certificate
-  const clientResult = await createSigningClient(walletResult.data, 'mainnet');
-  if (!clientResult.success) throw clientResult.error;
-
-  const certResult = await ensureCertificate(
-    walletResult.data,
-    'mainnet',
-    clientResult.data.client
-  );
-  if (!certResult.success) throw certResult.error;
-
-  // Step 3: Load profile from disk
-  const profile = JSON.parse(
-    fs.readFileSync('./agent.json', 'utf-8')
-  ).deploy['production'];
-
-  // Step 4: Setup registry
-  const registryCtx = await setupRegistryIfNeeded(profile, console, {
-    containerEngine: 'docker',
-    tunnelService: 'serveo'
-  });
-
-  try {
-    // Step 5: Deploy
-    const result = await deployToAkash({
-      loadedProfile: { profile: registryCtx.deployableProfile },
-      wallet: walletResult.data,
-      certificate: certResult.data,
-      bidSelector: selectCheapestBid
-    });
-
-    if (!result.success) {
-      throw new Error(result.error.message);
-    }
-
-    console.log('Deployed!', result.data);
-
-  } finally {
-    await registryCtx.cleanup();
-  }
-}
-
-deploy().catch(console.error);
-```
-
-**Issues**:
-- Verbose error checking
-- Manual orchestration
-- Easy to forget cleanup
-
-#### After (Pipeline Builder)
-
-```typescript
-// deploy.ts - User's custom deployment script
-
-import {
-  DeploymentPipeline,
-  connectWallet,
-  ensureCertificate,
-  createSigningClient,
-  selectCheapestBid
-} from '@kadi.build/deploy-ability/akash';
-
-async function deploy() {
-  // Setup wallet & certificate (same as before)
-  const walletResult = await connectWallet({ network: 'mainnet' });
-  if (!walletResult.success) throw walletResult.error;
-
-  const clientResult = await createSigningClient(walletResult.data, 'mainnet');
-  if (!clientResult.success) throw clientResult.error;
-
-  const certResult = await ensureCertificate(
-    walletResult.data,
-    'mainnet',
-    clientResult.data.client
-  );
-  if (!certResult.success) throw certResult.error;
-
-  // Deploy with pipeline - much simpler!
-  const result = await DeploymentPipeline
-    .create({
-      projectRoot: './',
-      profile: 'production',
-      network: 'mainnet'
-    })
-    .withLocalImageSupport({ tunnelService: 'serveo' })
-    .withWallet(walletResult.data)
-    .withCertificate(certResult.data)
-    .withBidSelector(selectCheapestBid)
-    .execute();
-
-  if (!result.success) {
-    throw new Error(result.error.message);
-  }
-
-  console.log('Deployed!', result.data);
-}
-
-deploy().catch(console.error);
-```
-
-**Improvements**:
-- Cleaner deployment orchestration
-- No manual cleanup
-- Easier to read and understand
-
-### Consumer: Autonomous Agent (Model Manager)
-
-#### Before (Current Design)
-
-```typescript
-// src/services/deployment-logic.ts (Model Manager Agent)
-
-async deployModel(request: DeploymentRequest) {
-  const profile = this.profileGenerator.generate(request);
-
-  // Manual registry setup
-  const registryCtx = await setupRegistryIfNeeded(
-    profile,
-    this.logger,
-    { containerEngine: 'docker' }
-  );
-
-  try {
-    const result = await deployToAkash({
-      loadedProfile: { profile: registryCtx.deployableProfile },
-      wallet: this.walletContext,
-      certificate: this.certificate,
-      bidSelector: selectCheapestBid,
-      logger: this.logger
-    });
-
-    if (!result.success) {
-      throw new Error(result.error.message);
-    }
-
-    return {
-      dseq: result.data.dseq,
-      provider: result.data.providerUri,
-      endpoints: result.data.endpoints
-    };
-
-  } finally {
-    await registryCtx.cleanup();
-  }
-}
-```
-
-#### After (Pipeline Builder)
-
-```typescript
-// src/services/deployment-logic.ts (Model Manager Agent)
-
-async deployModel(request: DeploymentRequest) {
-  const profile = this.profileGenerator.generate(request);
-
-  // Pipeline handles everything
-  const result = await DeploymentPipeline
-    .createFromProfile(profile, request.model.name)
-    .withLocalImageSupport()  // Auto-detects, no-op if not needed
-    .withWallet(this.walletContext)
-    .withCertificate(this.certificate)
-    .withBidSelector(selectCheapestBid)
-    .withLogger(this.logger)
-    .execute();
-
-  if (!result.success) {
-    throw new Error(result.error.message);
-  }
-
-  return {
-    dseq: result.data.dseq,
-    provider: result.data.providerUri,
-    endpoints: result.data.endpoints
-  };
-}
-```
-
-**Improvements**:
-- Simpler agent code
-- Automatic resource cleanup
-- Better error handling
-
----
-
-## Implementation Plan
-
-### Phase 1: Core Pipeline Builder
-
-**Goal**: Implement basic pipeline with existing primitives
-
-**Files to Create**:
-```
-src/targets/akash/
-  ├── pipeline/
-  │   ├── index.ts              # Public exports
-  │   ├── DeploymentPipeline.ts # Main builder class
-  │   ├── PipelineStage.ts      # Stage definitions
-  │   ├── PipelineContext.ts    # Internal state
-  │   ├── PipelineValidator.ts  # Validation logic
-  │   └── errors.ts             # Pipeline-specific errors
-```
-
-**Implementation**:
-
-```typescript
-// src/targets/akash/pipeline/DeploymentPipeline.ts
-
-export class DeploymentPipeline {
-  private context: PipelineContext;
-
-  private constructor(context: PipelineContext) {
-    this.context = context;
-  }
-
-  // ========================================
-  // Factory Methods
-  // ========================================
-
-  static create(options: {
-    projectRoot: string;
-    profile: string;
-    network?: AkashNetwork;
-  }): DeploymentPipeline {
-    return new DeploymentPipeline({
-      stage: 'initialized',
-      options
-    });
-  }
-
-  static createFromProfile(
-    profile: AkashDeploymentProfile,
-    profileName: string
-  ): DeploymentPipeline {
-    return new DeploymentPipeline({
-      stage: 'profile-loaded',
-      loadedProfile: { profile, name: profileName }
-    });
-  }
-
-  // ========================================
-  // Builder Methods
-  // ========================================
-
-  withLocalImageSupport(options?: RegistryOptions): DeploymentPipeline {
-    this.context.registryOptions = options || {};
-    this.context.enableRegistry = true;
-    return this;
-  }
-
-  withWallet(wallet: WalletContext): DeploymentPipeline {
-    this.context.wallet = wallet;
-    return this;
-  }
-
-  withCertificate(certificate: AkashProviderTlsCertificate): DeploymentPipeline {
-    this.context.certificate = certificate;
-    return this;
-  }
-
-  withBidSelector(selector: BidSelector): DeploymentPipeline {
-    this.context.bidSelector = selector;
-    return this;
-  }
-
-  withLogger(logger: DeploymentLogger): DeploymentPipeline {
-    this.context.logger = logger;
-    return this;
-  }
-
-  // ========================================
-  // Execution
-  // ========================================
-
-  async execute(): Promise<AkashDeploymentResult> {
-    // Validate pipeline configuration
-    this.validate();
-
-    // Track resources for cleanup
-    const resources: ResourceHandle[] = [];
-
-    try {
-      // Stage 1: Load profile if needed
-      await this.loadProfileIfNeeded();
-
-      // Stage 2: Setup registry if needed
-      const registryHandle = await this.setupRegistryIfNeeded();
-      if (registryHandle) resources.push(registryHandle);
-
-      // Stage 3: Deploy to Akash
-      const result = await this.deploy();
-
-      return result;
-
-    } finally {
-      // Automatic cleanup (reverse order)
-      await this.cleanup(resources);
-    }
-  }
-
-  async dryRun(): Promise<AkashDeploymentResult> {
-    await this.loadProfileIfNeeded();
-    // Generate SDL only, no deployment
-    const sdl = generateAkashSdl(this.context.loadedProfile!);
-    return success({
-      dryRun: true,
-      sdl,
-      profile: this.context.loadedProfile!.name,
-      network: this.context.options!.network || 'mainnet'
-    });
-  }
-
-  // ========================================
-  // Internal Methods
-  // ========================================
-
-  private validate(): void {
-    if (!this.context.wallet) {
-      throw new PipelineValidationError(
-        'Wallet is required. Call .withWallet(wallet) before .execute()'
-      );
-    }
-
-    if (!this.context.certificate) {
-      throw new PipelineValidationError(
-        'Certificate is required. Call .withCertificate(cert) before .execute()'
-      );
-    }
-
-    // More validation...
-  }
-
-  private async loadProfileIfNeeded(): Promise<void> {
-    if (this.context.loadedProfile) return;
-
-    const profile = await loadProfile(
-      this.context.options!.projectRoot,
-      this.context.options!.profile,
-      this.context.logger || defaultLogger
-    );
-
-    this.context.loadedProfile = profile;
-  }
-
-  private async setupRegistryIfNeeded(): Promise<ResourceHandle | null> {
-    if (!this.context.enableRegistry) return null;
-
-    const logger = this.context.logger || defaultLogger;
-    const registryCtx = await setupRegistryIfNeeded(
-      this.context.loadedProfile!.profile,
-      logger,
-      this.context.registryOptions
-    );
-
-    // Update profile with transformed version
-    this.context.loadedProfile!.profile = registryCtx.deployableProfile;
-
-    // Return cleanup handle
-    return {
-      name: 'registry',
-      cleanup: registryCtx.cleanup
-    };
-  }
-
-  private async deploy(): Promise<AkashDeploymentResult> {
-    return deployToAkash({
-      loadedProfile: this.context.loadedProfile!,
-      wallet: this.context.wallet!,
-      certificate: this.context.certificate!,
-      bidSelector: this.context.bidSelector || selectCheapestBid,
-      logger: this.context.logger
-    });
-  }
-
-  private async cleanup(resources: ResourceHandle[]): Promise<void> {
-    // Cleanup in reverse order (LIFO)
-    for (const resource of resources.reverse()) {
-      try {
-        await resource.cleanup();
-      } catch (error) {
-        const logger = this.context.logger || defaultLogger;
-        logger.warn(`Failed to cleanup ${resource.name}:`, error);
-      }
-    }
-  }
-}
-
-// ========================================
-// Supporting Types
-// ========================================
-
-interface PipelineContext {
-  stage: 'initialized' | 'profile-loaded' | 'registry-setup' | 'deploying';
-  options?: {
-    projectRoot: string;
-    profile: string;
-    network?: AkashNetwork;
-  };
-  loadedProfile?: {
-    profile: AkashDeploymentProfile;
-    name: string;
-  };
-  enableRegistry?: boolean;
-  registryOptions?: RegistryOptions;
-  wallet?: WalletContext;
-  certificate?: AkashProviderTlsCertificate;
-  bidSelector?: BidSelector;
-  logger?: DeploymentLogger;
-}
-
-interface ResourceHandle {
-  name: string;
-  cleanup: () => Promise<void>;
-}
-
-export class PipelineValidationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'PipelineValidationError';
-  }
-}
-```
-
-### Phase 2: Enhanced Features
-
-**Add lifecycle callbacks**:
-
-```typescript
-withCallbacks(callbacks: {
-  onRegistryStarted?: (info: RegistryInfo) => void;
-  onProfileLoaded?: (profile: AkashDeploymentProfile) => void;
-  onBidsReceived?: (bids: EnhancedBid[]) => void;
-  onLeaseCreated?: (lease: LeaseDetails) => void;
-}): DeploymentPipeline
-```
-
-**Add monitoring integration**:
-
-```typescript
-withMonitoring(options: {
-  waitForContainers?: boolean;
-  containerTimeout?: number;
-  streamLogs?: boolean;
-}): DeploymentPipeline
-```
-
-### Phase 3: Documentation & Examples
-
-1. Update main README with pipeline examples
-2. Create `docs/PIPELINE_API.md` with full API reference
-3. Add examples to `examples/` directory
-4. Update TypeDoc comments
-
----
-
-## Migration Strategy
-
-### Backward Compatibility
-
-**Principle**: The pipeline builder is **additive** - all existing functions remain unchanged.
-
-```typescript
-// Old way still works!
-import { deployToAkash, setupRegistryIfNeeded } from '@kadi.build/deploy-ability/akash';
-
-const registryCtx = await setupRegistryIfNeeded(...);
-try {
-  const result = await deployToAkash({
-    loadedProfile: { profile: registryCtx.deployableProfile },
-    ...
-  });
-} finally {
-  await registryCtx.cleanup();
-}
-```
-
-```typescript
-// New way is optional
-import { DeploymentPipeline } from '@kadi.build/deploy-ability/akash';
-
-const result = await DeploymentPipeline
-  .create({ projectRoot: './', profile: 'prod' })
-  .withLocalImageSupport()
-  .withWallet(wallet)
-  .withCertificate(cert)
-  .execute();
-```
-
-### Migration Path
-
-#### Step 1: Soft Deprecation (v0.1.0)
-
-- Add pipeline builder to library
-- Update docs to show pipeline as recommended approach
-- Mark old approach as "still supported"
-
-```typescript
-/**
- * @deprecated Prefer using DeploymentPipeline for better ergonomics
- * @see DeploymentPipeline
- */
-export async function deployToAkash(...) { ... }
-```
-
-#### Step 2: Community Feedback (v0.2.0 - v0.5.0)
-
-- Gather feedback on pipeline API
-- Iterate on design based on real usage
-- Keep both approaches working
-
-#### Step 3: Hard Deprecation (v1.0.0)
-
-- Pipeline is primary API
-- Old functions remain but warn in console
-- Documentation shows pipeline only
-
-#### Step 4: Removal (v2.0.0)
-
-- Remove old functions (breaking change)
-- Pipeline is the only way
-
-### Gradual Adoption
-
-**Users can adopt incrementally**:
-
-```typescript
-// Week 1: Just wrap existing code
-const result = await DeploymentPipeline
-  .createFromProfile(profile, 'prod')
-  .withWallet(wallet)
-  .withCertificate(cert)
-  .execute();
-
-// Week 2: Add local image support
-const result = await DeploymentPipeline
-  .create({ projectRoot: './', profile: 'prod' })
-  .withLocalImageSupport()  // ← New!
-  .withWallet(wallet)
-  .withCertificate(cert)
-  .execute();
-
-// Week 3: Add custom bid selection
-const result = await DeploymentPipeline
-  .create({ projectRoot: './', profile: 'prod' })
-  .withLocalImageSupport()
-  .withWallet(wallet)
-  .withCertificate(cert)
-  .withBidSelector(customSelector)  // ← New!
-  .execute();
-```
-
----
-
-## Benefits & Trade-offs
-
-### Benefits
-
-#### 1. **Discoverability**
-- IDE autocomplete guides you through steps
-- Method names are self-documenting
-- Can't forget required steps
-
-#### 2. **Safety**
-- Validation catches configuration errors early
-- Automatic cleanup prevents resource leaks
-- Type system encodes requirements
-
-#### 3. **Ergonomics**
-- Less boilerplate (60% reduction)
-- No manual lifecycle management
-- Cleaner, more readable code
-
-#### 4. **Flexibility**
-- Stages are optional (progressive disclosure)
-- Can still use primitives for advanced cases
-- Backward compatible
-
-#### 5. **Error Messages**
-```typescript
-// Before: Confusing error at runtime on Akash
-"Failed to pull image: my-app:latest"
-
-// After: Clear error immediately
-"Pipeline validation failed: Wallet is required.
-Call .withWallet(wallet) before .execute()"
-```
-
-### Trade-offs
-
-#### 1. **More Code in Library**
-- **Cost**: ~500 lines for pipeline implementation
-- **Benefit**: Shared across all consumers (net reduction overall)
-
-#### 2. **Learning Curve**
-- **Cost**: Users need to learn builder pattern
-- **Benefit**: Pattern is familiar from other libraries (e.g., Axios, TypeORM)
-
-#### 3. **Less Control**
-- **Cost**: Some orchestration is hidden
-- **Benefit**: Can still use primitives for full control
-
-#### 4. **Testing Complexity**
-- **Cost**: Need to test pipeline stages
-- **Benefit**: Better test coverage overall
-
-### Comparison Table
-
-| Aspect | Current (Primitives) | Pipeline Builder |
-|--------|---------------------|------------------|
-| **Lines of Code** | ~40-50 lines | ~15-20 lines |
-| **Discoverability** | ❌ Poor | ✅ Excellent |
-| **Error Messages** | ❌ Confusing | ✅ Clear |
-| **Lifecycle Management** | ❌ Manual | ✅ Automatic |
-| **Type Safety** | ⚠️  Partial | ✅ Complete |
-| **Flexibility** | ✅ Full control | ✅ Still available |
-| **Learning Curve** | ⚠️  Medium | ⚠️  Medium |
-| **Code in Library** | ✅ Minimal | ⚠️  More |
-
----
-
-## Conclusion
-
-The Pipeline Builder pattern addresses the key usability issues with deploy-ability while maintaining its architectural strengths. By making deployment steps explicit and handling lifecycle automatically, we create an API that's both powerful and hard to misuse.
-
-### Next Steps
-
-1. **Review**: Gather feedback on this proposal
-2. **Prototype**: Implement Phase 1 (core pipeline)
-3. **Test**: Migrate kadi-deploy to use pipeline
-4. **Iterate**: Refine based on real usage
-5. **Document**: Write comprehensive guides
-6. **Release**: Ship as part of deploy-ability v0.1.0
-
-### Open Questions
-
-1. Should pipeline builder be in a separate package or same as deploy-ability?
-2. What's the right balance between automatic and explicit?
-3. Should we support middleware/plugins for custom stages?
-4. How should we handle errors in pipeline stages?
-
----
-
-**Feedback Welcome**: Please share thoughts, concerns, or suggestions!