fr3kc0d3/DEVELOPMENT.md

Personal AI Infrastructure (PAI) - Complete implementation of Daniel Miessler's PAI vision with 4-layer context enforcement, FOBs system, flow orchestration, and Kai digital assistant

# DEVELOPMENT.md

This file provides development guidance for the fr3kc0de groq-cli project.

## Project Overview

fr3kc0de is a powerful multi-provider AI CLI built on groq-cli architecture that integrates multiple AI providers (Groq, OpenRouter, DeepSeek) with extensible MCP (Model Context Protocol) server capabilities for enhanced AI agent workflows. The system features specialized tools across multiple modules, comprehensive NLP routing, and agentic AI capabilities.

**Key Technologies**: TypeScript, Node.js, React (Ink), MCP (Model Context Protocol), Multi-AI providers (Groq, OpenRouter, DeepSeek), n8n Workflow Automation, SuperCode Integration

**Latest Updates**: ✅ Multi-provider integration, ✅ MCP tools fully operational, ✅ `/howto` command for setup guidance, ✅ Clean groq-cli architecture

## Build, Test, and Development Commands

```bash
# Build the project
npm run build

# Development with file watching  
npm run dev

# Run tests
npm run test
npm run test:watch
npm run test:verbose

# Global testing (tests the CLI binary)
npm run test-global

# Setup for first-time users
npm run setup
```

## Project Architecture

### High-Level Structure

```
fr3kc0de CLI
├── Multi-Provider AI Engine (src/core/ai-client.ts)
│   ├── Groq Integration (ultra-fast inference)
│   ├── OpenRouter Integration (Claude, GPT-4, Gemini access)
│   └── DeepSeek Integration (specialized reasoning)
├── Unified MCP Server (mcp-servers/fr3kc0de-unified.js)
│   ├── Intelligence Module (AI routing, multi-expert systems)
│   ├── Data Module (real-time streams, anomaly detection)
│   ├── Adaptive Module (ML pattern recognition)
│   ├── Memory Module (persistent storage, recall)
│   ├── Prompt Module (template management)
│   └── N8N Automation Module (workflow automation, SuperCode)
└── CLI Interface (src/core/cli.ts + React Ink UI)
    ├── Interactive Chat Mode
    ├── Single Prompt Mode (-p flag)
    └── Command System with NLP parsing
```

### Key Components

- **CLI Entry Point**: `bin/fr3kc0de` → `src/core/cli.ts`
- **Agent System**: `src/core/agent.ts` - Main AI interaction logic
- **MCP Integration**: `src/core/mcp-client.ts` - Connects to unified MCP server
- **Multi-Provider Config**: `src/utils/multi-provider-config.ts` - AI provider management
- **UI Framework**: React Ink components in `src/ui/`
- **Tool Definitions**: `src/tools/` - MCP tool schemas and implementations

### MCP Server Architecture

The project uses a **unified MCP server** (`mcp-servers/fr3kc0de-unified.js`) that consolidates AI tools into a single process for better performance and reliability.

**Tool Categories**:
- **intel_***: AI methodology routing (BMAD, AutoExpert, Synapse, DSPy) (5+ tools)
- **data_***: Real-time streams, anomaly detection (4+ tools)
- **adapt_***: Machine learning, behavioral analysis (5+ tools)
- **memory_***: Storage, recall, reflection, consolidation (6+ tools)
- **prompt_***: Template creation and management (3+ tools)
- **n8n_***: Workflow creation, deployment, SuperCode integration (7+ tools)

### Configuration System

**Provider Configuration**: `~/.cliv2/providers.json`
```json
{
  "defaultProvider": "groq",
  "providers": {
    "groq": { "apiKey": "...", "currentModel": "llama-3.3-70b-versatile" },
    "openrouter": { "apiKey": "...", "currentModel": "anthropic/claude-3.5-sonnet" },
    "deepseek": { "apiKey": "...", "currentModel": "deepseek-chat" }
  }
}
```

**Setup Files**: 
- Setup script: `scripts/setup.js`
- Post-install: `scripts/postinstall.js`
- Setup completion flag: `~/.cliv2/.setup_complete`

## Common Development Patterns

### Adding New MCP Tools

1. Define tool in appropriate module under `mcp-servers/modules/`
2. Add tool schema to the module's index.js
3. Register tool in `fr3kc0de-unified.js` 
4. Update tool count in documentation

### AI Provider Integration

The system uses a multi-provider pattern with automatic failover:
- Primary provider configuration in `MultiProviderConfigManager`
- Dynamic provider switching during conversation
- API key rotation support for rate limit handling

### Testing MCP Tools

```bash
# Test individual tools
node mcp-servers/fr3kc0de-unified.js -p trading_calculate_rsi

# Test tool modules  
node mcp-servers/fr3kc0de-unified.js -m trading

# List all available tools
node mcp-servers/fr3kc0de-unified.js -l

# Single prompt mode for testing
./bin/fr3kc0de -p "analyze BTC using RSI"
```

### React Ink UI Development

The CLI uses React Ink for the interactive interface:
- Main app component: `src/ui/App.tsx`
- Core components: `src/ui/components/core/`
- Display components: `src/ui/components/display/`
- Input overlays: `src/ui/components/input-overlays/`

## Key File Locations

- **Main CLI**: `src/core/cli.ts` 
- **Agent Logic**: `src/core/agent.ts`
- **MCP Client**: `src/core/mcp-client.ts`
- **Provider Config**: `src/utils/multi-provider-config.ts`
- **Unified MCP Server**: `mcp-servers/fr3kc0de-unified.js`
- **Tool Modules**: `mcp-servers/modules/*/index.js`
- **Global Binary**: `bin/fr3kc0de`
- **N8N Command**: `src/commands/definitions/n8n.ts`
- **N8N Module**: `mcp-servers/modules/n8n/index.js`
- **N8N Prompts**: `src/prompts/n8n-workflow-generation.ts`
- **N8N Builder**: `src/core/n8n-builder.ts`
- **N8N Validator**: `src/utils/n8n-validator.ts`

## N8N Workflow Automation Integration

### N8N Module Overview

The n8n integration provides comprehensive workflow automation capabilities:

**Core Features**:
- **Workflow Creation**: Generate n8n workflows from natural language prompts
- **SuperCode Integration**: Custom JavaScript execution using @kenkaiii/n8n-nodes-supercode.superCodeNodeVmSafe
- **Smart Alert Systems**: Pre-built crypto alert workflow templates
- **API Orchestration**: Complex multi-step API workflows
- **Real-time Monitoring**: Live workflow execution tracking
- **Configuration Management**: Environment-specific deployments

**Available N8N Tools** (7 total):
1. `n8n_n8n_create_workflow` - Create workflows from natural language
2. `n8n_n8n_validate_workflow` - Validate n8n workflow JSON structure
3. `n8n_n8n_deploy_workflow` - Deploy workflows to n8n instances
4. `n8n_n8n_generate_supercode` - Generate SuperCode node scripts
5. `n8n_n8n_list_workflows` - List and manage existing workflows
6. `n8n_n8n_configure_instance` - Configure n8n instance settings
7. `n8n_n8n_create_alert_system` - Create smart crypto alert systems

### N8N Command Usage

```bash
# Create workflow from prompt
fr3kc0de /n8n create "Smart BTC price alert with RSI analysis"

# Deploy to n8n instance  
fr3kc0de /n8n deploy --workflow-id "crypto-alerts" --instance "production"

# List existing workflows
fr3kc0de /n8n list

# Configure n8n instance
fr3kc0de /n8n config --url "https://n8n.myserver.com" --auth "token:abc123"
```

### SuperCode Integration

The system integrates with the SuperCode n8n node (@kenkaiii/n8n-nodes-supercode.superCodeNodeVmSafe) for:
- **Custom JavaScript Execution**: Run complex analysis scripts within workflows
- **Crypto Analysis Functions**: Built-in technical analysis libraries
- **API Integration**: Connect to exchanges and data providers
- **Real-time Processing**: Process streaming data within n8n workflows

### Workflow Templates

Pre-built templates available:
- **Smart Crypto Alerts**: Price threshold alerts with technical analysis
- **Arbitrage Detection**: Multi-exchange price monitoring
- **Technical Analysis Automation**: RSI, MACD, Bollinger Bands workflows
- **Portfolio Monitoring**: Real-time portfolio tracking and alerts
- **Market Data Aggregation**: Multi-source data consolidation workflows

### Natural Language Processing

The system includes enhanced NLP for n8n workflow creation:
- **Intent Recognition**: Automatically detect n8n workflow automation intents
- **Workflow Pattern Matching**: Identify common workflow patterns from prompts
- **SuperCode Generation**: Generate JavaScript code from natural language
- **Configuration Inference**: Auto-configure workflow settings from context

## Development Notes

- The project migrated from multiple MCP servers to a single unified server for better performance
- Build output goes to `dist/` directory
- TypeScript configuration supports ES modules
- Testing uses AVA framework with TypeScript support
- The system supports both installed (npm) and development (tsx) execution modes
- Configuration automatically migrates from older Groq-only setups to multi-provider format
- **N8N Integration**: Full workflow automation with SuperCode node support
- **Enhanced NLP**: Added n8n workflow automation intent patterns
- **Template System**: Pre-built workflow templates for common crypto use cases

## Recent Updates and Fixes

### ✅ Pattern Precedence Issue Resolved
- **Fixed**: Sacred geometry analysis routing issue where "sacred geometry analysis Bitcoin" was routing to general analysis
- **Solution**: Moved cosmic patterns to higher priority (95% confidence) in NLP intent patterns
- **Result**: Sacred geometry now routes correctly to `cosmic_sacred_geometry` tool

### ✅ N8N Tools Integration Completed
- **Fixed**: N8N tools were not accessible from CLI due to missing tool mappings and routing handlers
- **Solution**: Added N8N tool mappings to `src/tools/tools.ts` and `case 'n8n':` handler to NLP routing
- **Available Tools**: n8n_list_workflows, n8n_create_workflow, n8n_validate_workflow, n8n_deploy_workflow, n8n_generate_supercode, n8n_test_workflow, n8n_check_status

### ✅ New `/howto` Command for Non-Technical Users
- **Added**: Comprehensive setup and configuration guides
- **Available Topics**:
  - `/howto setup` - Complete installation and first-run guide
  - `/howto providers` - API key setup for Groq, OpenRouter, DeepSeek with step-by-step instructions
  - `/howto n8n` - N8N automation setup with Docker/NPM installation guides
  - `/howto trading` - All trading commands, patterns, and features
  - `/howto cosmic` - Cosmic intelligence features and usage guide

### 🔧 N8N Configuration System
- **Existing**: Comprehensive N8N configuration already implemented
- **Commands**: `/n8n config`, `/n8n config baseUrl`, `/n8n config apiKey`, `/n8n config enabled true`
- **Features**: Health checking, deployment, validation, SuperCode generation

## Special Considerations

- **Security**: API keys stored in `~/.cliv2/` with proper file permissions
- **Performance**: Tool calls have sub-millisecond response times via unified MCP server  
- **Reliability**: Built-in failover between AI providers and automatic error recovery
- **Testing**: Comprehensive test suite covers individual tools, modules, and full system integration
- **N8N Security**: SuperCode execution uses safe VM sandbox for JavaScript execution
- **Workflow Validation**: All n8n workflows validated before deployment
- **Configuration Management**: Environment-specific n8n instance configurations
- **Template Security**: Pre-built templates follow security best practices
- **NLP Routing**: Enhanced pattern matching with 85-95% confidence across all major intents