agentvault 1.0.0 → 1.0.2

package/dist/src/icp/icpcli.js

@@ -0,0 +1,374 @@
+/**
+ * icp-cli Wrapper
+ *
+ * TypeScript wrapper around the icp CLI tool (v0.1.0).
+ * The binary name is `icp` (not `icp-cli`).
+ *
+ * Provides typed interfaces for build, deploy, canister operations,
+ * cycles management, identity management, network management,
+ * token operations, sync, and environment queries.
+ */
+import { execa } from 'execa';
+const ICP_BIN = 'icp';
+/**
+ * Build common arguments from IcpCommonOptions.
+ */
+function buildCommonArgs(options) {
+    const args = [];
+    if (options.environment) {
+        args.push('-e', options.environment);
+    }
+    if (options.projectRoot) {
+        args.push('--project-root-override', options.projectRoot);
+    }
+    if (options.identity) {
+        args.push('--identity', options.identity);
+    }
+    if (options.identityPasswordFile) {
+        args.push('--identity-password-file', options.identityPasswordFile);
+    }
+    if (options.debug) {
+        args.push('--debug');
+    }
+    return args;
+}
+/**
+ * Execute an icp command and return the result.
+ *
+ * @param args - Command-line arguments (after 'icp')
+ * @param timeoutMs - Timeout in milliseconds (default 120s)
+ * @param cwd - Working directory
+ * @returns Structured result
+ */
+async function runIcp(args, timeoutMs = 120_000, cwd) {
+    try {
+        const result = await execa(ICP_BIN, args, {
+            reject: false,
+            timeout: timeoutMs,
+            cwd,
+        });
+        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,
+        };
+    }
+}
+// ─── Build ─────────────────────────────────────────────────────────────────
+/**
+ * Build canisters using icp build.
+ *
+ * @param options - Build options
+ * @returns Command result
+ */
+export async function build(options = {}) {
+    const args = ['build', ...buildCommonArgs(options)];
+    if (options.canisters && options.canisters.length > 0) {
+        args.push(...options.canisters);
+    }
+    return runIcp(args, 300_000, options.projectRoot);
+}
+// ─── Deploy ────────────────────────────────────────────────────────────────
+/**
+ * Deploy project to an environment.
+ *
+ * @param options - Deploy options
+ * @returns Command result
+ */
+export async function deploy(options = {}) {
+    const args = ['deploy', ...buildCommonArgs(options)];
+    if (options.mode) {
+        args.push('-m', options.mode);
+    }
+    if (options.canisters && options.canisters.length > 0) {
+        args.push(...options.canisters);
+    }
+    return runIcp(args, 300_000, options.projectRoot);
+}
+// ─── Canister Operations ───────────────────────────────────────────────────
+/**
+ * Get canister status.
+ *
+ * @param options - Canister status options
+ * @returns Command result with status in stdout
+ */
+export async function canisterStatus(options) {
+    const args = ['canister', 'status', options.canister, ...buildCommonArgs(options)];
+    return runIcp(args, 30_000, options.projectRoot);
+}
+/**
+ * Call a canister method.
+ *
+ * @param options - Canister call options
+ * @returns Command result with response in stdout
+ */
+export async function canisterCall(options) {
+    const args = ['canister', 'call', options.canister, options.method, ...buildCommonArgs(options)];
+    if (options.args) {
+        args.push(options.args);
+    }
+    return runIcp(args, 30_000, options.projectRoot);
+}
+/**
+ * List canisters in the project.
+ *
+ * @param options - Common options
+ * @returns Command result with canister list in stdout
+ */
+export async function canisterList(options = {}) {
+    const args = ['canister', 'list', ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+/**
+ * Start a stopped canister.
+ *
+ * @param canister - Canister ID or name
+ * @param options - Common options
+ * @returns Command result
+ */
+export async function canisterStart(canister, options = {}) {
+    const args = ['canister', 'start', canister, ...buildCommonArgs(options)];
+    return runIcp(args, 30_000, options.projectRoot);
+}
+/**
+ * Stop a running canister.
+ *
+ * @param canister - Canister ID or name
+ * @param options - Common options
+ * @returns Command result
+ */
+export async function canisterStop(canister, options = {}) {
+    const args = ['canister', 'stop', canister, ...buildCommonArgs(options)];
+    return runIcp(args, 30_000, options.projectRoot);
+}
+/**
+ * Delete a canister.
+ *
+ * @param canister - Canister ID or name
+ * @param options - Common options
+ * @returns Command result
+ */
+export async function canisterDelete(canister, options = {}) {
+    const args = ['canister', 'delete', canister, ...buildCommonArgs(options)];
+    return runIcp(args, 30_000, options.projectRoot);
+}
+// ─── Cycles Management ────────────────────────────────────────────────────
+/**
+ * Check cycle balance of a canister.
+ *
+ * @param options - Cycles balance options
+ * @returns Command result with balance in stdout
+ */
+export async function cyclesBalance(options) {
+    const args = ['cycles', 'balance', options.canister, ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+/**
+ * Mint cycles.
+ *
+ * @param options - Mint options
+ * @returns Command result
+ */
+export async function cyclesMint(options) {
+    const args = ['cycles', 'mint', options.amount, ...buildCommonArgs(options)];
+    return runIcp(args, 30_000, options.projectRoot);
+}
+/**
+ * Transfer cycles to a canister.
+ *
+ * @param options - Transfer options
+ * @returns Command result
+ */
+export async function cyclesTransfer(options) {
+    const args = ['cycles', 'transfer', options.amount, '--to', options.to, ...buildCommonArgs(options)];
+    return runIcp(args, 30_000, options.projectRoot);
+}
+// ─── Identity Management ──────────────────────────────────────────────────
+/**
+ * List available identities.
+ *
+ * @param options - Common options
+ * @returns Command result with identity list in stdout
+ */
+export async function identityList(options = {}) {
+    const args = ['identity', 'list', ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+/**
+ * Create a new identity.
+ *
+ * @param options - New identity options
+ * @returns Command result
+ */
+export async function identityNew(options) {
+    const args = ['identity', 'new', ...(options.name ? [options.name] : []), ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+/**
+ * Export an identity.
+ *
+ * @param options - Export options
+ * @returns Command result with PEM data in stdout
+ */
+export async function identityExport(options) {
+    const args = ['identity', 'export', ...(options.name ? [options.name] : []), ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+/**
+ * Import an identity from a PEM file.
+ *
+ * @param options - Import options
+ * @returns Command result
+ */
+export async function identityImport(options) {
+    const args = ['identity', 'import', ...(options.name ? [options.name] : []), ...(options.pemFile ? [options.pemFile] : []), ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+/**
+ * Get the principal of the current or named identity.
+ *
+ * @param options - Common options (use identity field to specify which identity)
+ * @returns Command result with principal in stdout
+ */
+export async function identityPrincipal(options = {}) {
+    const args = ['identity', 'principal', ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+/**
+ * Get the default identity name.
+ *
+ * @param options - Common options
+ * @returns Command result with default identity name in stdout
+ */
+export async function identityDefault(options = {}) {
+    const args = ['identity', 'default', ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+// ─── Network Management ───────────────────────────────────────────────────
+/**
+ * Start a local test network.
+ *
+ * @param options - Network start options
+ * @returns Command result
+ */
+export async function networkStart(options = {}) {
+    const args = ['network', 'start', ...buildCommonArgs(options)];
+    if (options.network) {
+        args.push(options.network);
+    }
+    return runIcp(args, 60_000, options.projectRoot);
+}
+/**
+ * Stop a local test network.
+ *
+ * @param options - Network stop options
+ * @returns Command result
+ */
+export async function networkStop(options = {}) {
+    const args = ['network', 'stop', ...buildCommonArgs(options)];
+    if (options.network) {
+        args.push(options.network);
+    }
+    return runIcp(args, 30_000, options.projectRoot);
+}
+/**
+ * Get network status.
+ *
+ * @param options - Common options
+ * @returns Command result with status in stdout
+ */
+export async function networkStatus(options = {}) {
+    const args = ['network', 'status', ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+/**
+ * List available networks.
+ *
+ * @param options - Common options
+ * @returns Command result with network list in stdout
+ */
+export async function networkList(options = {}) {
+    const args = ['network', 'list', ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+/**
+ * Ping a network to check connectivity.
+ *
+ * @param options - Common options
+ * @returns Command result
+ */
+export async function networkPing(options = {}) {
+    const args = ['network', 'ping', ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+// ─── Sync ──────────────────────────────────────────────────────────────────
+/**
+ * Synchronize canisters with the network.
+ *
+ * @param options - Sync options
+ * @returns Command result
+ */
+export async function sync(options = {}) {
+    const args = ['sync', ...buildCommonArgs(options)];
+    return runIcp(args, 120_000, options.projectRoot);
+}
+// ─── Token Operations ─────────────────────────────────────────────────────
+/**
+ * Get token balance.
+ *
+ * @param options - Token balance options
+ * @returns Command result with balance in stdout
+ */
+export async function tokenBalance(options = {}) {
+    const args = ['token', 'balance', ...buildCommonArgs(options)];
+    if (options.canister) {
+        args.push('--canister', options.canister);
+    }
+    return runIcp(args, 15_000, options.projectRoot);
+}
+/**
+ * Transfer tokens.
+ *
+ * @param options - Token transfer options
+ * @returns Command result
+ */
+export async function tokenTransfer(options) {
+    const args = ['token', 'transfer', options.amount, '--to', options.to, ...buildCommonArgs(options)];
+    if (options.canister) {
+        args.push('--canister', options.canister);
+    }
+    return runIcp(args, 30_000, options.projectRoot);
+}
+// ─── Environment ──────────────────────────────────────────────────────────
+/**
+ * List project environments.
+ *
+ * @param options - Common options
+ * @returns Command result with environments in stdout
+ */
+export async function environmentList(options = {}) {
+    const args = ['environment', 'list', ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+// ─── Project ──────────────────────────────────────────────────────────────
+/**
+ * Show project information (effective YAML config).
+ *
+ * @param options - Common options
+ * @returns Command result with project info in stdout
+ */
+export async function projectShow(options = {}) {
+    const args = ['project', 'show', ...buildCommonArgs(options)];
+    return runIcp(args, 15_000, options.projectRoot);
+}
+//# sourceMappingURL=icpcli.js.map

package/dist/src/icp/icwasm.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 type { IcWasmResult, IcWasmOptimizeOptions, IcWasmShrinkOptions, IcWasmResourceOptions, IcWasmMetadataOptions, IcWasmCheckEndpointsOptions, IcWasmInstrumentOptions, IcWasmInfo } from './types.js';
+/**
+ * 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 declare function optimize(options: IcWasmOptimizeOptions): Promise<IcWasmResult>;
+/**
+ * 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 declare function shrink(options: IcWasmShrinkOptions): Promise<IcWasmResult>;
+/**
+ * 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 declare function setResource(options: IcWasmResourceOptions): Promise<IcWasmResult>;
+/**
+ * List metadata in a WASM module.
+ *
+ * @param input - Input WASM file path
+ * @returns Command result with metadata listing in stdout
+ */
+export declare function listMetadata(input: string): Promise<IcWasmResult>;
+/**
+ * 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 declare function getMetadata(input: string, name: string): Promise<IcWasmResult>;
+/**
+ * Set metadata on a WASM module.
+ *
+ * @param options - Metadata options
+ * @returns Command result
+ */
+export declare function setMetadata(options: IcWasmMetadataOptions): Promise<IcWasmResult>;
+/**
+ * Get detailed information about a WASM canister module.
+ *
+ * @param input - Input WASM file path
+ * @returns Parsed info result
+ */
+export declare function info(input: string): Promise<IcWasmInfo>;
+/**
+ * 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 declare function checkEndpoints(options: IcWasmCheckEndpointsOptions): Promise<IcWasmResult>;
+/**
+ * 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 declare function instrument(options: IcWasmInstrumentOptions): Promise<IcWasmResult>;
+//# sourceMappingURL=icwasm.d.ts.map

package/dist/src/icp/icwasm.js

@@ -0,0 +1,197 @@
+/**
+ * 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';
+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, timeoutMs = 60_000) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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, name) {
+    return runIcWasm([input, 'metadata', name]);
+}
+/**
+ * Set metadata on a WASM module.
+ *
+ * @param options - Metadata options
+ * @returns Command result
+ */
+export async function setMetadata(options) {
+    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) {
+    const result = await runIcWasm([input, 'info']);
+    const parsed = { raw: result.stdout };
+    // Best-effort parsing of info output into sections
+    if (result.success && result.stdout) {
+        const sections = {};
+        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) {
+    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) {
+    return runIcWasm([options.input, 'instrument', '-o', options.output]);
+}
+//# sourceMappingURL=icwasm.js.map