codeflow-hook 1.3.0 → 2.0.0

package/README.md

@@ -1,116 +1,48 @@
 # Codeflow Commander — Nexus Gateway CLI
 
-**The Command-Line Interface for the Autonomous Engineering Platform**
+**AI-Powered Code Analysis and Git Hook Management**
 
-Your gateway to the Codeflow Commander Nexus Gateway — a comprehensive AI-driven engineering ecosystem that spans the entire software development lifecycle. This CLI tool serves as the entry point to enterprise-wide autonomous engineering capabilities, from intelligent code analysis to organization-scale workflow automation.
+A lightweight command-line tool that provides AI-driven code analysis, automated git hook installation, and intelligent code review capabilities. This CLI client analyzes your local code changes using advanced AI models and helps maintain code quality through automated pre-commit and pre-push checks.
 
-This is the universal command-line client for interacting with the **Phase 4 Autonomous Engineering Platform**, featuring next-generation components including the Enterprise Knowledge Graph (EKG), Autonomous Agent Network (AAN), Multi-Modal Interface Layer (MMIL), and Predictive Intelligence Engine (PIE).
+**⚠️ Important**: This is the **client-side CLI tool** only. Enterprise features like the Enterprise Knowledge Graph (EKG), Autonomous Agent Network (AAN), and ingestion services are part of the broader Codeflow Commander platform and require separate enterprise deployment.
 
-## 🚀 Key Capabilities
+## 🚀 What This CLI Tool Provides
 
-### **Enterprise Knowledge Graph (EKG)**
-- **Cross-Repository Intelligence**: Unified knowledge across all organizational repositories
-- **Semantic Dependency Mapping**: Understand organizational code relationships and patterns
-- **Expert Discovery**: Identify domain experts through code analysis patterns
-- **Supply Chain Intelligence**: Vulnerability tracking and license compliance across repositories
+### **AI-Powered Code Analysis**
+- **Local Code Diff Analysis**: Analyze git diffs using Gemini, OpenAI GPT, or Claude AI models
+- **Quality Assessment**: Get 1-10 quality ratings with detailed feedback on code changes
+- **Security Detection**: Identify potential security vulnerabilities in code changes
+- **Performance Insights**: Receive suggestions for performance optimizations
 
-### **Autonomous Agent Network (AAN)**
-- **Workflow Automation**: Transform JIRA tickets into validated pull requests automatically
-- **Self-Healing Operations**: Monitor, detect, diagnose, and fix production issues autonomously
-- **Predictive Maintenance**: Scheduled optimization tasks and dependency updates
-- **Multi-Agent Coordination**: Intelligent conflict resolution and approval workflows
+### **Git Hook Automation**
+- **Pre-commit Hooks**: Automatic analysis of staged changes before commits
+- **Pre-push Hooks**: Comprehensive code review simulation before pushing to remote
+- **Quality Gates**: Prevent problematic commits and pushes based on AI analysis
+- **Customizable Thresholds**: Configure when to block commits based on quality scores
 
-### **Multi-Modal Interface Layer (MMIL)**
-- **Conversational Code Generation**: Natural language → complex refactorings and implementations
-- **Design-to-Code Pipeline**: Figma designs to validated production code
-- **IDE Ecosystem Integration**: Native support across VSCode, IntelliJ, Vim, and more
-- **API-First Architecture**: REST APIs for all platform capabilities
+### **Local Knowledge Base (RAG)**
+- **Project Context Indexing**: Build searchable knowledge base from your project files
+- **Context-Aware Analysis**: AI analysis considers your project's documentation and code patterns
+- **Offline Capability**: Works without internet for local analysis (with indexed knowledge)
+- **Incremental Updates**: Automatically update knowledge base as project evolves
 
-### **Predictive Intelligence Engine (PIE)**
-- **Tech Debt Forecasting**: Predict maintenance hotspots and cost estimates
-- **Performance Prediction**: Identify regressions before deployment
-- **Engineering Analytics**: Data-driven process optimization and insights
-- **Risk Assessment**: Proactive security and compliance monitoring
+### **Multi-Provider AI Support**
+- **Google Gemini**: Default AI provider with latest models (1.5 Pro, 1.5 Flash, Pro)
+- **OpenAI GPT**: Support for GPT-4, GPT-4 Turbo, GPT-3.5 Turbo
+- **Anthropic Claude**: Integration with Claude 3 Opus, Sonnet, and Haiku
+- **Custom Endpoints**: Connect to self-hosted or custom AI model endpoints
 
-### **Governance Safety Framework (GSF)**
-- **Autonomous Permissions**: Dynamic access control based on context and risk
-- **Real-time Compliance**: Continuous regulatory and policy validation
-- **Emergency Controls**: System-wide safety mechanisms and overrides
-- **Human-in-the-Loop**: Graduated approval workflows for different risk levels
+## 📦 How It Works
 
-### **Distributed Execution Engine (DEE)**
-- **Repository Federation**: Coordinate operations across multiple repositories
-- **Workflow Orchestration**: Complex process execution with dependency management
-- **State Synchronization**: Federated data consistency across the enterprise
-- **Resource Optimization**: Intelligent load balancing and execution management
+The CLI tool operates entirely on your local machine and analyzes your code changes using AI. Here's the workflow:
 
-## 🏗️ Architecture Overview
+1. **Local Analysis**: When you run analysis, the tool captures your git diff locally
+2. **AI Processing**: Sends the diff to your configured AI provider (Gemini/OpenAI/Claude)
+3. **Context Enhancement**: Optionally includes your project's indexed knowledge for better analysis
+4. **Feedback Generation**: Returns quality scores, issues, and recommendations
+5. **Hook Integration**: Automatically runs during git operations to maintain code quality
 
-The CLI serves as your interface to the Codeflow Commander Nexus Gateway — a distributed, autonomous engineering platform designed for enterprise-scale operation.
-
-```
-┌─────────────────────────────────────────────────────────┐
-│               MULTI-MODAL INTERFACE LAYER (MMIL)      │
-│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
-│  │ Conversational  │ │ Design→Code     │ │  IDE        │ │
-│  │ Interfaces      │ │ Pipeline        │ │ Integrations│ │
-│  └─────────────────┘ └─────────────────┘ └─────────────┘ │
-└─────────────────────────────────────────────────────────┘
-                                   │
-                                   ▼
-┌─────────────────────────────────────────────────────────┐
-│         AUTONOMOUS AGENT NETWORK (AAN) - ORCHESTRATOR  │
-│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
-│  │ Workflow Agents │ │ Maintenance     │ │ Self-Heal   │ │
-│  │                 │ │ Bots            │ │ Agents      │ │
-│  └─────────────────┘ └─────────────────┘ └─────────────┘ │
-└─────────────────────────────────────────────────────────┘
-                                   │
-                                   ▼
-┌─────────────────────────────────────────────────────────┐
-│      GOVERNANCE & SAFETY FRAMEWORK - RISK CONTROL      │
-│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
-│  │ Permission      │ │ Audit &        │ │ Emergency    │ │
-│  │ Engine          │ │ Compliance      │ │ Controls    │ │
-│  └─────────────────┘ └─────────────────┘ └─────────────┘ │
-└─────────────────────────────────────────────────────────┘
-                                   │
-                                   ▼
-┌─────────────────────────────────────────────────────────┐
-│     ENTERPRISE KNOWLEDGE GRAPH (EKG) - INTELLIGENCE    │
-│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
-│  │ Cross-Repo      │ │ Semantic        │ │ Expert      │ │
-│  │ Dependencies    │ │ Mapping         │ │ Discovery   │ │
-│  └─────────────────┘ └─────────────────┘ └─────────────┘ │
-└─────────────────────────────────────────────────────────┘
-                                   │
-                                   ▼
-┌─────────────────────────────────────────────────────────┐
-│  PREDICTIVE INTELLIGENCE ENGINE (PIE) - FORECASTING    │
-│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
-│  │ Tech Debt       │ │ Performance     │ │ Risk        │ │
-│  │ Forecasting     │ │ Prediction      │ │ Analytics   │ │
-│  └─────────────────┘ └─────────────────┘ └─────────────┘ │
-└─────────────────────────────────────────────────────────┘
-                                   │
-                                   ▼
-┌─────────────────────────────────────────────────────────┐
-│      DISTRIBUTED EXECUTION ENGINE (DEE) - RUNTIME      │
-│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
-│  │ Repository      │ │ Workflow        │ │ State       │ │
-│  │ Federation      │ │ Orchestration   │ │ Sync        │ │
-│  └─────────────────┘ └─────────────────┘ └─────────────┘ │
-└─────────────────────────────────────────────────────────┘
-                                   │
-                                   ▼
-┌─────────────────────────────────────────────────────────┐
-│         EXTERNAL SYSTEMS INTEGRATION                    │
-│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐       │
-│  │GitHub│ │GitLab│ │JIRA │ │Slack│ │Jenkins│     │
-│  │Actions│ │     │ │     │ │     │ │       │     │
-│  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘       │
-└─────────────────────────────────────────────────────────┘
-```
+**No data is sent to external servers** except for AI API calls to your configured provider. Your code stays on your machine.
 
 ## 📦 Installation
 
@@ -269,33 +201,117 @@ codeflow-hook analyze-diff --help # Analysis options
 - Best practice recommendations
 - Maintainability evaluation
 
-## 🔬 Enterprise Technology Stack
+## 💡 Usage Examples
+
+### Standard Development Workflow
+
+```bash
+# Stage your changes
+git add .
+
+# Pre-commit hook automatically runs AI analysis
+git commit -m "feat: add new authentication"
+
+# Pre-push hook runs tests and full AI review
+git push origin main
+```
+
+### Manual Analysis
+
+```bash
+# Analyze uncommitted changes
+git diff | codeflow-hook analyze-diff
+
+# Analyze specific files
+git diff path/to/file.js | codeflow-hook analyze-diff
+
+# Analyze between commits
+git diff HEAD~1 HEAD | codeflow-hook analyze-diff
+```
+
+## 🎯 AI Analysis Output
+
+The tool provides:
+
+- **Rating**: 1-10 quality score with color coding
+- **Summary**: Brief assessment of changes
+- **Issues**: Specific problems with solutions
+- **Recommendations**: Improvement suggestions
+
+Example output:
+```
+⭐ **Rating:** 9/10
+📝 **Summary:** Clean implementation with good separation of concerns
+
+⚠️ **Issues:**
+- Consider adding input validation for edge cases
 
-### **Multi-Modal AI Integration**
-The Nexus Gateway integrates multiple AI modalities for comprehensive engineering intelligence:
+💡 **Recommendations:**
+- Add comprehensive error handling
+- Consider extracting common logic to a utility function
+```
 
-**🤖 Conversational Interface Layer**: Natural language processing for requirement analysis and complex code generation
-**🎨 Design-to-Code Pipeline**: Computer vision and ML models for design artifact ingestion
-**📊 Predictive Analytics Engine**: Time-series analysis and machine learning for trend forecasting
-**🔍 Semantic Code Analysis**: Advanced NLP for code understanding and pattern recognition
+## 🔧 Configuration
 
-### **Autonomous Agent Architecture**
-The core platform intelligence is delivered through specialized agent networks:
+Configuration is stored in `~/.codeflow-hook/config.json`:
 
-**🎯 Workflow Execution Agents**:
-- Ticket-to-PR automation with full engineering lifecycle management
-- Self-healing operations with automated issue detection and remediation
-- Dependency management with intelligent version conflict resolution
+```json
+{
+  "provider": "gemini",
+  "apiKey": "your-api-key",
+  "apiUrl": "https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent",
+  "model": "gemini-pro"
+}
+```
+
+### Supported AI Providers
 
-**🔬 Observational Intelligence Agents**:
-- Predictive maintenance scheduling based on code analysis patterns
-- Performance regression detection using historical benchmarking
-- Risk assessment with real-time compliance monitoring
+- **Gemini**: `provider: "gemini"` - Default, uses Google AI
+- **OpenAI**: `provider: "openai"` - GPT models
+- **Claude**: `provider: "claude"` - Anthropic models
+
+Each provider has optimized prompts and supports custom endpoints.
 
-**🤝 Collaborative Learning Agents**:
-- Cross-repository knowledge synthesis and pattern mining
-- Expert identification through contribution analysis
-- Team productivity optimization through workflow analysis
+## 📋 Requirements
+
+- Node.js 16+
+- Git repository
+- Gemini API key
+
+##  Security
+
+- API keys stored locally (not in your repo)
+- Have to make an .env file for the credentials
+- No data sent to third parties except Google Gemini
+- Code diffs analyzed locally before sending
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**"No configuration found"**
+```bash
+codeflow-hook config -k YOUR_API_KEY
+```
+
+**Hooks not running**
+```bash
+- **Design Pattern Compliance**: Validation against organizational architectural standards
+- **Coupling Analysis**: Detection of tight coupling and circular dependencies
+- **Layer Architecture**: Enforcement of proper separation between presentation, business logic, and data layers
+- **Complexity Assessment**: Monitoring of code complexity and maintainability metrics
+
+**⚡ Performance Agent**:
+- **Algorithm Analysis**: Detection of inefficient algorithms and time/space complexity issues
+- **Memory Optimization**: Identification of memory leaks and inefficient data structures
+- **I/O Optimization**: Analysis of database queries, file operations, and network calls
+- **Caching Opportunities**: Recommendations for implementing caching strategies
+
+**✨ Quality Agent**:
+- **Code Style Enforcement**: Automated linting and formatting consistency checks
+- **Documentation Analysis**: Validation of code comments, JSDoc, and README completeness
+- **Test Coverage Assessment**: Analysis of unit test coverage and quality
+- **Dead Code Detection**: Identification of unused functions, variables, and imports
 
 ### **Federated Data Architecture**
 Enterprise-scale data management across distributed repositories:
@@ -482,7 +498,9 @@ Built with ❤️ using enterprise-grade technologies:
 
 ### **Core Intelligence Stack**
 - **Multi-Modal AI Integration**: Google Gemini, OpenAI GPT-4, Anthropic Claude
-- **Distributed Graph Database**: Neo4j Enterprise for Knowledge Graph operations
+- **Distributed Graph Database**: Amazon Neptune for Enterprise Knowledge Graph operations
+- **Ingestion & Query Services**: Microservices architecture with GraphQL APIs
+- **Autonomous Agent Network**: Specialized agents for Security, Architecture, Performance, and Quality analysis
 - **Federated Learning Infrastructure**: PyTorch and TensorFlow for ML model training
 - **Container Orchestration**: Kubernetes for enterprise-scale deployment