kadi-deploy 0.19.0

package/.env.example

@@ -0,0 +1,6 @@
+# KADI Deploy Environment Variables
+# Copy this file to .env and fill in your values
+
+# WalletConnect Project ID for Akash wallet connections
+# Get one at: https://cloud.walletconnect.com/
+WALLETCONNECT_PROJECT_ID=your_walletconnect_project_id_here

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "printWidth": 80,
+  "singleQuote": true,
+  "trailingComma": "none",
+  "semi": true
+}

package/README.md

@@ -0,0 +1,589 @@
+# kadi-deploy
+
+Deploy KADI agents to local Docker/Podman or Akash Network using profiles defined in `agent.json`.
+
+This is a **CLI plugin** that provides the `deploy` command. See [kadi-by-example](https://gitlab.com/humin-game-lab/kadi/kadi-by-example) for tutorials.
+
+---
+
+## Installation
+
+```bash
+kadi install kadi-deploy
+```
+
+---
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `kadi deploy` | Deploy using first available profile |
+| `kadi deploy --profile production` | Deploy using a specific profile |
+| `kadi deploy --autonomous` | Fully autonomous deployment (no human interaction) |
+| `kadi deploy --dry-run` | Preview deployment without executing || `kadi deploy down` | Tear down an active deployment |
+| `kadi deploy down --profile <name>` | Tear down a specific profile's deployment |
+| `kadi deploy down --autonomous` | Tear down Akash deployment without human interaction |
+| `kadi deploy down --yes` | Tear down without confirmation prompt |
+---
+
+## Quick Start
+
+### 1. Add a deploy profile to `agent.json`
+
+```json
+{
+  "name": "my-agent",
+  "version": "1.0.0",
+  "deploy": {
+    "local": {
+      "target": "local",
+      "engine": "docker",
+      "services": {
+        "app": {
+          "image": "my-agent:latest",
+          "expose": [{ "port": 3000, "as": 3000 }]
+        }
+      }
+    }
+  }
+}
+```
+
+### 2. Deploy
+
+```bash
+kadi deploy --profile local
+```
+
+That's it. For Akash Network deployment, see [Deploying to Akash](#deploying-to-akash).
+
+---
+
+## Deploying Locally
+
+Local deployment uses Docker or Podman to run your services via docker-compose.
+
+```json
+{
+  "deploy": {
+    "local": {
+      "target": "local",
+      "engine": "docker",
+      "services": {
+        "web": {
+          "image": "nginx:alpine",
+          "expose": [{ "port": 80, "as": 8080 }]
+        }
+      }
+    }
+  }
+}
+```
+
+```bash
+kadi deploy --profile local
+```
+
+**Local profile options:**
+
+| Field | Description |
+|-------|-------------|
+| `target` | Must be `"local"` |
+| `engine` | `"docker"` or `"podman"` |
+| `network` | Docker network name (optional) |
+| `services` | Service definitions (see below) |
+
+---
+
+## Deploying to Akash
+
+Akash Network is a decentralized cloud platform. Deploying to Akash requires:
+1. A Keplr wallet with AKT tokens
+2. Scanning a QR code to connect your wallet
+3. Selecting a provider from the bid list
+
+```json
+{
+  "deploy": {
+    "production": {
+      "target": "akash",
+      "network": "mainnet",
+      "services": {
+        "web": {
+          "image": "nginx:alpine",
+          "expose": [{ "port": 80, "as": 80, "to": [{ "global": true }] }],
+          "resources": {
+            "cpu": 0.5,
+            "memory": "512Mi",
+            "ephemeralStorage": "1Gi"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+```bash
+kadi deploy --profile production
+```
+
+The CLI will:
+1. Generate a QR code - scan with Keplr mobile
+2. Create/load your deployment certificate
+3. Submit to Akash and collect bids
+4. Let you select a provider interactively
+5. Deploy and show your service endpoints
+
+**Akash profile options:**
+
+| Field | Description |
+|-------|-------------|
+| `target` | Must be `"akash"` |
+| `network` | `"mainnet"` or `"testnet"` |
+| `services` | Service definitions (see below) |
+| `blacklist` | Provider addresses to exclude |
+| `deposit` | Escrow deposit in AKT (default: 5) |
+| `cert` | Path to saved certificate file |
+| `useRemoteRegistry` | Skip local tunnel, assume images are in a public registry |
+
+---
+
+## Autonomous Deployment (Agent-Controlled)
+
+The `--autonomous` flag enables fully autonomous deployment with **zero human interaction**. This is designed for AI agents and automation pipelines that need to deploy without prompts, QR codes, or manual bid selection.
+
+### Prerequisites
+
+Store your Akash wallet mnemonic in the KADI secrets vault:
+
+```bash
+kadi secret set AKASH_WALLET "your twelve or twenty four word mnemonic phrase here" -v global
+```
+
+The mnemonic is encrypted at rest using age (ChaCha20-Poly1305) with your OS keychain protecting the master key.
+
+### Usage
+
+```bash
+# Basic autonomous deployment (cheapest bid)
+kadi deploy --profile production --autonomous
+
+# Use a specific bid strategy
+kadi deploy --autonomous --bid-strategy balanced
+
+# Set a maximum price and require audited providers
+kadi deploy --autonomous --bid-max-price 500 --require-audited
+
+# Use a custom secrets vault
+kadi deploy --autonomous --secrets-vault my-vault --bid-strategy balanced
+```
+
+### What Happens
+
+When `--autonomous` is set, the CLI:
+
+1. **Reads wallet mnemonic** from the secrets vault (no QR code / Keplr)
+2. **Creates or loads** the deployment certificate automatically
+3. **Submits the deployment** to Akash Network
+4. **Selects a provider** algorithmically based on `--bid-strategy`
+5. **Shares secrets** with the deployment automatically (no approval prompt)
+6. **Reports results** including endpoints and lease info
+
+### Autonomous Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--autonomous` | Enable autonomous mode | `false` |
+| `--bid-strategy <strategy>` | `cheapest`, `most-reliable`, or `balanced` | `cheapest` |
+| `--bid-max-price <uakt>` | Max price per block in uAKT | No limit |
+| `--require-audited` | Only accept bids from audited providers | `false` |
+| `--secrets-vault <vault>` | Vault for wallet mnemonic (does NOT affect deployment secrets) | `global` |
+| `--auto-approve-secrets` | Auto-approve secret sharing (also works in interactive mode) | `false` |
+| `--secret-timeout <ms>` | How long to wait for the agent to request secrets | `300000` |
+
+### Bid Strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| `cheapest` | Selects the lowest-price bid. Best for cost-sensitive workloads. |
+| `most-reliable` | Selects the provider with the highest uptime. Best for production. |
+| `balanced` | Weighs price and reliability together. Good default for most cases. |
+
+### Example: Agent Workflow
+
+An AI agent can deploy with a single command:
+
+```bash
+kadi deploy \
+  --profile production \
+  --autonomous \
+  --bid-strategy balanced \
+  --bid-max-price 1000 \
+  --require-audited
+```
+
+The entire flow completes without any human interaction.
+
+---
+
+## Tearing Down Deployments
+
+The `kadi deploy down` command tears down an active deployment launched by `kadi deploy`. It works for both local (Docker/Podman) and Akash deployments.
+
+After a successful deployment, kadi-deploy writes a `.kadi-deploy.lock` file to the project root that records everything needed to tear it down. The lock file supports **multiple simultaneous deployments** — you can have a local dev deployment and an Akash production deployment active at the same time.
+
+### Multi-Profile Support
+
+When multiple deployments are active:
+
+```bash
+# Specify which profile to tear down
+kadi deploy down --profile dev
+kadi deploy down --profile production
+
+# If only one deployment is active, it's auto-selected
+kadi deploy down
+
+# If multiple are active and no --profile, you'll be prompted to choose
+kadi deploy down --yes
+```
+
+### Local Teardown
+
+```bash
+# Tear down local containers
+kadi deploy down
+
+# Skip confirmation
+kadi deploy down --yes
+
+# Override container engine
+kadi deploy down --engine podman
+```
+
+This runs `docker compose down --remove-orphans` (or `podman compose`) against the compose file recorded in the lock.
+
+### Akash Teardown (Interactive)
+
+```bash
+# Close Akash deployment via WalletConnect QR
+kadi deploy down
+```
+
+The CLI will:
+1. Display the active deployment details (DSEQ, provider, network)
+2. Ask for confirmation
+3. Show a QR code — scan with Keplr mobile
+4. Call `closeDeployment` on the blockchain
+5. Display the transaction hash and refund info
+6. Delete the lock file
+
+### Akash Teardown (Autonomous)
+
+For fully automated teardown without human interaction:
+
+```bash
+# Autonomous teardown using vault mnemonic
+kadi deploy down --autonomous
+
+# With custom vault
+kadi deploy down --autonomous --secrets-vault my-wallet-vault
+
+# Tear down a specific profile (required when multiple deployments are active)
+kadi deploy down --autonomous --profile production
+```
+
+The autonomous path skips all interactive prompts (confirmation and profile selection), reads the wallet mnemonic from the secrets vault (same as `kadi deploy --autonomous`), signs the close transaction directly, and refunds the remaining escrow to your wallet.
+
+> **Note:** If multiple deployments are active, `--autonomous` requires `--profile` to specify which one to tear down (it cannot prompt for selection).
+
+### Down Flags
+
+| Flag | Description | Default |
+|------|-------------|----------|
+| `-p, --project <path>` | Path to project with `.kadi-deploy.lock` | Current directory |
+| `--profile <profile>` | Profile name to tear down (prompts if multiple; **required** in autonomous mode with multiple deployments) | Auto-select |
+| `--engine <engine>` | Override container engine (`docker`/`podman`) | From lock file |
+| `--network <network>` | Override Akash network (`mainnet`/`testnet`) | From lock file |
+| `--autonomous` | No human interaction — skips confirmation, uses vault mnemonic for Akash | `false` |
+| `--secrets-vault <vault>` | Vault for wallet mnemonic (autonomous mode) | `global` |
+| `-y, --yes` | Skip confirmation prompt (implied by `--autonomous`) | `false` |
+| `--verbose` | Detailed output | `false` |
+
+### The Lock File
+
+The `.kadi-deploy.lock` file is written to the project root after every successful deployment. It uses a v2 format that supports multiple simultaneous deployments keyed by profile name:
+
+```json
+{
+  "version": 2,
+  "deployments": {
+    "dev": {
+      "target": "local",
+      "profile": "dev",
+      "deployedAt": "2026-02-25T12:00:00.000Z",
+      "local": { "composePath": "...", "engine": "docker", ... }
+    },
+    "production": {
+      "target": "akash",
+      "profile": "production",
+      "deployedAt": "2026-02-25T14:00:00.000Z",
+      "akash": { "dseq": 12345678, "owner": "akash1...", ... }
+    }
+  }
+}
+```
+
+Each entry contains:
+
+- **Local deployments**: compose file path, engine, network, service names, container IDs
+- **Akash deployments**: DSEQ, owner address, provider, network, gseq/oseq
+
+When you tear down a profile, only that entry is removed. The file is deleted entirely when the last deployment is removed. Existing v1 lock files (single deployment) are transparently migrated on read.
+
+It is safe to add `.kadi-deploy.lock` to `.gitignore`.
+
+If the lock file is missing or was manually deleted, you can still tear down containers directly:
+
+```bash
+# Local: run compose down manually
+docker compose down --remove-orphans
+
+# Akash: close via Akash Console or CLI
+# You'll need the DSEQ from the original deployment output
+```
+
+---
+
+## Deployment Secrets
+
+Declare secrets your deployed agent needs in the `secrets` block of a deploy profile. Before deployment, `kadi deploy` validates that every required secret exists in the vault and shares them with the container.
+
+### Single Vault (Legacy)
+
+```json
+{
+  "deploy": {
+    "production": {
+      "target": "akash",
+      "network": "mainnet",
+      "services": { "..." : "..." },
+      "secrets": {
+        "vault": "my-agent",
+        "required": ["API_KEY", "DB_URL"],
+        "optional": ["DEBUG_KEY"],
+        "delivery": "broker"
+      }
+    }
+  }
+}
+```
+
+### Multi-Vault
+
+When your agent needs secrets from more than one vault, use the `vaults` array:
+
+```json
+{
+  "deploy": {
+    "production": {
+      "target": "akash",
+      "network": "mainnet",
+      "services": { "..." : "..." },
+      "secrets": {
+        "vaults": [
+          { "vault": "my-agent", "required": ["API_KEY", "API_URL"] },
+          { "vault": "infra", "required": ["TUNNEL_TOKEN"], "optional": ["OBSERVABILITY_KEY"] }
+        ],
+        "delivery": "broker"
+      }
+    }
+  }
+}
+```
+
+Each vault entry specifies which secrets to pull from that vault. All vaults are created inside the container and each secret is stored in its designated vault.
+
+### Secrets Fields
+
+| Field | Description |
+|-------|-------------|
+| `vault` | (Legacy) Single vault name |
+| `vaults` | (Multi-vault) Array of `{ vault, required?, optional? }` entries |
+| `required` | Secret names that **must** exist before deployment (deploy fails if missing) |
+| `optional` | Secret names shared if available (no error if missing) |
+| `delivery` | `"env"` (default) — injected as plain env vars. `"broker"` — E2E encrypted handshake via broker |
+
+Both formats are fully backwards compatible. Existing single-vault configs continue to work unchanged.
+
+---
+
+## Service Configuration
+
+Services are defined the same way for both local and Akash deployments:
+
+```json
+{
+  "services": {
+    "api": {
+      "image": "myapp:latest",
+      "command": ["node", "server.js"],
+      "env": ["PORT=3000", "NODE_ENV=production"],
+      "expose": [{ "port": 3000, "as": 80, "to": [{ "global": true }] }],
+      "resources": {
+        "cpu": 0.5,
+        "memory": "512Mi",
+        "ephemeralStorage": "1Gi"
+      }
+    }
+  }
+}
+```
+
+**Service fields:**
+
+| Field | Description |
+|-------|-------------|
+| `image` | Container image |
+| `command` | Override container command (array) |
+| `env` | Environment variables (array of `KEY=value`) |
+| `expose` | Port mappings |
+| `resources` | CPU, memory, storage (Akash only) |
+| `credentials` | Registry credentials for private images |
+
+### Private Registry
+
+For private images, add credentials:
+
+```json
+{
+  "services": {
+    "app": {
+      "image": "ghcr.io/myorg/private-app:main",
+      "credentials": {
+        "host": "ghcr.io",
+        "username": "github-username",
+        "password": "github-token"
+      }
+    }
+  }
+}
+```
+
+### Multi-Service
+
+Services can communicate with each other:
+
+```json
+{
+  "services": {
+    "frontend": {
+      "image": "nginx:alpine",
+      "expose": [{ "port": 80, "as": 80, "to": [{ "global": true }] }]
+    },
+    "backend": {
+      "image": "node:20-alpine",
+      "expose": [{ "port": 3000, "to": [{ "service": "frontend" }] }]
+    }
+  }
+}
+```
+
+---
+
+## Local Images on Akash
+
+When deploying local images to Akash, kadi-deploy automatically:
+
+1. Starts a temporary container registry
+2. Pushes your local images to it
+3. Exposes the registry via tunnel (kadi, ngrok, serveo, or localtunnel)
+4. Rewrites image URLs in the deployment manifest
+5. Waits for the provider to pull images
+6. Shuts down the registry once containers are running
+
+This happens automatically - no configuration needed for local images.
+
+---
+
+## CLI Options
+
+```bash
+kadi deploy                         # Use first available profile
+kadi deploy --profile production    # Use specific profile
+kadi deploy --project /path/to/app  # Specify project directory
+kadi deploy --dry-run               # Preview without deploying
+kadi deploy --verbose               # Detailed output
+kadi deploy --yes                   # Skip confirmation prompts
+```
+
+**Override profile settings:**
+
+```bash
+kadi deploy --network testnet       # Override Akash network
+kadi deploy --engine podman         # Override container engine
+```
+
+**Autonomous deployment:**
+
+```bash
+kadi deploy --autonomous                        # No human interaction
+kadi deploy --autonomous --bid-strategy balanced # Pick balanced provider
+kadi deploy --autonomous --bid-max-price 500     # Cap bid price
+kadi deploy --autonomous --require-audited       # Audited providers only
+kadi deploy --autonomous --secrets-vault myvault  # Custom vault
+kadi deploy --auto-approve-secrets               # Works in interactive mode too
+kadi deploy --secret-timeout 120000              # 2 min timeout for secret handshake
+```
+
+**Tear down deployments:**
+
+```bash
+kadi deploy down                                 # Tear down active deployment
+kadi deploy down --yes                           # Skip confirmation (interactive)
+kadi deploy down --autonomous                    # Fully non-interactive (skips confirmation + QR)
+kadi deploy down --autonomous --profile prod     # Required when multiple deployments active
+kadi deploy down --autonomous --secrets-vault v   # Akash: custom vault
+kadi deploy down --engine podman                 # Override container engine
+kadi deploy down --verbose                       # Detailed output
+```
+
+---
+
+## Troubleshooting
+
+### Local Deployment
+
+```bash
+# Check container engine
+docker --version
+podman --version
+
+# Start Podman machine (macOS)
+podman machine start
+```
+
+### Akash Deployment
+
+**Certificate issues:** If deployment fails with a certificate error, add the cert path to your profile:
+```json
+{
+  "deploy": {
+    "production": {
+      "cert": "~/.kadi/certificate.json"
+    }
+  }
+}
+```
+
+**Preview before deploying:**
+```bash
+kadi deploy --profile production --dry-run
+```
+
+**Verbose output for debugging:**
+```bash
+kadi deploy --profile production --verbose
+```

package/agent.json

@@ -0,0 +1,23 @@
+{
+  "name": "kadi-deploy",
+  "version": "0.19.0",
+  "license": "MIT",
+  "type": "plugin",
+  "entrypoint": "dist/index.js",
+  "commands": ["deploy"],
+  "description": "CLI plugin that converts an agent's deploy spec into platform-specific artifacts (Akash SDL, Docker Compose, etc.) and orchestrates the deployment process.",
+  "repo": "https://gitlab.com/humin-game-lab/kadi/kadi-deploy.git",
+  "lib": "https://gitlab.com/humin-game-lab/kadi/kadi-deploy/-/archive/v0.19.0/kadi-deploy-v0.19.0.zip",
+  "api": "http://127.0.0.1:8000",
+  "brokers": {
+    "local": "ws://127.0.0.1:8080",
+    "remote": "wss://broker.kadi.build"
+  },
+  "abilities": {
+    "secret-ability": "^0.9.1"
+  },
+  "scripts": {
+    "preflight": "node scripts/preflight.js",
+    "setup": "npm install && npm run build"
+  }
+}

package/index.js

@@ -0,0 +1,11 @@
+/**
+ * KADI Deploy Plugin Entry Point
+ *
+ * This file imports and re-exports the TypeScript implementation
+ * of the deploy plugin.
+ * The TypeScript version provides profile-based configuration while
+ * maintaining full backward compatibility with the existing CLI flags.
+ */
+
+// Import the compiled TypeScript implementation
+export { default } from './dist/index.js';

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "kadi-deploy",
+  "version": "0.19.0",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc",
+    "setup": "npm install && npm run build",
+    "format": "prettier --write .",
+    "test": "vitest run"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "@kadi.build/container-registry-ability": "^0.0.7",
+    "@kadi.build/core": "^0.11.0",
+    "@kadi.build/deploy-ability": "^0.0.13",
+    "chalk": "^5",
+    "commander": "^14.0.0",
+    "debug": "^4.3.7",
+    "ed2curve": "^0.3.0",
+    "enquirer": "^2",
+    "node-localstorage": "^3.0.5",
+    "ora": "^7",
+    "qrcode-terminal": "^0.12.0",
+    "tweetnacl": "^1.0.3",
+    "tweetnacl-sealedbox-js": "^1.2.0",
+    "tweetnacl-util": "^0.15.1",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "@types/node": "^24.3.0",
+    "@types/node-localstorage": "^1.3.3",
+    "@types/qrcode-terminal": "^0.12.2",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}