@agirails/sdk 2.0.1-beta → 2.0.2

package/src/cli/utils/output.ts

@@ -0,0 +1,465 @@
+/**
+ * CLI Output Formatting Utilities
+ *
+ * Handles multi-mode output for human and machine consumption.
+ * Supports three output modes:
+ * - human: Colorful, formatted output for terminal users
+ * - json: Machine-readable JSON for scripting
+ * - quiet: Minimal output (just the essential value)
+ *
+ * @module cli/utils/output
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Output mode for CLI commands
+ */
+export type OutputMode = 'human' | 'json' | 'quiet';
+
+/**
+ * Structured error for JSON output
+ */
+export interface CLIError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Transaction display format
+ */
+export interface TransactionDisplay {
+  txId: string;
+  state: string;
+  requester: string;
+  provider: string;
+  amount: string;
+  deadline: string;
+  escrowId?: string | null;
+  createdAt?: string;
+}
+
+// ============================================================================
+// Color Support Detection
+// ============================================================================
+
+/**
+ * Check if terminal supports colors
+ */
+function supportsColor(): boolean {
+  // Force no color in tests or CI when FORCE_COLOR not set
+  if (process.env.NO_COLOR !== undefined) return false;
+  if (process.env.FORCE_COLOR !== undefined) return true;
+
+  // Check if stdout is TTY
+  if (!process.stdout.isTTY) return false;
+
+  // Check TERM
+  const term = process.env.TERM || '';
+  if (term === 'dumb') return false;
+
+  return true;
+}
+
+// ============================================================================
+// ANSI Color Codes (inline, no dependencies)
+// ============================================================================
+
+const COLORS_ENABLED = supportsColor();
+
+const colors = {
+  reset: COLORS_ENABLED ? '\x1b[0m' : '',
+  bold: COLORS_ENABLED ? '\x1b[1m' : '',
+  dim: COLORS_ENABLED ? '\x1b[2m' : '',
+  underline: COLORS_ENABLED ? '\x1b[4m' : '',
+
+  // Foreground
+  red: COLORS_ENABLED ? '\x1b[31m' : '',
+  green: COLORS_ENABLED ? '\x1b[32m' : '',
+  yellow: COLORS_ENABLED ? '\x1b[33m' : '',
+  blue: COLORS_ENABLED ? '\x1b[34m' : '',
+  magenta: COLORS_ENABLED ? '\x1b[35m' : '',
+  cyan: COLORS_ENABLED ? '\x1b[36m' : '',
+  white: COLORS_ENABLED ? '\x1b[37m' : '',
+  gray: COLORS_ENABLED ? '\x1b[90m' : '',
+};
+
+// ============================================================================
+// Text Formatting Helpers
+// ============================================================================
+
+export const fmt = {
+  bold: (s: string) => `${colors.bold}${s}${colors.reset}`,
+  dim: (s: string) => `${colors.dim}${s}${colors.reset}`,
+  underline: (s: string) => `${colors.underline}${s}${colors.reset}`,
+
+  red: (s: string) => `${colors.red}${s}${colors.reset}`,
+  green: (s: string) => `${colors.green}${s}${colors.reset}`,
+  yellow: (s: string) => `${colors.yellow}${s}${colors.reset}`,
+  blue: (s: string) => `${colors.blue}${s}${colors.reset}`,
+  magenta: (s: string) => `${colors.magenta}${s}${colors.reset}`,
+  cyan: (s: string) => `${colors.cyan}${s}${colors.reset}`,
+  white: (s: string) => `${colors.white}${s}${colors.reset}`,
+  gray: (s: string) => `${colors.gray}${s}${colors.reset}`,
+
+  // Semantic formatting
+  success: (s: string) => `${colors.green}${s}${colors.reset}`,
+  error: (s: string) => `${colors.red}${s}${colors.reset}`,
+  warning: (s: string) => `${colors.yellow}${s}${colors.reset}`,
+  info: (s: string) => `${colors.cyan}${s}${colors.reset}`,
+  label: (s: string) => `${colors.gray}${s}${colors.reset}`,
+  value: (s: string) => `${colors.white}${colors.bold}${s}${colors.reset}`,
+};
+
+// ============================================================================
+// State Formatting
+// ============================================================================
+
+/**
+ * Format transaction state with appropriate color
+ */
+export function formatState(state: string): string {
+  switch (state) {
+    case 'INITIATED':
+      return fmt.yellow(state);
+    case 'QUOTED':
+      return fmt.cyan(state);
+    case 'COMMITTED':
+      return fmt.blue(state);
+    case 'IN_PROGRESS':
+      return fmt.magenta(state);
+    case 'DELIVERED':
+      return fmt.green(state);
+    case 'SETTLED':
+      return fmt.green(fmt.bold(state));
+    case 'DISPUTED':
+      return fmt.red(state);
+    case 'CANCELLED':
+      return fmt.dim(state);
+    default:
+      return state;
+  }
+}
+
+// ============================================================================
+// Output Class
+// ============================================================================
+
+/**
+ * Output formatter for CLI commands
+ *
+ * Provides consistent output across all commands with support for
+ * human-readable, JSON, and quiet modes.
+ *
+ * @example
+ * ```typescript
+ * const output = new Output('human');
+ *
+ * // Success message
+ * output.success('Transaction created!');
+ *
+ * // Key-value output
+ * output.keyValue('Transaction ID', txId);
+ *
+ * // JSON output (in json mode, prints JSON)
+ * output.result({ txId, state: 'INITIATED' });
+ * ```
+ */
+export class Output {
+  public readonly mode: OutputMode;
+
+  constructor(mode: OutputMode = 'human') {
+    this.mode = mode;
+  }
+
+  // ==========================================================================
+  // Basic Output Methods
+  // ==========================================================================
+
+  /**
+   * Print a line (human mode only)
+   */
+  print(message: string): void {
+    if (this.mode === 'human') {
+      console.log(message);
+    }
+  }
+
+  /**
+   * Print success message
+   */
+  success(message: string): void {
+    if (this.mode === 'human') {
+      console.log(fmt.success('[+] ' + message));
+    }
+  }
+
+  /**
+   * Print error message
+   */
+  error(message: string): void {
+    if (this.mode === 'human') {
+      console.error(fmt.error('[!] ' + message));
+    }
+  }
+
+  /**
+   * Print warning message
+   */
+  warning(message: string): void {
+    if (this.mode === 'human') {
+      console.warn(fmt.warning('[*] ' + message));
+    }
+  }
+
+  /**
+   * Print info message
+   */
+  info(message: string): void {
+    if (this.mode === 'human') {
+      console.log(fmt.info('[i] ' + message));
+    }
+  }
+
+  /**
+   * Print a blank line (human mode only)
+   */
+  blank(): void {
+    if (this.mode === 'human') {
+      console.log('');
+    }
+  }
+
+  // ==========================================================================
+  // Structured Output
+  // ==========================================================================
+
+  /**
+   * Print a key-value pair
+   */
+  keyValue(key: string, value: string | number | boolean): void {
+    if (this.mode === 'human') {
+      console.log(`  ${fmt.label(key + ':')} ${fmt.value(String(value))}`);
+    }
+  }
+
+  /**
+   * Print a section header
+   */
+  section(title: string): void {
+    if (this.mode === 'human') {
+      console.log('');
+      console.log(fmt.bold(title));
+      console.log(fmt.dim('-'.repeat(40)));
+    }
+  }
+
+  /**
+   * Print a transaction in human-readable format
+   */
+  transaction(tx: TransactionDisplay): void {
+    if (this.mode === 'human') {
+      console.log('');
+      console.log(fmt.bold('Transaction Details'));
+      console.log(fmt.dim('-'.repeat(40)));
+      console.log(`  ${fmt.label('ID:')} ${fmt.value(tx.txId)}`);
+      console.log(`  ${fmt.label('State:')} ${formatState(tx.state)}`);
+      console.log(`  ${fmt.label('Requester:')} ${tx.requester}`);
+      console.log(`  ${fmt.label('Provider:')} ${tx.provider}`);
+      console.log(`  ${fmt.label('Amount:')} ${fmt.value(tx.amount)}`);
+      console.log(`  ${fmt.label('Deadline:')} ${tx.deadline}`);
+      if (tx.escrowId) {
+        console.log(`  ${fmt.label('Escrow ID:')} ${tx.escrowId}`);
+      }
+      if (tx.createdAt) {
+        console.log(`  ${fmt.label('Created:')} ${tx.createdAt}`);
+      }
+    }
+  }
+
+  /**
+   * Print a table of transactions
+   */
+  transactionTable(transactions: TransactionDisplay[]): void {
+    if (this.mode === 'human') {
+      if (transactions.length === 0) {
+        console.log(fmt.dim('  No transactions found.'));
+        return;
+      }
+
+      // Header
+      console.log('');
+      console.log(
+        fmt.bold(
+          '  ID (short)        State           Amount            Provider'
+        )
+      );
+      console.log(fmt.dim('  ' + '-'.repeat(70)));
+
+      // Rows
+      for (const tx of transactions) {
+        const shortId = tx.txId.slice(0, 10) + '...';
+        const stateFormatted = formatState(tx.state).padEnd(20);
+        const amountPadded = tx.amount.padEnd(16);
+        const providerShort = tx.provider.slice(0, 10) + '...';
+
+        console.log(`  ${shortId}  ${stateFormatted}  ${amountPadded}  ${providerShort}`);
+      }
+
+      console.log(fmt.dim('  ' + '-'.repeat(70)));
+      console.log(fmt.dim(`  ${transactions.length} transaction(s)`));
+    }
+  }
+
+  // ==========================================================================
+  // Result Output (Mode-Aware)
+  // ==========================================================================
+
+  /**
+   * Output a result object
+   *
+   * - human mode: Pretty prints with colors
+   * - json mode: Outputs JSON
+   * - quiet mode: Outputs just the primary value (first key or specified)
+   */
+  result(
+    data: Record<string, unknown>,
+    options: { quietKey?: string } = {}
+  ): void {
+    switch (this.mode) {
+      case 'json':
+        console.log(JSON.stringify(data, null, 2));
+        break;
+
+      case 'quiet': {
+        const key = options.quietKey || Object.keys(data)[0];
+        const value = data[key];
+        if (value !== undefined && value !== null) {
+          console.log(String(value));
+        }
+        break;
+      }
+
+      case 'human':
+      default:
+        for (const [key, value] of Object.entries(data)) {
+          this.keyValue(key, value as string | number | boolean);
+        }
+        break;
+    }
+  }
+
+  /**
+   * Output raw value (for quiet mode piping)
+   */
+  raw(value: string): void {
+    console.log(value);
+  }
+
+  // ==========================================================================
+  // Error Output
+  // ==========================================================================
+
+  /**
+   * Output a structured error
+   */
+  errorResult(error: CLIError): void {
+    switch (this.mode) {
+      case 'json':
+        console.error(JSON.stringify({ error }, null, 2));
+        break;
+
+      case 'quiet':
+        console.error(error.message);
+        break;
+
+      case 'human':
+      default:
+        console.error('');
+        console.error(fmt.error(`Error: ${error.message}`));
+        if (error.details) {
+          console.error(fmt.dim(JSON.stringify(error.details, null, 2)));
+        }
+        console.error(fmt.dim(`(code: ${error.code})`));
+        break;
+    }
+  }
+
+  // ==========================================================================
+  // Progress Indicators
+  // ==========================================================================
+
+  /**
+   * Start a spinner (human mode only)
+   *
+   * Returns a stop function to call when done.
+   * No-op in json/quiet modes.
+   */
+  spinner(message: string): { stop: (success?: boolean) => void } {
+    if (this.mode !== 'human') {
+      return { stop: () => {} };
+    }
+
+    const frames = ['|', '/', '-', '\\'];
+    let i = 0;
+
+    process.stdout.write(fmt.cyan(`[${frames[0]}] ${message}`));
+
+    const interval = setInterval(() => {
+      i = (i + 1) % frames.length;
+      process.stdout.write(`\r${fmt.cyan(`[${frames[i]}] ${message}`)}`);
+    }, 100);
+
+    return {
+      stop: (success = true) => {
+        clearInterval(interval);
+        const symbol = success ? fmt.green('[+]') : fmt.red('[!]');
+        process.stdout.write(`\r${symbol} ${message}\n`);
+      },
+    };
+  }
+}
+
+// ============================================================================
+// Global Output Instance
+// ============================================================================
+
+let globalOutput: Output = new Output('human');
+
+/**
+ * Set the global output mode
+ */
+export function setOutputMode(mode: OutputMode): void {
+  globalOutput = new Output(mode);
+}
+
+/**
+ * Get the global output instance
+ */
+export function getOutput(): Output {
+  return globalOutput;
+}
+
+// ============================================================================
+// Exit Codes
+// ============================================================================
+
+/**
+ * Standard exit codes for CLI commands
+ *
+ * Following Unix conventions and extending for ACTP-specific states.
+ */
+export const ExitCode = {
+  SUCCESS: 0,
+  ERROR: 1,
+  PENDING: 2, // Transaction in pending state
+  INVALID_INPUT: 3,
+  NOT_INITIALIZED: 4,
+  NETWORK_ERROR: 5,
+  TIMEOUT: 6,
+} as const;
+
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];

package/src/config/networks.ts

@@ -1,5 +1,20 @@
 import { ethers } from 'ethers';
 
+// ============================================================================
+// SECURITY FIX (C-7): RPC URL Configuration
+// ============================================================================
+// Environment variables take priority over hardcoded defaults.
+// This prevents accidental API key leakage if developers modify this file.
+// Public RPC endpoints are used as fallbacks for ease of use.
+//
+// Set these environment variables to use your own RPC provider:
+//   BASE_SEPOLIA_RPC - Custom RPC for Base Sepolia testnet
+//   BASE_MAINNET_RPC - Custom RPC for Base Mainnet
+// ============================================================================
+
+const BASE_SEPOLIA_RPC_URL = process.env.BASE_SEPOLIA_RPC || 'https://sepolia.base.org';
+const BASE_MAINNET_RPC_URL = process.env.BASE_MAINNET_RPC || 'https://mainnet.base.org';
+
 /**
  * Network configuration
  */
@@ -14,6 +29,7 @@ export interface NetworkConfig {
     usdc: string;
     eas: string; // EAS contract address
     easSchemaRegistry: string; // EAS SchemaRegistry contract
+    agentRegistry?: string; // AIP-7 Agent Registry (optional until deployed)
   };
   eas: {
     deliverySchemaUID: string; // AIP-4 delivery proof schema
@@ -30,16 +46,18 @@ export interface NetworkConfig {
 export const BASE_SEPOLIA: NetworkConfig = {
   name: 'Base Sepolia',
   chainId: 84532,
-  rpcUrl: 'https://sepolia.base.org',
+  rpcUrl: BASE_SEPOLIA_RPC_URL,
   blockExplorer: 'https://sepolia.basescan.org',
   contracts: {
-    // Redeployed 2025-11-25 by Arha (fixed auto-transition in linkEscrow, optimizer-runs 200)
-    actpKernel: '0x6aDB650e185b0ee77981AC5279271f0Fa6CFe7ba',
-    escrowVault: '0x921edE340770db5DB6059B5B866be987d1b7311F',
+    // Redeployed 2025-12-10 by Arha (new deployer wallet 0x42a2f11555b9363fb7ebdcdc76d7cb26e01dcb00)
+    actpKernel: '0xD199070F8e9FB9a127F6Fe730Bc13300B4b3d962',
+    escrowVault: '0x948b9Ea081C4Cec1E112Af2e539224c531d4d585',
     usdc: '0x444b4e1A65949AB2ac75979D5d0166Eb7A248Ccb', // MockUSDC
     // EAS contracts (Base native deployment)
     eas: '0x4200000000000000000000000000000000000021',
-    easSchemaRegistry: '0x4200000000000000000000000000000000000020'
+    easSchemaRegistry: '0x4200000000000000000000000000000000000020',
+    // AIP-7 Agent Registry (deployed 2025-12-11)
+    agentRegistry: '0xFed6914Aa70c0a53E9c7Cc4d2Ae159e4748fb09D'
   },
   eas: {
     // Deployed 2025-11-23 - AIP-4 delivery proof schema
@@ -53,14 +71,18 @@ export const BASE_SEPOLIA: NetworkConfig = {
 
 /**
  * Base Mainnet Configuration
+ *
+ * WARNING: Mainnet contracts are NOT YET DEPLOYED.
+ * Using 'base-mainnet' will throw an error until contracts are deployed.
+ * Use 'base-sepolia' for testnet development.
  */
 export const BASE_MAINNET: NetworkConfig = {
   name: 'Base Mainnet',
   chainId: 8453,
-  rpcUrl: 'https://mainnet.base.org',
+  rpcUrl: BASE_MAINNET_RPC_URL,
   blockExplorer: 'https://basescan.org',
   contracts: {
-    // TODO: Update after mainnet deployment
+    // NOT DEPLOYED: Will throw error via validateNetworkConfig()
     actpKernel: '0x0000000000000000000000000000000000000000',
     escrowVault: '0x0000000000000000000000000000000000000000',
     usdc: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // Official USDC on Base
@@ -69,7 +91,7 @@ export const BASE_MAINNET: NetworkConfig = {
     easSchemaRegistry: '0x4200000000000000000000000000000000000020'
   },
   eas: {
-    // TODO: Deploy delivery schema to mainnet
+    // NOT DEPLOYED: Requires mainnet schema registration
     deliverySchemaUID: '0x0000000000000000000000000000000000000000000000000000000000000000'
   },
   gasSettings: {
@@ -111,7 +133,8 @@ export function getNetwork(network: string): NetworkConfig {
       escrowVault: config.contracts.escrowVault,
       usdc: config.contracts.usdc,
       eas: config.contracts.eas,
-      easSchemaRegistry: config.contracts.easSchemaRegistry
+      easSchemaRegistry: config.contracts.easSchemaRegistry,
+      agentRegistry: config.contracts.agentRegistry
     },
     eas: {
       deliverySchemaUID: config.eas.deliverySchemaUID