[Phase 1.4] CLI Framework & Interface (Days 4-7)

[mfittko]

💻 CLI Framework & Interface (Days 4-7)

Component: Command Line Interface | User-Facing: Primary interaction method
Parent Issue: #2 | Timeline: Days 4-7 of Phase 1

🎯 Objective

Create comprehensive command-line interface using Commander.js with workflow execution, validation, and MCP server modes.

📋 Tasks

4.1 CLI Command Structure

• 4.1.1 Set up Commander.js with TypeScript

  • Configure Commander.js with proper TypeScript types
  • Set up command structure and global options
  • Add proper help text and version information
  • Configure argument parsing and validation

• 4.1.2 Implement run command with comprehensive options

  • agents-cli run --config <file> --input <text>
  • File input options (--files, --context)
  • Output options (--output, --format json|text)
  • Execution options (--timeout, --max-turns)

• 4.1.3 Implement validate command for configuration testing

  • agents-cli validate --config <file>
  • Schema validation with detailed error reporting
  • Configuration merge and override testing
  • Dry-run mode for workflow validation

• 4.1.4 Implement serve command for MCP server mode

  • agents-cli serve --port <port> --config <file>
  • Server startup and shutdown handling
  • Configuration hot-reloading
  • Connection status and monitoring

4.2 Command Handlers

• 4.2.1 Create RunWorkflowCommand with full workflow execution

  • Configuration loading and validation
  • Agent initialization and workflow setup
  • Execution with progress reporting
  • Results collection and formatting

• 4.2.2 Create ValidateCommand with detailed validation feedback

  • Schema validation with clear error messages
  • Configuration completeness checking
  • Warning detection for potential issues
  • Success confirmation with summary

• 4.2.3 Create ServeCommand for MCP server startup

  • Server initialization and configuration
  • Health check endpoints
  • Graceful shutdown handling
  • Connection monitoring and logging

• 4.2.4 Add global error handling with appropriate exit codes

  • Standardized error codes for different failure types
  • User-friendly error messages
  • Debug mode with detailed stack traces
  • Logging integration with different levels

4.3 Output Formatting

• 4.3.1 Create console formatter with Chalk for colored output

  • Colored success/error/warning messages
  • Progress indicators and spinners
  • Structured table output for results
  • Interactive prompts for user input

• 4.3.2 Implement structured JSON output writer

  • Machine-readable JSON output mode
  • Consistent schema for all output types
  • Error reporting in structured format
  • Metadata inclusion (timestamps, versions)

• 4.3.3 Add streaming progress indicators

  • Real-time progress for long-running operations
  • Agent handoff visualization
  • Tool execution status updates
  • Cancellation support (Ctrl+C handling)

• 4.3.4 Create results summary formatter

  • Executive summary of workflow results
  • Agent contributions and handoffs
  • Tool usage statistics
  • Performance metrics (execution time, etc.)

✅ Definition of Done

• agents-cli --help shows clear usage information
• agents-cli run --config example.json executes successfully
• agents-cli validate --config example.json provides clear feedback
• agents-cli serve --port 3000 starts MCP server
• Error messages are user-friendly and actionable
• JSON output mode works for automation
• Progress indicators work for long operations
• Exit codes are appropriate for different scenarios

🔗 Dependencies

• Requires: Project Setup ([Phase 1.1] Project Setup & Infrastructure (Days 1-2) #3) and Schema Design ([Phase 1.2] Schema Design & Validation (Days 3-5) #4)
• Integrates: MCP Server ([Phase 1.3] MCP Server Basic Implementation (Days 6-9) #5) and OpenAI SDK integration

📚 References

• Commander.js Documentation
• Chalk Color Library
• CLI Best Practices

Note: This CLI is the primary user interface and must be intuitive and robust.