agentvault 1.0.0 → 1.0.2

package/src/icp/icwasm.ts

@@ -1,222 +0,0 @@
-/**
- * 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/index.ts

@@ -1,94 +0,0 @@
-/**
- * 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

@@ -1,242 +0,0 @@
-/**
- * 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/tool-detector.ts

@@ -1,110 +0,0 @@
-/**
- * Tool Detector
- *
- * Auto-detects availability of ICP tools (ic-wasm, icp, dfx)
- * on the current system. Used for hybrid compatibility strategy:
- * prefer icp-cli when available, fall back to dfx.
- */
-
-import { execaCommand } from 'execa';
-import type { ToolName, ToolInfo, ToolchainStatus } from './types.js';
-
-/**
- * Detect whether a single tool is installed and get its version.
- *
- * @param name - Tool binary name
- * @returns ToolInfo with availability, path, and version
- */
-export async function detectTool(name: ToolName): Promise<ToolInfo> {
-  const result: ToolInfo = { name, available: false };
-
-  // Locate the binary
-  try {
-    const whichResult = await execaCommand(`which ${name}`, {
-      reject: false,
-      timeout: 5000,
-    });
-    if (whichResult.exitCode === 0 && whichResult.stdout.trim()) {
-      result.path = whichResult.stdout.trim();
-    } else {
-      return result;
-    }
-  } catch {
-    return result;
-  }
-
-  // Get the version
-  try {
-    const versionResult = await execaCommand(`${name} --version`, {
-      reject: false,
-      timeout: 5000,
-    });
-    if (versionResult.exitCode === 0) {
-      const output = versionResult.stdout.trim() || versionResult.stderr.trim();
-      // Extract version number from output like "ic-wasm 0.9.11" or "icp 0.1.0" or "dfx 0.25.0"
-      const match = output.match(/(\d+\.\d+\.\d+)/);
-      if (match) {
-        result.version = match[1];
-      } else {
-        result.version = output;
-      }
-      result.available = true;
-    }
-  } catch {
-    // Binary exists but version check failed - still mark as available
-    result.available = !!result.path;
-  }
-
-  return result;
-}
-
-/**
- * Detect all ICP tools and determine the preferred toolchain.
- *
- * @returns Complete toolchain status
- */
-export async function detectToolchain(): Promise<ToolchainStatus> {
-  const [icWasm, icp, dfx] = await Promise.all([
-    detectTool('ic-wasm'),
-    detectTool('icp'),
-    detectTool('dfx'),
-  ]);
-
-  let preferredDeployTool: 'icp' | 'dfx' | null = null;
-  if (icp.available) {
-    preferredDeployTool = 'icp';
-  } else if (dfx.available) {
-    preferredDeployTool = 'dfx';
-  }
-
-  return {
-    icWasm,
-    icp,
-    dfx,
-    preferredDeployTool,
-    canOptimize: icWasm.available,
-  };
-}
-
-/**
- * Require a specific tool, throwing a descriptive error if not found.
- *
- * @param name - Tool to require
- * @param purpose - Human-readable description of why it's needed
- * @returns ToolInfo (guaranteed available)
- * @throws Error if tool is not available
- */
-export async function requireTool(name: ToolName, purpose: string): Promise<ToolInfo> {
-  const tool = await detectTool(name);
-  if (!tool.available) {
-    const installHints: Record<ToolName, string> = {
-      'ic-wasm': 'Install with: cargo install ic-wasm',
-      'icp': 'Install from: https://github.com/dfinity/icp-cli',
-      'dfx': 'Install with: sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"',
-    };
-    throw new Error(
-      `Tool '${name}' is required for ${purpose} but was not found.\n${installHints[name]}`
-    );
-  }
-  return tool;
-}