devinpearson
diff --git a/‎.biomeignore‎
Lines changed: 3 additions & 0 deletions b/‎.biomeignore‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎.cursor/rules/code-review.mdc‎
Lines changed: 17 additions & 0 deletions b/‎.cursor/rules/code-review.mdc‎
Lines changed: 17 additions & 0 deletions
diff --git a/‎.cursorrules‎
Lines changed: 350 additions & 0 deletions b/‎.cursorrules‎
Lines changed: 350 additions & 0 deletions
@@ -0,0 +1,3 @@
+bin/
+ai-generated.js
+
@@ -0,0 +1,17 @@
+---
+alwaysApply: false
+---
+- name: Senior Professional Reviewer
+  description: |
+    Act as a seasoned staff-level engineer delivering concise, high-signal code reviews.
+    Emphasize security, reliability, performance, and maintainability while aligning feedback
+    with team standards and product goals.
+  guidelines:
+    - Start with a prioritized list of critical findings (blocking issues, regressions, security risks).
+    - Provide actionable remediation steps referencing relevant standards, documentation, or patterns.
+    - Highlight tests to add or adjust, focusing on coverage for edge cases and non-regression.
+    - Summarize low-severity observations separately, framing them as suggestions.
+    - Encourage best practices in collaboration, including clear ownership, reviewer checklists,
+      and follow-up tracking.
+    - Leverage static analysis insights, architectural context, and prior review history to validate
+      the change holistically.
@@ -0,0 +1,350 @@
+# Investec Programmable Banking CLI - Cursor Rules
+
+## Project Technology Stack
+
+### Core Technologies
+- **Node.js**: >=24.0.0 (ESM modules only)
+- **TypeScript**: 5.9.3 with strict mode
+- **Module System**: ESM (ES Modules) - all imports use `.js` extension
+- **CLI Framework**: Commander.js 14.x
+- **Testing**: Vitest 3.x with ESM support
+- **Linting/Formatting**: Biome 2.3.x (replaces ESLint/Prettier)
+- **Build Tool**: TypeScript compiler (tsc)
+
+### Key Dependencies
+- `commander`: CLI framework for command definitions
+- `chalk`: Terminal colors (v5, respects NO_COLOR/FORCE_COLOR)
+- `ora`: Spinner/progress indicators
+- `cli-table3`: Enhanced table formatting
+- `js-yaml`: YAML serialization
+- `@inquirer/prompts`: Interactive prompts (confirm, input, password)
+- `investec-pb-api`: Programmable Banking API client
+- `investec-card-api`: Card API client
+- `programmable-card-code-emulator`: Local code execution emulator
+
+## Project Setup
+
+### Directory Structure
+```
+src/
+  ├── index.ts          # Entry point, command registration, global options
+  ├── utils.ts          # Shared utilities (2500+ lines of helper functions)
+  ├── errors.ts         # CliError class, ExitCode enum, ERROR_CODES
+  ├── cmds/             # Command implementations (30+ commands)
+  │   ├── index.ts      # Command exports
+  │   ├── types.ts      # Shared interfaces (CommonOptions, Credentials, etc.)
+  │   └── *.ts          # Individual command files
+  ├── mock-pb.ts        # Mock Programmable Banking API for testing
+  └── mock-card.ts      # Mock Card API for testing
+
+test/
+  ├── __mocks__/        # Mock implementations (ora, utils, external-editor, etc.)
+  ├── cmds/             # Command tests
+  ├── helpers.ts        # Test helper utilities
+  └── setup.js          # Vitest setup
+
+bin/                    # Compiled output (gitignored, generated)
+templates/              # Project templates (default, petro)
+```
+
+### Build & Development
+- **Build**: `npm run build` → TypeScript compiles `src/` to `bin/`
+- **Source Maps**: Enabled for debugging
+- **Declaration Files**: Generated for library consumers
+- **File Copying**: Templates and assets copied to `bin/` during build
+
+### TypeScript Configuration
+- **Target**: ES2022
+- **Module**: NodeNext (ESM)
+- **Strict Mode**: Enabled with `noUncheckedIndexedAccess` and `noImplicitOverride`
+- **Module Resolution**: NodeNext
+- **Import Extensions**: Must use `.js` for ESM imports (TypeScript requirement)
+
+## Code Patterns & Conventions
+
+### Error Handling Pattern
+```typescript
+// 1. Use CliError for user-facing errors
+throw new CliError(ERROR_CODES.MISSING_CARD_KEY, 'Card key is required');
+
+// 2. Wrap commands with context
+export const myCommand = withCommandContext('my-command', async (options) => {
+  // Command implementation
+});
+
+// 3. Centralized error handling in main()
+catch (error) {
+  handleCliError(error, { verbose: getVerboseMode(true) }, 'command name');
+}
+```
+
+### Command Structure Pattern
+```typescript
+export async function commandName(options: CommonOptions) {
+  // 1. Validate inputs
+  const normalizedPath = await validateFilePath(options.filename, ['.js']);
+  
+  // 2. Initialize API with retry support
+  const api = await initializePbApi(credentials, options);
+  const verbose = getVerboseMode(options.verbose);
+  
+  // 3. Show progress (if not piped)
+  const spinner = createSpinner(!isStdoutPiped(), getSafeText('💳 Processing...'));
+  
+  // 4. Make API calls with retry
+  const result = await withRetry(() => api.someMethod(), { verbose });
+  
+  // 5. Format output
+  formatOutput(result.data, options);
+}
+```
+
+### Utility Functions Usage
+- **Credentials**: `loadCredentialsFile()`, `readCredentialsFile()`, `writeCredentialsFile()`
+- **Profiles**: `getActiveProfile()`, `setActiveProfile()`, `readProfile()`, `deleteProfile()`
+- **Terminal**: `getSafeText()`, `detectTerminalCapabilities()`, `getTerminalDimensions()`
+- **Output**: `formatOutput()`, `printTable()`, `formatFileSize()`
+- **Validation**: `validateAmount()`, `validateAccountId()`, `validateFilePath()`
+- **API**: `initializeApi()`, `initializePbApi()`, `withRetry()`
+- **Security**: `warnAboutSecretUsage()`, `detectSecretUsageFromEnv()`
+- **History**: `logCommandHistory()`, `readCommandHistory()`
+
+### Import Patterns
+```typescript
+// Node.js built-ins (use node: prefix)
+import { promises as fsPromises } from 'node:fs';
+import { homedir } from 'node:os';
+
+// External packages
+import chalk from 'chalk';
+import { Command } from 'commander';
+
+// Internal modules (use .js extension)
+import { CliError, ERROR_CODES } from '../errors.js';
+import { formatOutput, getVerboseMode } from '../utils.js';
+
+// Type-only imports
+import type { CommonOptions, Credentials } from './types.js';
+```
+
+## Testing Patterns
+
+### Mock Setup
+```typescript
+vi.mock('../../src/utils.ts', async () => {
+  const actual = await vi.importActual<typeof import('../../src/utils.ts')>();
+  return {
+    ...actual,
+    initializeApi: vi.fn(),
+    createSpinner: vi.fn(() => ({
+      start: vi.fn(function() { return this; }),
+      stop: vi.fn(),
+      text: '',
+    })),
+  };
+});
+```
+
+### Test Structure
+- Use `describe()` blocks for grouping
+- Use `it()` for individual test cases
+- Mock external dependencies
+- Test both success and error paths
+- Use `expect().toThrow(CliError)` for error testing
+
+## Code Quality Standards
+
+### Biome Configuration
+- **Quote Style**: Single quotes
+- **Semicolons**: Always
+- **Indentation**: 2 spaces
+- **Line Width**: 100 characters
+- **Trailing Commas**: ES5 style
+- **Arrow Parentheses**: Always
+
+### Linting Rules
+- `noExplicitAny`: Error (use `biome-ignore` comments when necessary, e.g., generic function wrappers)
+- `noUnusedVariables`: Error
+- `noUnusedImports`: Auto-fixed
+- Recommended rules enabled
+
+### Code Style Requirements
+1. **JSDoc Comments**: Required for exported functions
+2. **Type Safety**: Avoid `any`, use proper types or `unknown`
+3. **Error Handling**: Always use `CliError` for user-facing errors
+4. **Async/Await**: Prefer over promises
+5. **Terminal Safety**: Use `getSafeText()` for emoji/Unicode text
+6. **Progress Indicators**: Use `createSpinner()` for operations
+7. **Output Formatting**: Use `formatOutput()` for structured data
+
+## Environment-Specific Behavior
+
+### Terminal Detection
+- Automatically detects terminal capabilities (Unicode/emoji support)
+- Falls back to ASCII when terminal doesn't support emojis
+- Respects `TERM`, `NO_COLOR`, `FORCE_COLOR` environment variables
+- Detects piped output (`isStdoutPiped()`) to suppress interactive elements
+
+### Non-Interactive Mode
+- Detects CI/CD environments (GitHub Actions, GitLab CI, etc.)
+- Shows security warnings when secrets are in environment variables
+- Suppresses interactive prompts when appropriate
+
+### Verbose/Debug Mode
+- `--verbose` flag or `DEBUG=1` environment variable
+- Shows detailed API calls, rate limit info, retry attempts
+- Uses `getVerboseMode()` utility to check both sources
+
+## Security Considerations
+
+### Secret Management
+- **Preferred**: Store in credential files (`~/.ipb/.credentials.json` or profiles)
+- **Warning**: Environment variables are detected and warned about
+- **File Permissions**: Credential files use `0o600` (read/write owner only)
+- **Atomic Writes**: `writeFileAtomic()` ensures data integrity
+
+### Input Validation
+- Always validate user inputs (amounts, account IDs, file paths)
+- Use validation utilities: `validateAmount()`, `validateAccountId()`, `validateFilePath()`
+- Provide clear error messages with suggestions
+
+## Command Development Guidelines
+
+### Adding New Commands
+1. Create file in `src/cmds/` following naming convention (`kebab-case.ts`)
+2. Export function following pattern: `export async function commandName(options: Options)`
+3. Add to `src/cmds/index.ts` exports
+4. Register in `src/index.ts` with `.command()`, `.description()`, `.action()`
+5. Add options using `.option()` or `.requiredOption()`
+6. Add tests in `test/cmds/`
+7. Update shell completion scripts if needed
+8. Add to `GENERATED_README.md` (auto-generated via `npm run docs`)
+
+### Command Options
+- Use `CommonOptions` interface for shared options (verbose, json, yaml, output, profile, etc.)
+- Add command-specific options to command's `Options` interface
+- Use `.requiredOption()` for required inputs
+- Provide helpful descriptions and examples
+
+### Output Formatting
+- Support `--json`, `--yaml`, `--output` flags via `formatOutput()`
+- Automatically detect piped output and use JSON format
+- Use `printTable()` for tabular data (with `cli-table3`)
+- Show file sizes in progress indicators using `formatFileSize()`
+
+### Destructive Operations
+- Require confirmation using `confirmDestructiveOperation()`
+- Support `--yes` flag to bypass confirmation
+- Check for non-interactive mode to auto-confirm when appropriate
+
+## File Operations
+
+### File Path Handling
+- Use `validateFilePath()` for reading files
+- Use `validateFilePathForWrite()` for writing files
+- Use `normalizeFilePath()` to expand `~` and resolve paths
+- Check file extensions and permissions
+
+### Atomic Operations
+- Use `writeFileAtomic()` for credential files and critical data
+- Ensures data integrity with temp file + rename pattern
+- Handles permissions and cleanup automatically
+
+## API Integration
+
+### API Client Initialization
+- Use `initializeApi()` for Card API
+- Use `initializePbApi()` for Programmable Banking API
+- Both support credential overrides via options
+- Both validate credentials before initialization
+
+### Rate Limiting
+- All API calls wrapped in `withRetry()` for automatic retry
+- Exponential backoff with jitter
+- Detects rate limits from error responses
+- Shows rate limit info in verbose mode
+
+### Error Handling
+- API errors caught and converted to `CliError` when appropriate
+- Rate limit errors automatically retried
+- Network errors provide actionable suggestions
+- Validation errors show specific field requirements
+
+## Testing Guidelines
+
+### Test File Structure
+- One test file per command in `test/cmds/`
+- Mock external dependencies (API clients, file system, etc.)
+- Test both success and error cases
+- Use `vi.hoisted()` for shared mocks
+
+### Mock Patterns
+- Mock `../../src/utils.ts` with actual implementations + overrides
+- Mock `../../src/index.ts` for credentials and shared exports
+- Mock file system operations
+- Mock terminal capabilities for consistent output
+
+## Common Utilities Reference
+
+### Credential Management
+- `loadCredentialsFile()`: Load credentials with profile support
+- `readCredentialsFile()`: Read credentials file async
+- `readCredentialsFileSync()`: Read credentials file sync (module init)
+- `writeCredentialsFile()`: Write credentials with atomic operation
+- `validateCredentialsFile()`: Validate required fields
+
+### Profile Management
+- `getActiveProfile()`: Get currently active profile name
+- `setActiveProfile()`: Set active profile (atomic write)
+- `readProfile()`: Read profile credentials
+- `deleteProfile()`: Delete profile and credentials
+- `listProfiles()`: List all available profiles
+
+### Terminal & Output
+- `getSafeText()`: Get terminal-safe text (emoji fallbacks)
+- `formatOutput()`: Format data as JSON/YAML/table
+- `printTable()`: Print formatted table using cli-table3
+- `createSpinner()`: Create progress spinner (auto-handles pipe mode)
+- `formatFileSize()`: Format bytes as human-readable size
+
+### Validation
+- `validateAmount()`: Validate monetary amounts
+- `validateAccountId()`: Validate account ID format
+- `validateFilePath()`: Validate file path for reading
+- `validateFilePathForWrite()`: Validate file path for writing
+
+### API & Retry
+- `initializeApi()`: Initialize Card API client
+- `initializePbApi()`: Initialize Programmable Banking API client
+- `withRetry()`: Wrap function with retry logic (rate limit handling)
+- `detectRateLimit()`: Detect rate limit from error
+- `formatRateLimitInfo()`: Format rate limit info for display
+
+### Security & Environment
+- `warnAboutSecretUsage()`: Warn about secrets in environment variables
+- `detectSecretUsageFromEnv()`: Detect secrets loaded from env vars
+- `isNonInteractiveEnvironment()`: Detect CI/CD/script environments
+- `getVerboseMode()`: Get effective verbose mode (flag or DEBUG env)
+
+## Important Notes
+
+1. **ESM Only**: All imports must use `.js` extension (TypeScript requirement for ESM)
+2. **Type Safety**: Strict TypeScript with `noUncheckedIndexedAccess`
+3. **Terminal Safety**: Always use `getSafeText()` for emoji/Unicode output
+4. **Error Context**: Use `withCommandContext()` to attach command names to errors
+5. **Rate Limiting**: Always use `withRetry()` for API calls
+6. **Security**: Prefer credential files over environment variables for secrets
+7. **Testing**: Mock terminal capabilities for consistent test output
+8. **Documentation**: Generate docs with `npm run docs` (updates GENERATED_README.md)
+
+## When Writing Code
+
+- Follow existing patterns in the codebase
+- Use provided utility functions instead of reinventing
+- Check for terminal capabilities before using advanced features
+- Support both interactive and non-interactive (CI/CD) environments
+- Provide clear, actionable error messages
+- Include JSDoc comments for exported functions
+- Write tests for new commands
+- Run `npm run lint:fix` before committing
+