agentvault 1.0.0

package/src/icp/icwasm.ts

@@ -0,0 +1,222 @@
+/**
+ * ic-wasm Wrapper
+ *
+ * TypeScript wrapper around the ic-wasm CLI tool (v0.9.11).
+ * Provides typed interfaces for WASM optimization, shrinking,
+ * metadata management, resource limiting, endpoint validation,
+ * and instrumentation.
+ *
+ * Usage pattern:
+ *   ic-wasm [OPTIONS] <INPUT> <COMMAND>
+ *   Output is written with -o <OUTPUT>
+ */
+
+import { execa } from 'execa';
+import type {
+  IcWasmResult,
+  IcWasmOptimizeOptions,
+  IcWasmShrinkOptions,
+  IcWasmResourceOptions,
+  IcWasmMetadataOptions,
+  IcWasmCheckEndpointsOptions,
+  IcWasmInstrumentOptions,
+  IcWasmInfo,
+} from './types.js';
+
+const IC_WASM_BIN = 'ic-wasm';
+
+/**
+ * Execute an ic-wasm command and return the result.
+ *
+ * @param args - Command-line arguments (after 'ic-wasm')
+ * @param timeoutMs - Timeout in milliseconds (default 60s)
+ * @returns Structured result with stdout, stderr, exitCode
+ */
+async function runIcWasm(args: string[], timeoutMs = 60_000): Promise<IcWasmResult> {
+  try {
+    const result = await execa(IC_WASM_BIN, args, {
+      reject: false,
+      timeout: timeoutMs,
+    });
+    return {
+      success: result.exitCode === 0,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.exitCode ?? 1,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    return {
+      success: false,
+      stdout: '',
+      stderr: message,
+      exitCode: 1,
+    };
+  }
+}
+
+/**
+ * Optimize a WASM module using wasm-opt.
+ *
+ * Applies dead-code elimination, constant folding, and other
+ * optimizations to reduce WASM size and improve performance.
+ *
+ * @param options - Optimization options
+ * @returns Command result
+ */
+export async function optimize(options: IcWasmOptimizeOptions): Promise<IcWasmResult> {
+  const args = [options.input, 'optimize', '-o', options.output];
+  if (options.level) {
+    args.push(`--${options.level}`);
+  }
+  return runIcWasm(args, 120_000);
+}
+
+/**
+ * Shrink a WASM module by removing unused functions and debug info.
+ *
+ * This is a lighter-weight optimization focused purely on size reduction
+ * without the full wasm-opt pipeline.
+ *
+ * @param options - Shrink options
+ * @returns Command result
+ */
+export async function shrink(options: IcWasmShrinkOptions): Promise<IcWasmResult> {
+  const args = [options.input, 'shrink', '-o', options.output];
+  return runIcWasm(args);
+}
+
+/**
+ * Set resource limits on a WASM module.
+ *
+ * Embeds resource constraints (memory, compute) into the WASM metadata
+ * so the ICP runtime can enforce them.
+ *
+ * @param options - Resource limit options
+ * @returns Command result
+ */
+export async function setResource(options: IcWasmResourceOptions): Promise<IcWasmResult> {
+  const args = [
+    options.input,
+    'resource',
+    '-o', options.output,
+    options.name,
+    options.value,
+  ];
+  return runIcWasm(args);
+}
+
+/**
+ * List metadata in a WASM module.
+ *
+ * @param input - Input WASM file path
+ * @returns Command result with metadata listing in stdout
+ */
+export async function listMetadata(input: string): Promise<IcWasmResult> {
+  return runIcWasm([input, 'metadata', 'list']);
+}
+
+/**
+ * Get a specific metadata value from a WASM module.
+ *
+ * @param input - Input WASM file path
+ * @param name - Metadata key name
+ * @returns Command result with metadata value in stdout
+ */
+export async function getMetadata(input: string, name: string): Promise<IcWasmResult> {
+  return runIcWasm([input, 'metadata', name]);
+}
+
+/**
+ * Set metadata on a WASM module.
+ *
+ * @param options - Metadata options
+ * @returns Command result
+ */
+export async function setMetadata(options: IcWasmMetadataOptions): Promise<IcWasmResult> {
+  if (!options.output) {
+    return {
+      success: false,
+      stdout: '',
+      stderr: 'Output path is required for set metadata operations',
+      exitCode: 1,
+    };
+  }
+
+  const args = [options.input, 'metadata', options.name, '-o', options.output];
+
+  if (options.data !== undefined) {
+    args.push('-d', options.data);
+  } else if (options.file) {
+    args.push('-f', options.file);
+  }
+
+  if (options.visibility) {
+    args.push('-v', options.visibility);
+  }
+
+  return runIcWasm(args);
+}
+
+/**
+ * Get detailed information about a WASM canister module.
+ *
+ * @param input - Input WASM file path
+ * @returns Parsed info result
+ */
+export async function info(input: string): Promise<IcWasmInfo> {
+  const result = await runIcWasm([input, 'info']);
+  const parsed: IcWasmInfo = { raw: result.stdout };
+
+  // Best-effort parsing of info output into sections
+  if (result.success && result.stdout) {
+    const sections: Record<string, string> = {};
+    const lines = result.stdout.split('\n');
+    for (const line of lines) {
+      const colonIdx = line.indexOf(':');
+      if (colonIdx > 0) {
+        const key = line.substring(0, colonIdx).trim();
+        const value = line.substring(colonIdx + 1).trim();
+        if (key && value) {
+          sections[key] = value;
+        }
+      }
+    }
+    if (Object.keys(sections).length > 0) {
+      parsed.sections = sections;
+    }
+  }
+
+  return parsed;
+}
+
+/**
+ * Validate canister endpoints against a Candid interface.
+ *
+ * Compares the exported functions in the WASM module against the
+ * expected interface defined in a .did file. Returns success if
+ * all endpoints match.
+ *
+ * @param options - Check endpoints options
+ * @returns Command result (success means validation passed)
+ */
+export async function checkEndpoints(options: IcWasmCheckEndpointsOptions): Promise<IcWasmResult> {
+  return runIcWasm([
+    options.input,
+    'check-endpoints',
+    '--interface', options.candidInterface,
+  ]);
+}
+
+/**
+ * Instrument a WASM module for execution tracing (experimental).
+ *
+ * Modifies the WASM to emit execution traces to stable memory,
+ * useful for debugging and profiling canister behavior.
+ *
+ * @param options - Instrument options
+ * @returns Command result
+ */
+export async function instrument(options: IcWasmInstrumentOptions): Promise<IcWasmResult> {
+  return runIcWasm([options.input, 'instrument', '-o', options.output]);
+}

package/src/icp/identity.ts

@@ -0,0 +1,77 @@
+/**
+ * Identity Management
+ *
+ * Provides identity management via icp-cli.
+ * List identities, create new identities,
+ * import/export identities and manage default identity.
+ */
+
+import {
+  identityList,
+  identityNew,
+  identityExport,
+  identityPrincipal,
+  identityImport,
+  identityDefault,
+} from './icpcli.js';
+
+/**
+ * List all available identities.
+ *
+ * @returns Command result with identity list
+ */
+export async function listIdentities(): Promise<any> {
+  return identityList({});
+}
+
+/**
+ * Create a new identity.
+ *
+ * @param name - Identity name
+ * @returns Command result
+ */
+export async function createIdentity(name: string): Promise<any> {
+  return identityNew({ name });
+}
+
+/**
+ * Export an identity to PEM file.
+ *
+ * @param name - Identity name
+ * @returns Command result with PEM content
+ */
+export async function exportIdentity(name: string): Promise<any> {
+  return identityExport({ name });
+}
+
+/**
+ * Get the principal of a default or named identity.
+ *
+ * @param name - Identity name (if null, use default)
+ * @returns Command result with principal
+ */
+export async function getIdentityPrincipal(name?: string): Promise<string> {
+  const result = await identityPrincipal({ name });
+  return result.stdout || '';
+}
+
+/**
+ * Import an identity from a PEM file.
+ *
+ * @param name - Identity name to import
+ * @param pemFile - Path to PEM file
+ * @returns Command result
+ */
+export async function importIdentity(name: string, pemFile: string): Promise<any> {
+  return identityImport({ name, pemFile });
+}
+
+/**
+ * Set a default identity.
+ *
+ * @param name - Identity name to set as default
+ * @returns Command result
+ */
+export async function setDefaultIdentity(name: string): Promise<any> {
+  return identityDefault({ name });
+}

package/src/icp/index.ts

@@ -0,0 +1,94 @@
+/**
+ * ICP Tools Integration Module
+ *
+ * Provides typed wrappers around ic-wasm and icp-cli tooling,
+ * auto-detection of available tools, an optimization pipeline,
+ * and environment management.
+ */
+
+// Types
+export type {
+  ToolName,
+  ToolInfo,
+  ToolchainStatus,
+  IcWasmOptLevel,
+  IcWasmOptimizeOptions,
+  IcWasmShrinkOptions,
+  IcWasmResourceOptions,
+  IcWasmMetadataOptions,
+  IcWasmCheckEndpointsOptions,
+  IcWasmInstrumentOptions,
+  IcWasmResult,
+  IcWasmInfo,
+  MetadataVisibility,
+  IcWasmOptimizationResult,
+  IcWasmOptimizationPipelineOptions,
+  IcWasmOptimizationPipelineResult,
+  IcpEnvironment,
+  IcpDeployMode,
+  IcpCommonOptions,
+  IcpBuildOptions,
+  IcpDeployOptions,
+  IcpCanisterStatusOptions,
+  IcpCanisterCallOptions,
+  IcpCyclesBalanceOptions,
+  IcpCyclesMintOptions,
+  IcpCyclesTransferOptions,
+  IcpIdentityListOptions,
+  IcpIdentityNewOptions,
+  IcpIdentityExportOptions,
+  IcpIdentityImportOptions,
+  IcpNetworkStartOptions,
+  IcpNetworkStopOptions,
+  IcpSyncOptions,
+  IcpTokenBalanceOptions,
+  IcpTokenTransferOptions,
+  IcpEnvironmentListOptions,
+  IcpCliResult,
+  IcpNetworkConfig,
+  IcpCyclesConfig,
+  IcpEnvironmentConfig,
+  IcpOptimizationConfig,
+  IcpProjectConfig,
+} from './types.js';
+
+// Re-export monitoring types
+export type {
+  CanisterHealthStatus,
+  AlertSeverity,
+  CanisterStatusInfo,
+  MonitoringAlert,
+  HealthThresholds,
+  MonitoringOptions,
+  ResourceUsageSnapshot,
+} from '../monitoring/types.js';
+
+// Tool detection
+export {
+  detectTool,
+  detectToolchain,
+  requireTool,
+} from './tool-detector.js';
+
+// ic-wasm wrapper
+export * as icwasm from './icwasm.js';
+
+// icp-cli wrapper
+export * as icpcli from './icpcli.js';
+
+// Optimization pipeline
+export { runOptimizationPipeline } from './optimization.js';
+
+// Environment management
+export {
+  findConfigFile,
+  loadConfig,
+  getEnvironment,
+  getOptimizationConfig,
+  listEnvironments,
+  writeConfig,
+  generateDefaultConfig,
+} from './environment.js';
+
+// Batched canister operations
+export * from './batch.js';

package/src/icp/optimization.ts

@@ -0,0 +1,242 @@
+/**
+ * Optimization Pipeline
+ *
+ * Orchestrates ic-wasm optimize, shrink, resource limiting, metadata
+ * injection, and Candid validation into a single pipeline that runs
+ * after WASM generation in the packaging step.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { detectTool } from './tool-detector.js';
+import * as icwasm from './icwasm.js';
+import type {
+  IcWasmOptimizationPipelineOptions,
+  IcWasmOptimizationPipelineResult,
+  IcWasmOptLevel,
+} from './types.js';
+
+/**
+ * Run the full optimization pipeline on a WASM file.
+ *
+ * @param options - Pipeline options
+ * @returns Pipeline result with metrics
+ */
+export async function runOptimizationPipeline(
+  options: IcWasmOptimizationPipelineOptions,
+): Promise<IcWasmOptimizationPipelineResult> {
+  const startTime = Date.now();
+  const steps: IcWasmOptimizationPipelineResult['steps'] = [];
+  const warnings: string[] = [];
+  let currentInput = options.input;
+
+  // Verify input exists
+  if (!fs.existsSync(options.input)) {
+    return {
+      success: false,
+      outputPath: options.output,
+      originalSize: 0,
+      finalSize: 0,
+      reductionPercent: 0,
+      totalDurationMs: Date.now() - startTime,
+      steps: [],
+      warnings: [`Input file not found: ${options.input}`],
+    };
+  }
+
+  const originalSize = fs.statSync(options.input).size;
+
+  // Check if ic-wasm is available
+  const icWasmTool = await detectTool('ic-wasm');
+  if (!icWasmTool.available) {
+    // No optimization possible - copy input to output
+    fs.copyFileSync(options.input, options.output);
+    warnings.push('ic-wasm not found; skipping optimization. Install with: cargo install ic-wasm');
+    return {
+      success: true,
+      outputPath: options.output,
+      originalSize,
+      finalSize: originalSize,
+      reductionPercent: 0,
+      totalDurationMs: Date.now() - startTime,
+      steps: [],
+      warnings,
+    };
+  }
+
+  // Create temp directory for intermediate files
+  const tempDir = path.join(path.dirname(options.output), '.icp-optimize-tmp');
+  if (!fs.existsSync(tempDir)) {
+    fs.mkdirSync(tempDir, { recursive: true });
+  }
+  let tempCounter = 0;
+  function nextTemp(): string {
+    return path.join(tempDir, `step_${++tempCounter}.wasm`);
+  }
+
+  // Step 1: Shrink
+  if (options.shrink !== false) {
+    const stepStart = Date.now();
+    const tempOut = nextTemp();
+    const result = await icwasm.shrink({ input: currentInput, output: tempOut });
+    const step = {
+      step: 'shrink',
+      success: result.success,
+      durationMs: Date.now() - stepStart,
+      sizeAfter: undefined as number | undefined,
+      error: undefined as string | undefined,
+    };
+    if (result.success && fs.existsSync(tempOut)) {
+      step.sizeAfter = fs.statSync(tempOut).size;
+      currentInput = tempOut;
+    } else {
+      step.error = result.stderr || 'Shrink failed';
+      warnings.push(`Shrink step failed: ${step.error}`);
+    }
+    steps.push(step);
+  }
+
+  // Step 2: Optimize
+  if (options.optimize !== false) {
+    const stepStart = Date.now();
+    const tempOut = nextTemp();
+    const level: IcWasmOptLevel = options.optimizeLevel ?? 'O3';
+    const result = await icwasm.optimize({
+      input: currentInput,
+      output: tempOut,
+      level,
+    });
+    const step = {
+      step: `optimize (${level})`,
+      success: result.success,
+      durationMs: Date.now() - stepStart,
+      sizeAfter: undefined as number | undefined,
+      error: undefined as string | undefined,
+    };
+    if (result.success && fs.existsSync(tempOut)) {
+      step.sizeAfter = fs.statSync(tempOut).size;
+      currentInput = tempOut;
+    } else {
+      step.error = result.stderr || 'Optimize failed';
+      warnings.push(`Optimize step failed: ${step.error}`);
+    }
+    steps.push(step);
+  }
+
+  // Step 3: Resource limits
+  if (options.resourceLimits && Object.keys(options.resourceLimits).length > 0) {
+    for (const [name, value] of Object.entries(options.resourceLimits)) {
+      const stepStart = Date.now();
+      const tempOut: string = nextTemp();
+      const result = await icwasm.setResource({
+        input: currentInput as string,
+        output: tempOut,
+        name,
+        value,
+      });
+      const step = {
+        step: `resource (${name}=${value})`,
+        success: result.success,
+        durationMs: Date.now() - stepStart,
+        sizeAfter: undefined as number | undefined,
+        error: undefined as string | undefined,
+      };
+      if (result.success && fs.existsSync(tempOut)) {
+        step.sizeAfter = fs.statSync(tempOut).size;
+        currentInput = tempOut;
+      } else {
+        step.error = result.stderr || 'Resource limit failed';
+        warnings.push(`Resource limit '${name}' failed: ${step.error}`);
+      }
+      steps.push(step);
+    }
+  }
+
+  // Step 4: Metadata injection
+  if (options.metadata && options.metadata.length > 0) {
+    for (const meta of options.metadata) {
+      const stepStart = Date.now();
+      const tempOut = nextTemp();
+      const result = await icwasm.setMetadata({
+        input: currentInput,
+        output: tempOut,
+        name: meta.name,
+        data: meta.data,
+        visibility: meta.visibility,
+      });
+      const step = {
+        step: `metadata (${meta.name})`,
+        success: result.success,
+        durationMs: Date.now() - stepStart,
+        sizeAfter: undefined as number | undefined,
+        error: undefined as string | undefined,
+      };
+      if (result.success && fs.existsSync(tempOut)) {
+        step.sizeAfter = fs.statSync(tempOut).size;
+        currentInput = tempOut;
+      } else {
+        step.error = result.stderr || 'Metadata set failed';
+        warnings.push(`Metadata '${meta.name}' failed: ${step.error}`);
+      }
+      steps.push(step);
+    }
+  }
+
+  // Step 5: Candid validation (does not produce output, just validates)
+  let validationPassed: boolean | undefined;
+  if (options.candidInterface) {
+    const stepStart = Date.now();
+    const result = await icwasm.checkEndpoints({
+      input: currentInput,
+      candidInterface: options.candidInterface,
+    });
+    validationPassed = result.success;
+    const step = {
+      step: 'check-endpoints',
+      success: result.success,
+      durationMs: Date.now() - stepStart,
+      sizeAfter: undefined as number | undefined,
+      error: undefined as string | undefined,
+    };
+    if (!result.success) {
+      step.error = result.stderr || 'Endpoint validation failed';
+      warnings.push(`Candid validation failed: ${step.error}`);
+    }
+    steps.push(step);
+  }
+
+  // Move final result to output path
+  if (currentInput !== options.input) {
+    fs.copyFileSync(currentInput, options.output);
+  } else {
+    // No steps modified the file; copy input to output
+    fs.copyFileSync(options.input, options.output);
+  }
+
+  const finalSize = fs.statSync(options.output).size;
+
+  // Cleanup temp directory
+  try {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  } catch {
+    // Ignore cleanup errors
+  }
+
+  const reductionPercent = originalSize > 0
+    ? Math.round(((originalSize - finalSize) / originalSize) * 100)
+    : 0;
+
+  const allStepsSucceeded = steps.every((s: any) => s.success);
+
+  return {
+    success: allStepsSucceeded,
+    outputPath: options.output,
+    originalSize,
+    finalSize,
+    reductionPercent,
+    totalDurationMs: Date.now() - startTime,
+    steps,
+    validationPassed,
+    warnings,
+  };
+}

package/src/icp/tokens.ts

@@ -0,0 +1,36 @@
+/**
+ * Token Operations
+ *
+ * Provides token operations via icp-cli.
+ * Supports ICP and ICRC-1/ICRC-2 tokens.
+ */
+
+import { tokenBalance, tokenTransfer } from './icpcli.js';
+
+/**
+ * Check token balance for a canister.
+ *
+ * @param canister - Token canister ID
+ * @param options - Common ICP options
+ * @returns Command result with balance
+ */
+export async function checkBalance(
+  canister: string,
+): Promise<any> {
+  return tokenBalance({ canister });
+}
+
+/**
+ * Transfer tokens to a recipient.
+ *
+ * @param amount - Amount to transfer
+ * @param to - Recipient principal or account
+ * @param options - Common ICP options
+ * @returns Command result
+ */
+export async function transferTokens(
+  amount: string,
+  to: string,
+): Promise<any> {
+  return tokenTransfer({ amount, to });
+}