@kadi.build/deploy-ability 0.0.1

package/dist/utils/registry/types.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Registry Infrastructure Types
+ *
+ * Type definitions for temporary container registry that makes local images
+ * accessible to Akash providers during deployment.
+ *
+ * @module utils/registry/types
+ */
+import type { AkashDeploymentProfile } from '../../types/profiles.js';
+/**
+ * Registry context returned by setupRegistryIfNeeded
+ *
+ * Contains a transformed deployment profile where local image references have been
+ * replaced with public registry URLs, plus a cleanup function to shut down the
+ * temporary registry after deployment completes.
+ *
+ * **Lifecycle:**
+ * 1. Call `setupRegistryIfNeeded()` → Returns `RegistryContext`
+ * 2. Use `deployableProfile` for deployment
+ * 3. After deployment, call `cleanup()` to shut down registry
+ *
+ * @example
+ * ```typescript
+ * const ctx = await setupRegistryIfNeeded(profile, logger);
+ *
+ * try {
+ *   await deployToAkash({
+ *     loadedProfile: {
+ *       profile: ctx.deployableProfile // Use transformed profile
+ *     }
+ *   });
+ * } finally {
+ *   await ctx.cleanup(); // Always cleanup
+ * }
+ * ```
+ */
+export interface RegistryContext {
+    /**
+     * Profile ready for deployment to Akash
+     *
+     * Local images have been replaced with public registry URLs.
+     * For example:
+     *   - Original: `{ image: "my-app" }`
+     *   - Deployable: `{ image: "abc123.serveo.net/my-app:latest", credentials: {...} }`
+     *
+     * If no local images were detected, this will be the same as the original profile.
+     */
+    readonly deployableProfile: AkashDeploymentProfile;
+    /**
+     * Cleanup function to call after deployment
+     *
+     * Shuts down the temporary registry. Should be called after Akash providers
+     * have successfully pulled the images (containers are running).
+     *
+     * **Important:** Always call this in a finally block to ensure cleanup happens
+     * even if deployment fails.
+     *
+     * If no registry was started (no local images), this is a no-op function.
+     */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Configuration options for registry setup
+ *
+ * Controls how the temporary registry is started and exposed publicly.
+ */
+export interface RegistryOptions {
+    /**
+     * Skip registry setup and assume images are in remote registries
+     *
+     * When true, no temporary registry is started regardless of whether local
+     * images are detected. Use this when you've manually pushed all images to
+     * Docker Hub, GHCR, or another registry.
+     *
+     * **Warning:** If set to true but images aren't actually in a remote registry,
+     * deployment will fail when providers try to pull them.
+     *
+     * @default false
+     */
+    useRemoteRegistry?: boolean;
+    /**
+     * Container engine to use for image operations
+     *
+     * Used for checking if images exist locally and pushing them to the registry.
+     *
+     * @default 'docker'
+     */
+    containerEngine?: 'docker' | 'podman';
+    /**
+     * Tunnel service to expose registry publicly
+     *
+     * The temporary registry runs on localhost and needs to be exposed publicly
+     * so Akash providers can pull images. Choose a tunnel service:
+     *
+     * - **ngrok**: Reliable, requires auth token for extended sessions
+     * - **serveo**: Free, no signup, but less reliable
+     * - **bore**: Modern alternative, requires bore.pub service
+     *
+     * @default 'serveo'
+     */
+    tunnelService?: 'ngrok' | 'serveo' | 'bore';
+    /**
+     * How long to keep registry running before auto-shutdown (milliseconds)
+     *
+     * Provides a safety net in case cleanup() isn't called. The registry will
+     * automatically shut down after this duration.
+     *
+     * @default 600000 (10 minutes)
+     */
+    registryDuration?: number;
+    /**
+     * Enable automatic shutdown when downloads complete
+     *
+     * When true, the registry monitors download activity and automatically shuts
+     * down once all images have been pulled. This is more efficient than waiting
+     * for the duration timeout.
+     *
+     * @default true
+     */
+    autoShutdown?: boolean;
+    /**
+     * Authentication token for tunnel service
+     *
+     * Required for ngrok. Optional for other services depending on their features.
+     *
+     * **Environment variable:** Can also be set via NGROK_AUTH_TOKEN
+     *
+     * @default undefined
+     */
+    tunnelAuthToken?: string;
+    /**
+     * Region for tunnel service
+     *
+     * For ngrok: 'us', 'eu', 'ap', 'au', 'sa', 'jp', 'in'
+     *
+     * **Environment variable:** Can also be set via NGROK_REGION
+     *
+     * @default undefined (uses tunnel service default)
+     */
+    tunnelRegion?: string;
+    /**
+     * Protocol for tunnel
+     *
+     * @default 'http'
+     */
+    tunnelProtocol?: 'http' | 'https';
+    /**
+     * Custom subdomain for tunnel
+     *
+     * May require paid plan depending on tunnel service.
+     *
+     * @default undefined (random subdomain assigned)
+     */
+    tunnelSubdomain?: string;
+    /**
+     * Port for local registry server
+     *
+     * @default 3000
+     */
+    port?: number;
+}
+/**
+ * Container mapping that tracks original image to registry URL transformation
+ *
+ * Internal type used by TemporaryContainerRegistryManager to track how images
+ * are transformed during the registry setup process.
+ */
+export interface ContainerMapping {
+    /** Original image name from agent.json (e.g., "my-app" or "my-app:latest") */
+    originalImage: string;
+    /** Service name from profile (e.g., "frontend", "api") */
+    serviceName: string;
+    /** Full registry URL with credentials host (e.g., "temp-registry.serveo.net/my-app:latest") */
+    registryUrl: string;
+    /** Repository name extracted from image (e.g., "my-app") */
+    repoName: string;
+    /** Image tag (e.g., "latest", "v1.0.0") */
+    imageTag: string;
+    /** Sanitized alias used in registry (e.g., "my-app") */
+    actualAlias: string;
+}
+/**
+ * Registry credentials for SDL generation
+ *
+ * Credentials required for Akash providers to authenticate with the temporary registry.
+ * These are automatically added to the SDL services section.
+ */
+export interface RegistryCredentials {
+    /** Registry host without protocol (e.g., "abc123.serveo.net") */
+    host: string;
+    /** Username for registry authentication */
+    username: string;
+    /** Password for registry authentication */
+    password: string;
+}
+/**
+ * Registry information from container registry instance
+ *
+ * Internal type containing connection details for the running registry.
+ */
+export interface RegistryInfo {
+    /** Primary registry URL (tunnel URL if available, otherwise local) */
+    url: string;
+    /** Local registry URL (always present - always starts locally) */
+    localUrl: string;
+    /** Tunnel URL (optional - tunneling might fail) */
+    tunnelUrl?: string;
+    /** Authentication credentials (optional - may not be required) */
+    credentials?: {
+        username: string;
+        password: string;
+        accessKey: string;
+        secretKey: string;
+    };
+}
+/**
+ * Registry URL components including local and tunnel endpoints
+ *
+ * Internal type used for managing both local and public registry URLs.
+ */
+export interface RegistryUrls {
+    /** Local URL with protocol (e.g., "http://localhost:3000") */
+    localUrl: string;
+    /** Local domain without protocol (e.g., "localhost:3000") */
+    localDomain: string;
+    /** Tunnel URL with protocol (e.g., "https://abc123.serveo.net") or null */
+    tunnelUrl: string | null;
+    /** Tunnel domain without protocol (e.g., "abc123.serveo.net") or null */
+    tunnelDomain: string | null;
+}
+/**
+ * Container information returned by the registry
+ *
+ * Represents a container that has been added to the temporary registry.
+ * The alias is the sanitized name used to reference the container in the registry.
+ */
+export interface ContainerInfo {
+    /** Sanitized container alias used in the registry (e.g., "my-app") */
+    alias: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/utils/registry/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/registry/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;OASG;IACH,QAAQ,CAAC,iBAAiB,EAAE,sBAAsB,CAAC;IAEnD;;;;;;;;;;OAUG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAEtC;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IAE5C;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IAEtB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IAEpB,+FAA+F;IAC/F,WAAW,EAAE,MAAM,CAAC;IAEpB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IAEjB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IAEjB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IAEb,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IAEjB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IAEZ,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IAEjB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,kEAAkE;IAClE,WAAW,CAAC,EAAE;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IAEjB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IAEpB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB,yEAAyE;IACzE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/utils/registry/types.js

@@ -0,0 +1,10 @@
+/**
+ * Registry Infrastructure Types
+ *
+ * Type definitions for temporary container registry that makes local images
+ * accessible to Akash providers during deployment.
+ *
+ * @module utils/registry/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils/registry/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/utils/registry/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/docs/EXAMPLES.md

@@ -0,0 +1,293 @@
+# deploy-ability Examples
+
+Detailed examples for various use cases.
+
+## 3. CI/CD Automation
+
+**Scenario:** Automated deployments from GitHub Actions, GitLab CI, or other CI/CD platforms.
+
+### GitHub Actions Example
+
+```typescript
+// .github/workflows/deploy.ts
+import { createWalletContextFromSigner, deployToAkash } from 'deploy-ability';
+import { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';
+
+async function deploy() {
+  const environment = process.env.GITHUB_REF_NAME; // branch name
+  const profile = environment === 'main' ? 'production' : 'staging';
+  const network = environment === 'main' ? 'mainnet' : 'testnet';
+
+  console.log(`Deploying ${environment} to ${network}...`);
+
+  // Create signer from GitHub Secret
+  const mnemonic = process.env.AKASH_DEPLOYMENT_MNEMONIC!;
+  const signer = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, {
+    prefix: 'akash'
+  });
+
+  // Create wallet context
+  const wallet = await createWalletContextFromSigner(signer, network);
+
+  if (!wallet.success) {
+    console.error('Wallet setup failed:', wallet.error.message);
+    process.exit(1);
+  }
+
+  // Deploy!
+  const result = await deployToAkash({
+    wallet: wallet.data,
+    projectRoot: process.cwd(),
+    profile,
+    network
+  });
+
+  if (result.success) {
+    console.log(`Deployed successfully!`);
+    console.log(`   DSEQ: ${result.data.dseq}`);
+    console.log(`   Provider: ${result.data.providerUri}`);
+    console.log(`   Console: https://console.akash.network/deployments/${result.data.dseq}`);
+
+    // Post to Slack/Discord
+    await notify({
+      environment,
+      dseq: result.data.dseq,
+      url: `https://console.akash.network/deployments/${result.data.dseq}`
+    });
+
+    process.exit(0);
+  } else {
+    console.error('Deployment failed:', result.error.message);
+    process.exit(1);
+  }
+}
+
+deploy().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});
+```
+
+### GitHub Actions Workflow
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy to Akash
+
+on:
+  push:
+    branches: [main, staging]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Deploy to Akash
+        env:
+          AKASH_DEPLOYMENT_MNEMONIC: ${{ secrets.AKASH_DEPLOYMENT_MNEMONIC }}
+        run: npx tsx .github/workflows/deploy.ts
+```
+
+---
+
+## 4. API Servers
+
+**Scenario:** Deployment-as-a-Service - users trigger deployments via REST API.
+
+```typescript
+import express from 'express';
+import {
+  deployToAkash,
+  createWalletContextFromSigner,
+  DeploymentError
+} from 'deploy-ability';
+import { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';
+
+const app = express();
+app.use(express.json());
+
+// Service wallet (pays for deployments)
+let serviceWallet: WalletContext;
+
+async function initializeServiceWallet() {
+  const mnemonic = process.env.SERVICE_WALLET_MNEMONIC!;
+  const signer = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, {
+    prefix: 'akash'
+  });
+
+  const result = await createWalletContextFromSigner(signer, 'mainnet');
+  if (!result.success) throw result.error;
+
+  serviceWallet = result.data;
+  console.log('Service wallet initialized:', serviceWallet.address);
+}
+
+app.post('/api/deployments', async (req, res) => {
+  const { projectPath, profile, network } = req.body;
+
+  // Validate request
+  if (!projectPath || !profile) {
+    return res.status(400).json({
+      error: 'Missing required fields: projectPath, profile'
+    });
+  }
+
+  try {
+    // Deploy using service wallet
+    const result = await deployToAkash({
+      wallet: serviceWallet,
+      projectRoot: projectPath,
+      profile,
+      network: network || 'mainnet'
+    });
+
+    if (result.success) {
+      res.json({
+        success: true,
+        deployment: {
+          dseq: result.data.dseq,
+          provider: result.data.provider,
+          providerUri: result.data.providerUri,
+          consoleUrl: `https://console.akash.network/deployments/${result.data.dseq}`
+        }
+      });
+    } else {
+      res.status(500).json({
+        success: false,
+        error: result.error.message,
+        code: result.error.code
+      });
+    }
+  } catch (error) {
+    console.error('Deployment error:', error);
+
+    if (error instanceof DeploymentError) {
+      res.status(400).json({
+        success: false,
+        error: error.message,
+        code: error.code,
+        context: error.context
+      });
+    } else {
+      res.status(500).json({
+        success: false,
+        error: 'Internal server error'
+      });
+    }
+  }
+});
+
+// Initialize and start server
+initializeServiceWallet().then(() => {
+  app.listen(3000, () => {
+    console.log('Deployment API running on http://localhost:3000');
+  });
+});
+```
+
+---
+## Examples
+
+### Complete Deployment Script
+
+```typescript
+import {
+  connectWallet,
+  createSigningClient,
+  ensureCertificate,
+  deployToAkash
+} from 'deploy-ability';
+import QRCode from 'qrcode-terminal';
+
+async function main() {
+  console.log('Deploying to Akash Network...\n');
+
+  // 1. Connect wallet
+  console.log('Step 1: Connect Keplr Wallet');
+  const walletResult = await connectWallet(
+    'your-project-id',
+    'mainnet',
+    {
+      onUriGenerated: (uri) => {
+        QRCode.generate(uri, { small: true });
+        console.log('Scan QR code with Keplr mobile app');
+        console.log('Waiting for approval...');
+      },
+      timeoutMs: 120000
+    }
+  );
+
+  if (!walletResult.success) {
+    console.error('Wallet connection failed:', walletResult.error.message);
+    process.exit(1);
+  }
+
+  console.log(`Connected: ${walletResult.data.address}\n`);
+
+  // 2. Create signing client
+  console.log('Step 2: Connect to Akash Blockchain');
+  const clientResult = await createSigningClient(walletResult.data, 'mainnet');
+
+  if (!clientResult.success) {
+    console.error('Client creation failed:', clientResult.error.message);
+    process.exit(1);
+  }
+
+  console.log('Connected to Akash RPC\n');
+
+  // 3. Ensure certificate
+  console.log('Step 3: Setup Certificate');
+  const certResult = await ensureCertificate(
+    walletResult.data,
+    'mainnet',
+    clientResult.data.client
+  );
+
+  if (!certResult.success) {
+    console.error('Certificate setup failed:', certResult.error.message);
+    process.exit(1);
+  }
+
+  console.log('Certificate ready\n');
+
+  // 4. Deploy!
+  console.log('Step 4: Deploy to Akash');
+  const result = await deployToAkash({
+    wallet: walletResult.data,
+    certificate: certResult.data,
+    projectRoot: process.cwd(),
+    profile: 'production',
+    network: 'mainnet'
+  });
+
+  if (!result.success) {
+    console.error('Deployment failed:', result.error.message);
+    process.exit(1);
+  }
+
+  // Success!
+  console.log('\nDeployment Successful!\n');
+  console.log('Deployment Details:');
+  console.log(`  DSEQ: ${result.data.dseq}`);
+  console.log(`  Provider: ${result.data.provider}`);
+  console.log(`  Provider URI: ${result.data.providerUri}`);
+  console.log(`  Console: https://console.akash.network/deployments/${result.data.dseq}`);
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});
+```
+
+---