agentvault 1.0.0

package/src/deployment/promotion.ts

@@ -0,0 +1,161 @@
+/**
+ * Environment promotion for canister deployment
+ *
+ * Handles promoting canisters between environments (dev -> staging -> production)
+ * CLE-102: Wired to actual deploy path
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { parse, stringify } from 'yaml';
+import type { DeploymentHistory } from '../icp/types.js';
+
+const AGENTVAULT_DIR = path.join(os.homedir(), '.agentvault');
+const HISTORY_DIR = path.join(AGENTVAULT_DIR, 'history');
+
+function ensureHistoryDir(): void {
+  if (!fs.existsSync(AGENTVAULT_DIR)) {
+    fs.mkdirSync(AGENTVAULT_DIR, { recursive: true });
+  }
+  if (!fs.existsSync(HISTORY_DIR)) {
+    fs.mkdirSync(HISTORY_DIR, { recursive: true });
+  }
+}
+
+function getHistoryPath(agentName: string): string {
+  ensureHistoryDir();
+  return path.join(HISTORY_DIR, `${agentName}.yaml`);
+}
+
+export function loadDeploymentHistory(agentName: string): DeploymentHistory[] {
+  const historyPath = getHistoryPath(agentName);
+  
+  if (!fs.existsSync(historyPath)) {
+    return [];
+  }
+  
+  const content = fs.readFileSync(historyPath, 'utf8');
+  const parsed = parse(content) as unknown;
+  
+  if (Array.isArray(parsed)) {
+    return parsed as DeploymentHistory[];
+  }
+  
+  return [];
+}
+
+export function saveDeploymentHistory(agentName: string, history: DeploymentHistory[]): void {
+  const historyPath = getHistoryPath(agentName);
+  fs.writeFileSync(historyPath, stringify(history), 'utf8');
+}
+
+export function addDeploymentToHistory(deployment: DeploymentHistory): void {
+  const history = loadDeploymentHistory(deployment.agentName);
+  history.push(deployment);
+  saveDeploymentHistory(deployment.agentName, history);
+}
+
+export function getLatestDeployment(agentName: string, environment: string): DeploymentHistory | null {
+  const history = loadDeploymentHistory(agentName);
+  const envHistory = history.filter((d) => d.environment === environment && d.success);
+  
+  if (envHistory.length === 0) {
+    return null;
+  }
+  
+  return envHistory.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime())[0] ?? null;
+}
+
+export function getAllDeployments(agentName: string): DeploymentHistory[] {
+  return loadDeploymentHistory(agentName);
+}
+
+export interface PromotionOptions {
+  targetCanisterId?: string;
+  blueGreen?: boolean;
+  wasmPath?: string;
+  skipDeploy?: boolean;
+}
+
+/**
+ * Promote a canister from one environment to another
+ * Now calls actual deploy when skipDeploy is false
+ */
+export async function promoteCanister(
+  agentName: string,
+  fromEnv: string,
+  toEnv: string,
+  options: PromotionOptions = {},
+): Promise<DeploymentHistory> {
+  const sourceDeployment = getLatestDeployment(agentName, fromEnv);
+  
+  if (!sourceDeployment) {
+    throw new Error(`No successful deployment found for ${agentName} in ${fromEnv} environment`);
+  }
+  
+  const targetCanisterId = options.targetCanisterId || sourceDeployment.canisterId;
+  
+  if (!options.skipDeploy && options.wasmPath) {
+    const { deployAgent } = await import('./deployer.js');
+    
+    const deployResult = await deployAgent({
+      wasmPath: options.wasmPath,
+      network: toEnv,
+      canisterId: targetCanisterId,
+      mode: 'upgrade',
+    });
+
+    const targetDeployment: DeploymentHistory = {
+      agentName,
+      environment: toEnv,
+      canisterId: deployResult.canister.canisterId,
+      wasmHash: deployResult.canister.wasmHash || sourceDeployment.wasmHash,
+      timestamp: new Date(),
+      version: sourceDeployment.version + 1,
+      success: true,
+    };
+    
+    addDeploymentToHistory(targetDeployment);
+    
+    return targetDeployment;
+  }
+  
+  const targetDeployment: DeploymentHistory = {
+    agentName,
+    environment: toEnv,
+    canisterId: targetCanisterId,
+    wasmHash: sourceDeployment.wasmHash,
+    timestamp: new Date(),
+    version: sourceDeployment.version + 1,
+    success: true,
+  };
+  
+  addDeploymentToHistory(targetDeployment);
+  
+  return targetDeployment;
+}
+
+/**
+ * Get deployment history for rollback
+ */
+export function getDeploymentForRollback(agentName: string, environment: string, version: number): DeploymentHistory | null {
+  const history = loadDeploymentHistory(agentName);
+  const found = history.find((d) => d.environment === environment && d.version === version);
+  return found !== undefined ? found : null;
+}
+
+/**
+ * Get deployments by time range for rollback
+ */
+export function getDeploymentsByTimeRange(
+  agentName: string,
+  environment: string,
+  fromTime: Date,
+  toTime: Date,
+): DeploymentHistory[] {
+  const history = loadDeploymentHistory(agentName);
+  return history.filter(
+    (d) => d.environment === environment && d.timestamp >= fromTime && d.timestamp <= toTime && d.success,
+  ).sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+}

package/src/deployment/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Types for ICP canister deployment
+ */
+
+/**
+ * Network target for deployment
+ *
+ * - 'local': Local dfx/icp replica
+ * - 'ic': IC mainnet
+ * - string: Named environment from icp.yaml (e.g. 'dev', 'staging', 'production')
+ */
+export type NetworkType = 'local' | 'ic' | string;
+
+/**
+ * Which tool is being used for deployment
+ */
+export type DeployToolType = 'icp' | 'dfx' | 'sdk';
+
+/**
+ * Deployment status codes
+ */
+export type DeploymentStatus = 'pending' | 'deploying' | 'deployed' | 'failed' | 'running' | 'stopping' | 'stopped';
+
+/**
+ * Information about a deployed canister
+ */
+export interface CanisterInfo {
+  /** Canister ID on the network */
+  canisterId: string;
+  /** Network where the canister is deployed */
+  network: NetworkType;
+  /** Agent name associated with this canister */
+  agentName: string;
+  /** Deployment timestamp */
+  deployedAt: Date;
+  /** WASM module hash (for verification) */
+  wasmHash?: string;
+}
+
+/**
+ * Options for deployment operation
+ */
+export interface DeployOptions {
+  /** Path to the WASM file to deploy */
+  wasmPath: string;
+  /** Target network for deployment */
+  network: NetworkType;
+  /** Existing canister ID (for upgrades) */
+  canisterId?: string;
+  /** Skip confirmation prompts */
+  skipConfirmation?: boolean;
+  /** Path to dfx identity to use */
+  identityPath?: string;
+
+  // ── icp-cli options ───────────────────────────────────────────────────
+
+  /** Named environment from icp.yaml */
+  environment?: string;
+  /** Identity name for icp-cli */
+  identity?: string;
+  /** Cycles allocation for deployment */
+  cycles?: string;
+  /** Deploy mode (auto, install, reinstall, upgrade) */
+  mode?: 'auto' | 'install' | 'reinstall' | 'upgrade';
+  /** Override project root for icp.yaml lookup */
+  projectRoot?: string;
+}
+
+/**
+ * Result of a successful deployment
+ */
+export interface DeployResult {
+  /** Deployed canister information */
+  canister: CanisterInfo;
+  /** Whether this was a new deployment or upgrade */
+  isUpgrade: boolean;
+  /** Cycles consumed by deployment */
+  cyclesUsed?: bigint;
+  /** Any warnings during deployment */
+  warnings: string[];
+  /** Which tool was used for deployment */
+  deployTool?: DeployToolType;
+}
+
+/**
+ * Error that occurred during deployment
+ */
+export interface DeploymentError {
+  /** Error code for programmatic handling */
+  code: string;
+  /** Human-readable error message */
+  message: string;
+  /** Network where the error occurred */
+  network?: NetworkType;
+  /** Canister ID if applicable */
+  canisterId?: string;
+}
+
+/**
+ * Configuration for ICP client
+ */
+export interface ICPClientConfig {
+  /** Target network */
+  network: NetworkType;
+  /** Host URL (defaults based on network) */
+  host?: string;
+  /** Path to dfx identity file for signing */
+  identity?: string;
+  /** Canister ID for operations (optional, used when deploying/upgrading) */
+  canisterId?: string;
+}

package/src/icp/batch.ts

@@ -0,0 +1,374 @@
+/**
+ * Batched canister operations
+ *
+ * Executes multiple canister operations in parallel with dependency ordering,
+ * retries, and configurable concurrency.
+ */
+
+import type { IcpCommonOptions } from '../icp/types.js';
+import { canisterStatus, canisterCall } from '../icp/icpcli.js';
+
+export type BatchOperationType = 'call' | 'query' | 'status' | 'deploy';
+
+export interface BatchOperation {
+  /** Operation ID (auto-generated) */
+  id: string;
+  /** Operation type */
+  type: BatchOperationType;
+  /** Target canister ID */
+  canisterId: string;
+  /** Method name (for call/query) */
+  method?: string;
+  /** Arguments (Candid format) */
+  args?: string;
+  /** Options for the operation */
+  options?: IcpCommonOptions;
+  /** Dependencies (operation IDs that must complete first) */
+  dependsOn?: string[];
+}
+
+export interface BatchResult {
+  /** Operation ID */
+  operationId: string;
+  /** Whether this operation succeeded */
+  success: boolean;
+  /** Result data (if success) */
+  data?: unknown;
+  /** Error message (if failure) */
+  error?: string;
+  /** Execution duration in milliseconds */
+  durationMs: number;
+}
+
+export interface BatchExecutionResult {
+  /** Total operations */
+  total: number;
+  /** Successful operations */
+  succeeded: number;
+  /** Failed operations */
+  failed: number;
+  /** Individual results */
+  results: BatchResult[];
+  /** Total execution time */
+  totalDurationMs: number;
+}
+
+export interface BatchConfig {
+  /** Maximum concurrent operations */
+  maxConcurrency: number;
+  /** Timeout per operation in milliseconds */
+  operationTimeoutMs: number;
+  /** Whether to stop on first failure */
+  stopOnFailure: boolean;
+  /** Retry failed operations */
+  retryCount: number;
+  /** Retry delay in milliseconds */
+  retryDelayMs: number;
+}
+
+const DEFAULT_BATCH_CONFIG: BatchConfig = {
+  maxConcurrency: 10,
+  operationTimeoutMs: 30000,
+  stopOnFailure: false,
+  retryCount: 2,
+  retryDelayMs: 1000,
+};
+
+let operationCounter = 0;
+
+function generateOperationId(): string {
+  return `op_${++operationCounter}_${Date.now()}`;
+}
+
+/**
+ * Topologically sort operations by dependency graph
+ */
+function sortOperationsByDeps(operations: BatchOperation[]): BatchOperation[] {
+  const opMap = new Map(operations.map((op) => [op.id, op]));
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+  const sorted: BatchOperation[] = [];
+
+  function visit(opId: string): void {
+    if (visited.has(opId)) return;
+    if (visiting.has(opId)) {
+      throw new Error(`Circular dependency detected involving operation: ${opId}`);
+    }
+
+    visiting.add(opId);
+    const op = opMap.get(opId);
+    if (op !== undefined) {
+      if (op.dependsOn) {
+        for (const depId of op.dependsOn) {
+          visit(depId);
+        }
+      }
+      visiting.delete(opId);
+      visited.add(opId);
+      sorted.push(op);
+    }
+  }
+
+  for (const op of operations) {
+    visit(op.id);
+  }
+
+  return sorted;
+}
+
+/**
+ * Execute a single batch operation
+ */
+async function executeOperation(operation: BatchOperation, config: BatchConfig): Promise<BatchResult> {
+  const startTime = Date.now();
+  let result: BatchResult;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    setTimeout(() => reject(new Error(`Operation timeout after ${config.operationTimeoutMs}ms`)), config.operationTimeoutMs);
+  });
+
+  try {
+    const executionPromise = (async (): Promise<BatchResult> => {
+      switch (operation.type) {
+        case 'status': {
+          const statusResult = await canisterStatus({
+            canister: operation.canisterId,
+            ...operation.options,
+          });
+          return {
+            operationId: operation.id,
+            success: statusResult.success,
+            data: statusResult.stdout,
+            error: statusResult.success ? undefined : statusResult.stderr,
+            durationMs: 0,
+          };
+        }
+        case 'call':
+        case 'query': {
+          if (!operation.method) {
+            throw new Error('Method name is required for call/query operations');
+          }
+          const callResult = await canisterCall({
+            canister: operation.canisterId,
+            method: operation.method,
+            args: operation.args,
+            ...operation.options,
+          });
+          return {
+            operationId: operation.id,
+            success: callResult.success,
+            data: callResult.stdout,
+            error: callResult.success ? undefined : callResult.stderr,
+            durationMs: 0,
+          };
+        }
+        case 'deploy':
+          return {
+            operationId: operation.id,
+            success: true,
+            data: { message: 'Deploy operation placeholder' },
+            durationMs: 0,
+          };
+        default:
+          return {
+            operationId: operation.id,
+            success: false,
+            error: `Unknown operation type: ${operation.type}`,
+            durationMs: 0,
+          };
+      }
+    })();
+
+    result = await Promise.race([executionPromise, timeoutPromise]);
+  } catch (error) {
+    result = {
+      operationId: operation.id,
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error',
+      durationMs: 0,
+    };
+  }
+
+  result.durationMs = Date.now() - startTime;
+  return result;
+}
+
+/**
+ * BatchExecutor class for managing and executing batched canister operations
+ */
+export class BatchExecutor {
+  private operations: Map<string, BatchOperation> = new Map();
+  private config: BatchConfig;
+
+  constructor(config: Partial<BatchConfig> = {}) {
+    this.config = { ...DEFAULT_BATCH_CONFIG, ...config };
+  }
+
+  /**
+   * Add a single operation to the batch
+   */
+  addOperation(operation: BatchOperation): void {
+    this.operations.set(generateOperationId(), operation);
+  }
+
+  /**
+   * Add multiple operations to the batch
+   */
+  addOperations(ops: BatchOperation[]): void {
+    for (const op of ops) {
+      this.operations.set(generateOperationId(), op);
+    }
+  }
+
+  /**
+   * Execute all operations in the batch
+   */
+  async execute(): Promise<BatchExecutionResult> {
+    const startTime = Date.now();
+    const allOperations = Array.from(this.operations.values());
+    const sortedOps = sortOperationsByDeps(allOperations);
+
+    let succeeded = 0;
+    let failed = 0;
+    const executionResults: BatchResult[] = [];
+
+    for (let i = 0; i < sortedOps.length; i += this.config.maxConcurrency) {
+      const batch = sortedOps.slice(i, i + this.config.maxConcurrency);
+      const batchResults = await Promise.all(
+        batch.map((op) => this.executeWithRetry(op))
+      );
+
+      for (const result of batchResults) {
+        executionResults.push(result);
+        if (result.success) {
+          succeeded++;
+        } else {
+          failed++;
+          if (this.config.stopOnFailure) {
+            break;
+          }
+        }
+      }
+    }
+
+    return {
+      total: allOperations.length,
+      succeeded,
+      failed,
+      results: executionResults,
+      totalDurationMs: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * Execute an operation with retry logic
+   */
+  private async executeWithRetry(operation: BatchOperation): Promise<BatchResult> {
+    let lastError: string | undefined;
+    let delay = this.config.retryDelayMs;
+
+    for (let attempt = 0; attempt <= this.config.retryCount; attempt++) {
+      try {
+        const result = await executeOperation(operation, this.config);
+        if (result.success || attempt === this.config.retryCount) {
+          return result;
+        }
+        lastError = result.error;
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : 'Unknown error';
+      }
+
+      if (attempt < this.config.retryCount) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay *= 2;
+      }
+    }
+
+    return {
+      operationId: operation.id,
+      success: false,
+      error: lastError || 'Max retries exceeded',
+      durationMs: 0,
+    };
+  }
+
+  /**
+   * Get a dry-run plan of execution order
+   */
+  executeDryRun(): { order: string[]; parallelGroups: string[][] } {
+    const allOperations = Array.from(this.operations.values());
+    const sortedOps = sortOperationsByDeps(allOperations);
+    const order = sortedOps.map((op) => op.id);
+    const parallelGroups: string[][] = [];
+
+    for (let i = 0; i < sortedOps.length; i += this.config.maxConcurrency) {
+      parallelGroups.push(sortedOps.slice(i, i + this.config.maxConcurrency).map((op) => op.id));
+    }
+
+    return { order, parallelGroups };
+  }
+
+  /**
+   * Clear all operations
+   */
+  clear(): void {
+    this.operations.clear();
+  }
+}
+
+/**
+ * Create a new batch executor with custom config
+ */
+export function createBatchExecutor(config?: Partial<BatchConfig>): BatchExecutor {
+  return new BatchExecutor(config);
+}
+
+/**
+ * Helper to create a status-check operation
+ */
+export function createStatusOperation(canisterId: string, options?: IcpCommonOptions): BatchOperation {
+  return {
+    id: generateOperationId(),
+    type: 'status',
+    canisterId,
+    options,
+  };
+}
+
+/**
+ * Helper to create a query operation
+ */
+export function createQueryOperation(
+  canisterId: string,
+  method: string,
+  args?: string,
+  options?: IcpCommonOptions,
+): BatchOperation {
+  return {
+    id: generateOperationId(),
+    type: 'query',
+    canisterId,
+    method,
+    args,
+    options,
+  };
+}
+
+/**
+ * Helper to create a call operation
+ */
+export function createCallOperation(
+  canisterId: string,
+  method: string,
+  args?: string,
+  options?: IcpCommonOptions,
+): BatchOperation {
+  return {
+    id: generateOperationId(),
+    type: 'call',
+    canisterId,
+    method,
+    args,
+    options,
+  };
+}

package/src/icp/cycles.ts

@@ -0,0 +1,50 @@
+/**
+ * Cycles Management
+ *
+ * Provides cycles management via icp-cli.
+ * Check balances, mint cycles, transfer cycles.
+ */
+
+import {
+  cyclesBalance,
+  cyclesMint,
+  cyclesTransfer,
+} from './icpcli.js';
+
+/**
+ * Check cycle balance of a canister.
+ *
+ * @param canister - Canister ID or name
+ * @returns Command result with balance in stdout
+ */
+export async function checkBalance(
+  canister: string,
+): Promise<any> {
+  return cyclesBalance({ canister });
+}
+
+/**
+ * Mint cycles to a canister.
+ *
+ * @param amount - Amount to mint
+ * @returns Command result
+ */
+export async function mintCycles(
+  amount: string,
+): Promise<any> {
+  return cyclesMint({ amount });
+}
+
+/**
+ * Transfer cycles between canisters.
+ *
+ * @param amount - Amount to transfer
+ * @param to - Recipient principal or canister ID
+ * @returns Command result
+ */
+export async function transferCycles(
+  amount: string,
+  to: string,
+): Promise<any> {
+  return cyclesTransfer({ amount, to });
+}