@kadi.build/deploy-ability 0.0.5 → 0.0.7

package/docs/KADI_ABILITY_CONVERSION.md

@@ -1,1365 +0,0 @@
-# KADI Ability Conversion - Preserving Fluent APIs
-
-> **Document Purpose**: Guide for converting deploy-ability into a KADI ability while preserving the fluent API design
->
-> **Author**: KADI Team
->
-> **Date**: 2025-11-18
->
-> **Status**: Design Proposal
-
----
-
-## Executive Summary
-
-### The Question
-
-**Can we turn deploy-ability into a KADI ability while keeping the Pipeline Builder's fluent API?**
-
-### The Answer
-
-**Yes, absolutely!** Using the **dual export pattern** from secret-ability, you can have:
-
-- ✅ **Fluent API** for local/CLI use (best developer experience)
-- ✅ **Tool-based RPC** for distributed/remote use (best for agents)
-- ✅ **Both interfaces** maintained in the same package
-- ✅ **No breaking changes** to existing code
-
-### Key Insight
-
-**Fluent APIs and KADI abilities are NOT mutually exclusive.** They serve different use cases:
-
-| Use Case | Interface | Why |
-|----------|-----------|-----|
-| Local CLI commands | Fluent API | Best DX, discoverable, type-safe |
-| Agent-to-agent calls | Tool-based RPC | Stateless, distributed, simple |
-| Scripts/automation | Fluent API | Flexible, composable, clear |
-| Broker/MCP integration | Tool-based RPC | Standard protocol, interoperable |
-
----
-
-## The Dual Export Pattern
-
-### How secret-ability Does It
-
-secret-ability successfully implements this pattern:
-
-**package.json:**
-```json
-{
-  "name": "secret-ability",
-  "main": "./dist/kadi-ability.js",
-  "exports": {
-    ".": {
-      "types": "./dist/kadi-ability.d.ts",
-      "import": "./dist/kadi-ability.js"
-    },
-    "./lib": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  }
-}
-```
-
-**File structure:**
-```
-secret-ability/
-├── src/
-│   ├── index.ts           # Library export - Fluent API (Secrets class)
-│   ├── kadi-ability.ts    # Ability export - Tool-based RPC
-│   ├── core/
-│   │   └── secrets.ts     # The Secrets class with fluent initializer
-│   └── ...
-```
-
-### Two Interfaces, One Codebase
-
-**Library Interface (`/lib`):**
-```typescript
-import { Secrets } from '@kadi.build/secret-ability/lib';
-
-const secrets = new Secrets();
-await secrets.init()
-  .ensure('wallet', { type: 'custom', path: './wallet.vault' })
-  .use('wallet');
-
-await secrets.set('MNEMONIC', 'word1 word2 ...');
-```
-
-**Ability Interface (default):**
-```typescript
-const secrets = await client.load('secret-ability', 'native');
-
-await secrets.init({ vaults: [{ name: 'wallet', type: 'custom', path: './wallet.vault' }] });
-await secrets.useVault({ vaultName: 'wallet' });
-await secrets.set({ key: 'MNEMONIC', value: 'word1 word2 ...' });
-```
-
-Same functionality, different interfaces for different use cases!
-
----
-
-## Current State: deploy-ability
-
-### Current Architecture
-
-deploy-ability is currently a **pure library** - not yet a KADI ability.
-
-**How it's used today:**
-```typescript
-import { setupRegistryIfNeeded, loadProfile, deploy } from '@kadi.build/deploy-ability';
-
-// Manual setup and cleanup
-const registryManager = new DockerRegistryManager();
-await registryManager.startTemporaryRegistry();
-
-try {
-  const profile = await loadProfile('./agent.json', 'production');
-  await deploy(profile, wallet, certificate);
-} finally {
-  await registryManager.cleanup(); // Easy to forget!
-}
-```
-
-### The Pipeline Builder (Proposed)
-
-The fluent API design from `PIPELINE_BUILDER_DESIGN.md`:
-
-```typescript
-import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
-
-const result = await DeploymentPipeline
-  .create({ projectRoot: './', profile: 'production' })
-  .withLocalImageSupport({ tunnelService: 'serveo' })
-  .withWallet(wallet)
-  .withCertificate(certificate)
-  .execute();
-// Cleanup happens automatically! ✨
-```
-
-**This is excellent design** - we want to preserve it!
-
----
-
-## Proposed State: deploy-ability as KADI Ability
-
-### Package Structure
-
-**Updated package.json:**
-```json
-{
-  "name": "@kadi.build/deploy-ability",
-  "version": "0.0.5",
-  "description": "Multi-target deployment orchestration for KADI",
-  "type": "module",
-  "main": "./dist/kadi-ability.js",
-  "types": "./dist/kadi-ability.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/kadi-ability.d.ts",
-      "import": "./dist/kadi-ability.js"
-    },
-    "./lib": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./types": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/types/index.js"
-    }
-  },
-  "dependencies": {
-    "@kadi.build/core": "^0.0.1-alpha.15",
-    "zod": "^3.22.4"
-  }
-}
-```
-
-### File Structure
-
-```
-deploy-ability/
-├── src/
-│   ├── index.ts              # Library export - FLUENT API ✅
-│   │                         # Exports: DeploymentPipeline, types, utilities
-│   │
-│   ├── kadi-ability.ts       # Ability export - TOOL-BASED RPC
-│   │                         # Registers tools, wraps fluent API
-│   │
-│   ├── pipeline-builder.ts   # The beautiful fluent API
-│   │                         # DeploymentPipeline class
-│   │
-│   ├── targets/
-│   │   ├── local/
-│   │   │   └── local.ts
-│   │   └── akash/
-│   │       ├── akash.ts
-│   │       └── deployer.ts
-│   │
-│   ├── utils/
-│   │   └── registry/
-│   │       ├── manager.ts
-│   │       └── setup.ts
-│   │
-│   └── types/
-│       └── index.ts
-│
-└── docs/
-    ├── PIPELINE_BUILDER_DESIGN.md
-    └── KADI_ABILITY_CONVERSION.md  # This document
-```
-
-### Two Interfaces Working Together
-
-The **ability layer** internally uses the **fluent library**:
-
-```
-┌─────────────────────────────────────────────────────┐
-│  Consumer Code                                       │
-├─────────────────────────────────────────────────────┤
-│                                                       │
-│  Option A: Direct Library Import                     │
-│  ┌─────────────────────────────────────────┐        │
-│  │ import { DeploymentPipeline }           │        │
-│  │ from '@kadi.build/deploy-ability/lib'   │        │
-│  │                                          │        │
-│  │ await DeploymentPipeline.create(...)    │        │
-│  └─────────────────────────────────────────┘        │
-│         ↓                                             │
-│  ┌─────────────────────────────────────────┐        │
-│  │ Pipeline Builder (Fluent API)           │        │
-│  └─────────────────────────────────────────┘        │
-│                                                       │
-│  Option B: KADI Ability Loading                      │
-│  ┌─────────────────────────────────────────┐        │
-│  │ const deploy = await client.load(...)   │        │
-│  │ await deploy.deploy({ ... })            │        │
-│  └─────────────────────────────────────────┘        │
-│         ↓                                             │
-│  ┌─────────────────────────────────────────┐        │
-│  │ Tool-based RPC Interface                │        │
-│  │ (internally uses Pipeline Builder)      │        │
-│  └─────────────────────────────────────────┘        │
-│         ↓                                             │
-│  ┌─────────────────────────────────────────┐        │
-│  │ Pipeline Builder (Fluent API)           │        │
-│  └─────────────────────────────────────────┘        │
-│                                                       │
-└─────────────────────────────────────────────────────┘
-```
-
----
-
-## Code Examples - Before/After
-
-### Current Usage (Library Only)
-
-**kadi-deploy using deploy-ability today:**
-
-```typescript
-// kadi-deploy/src/index.ts
-import { loadProfile, setupRegistryIfNeeded } from '@kadi.build/deploy-ability';
-import { deploy as deployToAkash } from '@kadi.build/deploy-ability/targets/akash';
-
-export async function deploy(options: DeployOptions) {
-  // Load profile
-  const profile = await loadProfile(
-    options.projectRoot,
-    options.profile,
-    options
-  );
-
-  // Setup registry if needed (manual!)
-  const registryCleanup = await setupRegistryIfNeeded(profile);
-
-  try {
-    // Deploy
-    if (profile.target === 'akash') {
-      await deployToAkash(profile, wallet, certificate);
-    }
-    // ... other targets
-  } finally {
-    // Cleanup (easy to forget!)
-    if (registryCleanup) {
-      await registryCleanup();
-    }
-  }
-}
-```
-
-**Problems:**
-- Manual registry management
-- Easy to forget cleanup
-- Verbose error handling
-- Hard to compose operations
-
----
-
-### Proposed Usage (As KADI Ability)
-
-#### Option A: Library Import (for local/CLI use)
-
-**kadi-deploy using the fluent library API:**
-
-```typescript
-// kadi-deploy/src/index.ts
-import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
-
-export async function deploy(options: DeployOptions) {
-  // Beautiful fluent API! ✨
-  const result = await DeploymentPipeline
-    .create({
-      projectRoot: options.projectRoot,
-      profile: options.profile
-    })
-    .withLocalImageSupport({
-      tunnelService: options.tunnelService || 'serveo'
-    })
-    .withWallet(wallet)
-    .withCertificate(certificate)
-    .execute();
-
-  // Cleanup happens automatically!
-
-  return result;
-}
-```
-
-**Benefits:**
-- ✅ Automatic cleanup
-- ✅ Discoverable API
-- ✅ Type-safe
-- ✅ Easy to read and understand
-
----
-
-#### Option B: Ability Loading (for distributed use)
-
-**Remote agent calling deploy-ability as a KADI ability:**
-
-```typescript
-// model-manager-agent/src/services/deployment-controller.ts
-import { KadiClient } from '@kadi.build/core';
-
-export class DeploymentController {
-  private deployAbility: any;
-
-  async initialize() {
-    const client = new KadiClient({ name: 'model-manager' });
-
-    // Load deploy-ability as a KADI ability
-    this.deployAbility = await client.load('deploy-ability', 'native');
-  }
-
-  async deployModel(request: DeploymentRequest) {
-    // Tool-based interface (works remotely)
-    const result = await this.deployAbility.deploy({
-      projectRoot: './templates',
-      profile: 'ollama-runtime',
-      localImageSupport: {
-        tunnelService: 'serveo'
-      },
-      wallet: this.wallet,
-      certificate: this.certificate,
-      // Additional deployment-specific options
-      modelName: request.modelName,
-      gpuType: request.gpu
-    });
-
-    if (!result.success) {
-      throw new Error(`Deployment failed: ${result.message}`);
-    }
-
-    return result;
-  }
-}
-```
-
-**Benefits:**
-- ✅ Works across process boundaries
-- ✅ Version-isolated through KADI
-- ✅ Stateless RPC
-- ✅ Simple parameter passing
-
----
-
-## Implementation Guide
-
-### Step 1: Create `kadi-ability.ts`
-
-This is the new file that wraps your fluent API in a tool-based interface.
-
-**File: `src/kadi-ability.ts`**
-
-```typescript
-/**
- * KADI Ability Interface for deploy-ability
- *
- * Exposes deployment functionality through KADI's ability system.
- * Uses KadiClient to register tools with proper schemas and handlers.
- *
- * IMPORTANT: This is a thin wrapper around the fluent library API.
- * For local/CLI use, prefer importing from '/lib' for the fluent interface.
- *
- * @module kadi-ability
- */
-
-import { KadiClient, z } from '@kadi.build/core';
-import { DeploymentPipeline } from './pipeline-builder.js';
-import type {
-  DeploymentResult,
-  AkashWallet,
-  AkashCertificate
-} from './types/index.js';
-
-// Create the KadiClient instance
-const client = new KadiClient({
-  name: 'deploy-ability',
-  version: '0.0.5',
-  description: 'Multi-target deployment orchestration for KADI',
-  role: 'ability'
-});
-
-// ============================================================================
-// Tool Registration
-// ============================================================================
-
-/**
- * deploy - Deploy to target platform
- *
- * Main deployment tool that orchestrates the entire deployment process.
- * Internally uses the DeploymentPipeline fluent API for clean resource management.
- */
-const deployInputSchema = z.object({
-  projectRoot: z.string().describe('Project root directory'),
-  profile: z.string().describe('Deployment profile name'),
-
-  // Optional enhancements
-  localImageSupport: z.object({
-    tunnelService: z.enum(['serveo', 'ngrok', 'bore']).optional()
-      .describe('Tunnel service for exposing local registry'),
-    registryPort: z.number().optional()
-      .describe('Local registry port (default: 5001)')
-  }).optional().describe('Enable local image support with temporary registry'),
-
-  wallet: z.any().optional()
-    .describe('Akash wallet for blockchain transactions'),
-
-  certificate: z.any().optional()
-    .describe('Akash certificate for provider authentication'),
-
-  // CLI overrides
-  verbose: z.boolean().optional()
-    .describe('Enable verbose logging'),
-
-  dryRun: z.boolean().optional()
-    .describe('Simulate deployment without executing'),
-
-  yes: z.boolean().optional()
-    .describe('Auto-confirm all prompts'),
-});
-
-const deployOutputSchema = z.object({
-  success: z.boolean(),
-  deploymentId: z.string().optional()
-    .describe('Unique deployment identifier'),
-  dseq: z.string().optional()
-    .describe('Akash deployment sequence number'),
-  endpoints: z.array(z.string()).optional()
-    .describe('Accessible service endpoints'),
-  leaseInfo: z.object({
-    provider: z.string(),
-    price: z.string(),
-    priceUsd: z.number().optional()
-  }).optional().describe('Lease information for Akash deployments'),
-  message: z.string().optional()
-    .describe('Status or error message'),
-});
-
-client.registerTool({
-  name: 'deploy',
-  description: 'Deploy agent to target platform using specified profile',
-  input: deployInputSchema,
-  output: deployOutputSchema
-}, async (params: z.infer<typeof deployInputSchema>) => {
-  try {
-    // Build the deployment pipeline using the fluent API
-    let pipeline = DeploymentPipeline.create({
-      projectRoot: params.projectRoot,
-      profile: params.profile,
-      verbose: params.verbose,
-      dryRun: params.dryRun,
-      yes: params.yes
-    });
-
-    // Add local image support if requested
-    if (params.localImageSupport) {
-      pipeline = pipeline.withLocalImageSupport({
-        tunnelService: params.localImageSupport.tunnelService || 'serveo',
-        registryPort: params.localImageSupport.registryPort
-      });
-    }
-
-    // Add wallet if provided (Akash deployments)
-    if (params.wallet) {
-      pipeline = pipeline.withWallet(params.wallet as AkashWallet);
-    }
-
-    // Add certificate if provided (Akash deployments)
-    if (params.certificate) {
-      pipeline = pipeline.withCertificate(params.certificate as AkashCertificate);
-    }
-
-    // Execute the pipeline
-    // The pipeline handles all resource management and cleanup automatically
-    const result = await pipeline.execute();
-
-    return {
-      success: true,
-      deploymentId: result.deploymentId,
-      dseq: result.dseq,
-      endpoints: result.endpoints,
-      leaseInfo: result.leaseInfo,
-      message: 'Deployment completed successfully'
-    };
-
-  } catch (error) {
-    const errorMsg = error instanceof Error ? error.message : String(error);
-
-    return {
-      success: false,
-      message: `Deployment failed: ${errorMsg}`
-    };
-  }
-});
-
-/**
- * getDeploymentStatus - Check deployment status
- *
- * Query the status of an existing deployment.
- */
-const getStatusInputSchema = z.object({
-  deploymentId: z.string().describe('Deployment identifier to check'),
-  target: z.enum(['local', 'akash']).describe('Deployment target')
-});
-
-const getStatusOutputSchema = z.object({
-  success: z.boolean(),
-  status: z.enum(['pending', 'active', 'failed', 'closed']).optional(),
-  message: z.string().optional()
-});
-
-client.registerTool({
-  name: 'getDeploymentStatus',
-  description: 'Get the current status of a deployment',
-  input: getStatusInputSchema,
-  output: getStatusOutputSchema
-}, async (params: z.infer<typeof getStatusInputSchema>) => {
-  try {
-    // Implementation would query deployment status
-    // This is a placeholder for the actual implementation
-
-    return {
-      success: true,
-      status: 'active',
-      message: 'Deployment is running'
-    };
-  } catch (error) {
-    return {
-      success: false,
-      message: error instanceof Error ? error.message : String(error)
-    };
-  }
-});
-
-/**
- * closeDeployment - Close/stop a deployment
- *
- * Gracefully shut down and clean up a deployment.
- */
-const closeInputSchema = z.object({
-  deploymentId: z.string().describe('Deployment identifier to close'),
-  target: z.enum(['local', 'akash']).describe('Deployment target')
-});
-
-const closeOutputSchema = z.object({
-  success: z.boolean(),
-  message: z.string().optional()
-});
-
-client.registerTool({
-  name: 'closeDeployment',
-  description: 'Close and cleanup a deployment',
-  input: closeInputSchema,
-  output: closeOutputSchema
-}, async (params: z.infer<typeof closeInputSchema>) => {
-  try {
-    // Implementation would close the deployment
-    // This is a placeholder for the actual implementation
-
-    return {
-      success: true,
-      message: 'Deployment closed successfully'
-    };
-  } catch (error) {
-    return {
-      success: false,
-      message: error instanceof Error ? error.message : String(error)
-    };
-  }
-});
-
-// Export the client as default
-export default client;
-
-// Allow running standalone as stdio server
-if (import.meta.url === `file://${process.argv[1]}`) {
-  await client.serve('stdio');
-}
-```
-
----
-
-### Step 2: Update Library Export (`index.ts`)
-
-Make sure the library export exposes the fluent API:
-
-**File: `src/index.ts`**
-
-```typescript
-/**
- * deploy-ability - Library Export
- *
- * Main library interface for deploy-ability.
- * Provides fluent API through DeploymentPipeline.
- *
- * @module deploy-ability/lib
- */
-
-// ============================================================================
-// Fluent API - Primary Interface
-// ============================================================================
-
-export { DeploymentPipeline } from './pipeline-builder.js';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export type {
-  DeploymentProfile,
-  AkashDeploymentProfile,
-  LocalDeploymentProfile,
-  DeploymentResult,
-  AkashWallet,
-  AkashCertificate,
-  ServiceConfig,
-  // ... all other types
-} from './types/index.js';
-
-// ============================================================================
-// Legacy Exports (for backward compatibility)
-// ============================================================================
-
-// Keep these for existing code that uses the old API
-export { loadProfile } from './utils/profileUtils.js';
-export { setupRegistryIfNeeded } from './utils/registry/setup.js';
-export { DockerRegistryManager } from './utils/registry/manager.js';
-
-// Target implementations (advanced users)
-export { deploy as deployToLocal } from './targets/local/local.js';
-export { deploy as deployToAkash } from './targets/akash/akash.js';
-```
-
----
-
-### Step 3: Update `package.json`
-
-Add the exports configuration:
-
-```json
-{
-  "name": "@kadi.build/deploy-ability",
-  "version": "0.0.5",
-  "description": "Multi-target deployment orchestration for KADI",
-  "type": "module",
-  "main": "./dist/kadi-ability.js",
-  "types": "./dist/kadi-ability.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/kadi-ability.d.ts",
-      "import": "./dist/kadi-ability.js"
-    },
-    "./lib": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./types": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/types/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsc",
-    "build:watch": "tsc --watch",
-    "test": "vitest run"
-  },
-  "dependencies": {
-    "@kadi.build/core": "^0.0.1-alpha.15",
-    "zod": "^3.22.4"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.9.2",
-    "vitest": "^1.0.0"
-  }
-}
-```
-
----
-
-### Step 4: TypeScript Configuration
-
-Ensure TypeScript outputs both files correctly:
-
-**tsconfig.json:**
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ES2022",
-    "moduleResolution": "bundler",
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "strict": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}
-```
-
----
-
-## Usage Patterns
-
-### Pattern 1: CLI Commands (kadi deploy)
-
-**Use the library's fluent API:**
-
-```typescript
-// kadi-deploy/src/commands/deploy.ts
-import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
-
-export async function deployCommand(options: CommandOptions) {
-  const logger = createLogger(options.verbose);
-
-  logger.info('Starting deployment...');
-
-  try {
-    const result = await DeploymentPipeline
-      .create({
-        projectRoot: options.projectRoot || './',
-        profile: options.profile,
-        verbose: options.verbose,
-        dryRun: options.dryRun
-      })
-      .withLocalImageSupport({
-        tunnelService: options.tunnelService || 'serveo'
-      })
-      .withWallet(await loadWallet(options.walletPath))
-      .withCertificate(await loadCertificate(options.certPath))
-      .execute();
-
-    logger.success('Deployment completed!');
-    logger.info(`Deployment ID: ${result.deploymentId}`);
-
-    if (result.endpoints) {
-      logger.info('Endpoints:');
-      result.endpoints.forEach(ep => logger.info(`  - ${ep}`));
-    }
-
-  } catch (error) {
-    logger.error('Deployment failed:', error);
-    process.exit(1);
-  }
-}
-```
-
-**Why fluent API here?**
-- Running locally, in-process
-- Best developer experience
-- Type-safe and discoverable
-- Automatic cleanup
-
----
-
-### Pattern 2: Agent-to-Agent Calls
-
-**Use the ability's tool interface:**
-
-```typescript
-// model-manager-agent/src/services/deployment-controller.ts
-import { KadiClient } from '@kadi.build/core';
-
-export class DeploymentController {
-  private client: KadiClient;
-  private deployAbility: any;
-
-  constructor() {
-    this.client = new KadiClient({
-      name: 'model-manager-agent',
-      projectRoot: process.cwd()
-    });
-  }
-
-  async initialize() {
-    // Load deploy-ability as a KADI ability
-    this.deployAbility = await this.client.load('deploy-ability', 'native');
-  }
-
-  async deployModel(request: DeployModelRequest): Promise<DeploymentInfo> {
-    // Call the deploy tool
-    const result = await this.deployAbility.deploy({
-      projectRoot: './templates',
-      profile: this.selectProfile(request),
-      localImageSupport: {
-        tunnelService: 'serveo'
-      },
-      wallet: this.wallet,
-      certificate: this.certificate
-    });
-
-    if (!result.success) {
-      throw new Error(`Deployment failed: ${result.message}`);
-    }
-
-    return {
-      deploymentId: result.deploymentId,
-      dseq: result.dseq,
-      endpoints: result.endpoints,
-      status: 'active'
-    };
-  }
-}
-```
-
-**Why tool interface here?**
-- Might be running in different process
-- Stateless RPC
-- Simple parameter passing
-- Version isolation through KADI
-
----
-
-### Pattern 3: Automation Scripts
-
-**Use the library's fluent API:**
-
-```typescript
-// scripts/deploy-all-profiles.ts
-import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
-import { loadWallet, loadCertificate } from './utils.js';
-
-const profiles = ['staging', 'production', 'backup'];
-
-async function deployAll() {
-  const wallet = await loadWallet();
-  const cert = await loadCertificate();
-
-  for (const profile of profiles) {
-    console.log(`\nDeploying profile: ${profile}`);
-
-    try {
-      const result = await DeploymentPipeline
-        .create({ projectRoot: './', profile })
-        .withWallet(wallet)
-        .withCertificate(cert)
-        .execute();
-
-      console.log(`✅ ${profile}: ${result.deploymentId}`);
-    } catch (error) {
-      console.error(`❌ ${profile} failed:`, error);
-    }
-  }
-}
-
-deployAll();
-```
-
-**Why fluent API here?**
-- Local automation
-- Clear, readable code
-- Composable operations
-- Automatic resource management
-
----
-
-### Pattern 4: MCP/Broker Integration
-
-**Use the ability's tool interface:**
-
-```typescript
-// broker-integration/src/deploy-service.ts
-export class DeployService {
-  private client: KadiClient;
-
-  async handleDeployRequest(request: BrokerRequest): Promise<BrokerResponse> {
-    // Load deploy-ability through broker's client
-    const deployAbility = await this.client.load('deploy-ability', 'native');
-
-    // Parse request parameters
-    const params = JSON.parse(request.parameters);
-
-    // Execute deployment via tool
-    const result = await deployAbility.deploy({
-      projectRoot: params.projectRoot,
-      profile: params.profile,
-      wallet: params.wallet,
-      certificate: params.certificate
-    });
-
-    return {
-      success: result.success,
-      data: result,
-      message: result.message
-    };
-  }
-}
-```
-
-**Why tool interface here?**
-- Standard protocol (MCP/JSON-RPC)
-- Broker expects tool-based interface
-- May cross process boundaries
-- Needs to be serializable
-
----
-
-## Comparison: Why This Works
-
-### Fluent APIs vs Tool-based RPC
-
-| Aspect | Fluent API | Tool-based RPC |
-|--------|-----------|----------------|
-| **State** | Stateful (builder pattern) | Stateless (each call independent) |
-| **Location** | Local/in-process | Can be distributed |
-| **Composability** | High (method chaining) | Medium (parameter objects) |
-| **Discoverability** | Excellent (IDE autocomplete) | Good (schema-based) |
-| **Type Safety** | Excellent (compile-time) | Good (runtime validation) |
-| **Error Handling** | Synchronous exceptions | Result objects |
-| **Resource Management** | RAII pattern (automatic) | Manual or tool-managed |
-| **Network Serialization** | Not applicable | Required |
-| **Best For** | CLI, scripts, local dev | Agents, distributed, remote |
-
-### Why Both Are Valid
-
-**Fluent API strengths:**
-- Builder pattern allows incremental configuration
-- Automatic resource cleanup (RAII)
-- Type-safe at compile time
-- Great IDE support
-- Easy to read and understand
-
-**Tool-based RPC strengths:**
-- Works across process boundaries
-- Simple serialization (JSON)
-- Standard protocol (compatible with MCP, JSON-RPC)
-- Stateless (easy to scale)
-- Version isolation through KADI
-
-**The solution: Offer both!**
-
----
-
-## Migration Strategy
-
-### Phase 1: Add Ability Layer (No Breaking Changes)
-
-**Week 1-2:**
-1. Create `kadi-ability.ts`
-2. Add exports to `package.json`
-3. Write tests for tool interface
-4. Update documentation
-
-**Result:**
-- Existing code keeps working (uses `/lib` export)
-- New consumers can choose ability or library
-- No migration required
-
----
-
-### Phase 2: Update Internal Consumers
-
-**Week 3-4:**
-
-Update kadi-deploy and other consumers to use the fluent API:
-
-```typescript
-// Before (old verbose API)
-const registryCleanup = await setupRegistryIfNeeded(profile);
-try {
-  await deploy(profile, wallet, cert);
-} finally {
-  await registryCleanup?.();
-}
-
-// After (new fluent API)
-await DeploymentPipeline
-  .create({ projectRoot: './', profile: 'prod' })
-  .withLocalImageSupport()
-  .withWallet(wallet)
-  .withCertificate(cert)
-  .execute();
-```
-
-**Result:**
-- Cleaner code
-- Automatic cleanup
-- Better error handling
-- Same functionality
-
----
-
-### Phase 3: Gradual Adoption
-
-**Month 2:**
-
-As new use cases emerge:
-- **Local/CLI** → Use fluent API from `/lib`
-- **Distributed/Remote** → Use ability interface
-
-**Documentation updates:**
-- Add examples for both patterns
-- Explain when to use each
-- Migration guide for existing code
-
-**Result:**
-- Full ecosystem support
-- Clear patterns established
-- Best practices documented
-
----
-
-## Benefits & Trade-offs
-
-### Benefits
-
-✅ **Fluent API Preserved**
-- Keep the excellent Pipeline Builder design
-- Best developer experience for local use
-- Type-safe, discoverable, clean
-
-✅ **Distributed Capability Added**
-- Agents can call deployments remotely
-- Standard tool-based interface
-- Works with KADI ecosystem
-
-✅ **Ecosystem Integration**
-- Version management through KADI
-- Ability loading and isolation
-- Compatible with MCP/broker protocols
-
-✅ **Backward Compatibility**
-- Existing code keeps working
-- No forced migration
-- Gradual adoption path
-
-✅ **Resource Management**
-- Automatic cleanup via RAII (fluent API)
-- No manual cleanup needed
-- Fewer bugs from forgotten cleanup
-
-✅ **Flexibility**
-- Choose the right interface for your use case
-- Not locked into one pattern
-- Can mix both in same project
-
----
-
-### Trade-offs
-
-⚠️ **Slightly More Complex Package**
-- Two entry points (`./` and `./lib`)
-- Need to understand which to use when
-- More documentation needed
-
-**Mitigation:**
-- Clear documentation with examples
-- Decision tree for which interface to use
-- Both are well-designed and intuitive
-
-⚠️ **Two Interfaces to Maintain**
-- Library interface (fluent API)
-- Ability interface (tools)
-- Need to keep both in sync
-
-**Mitigation:**
-- Ability wraps library (single source of truth)
-- Changes to library automatically available in ability
-- Thin wrapper means less maintenance
-
-⚠️ **Learning Curve**
-- Developers need to know both patterns exist
-- When to use fluent vs tools
-
-**Mitigation:**
-- Good defaults (CLI → fluent, agents → tools)
-- Clear documentation and examples
-- Each interface is simple on its own
-
----
-
-### Overall Assessment
-
-**Score: 8/10**
-
-The dual export pattern is:
-- ✅ **Worth implementing** - benefits outweigh costs
-- ✅ **Proven pattern** - secret-ability demonstrates success
-- ✅ **Best of both worlds** - no compromises on either interface
-- ✅ **Future-proof** - supports both local and distributed use cases
-
----
-
-## Comparison with secret-ability
-
-### How They Use the Same Pattern
-
-Both use the dual export pattern, but for different domains:
-
-**secret-ability:**
-```typescript
-// Library (fluent API for vault management)
-import { Secrets } from '@kadi.build/secret-ability/lib';
-
-await secrets.init()
-  .ensure('wallet', { type: 'custom', path: './wallet.vault' })
-  .use('wallet');
-
-await secrets.set('KEY', 'value');
-```
-
-**deploy-ability (proposed):**
-```typescript
-// Library (fluent API for deployment)
-import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
-
-await DeploymentPipeline
-  .create({ projectRoot: './', profile: 'production' })
-  .withLocalImageSupport()
-  .execute();
-```
-
-### Lessons Learned from secret-ability
-
-1. **Fluent initializer pattern works great**
-   - secret-ability's `SecretsInitializer` is excellent
-   - Chainable setup, then execute
-   - We're using the same pattern
-
-2. **Tool interface is simple**
-   - Each tool maps to a library method
-   - Thin wrapper, minimal complexity
-   - Easy to maintain
-
-3. **Clear separation of concerns**
-   - Library handles business logic
-   - Ability handles RPC and protocols
-   - Works well in practice
-
-4. **Documentation is key**
-   - Need clear examples for both interfaces
-   - Explain when to use which
-   - Show the connection between them
-
-### Differences in Use Cases
-
-**secret-ability:**
-- Manages vault initialization and lifecycle
-- Secret CRUD operations
-- Vault registry management
-
-**deploy-ability:**
-- Orchestrates deployment pipelines
-- Manages temporary resources (registry, tunnel)
-- Coordinates multiple services
-
-**Both benefit from fluent APIs** because:
-- Complex multi-step processes
-- Resource lifecycle management
-- Clear configuration builders
-- Automatic cleanup needed
-
----
-
-## FAQ
-
-### "Why not just use fluent API for the ability too?"
-
-**Short answer:** Fluent APIs don't work across process boundaries.
-
-**Long answer:**
-
-Fluent APIs require maintaining state (the builder object):
-
-```typescript
-const pipeline = DeploymentPipeline.create({...}); // State created
-pipeline.withWallet(wallet);                        // State modified
-pipeline.withCertificate(cert);                     // State modified
-await pipeline.execute();                           // State executed
-```
-
-In a distributed system:
-- Each method call might go to a different instance
-- You can't serialize a builder object with all its state
-- The server doesn't maintain session state between calls
-
-Tool-based RPC is stateless:
-```typescript
-await deployAbility.deploy({
-  // Everything in one call
-  profile: 'prod',
-  wallet: wallet,
-  certificate: cert
-});
-```
-
-Each call is independent and self-contained.
-
----
-
-### "Can I use the fluent API from remote services?"
-
-**Yes, but only if you import the library directly:**
-
-```typescript
-// In a remote agent
-import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
-
-// This works because you're using the library, not the ability
-await DeploymentPipeline.create({...}).execute();
-```
-
-**However:**
-- You lose KADI version isolation
-- Direct npm dependency instead of ability loading
-- Might have version conflicts
-
-**Recommendation:** If you're remote, use the ability interface instead.
-
----
-
-### "Which interface should I use?"
-
-**Decision tree:**
-
-```
-Are you writing...
-├─ CLI command? → Use fluent API (/lib)
-├─ Local script? → Use fluent API (/lib)
-├─ Agent calling another agent? → Use ability interface (default)
-├─ Broker/MCP integration? → Use ability interface (default)
-└─ Not sure? → Use fluent API if local, ability if distributed
-```
-
-**Rule of thumb:**
-- **Same process** → Fluent API (`/lib`)
-- **Different process** → Ability interface (default)
-
----
-
-### "Will this break existing code?"
-
-**No! Here's why:**
-
-**For deploy-ability consumers:**
-- Current code imports from default export
-- We're keeping all existing exports in `/lib`
-- Old API remains available
-
-**Example:**
-```typescript
-// Old code (still works!)
-import { loadProfile, setupRegistryIfNeeded } from '@kadi.build/deploy-ability';
-
-// New code (better!)
-import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
-```
-
-Both work! No forced migration.
-
----
-
-### "Do I need to update my code immediately?"
-
-**No, it's optional:**
-
-The dual export pattern means:
-- ✅ Existing code keeps working
-- ✅ New code can use fluent API
-- ✅ Gradual migration possible
-- ✅ No breaking changes
-
-**When to update:**
-- When you want the fluent API benefits
-- When you need remote deployment capability
-- When you're writing new code
-- At your own pace
-
----
-
-## Conclusion
-
-### Summary
-
-**The dual export pattern enables deploy-ability to be both:**
-1. A KADI ability (tool-based RPC for distributed use)
-2. A fluent API library (for local/CLI use)
-
-**This is possible because:**
-- The ability layer is a thin wrapper around the library
-- Both interfaces serve different, valid use cases
-- secret-ability proves this pattern works
-
-**The Pipeline Builder fluent API is preserved and enhanced:**
-- ✅ Available via `/lib` export
-- ✅ Best-in-class developer experience
-- ✅ Automatic resource management
-- ✅ Type-safe and discoverable
-
-**The ability interface adds new capabilities:**
-- ✅ Distributed deployments
-- ✅ Agent-to-agent communication
-- ✅ KADI ecosystem integration
-- ✅ Standard tool-based protocol
-
-### Recommendation
-
-**Proceed with converting deploy-ability to a KADI ability using the dual export pattern.**
-
-**Implementation priority:**
-1. ✅ Create `kadi-ability.ts` with tool wrappers
-2. ✅ Update `package.json` with dual exports
-3. ✅ Update `index.ts` to export fluent API
-4. ✅ Write comprehensive documentation
-5. ✅ Add examples for both use cases
-6. ✅ Update existing consumers gradually
-
-**Expected outcome:**
-- Best of both worlds
-- No breaking changes
-- Future-proof architecture
-- Happy developers ✨
-
----
-
-**Document Version:** 1.0
-**Last Updated:** 2025-11-18
-**Author:** KADI Team
-**Status:** Design Proposal - Ready for Implementation