@agirails/sdk 2.0.0 → 2.0.1-beta

package/src/cli/index.ts

@@ -1,116 +0,0 @@
-#!/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

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

@@ -1,282 +0,0 @@
-/**
- * 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');
-}