@agirails/sdk 2.0.1-beta → 2.0.2

package/src/cli/index.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * ACTP CLI - Agent Commerce Transaction Protocol Command Line Interface
+ *
+ * The ACTP CLI is designed for AI agents - not humans clicking buttons.
+ * Key differentiators:
+ *
+ * 1. **Machine-readable output**: JSON by default for scripting
+ * 2. **Pipe-friendly**: Commands output just what you need
+ * 3. **Structured exit codes**: 0=success, 1=error, 2=pending
+ * 4. **Agent-first features**: watch, simulate, batch
+ *
+ * @module cli
+ * @see https://docs.agirails.io/cli
+ */
+
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+// Read version from package.json (works in both src and dist)
+function getVersion(): string {
+  try {
+    // Try dist location first (when running compiled)
+    const distPath = join(__dirname, '../../package.json');
+    const pkg = JSON.parse(readFileSync(distPath, 'utf-8'));
+    return pkg.version;
+  } catch {
+    try {
+      // Fallback to src location (when running ts-node)
+      const srcPath = join(__dirname, '../../../package.json');
+      const pkg = JSON.parse(readFileSync(srcPath, 'utf-8'));
+      return pkg.version;
+    } catch {
+      return '0.0.0'; // Fallback if package.json not found
+    }
+  }
+}
+
+// Import commands
+import { createInitCommand } from './commands/init';
+import { createPayCommand } from './commands/pay';
+import { createTxCommand } from './commands/tx';
+import { createBalanceCommand } from './commands/balance';
+import { createMintCommand } from './commands/mint';
+import { createConfigCommand } from './commands/config';
+import { createWatchCommand } from './commands/watch';
+import { createSimulateCommand } from './commands/simulate';
+import { createBatchCommand } from './commands/batch';
+import { createTimeCommand } from './commands/time';
+
+// ============================================================================
+// Program Setup
+// ============================================================================
+
+const program = new Command();
+
+program
+  .name('actp')
+  .description(
+    'ACTP CLI - Agent Commerce Transaction Protocol\n\n' +
+      'The payment layer for AI agents. Create escrow-backed transactions,\n' +
+      'track state changes, and settle payments programmatically.\n\n' +
+      'Quick Start:\n' +
+      '  $ actp init                     Initialize in current directory\n' +
+      '  $ actp pay 0xProvider 100       Create a payment\n' +
+      '  $ actp tx status <txId>         Check transaction status\n\n' +
+      'Output Modes:\n' +
+      '  --json     Machine-readable JSON output\n' +
+      '  --quiet    Minimal output (just the essential value)'
+  )
+  .version(getVersion(), '-v, --version', 'Output the version number')
+  .helpOption('-h, --help', 'Display help for command');
+
+// ============================================================================
+// Register Commands
+// ============================================================================
+
+// Core commands (most used)
+program.addCommand(createInitCommand());
+program.addCommand(createPayCommand());
+program.addCommand(createTxCommand());
+program.addCommand(createBalanceCommand());
+program.addCommand(createMintCommand());
+program.addCommand(createConfigCommand());
+
+// Agent-first features
+program.addCommand(createWatchCommand());
+program.addCommand(createSimulateCommand());
+program.addCommand(createBatchCommand());
+
+// Mock mode utilities
+program.addCommand(createTimeCommand());
+
+// ============================================================================
+// Error Handling
+// ============================================================================
+
+// Handle unknown commands
+program.on('command:*', (operands) => {
+  console.error(`Error: Unknown command '${operands[0]}'`);
+  console.error('');
+  console.error('Run "actp --help" for available commands.');
+  process.exit(1);
+});
+
+// ============================================================================
+// Parse & Execute
+// ============================================================================
+
+program.parse(process.argv);
+
+// If no arguments, show help
+if (process.argv.length === 2) {
+  program.outputHelp();
+}

package/src/cli/utils/client.ts

@@ -0,0 +1,249 @@
+/**
+ * SDK Client Factory for CLI
+ *
+ * Creates and manages ACTPClient instances based on CLI configuration.
+ * Handles mode-specific initialization and error mapping.
+ *
+ * SECURITY: Error messages are sanitized to prevent information disclosure.
+ *
+ * @module cli/utils/client
+ */
+
+import * as os from 'os';
+import { ACTPClient, ACTPClientConfig } from '../../ACTPClient';
+import { loadConfig, validateConfigForMode } from './config';
+
+// ============================================================================
+// Security: Path Sanitization
+// ============================================================================
+
+/**
+ * Sanitize a file path for safe display in error messages.
+ *
+ * SECURITY: Replaces home directory with ~ to prevent disclosure of:
+ * - Full home directory paths
+ * - Usernames embedded in paths
+ * - System-specific directory structures
+ *
+ * @param fullPath - The full file path to sanitize
+ * @returns Sanitized path safe for display
+ */
+function sanitizePath(fullPath: string): string {
+  const home = os.homedir();
+  // Replace home directory with ~ to avoid disclosing username/path
+  return fullPath.replace(home, '~');
+}
+
+// ============================================================================
+// Client Factory
+// ============================================================================
+
+/**
+ * Create an ACTPClient instance from CLI configuration
+ *
+ * Reads configuration from .actp/config.json and creates
+ * an appropriate client instance for the configured mode.
+ *
+ * @param projectRoot - Project root directory (defaults to cwd)
+ * @returns Initialized ACTPClient
+ * @throws Error if config invalid or client creation fails
+ */
+export async function createClient(
+  projectRoot: string = process.cwd()
+): Promise<ACTPClient> {
+  // Load configuration
+  const config = loadConfig(projectRoot);
+
+  // Validate config for the mode
+  validateConfigForMode(config);
+
+  // Build client config
+  const clientConfig: ACTPClientConfig = {
+    mode: config.mode,
+    requesterAddress: config.address,
+    stateDirectory: projectRoot,
+  };
+
+  // Create and return client
+  return ACTPClient.create(clientConfig);
+}
+
+// ============================================================================
+// Error Mapping
+// ============================================================================
+
+/**
+ * Error codes for CLI errors
+ */
+export const ErrorCode = {
+  // Configuration errors
+  NOT_INITIALIZED: 'NOT_INITIALIZED',
+  CONFIG_CORRUPTED: 'CONFIG_CORRUPTED',
+  INVALID_CONFIG: 'INVALID_CONFIG',
+
+  // Input validation errors
+  INVALID_ADDRESS: 'INVALID_ADDRESS',
+  INVALID_AMOUNT: 'INVALID_AMOUNT',
+  INVALID_DEADLINE: 'INVALID_DEADLINE',
+  INVALID_TX_ID: 'INVALID_TX_ID',
+
+  // Transaction errors
+  TX_NOT_FOUND: 'TX_NOT_FOUND',
+  INVALID_STATE_TRANSITION: 'INVALID_STATE_TRANSITION',
+  INSUFFICIENT_BALANCE: 'INSUFFICIENT_BALANCE',
+  DEADLINE_PASSED: 'DEADLINE_PASSED',
+  DISPUTE_WINDOW_ACTIVE: 'DISPUTE_WINDOW_ACTIVE',
+
+  // System errors
+  FILE_LOCK_ERROR: 'FILE_LOCK_ERROR',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+} as const;
+
+export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+/**
+ * Structured CLI error with code and details
+ */
+export interface StructuredError {
+  code: ErrorCodeValue;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Map SDK errors to CLI-friendly structured errors.
+ *
+ * SECURITY: Sanitizes paths and stack traces to prevent information disclosure.
+ */
+export function mapError(error: unknown): StructuredError {
+  const err = error as Error;
+  // Sanitize the message to remove full paths
+  const rawMessage = err?.message || String(error);
+  const message = sanitizePath(rawMessage);
+
+  // Configuration errors
+  if (message.includes('not initialized') || message.includes('actp init')) {
+    return {
+      code: ErrorCode.NOT_INITIALIZED,
+      message: 'ACTP not initialized. Run "actp init" first.',
+    };
+  }
+
+  if (message.includes('Config file corrupted')) {
+    return {
+      code: ErrorCode.CONFIG_CORRUPTED,
+      message: 'Configuration file is corrupted.',
+      details: { suggestion: 'Run "actp init --force" to reinitialize.' },
+    };
+  }
+
+  // Transaction errors (from SDK error classes)
+  if (err?.name === 'TransactionNotFoundError' || message.includes('Transaction not found')) {
+    const txIdMatch = message.match(/Transaction not found: (0x[a-fA-F0-9]+)/);
+    return {
+      code: ErrorCode.TX_NOT_FOUND,
+      message: 'Transaction not found.',
+      details: txIdMatch ? { txId: txIdMatch[1] } : undefined,
+    };
+  }
+
+  if (err?.name === 'InvalidStateTransitionError' || message.includes('Invalid state transition')) {
+    return {
+      code: ErrorCode.INVALID_STATE_TRANSITION,
+      message: 'Invalid state transition.',
+      // SECURITY: Don't expose original message which may contain sensitive info
+    };
+  }
+
+  if (err?.name === 'InsufficientBalanceError' || message.includes('Insufficient balance')) {
+    return {
+      code: ErrorCode.INSUFFICIENT_BALANCE,
+      message: 'Insufficient balance for this operation.',
+      // SECURITY: Don't expose balance details
+    };
+  }
+
+  if (err?.name === 'DeadlinePassedError' || message.includes('Deadline passed')) {
+    return {
+      code: ErrorCode.DEADLINE_PASSED,
+      message: 'Transaction deadline has passed.',
+    };
+  }
+
+  if (err?.name === 'DisputeWindowActiveError' || message.includes('Dispute window')) {
+    return {
+      code: ErrorCode.DISPUTE_WINDOW_ACTIVE,
+      message: 'Dispute window is still active.',
+      // SECURITY: Don't expose window timing details
+    };
+  }
+
+  // Validation errors
+  if (err?.name === 'ValidationError') {
+    if (message.includes('address')) {
+      return {
+        code: ErrorCode.INVALID_ADDRESS,
+        message: sanitizePath(message),
+      };
+    }
+    if (message.includes('amount') || message.includes('Amount')) {
+      return {
+        code: ErrorCode.INVALID_AMOUNT,
+        message: sanitizePath(message),
+      };
+    }
+    if (message.includes('deadline') || message.includes('Deadline')) {
+      return {
+        code: ErrorCode.INVALID_DEADLINE,
+        message: sanitizePath(message),
+      };
+    }
+  }
+
+  // Lock errors
+  if (message.includes('lock') || message.includes('ELOCKED')) {
+    return {
+      code: ErrorCode.FILE_LOCK_ERROR,
+      message: 'Could not acquire lock. Another process may be using ACTP.',
+      details: { suggestion: 'Wait a moment and try again.' },
+    };
+  }
+
+  // Default: unknown error
+  // SECURITY: Do NOT include stack traces in production - they reveal internal paths
+  return {
+    code: ErrorCode.UNKNOWN_ERROR,
+    message: sanitizePath(message) || 'An unknown error occurred.',
+    // SECURITY FIX: Stack traces removed to prevent information disclosure
+    // In development mode, errors can be logged separately if needed
+  };
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Validate transaction ID format
+ */
+export function isValidTxId(txId: string): boolean {
+  return /^0x[a-fA-F0-9]{64}$/.test(txId);
+}
+
+/**
+ * Format address for display (truncate middle)
+ */
+export function formatAddress(address: string, length: number = 10): string {
+  if (address.length <= length * 2 + 2) {
+    return address;
+  }
+  return `${address.slice(0, length + 2)}...${address.slice(-length)}`;
+}
+
+/**
+ * Format transaction ID for display (truncate)
+ */
+export function formatTxId(txId: string, length: number = 8): string {
+  return `${txId.slice(0, length + 2)}...`;
+}

package/src/cli/utils/config.ts

@@ -0,0 +1,282 @@
+/**
+ * CLI Configuration Management
+ *
+ * Handles reading/writing CLI configuration stored in .actp/config.json.
+ * Supports mock, testnet, and mainnet modes with mode-specific validation.
+ *
+ * @module cli/utils/config
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * CLI operating mode
+ */
+export type CLIMode = 'mock' | 'testnet' | 'mainnet';
+
+/**
+ * CLI configuration stored in .actp/config.json
+ */
+export interface CLIConfig {
+  /** Operating mode */
+  mode: CLIMode;
+
+  /** User's Ethereum address */
+  address: string;
+
+  /** Optional: Private key for testnet/mainnet mode */
+  privateKey?: string;
+
+  /** Optional: RPC URL override */
+  rpcUrl?: string;
+
+  /** Configuration version for migrations */
+  version: string;
+}
+
+/**
+ * Default configuration values
+ */
+export const CONFIG_DEFAULTS: CLIConfig = {
+  mode: 'mock',
+  address: '',
+  version: '1.0',
+};
+
+// ============================================================================
+// Paths
+// ============================================================================
+
+/**
+ * Get the .actp directory path
+ */
+export function getActpDir(projectRoot: string = process.cwd()): string {
+  return path.join(projectRoot, '.actp');
+}
+
+/**
+ * Get the config.json path
+ */
+export function getConfigPath(projectRoot: string = process.cwd()): string {
+  return path.join(getActpDir(projectRoot), 'config.json');
+}
+
+// ============================================================================
+// Config Operations
+// ============================================================================
+
+/**
+ * Check if ACTP is initialized in the current directory
+ */
+export function isInitialized(projectRoot: string = process.cwd()): boolean {
+  return fs.existsSync(getConfigPath(projectRoot));
+}
+
+/**
+ * Load configuration from disk
+ *
+ * SECURITY: Warns about private key storage in config file.
+ *
+ * @throws Error if config doesn't exist or is corrupted
+ */
+export function loadConfig(projectRoot: string = process.cwd()): CLIConfig {
+  const configPath = getConfigPath(projectRoot);
+
+  if (!fs.existsSync(configPath)) {
+    throw new Error(
+      'ACTP not initialized in this directory.\n' +
+        'Run "actp init" to initialize.'
+    );
+  }
+
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    const config = JSON.parse(raw) as CLIConfig;
+
+    // Validate required fields
+    if (!config.mode) {
+      throw new Error('Config missing required field: mode');
+    }
+    if (!config.address) {
+      throw new Error('Config missing required field: address');
+    }
+
+    // SECURITY FIX (L-2): Warn about private key storage in config file
+    if (config.privateKey) {
+      console.warn('\x1b[33m%s\x1b[0m', 'WARNING: Private key stored in config file.');
+      console.warn('\x1b[33m%s\x1b[0m', '         Consider using ACTP_PRIVATE_KEY environment variable instead.');
+      console.warn('\x1b[33m%s\x1b[0m', '         Run: export ACTP_PRIVATE_KEY=<your-key>');
+    }
+
+    return config;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(
+        `Config file corrupted: ${configPath}\n` +
+          'Delete it manually or run "actp init --force"'
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Save configuration to disk
+ *
+ * Creates .actp directory if it doesn't exist.
+ * Uses atomic write (temp file + rename).
+ */
+export function saveConfig(
+  config: CLIConfig,
+  projectRoot: string = process.cwd()
+): void {
+  const actpDir = getActpDir(projectRoot);
+  const configPath = getConfigPath(projectRoot);
+  const tempPath = `${configPath}.tmp`;
+
+  // Ensure .actp directory exists
+  if (!fs.existsSync(actpDir)) {
+    fs.mkdirSync(actpDir, { recursive: true, mode: 0o755 });
+  }
+
+  try {
+    // Atomic write: write to temp, then rename
+    const json = JSON.stringify(config, null, 2);
+    fs.writeFileSync(tempPath, json, { encoding: 'utf-8', mode: 0o600 }); // Secure permissions
+    fs.renameSync(tempPath, configPath);
+  } catch (error) {
+    // Clean up temp file on error
+    if (fs.existsSync(tempPath)) {
+      try {
+        fs.unlinkSync(tempPath);
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+    throw error;
+  }
+}
+
+/**
+ * Update specific config values
+ *
+ * Loads existing config, merges updates, and saves.
+ */
+export function updateConfig(
+  updates: Partial<CLIConfig>,
+  projectRoot: string = process.cwd()
+): CLIConfig {
+  const config = loadConfig(projectRoot);
+  const updated = { ...config, ...updates };
+  saveConfig(updated, projectRoot);
+  return updated;
+}
+
+/**
+ * Get a specific config value
+ */
+export function getConfigValue<K extends keyof CLIConfig>(
+  key: K,
+  projectRoot: string = process.cwd()
+): CLIConfig[K] {
+  const config = loadConfig(projectRoot);
+  return config[key];
+}
+
+/**
+ * Set a specific config value
+ */
+export function setConfigValue<K extends keyof CLIConfig>(
+  key: K,
+  value: CLIConfig[K],
+  projectRoot: string = process.cwd()
+): void {
+  updateConfig({ [key]: value } as Partial<CLIConfig>, projectRoot);
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Validate Ethereum address format
+ */
+export function validateAddress(address: string): boolean {
+  return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+
+/**
+ * Validate private key format (64 hex chars, optionally with 0x prefix)
+ */
+export function validatePrivateKey(key: string): boolean {
+  // Remove 0x prefix if present
+  const normalized = key.startsWith('0x') ? key.slice(2) : key;
+  return /^[a-fA-F0-9]{64}$/.test(normalized);
+}
+
+/**
+ * Validate config for the specified mode
+ *
+ * @throws Error if config is invalid for the mode
+ */
+export function validateConfigForMode(config: CLIConfig): void {
+  // All modes require a valid address
+  if (!validateAddress(config.address)) {
+    throw new Error(
+      `Invalid address: "${config.address}"\n` +
+        'Expected 0x-prefixed 40-character hex string.'
+    );
+  }
+
+  // Testnet and mainnet require private key
+  if (config.mode !== 'mock') {
+    if (!config.privateKey) {
+      throw new Error(
+        `Private key required for ${config.mode} mode.\n` +
+          'Run: actp config set privateKey <your-private-key>'
+      );
+    }
+
+    if (!validatePrivateKey(config.privateKey)) {
+      throw new Error(
+        'Invalid private key format.\n' +
+          'Expected 64-character hex string (with or without 0x prefix).'
+      );
+    }
+  }
+}
+
+// ============================================================================
+// Gitignore Management
+// ============================================================================
+
+/**
+ * Add .actp to .gitignore if not already present
+ */
+export function addToGitignore(projectRoot: string = process.cwd()): void {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+
+  let content = '';
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, 'utf-8');
+  }
+
+  // Check if .actp is already in gitignore
+  if (content.includes('.actp')) {
+    return;
+  }
+
+  // Add .actp to gitignore
+  const newContent =
+    content +
+    (content.endsWith('\n') ? '' : '\n') +
+    '# ACTP local state (contains mock blockchain state)\n' +
+    '.actp/\n';
+
+  fs.writeFileSync(gitignorePath, newContent, 'utf-8');
+}