mycontext-cli 1.0.95 → 2.0.1

package/README.md

@@ -1,415 +1,388 @@
 # MyContext CLI
 
-**🧠 The AI That Actually Understands Your Project**
+**🧠 AI-Powered Full-Stack App Generation with Production-Ready Guarantees**
 
-AI-powered tool that generates production-ready React components through an advanced agent-driven workflow that deeply understands your project context.
+[![npm version](https://badge.fury.io/js/mycontext-cli.svg)](https://www.npmjs.com/package/mycontext-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
 
-## Installation
+Generate complete Next.js applications from natural language with **guaranteed zero linter/build errors** through AI-powered validation gates and automatic build checking.
 
-```bash
-npm install -g mycontext-cli
-# or
-pnpm add -g mycontext-cli
-# or
-yarn global add mycontext-cli
-```
-
-## Quick Start
+## 🚀 Quick Start
 
 ```bash
-# Initialize a new project
-mycontext init my-project
-
-# Set up AI provider (X.AI Grok recommended for best results)
-echo 'MYCONTEXT_XAI_API_KEY=xai-xxx' > .mycontext/.env
-
-# Generate context files (A/B/C/D workflow)
-mycontext generate-context-files --description 'Modern todo app'
-
-# Compile PRD from context files
-mycontext compile-prd
+# Install globally
+npm install -g mycontext-cli
 
-# Generate components
-mycontext generate-components all --with-tests
+# Build a complete app in one command
+mycontext build-app --description "Your app idea" --interactive
 ```
 
-## Features
+## 💡 Philosophy: "LLM as Compiler"
 
-- **🤖 AI-Powered Generation**: Uses advanced AI models to understand your project context
-- **⚡ Fast Setup**: Initialize projects in seconds with Next.js, TypeScript, and Tailwind CSS
-- **🎨 Component Generation**: Create production-ready React components with Shadcn UI
-- **📋 Context-Aware**: Generates PRDs, types, and branding based on your project
-- **🧠 Interactive Strategy Planning**: AI-powered build strategy recommendations through guided questions
-- **🎯 Smart Planning**: Get personalized development approach recommendations
-- **🔧 Developer-Friendly**: Built-in validation, testing, and preview capabilities
-- **🆓 Free Tier**: Use Qwen3 Coder model for free testing, or premium X.AI/Claude for production
+MyContext treats AI as a **compiler** that transforms requirements into production-ready code:
+- **You write the spec** → PRD with user approval gates
+- **AI compiles it** → Generates components with validation
+- **System validates** → TypeScript, ESLint, build checks
+- **You approve** → 12+ validation checkpoints
 
-### 🚀 **Claude Agent SDK Integration** (NEW!)
+**Result:** Production-ready code with 0 errors guaranteed.
 
-- **🧠 Advanced Context Management**: Automatic context compaction and intelligent memory management
-- **🔐 Fine-Grained Tool Permissions**: Granular control over AI capabilities with strict/permissive modes
-- **🔌 MCP Integration**: Model Context Protocol support for external tools and services
-- **⚡ Enhanced Workflows**: Intelligent agent coordination with automatic error handling and retry logic
-- **🎯 Smart Fallbacks**: Seamless fallback to standard clients when Agent SDK isn't available
-- **📊 Context Analytics**: Detailed context statistics and compression ratios
-- **🛡️ Security Controls**: File size limits, directory restrictions, and tool validation
+---
 
-## Commands
+## 📖 Examples
 
-### Project Setup
+### Tic-Tac-Toe Game
 
 ```bash
-mycontext init <project-name>          # Initialize new project
-mycontext setup                        # Configure AI providers
-mycontext analyze                      # Analyze existing project
+mycontext build-app \
+  --description "Tic-tac-toe with AI opponent, score tracking, and responsive design" \
+  --interactive \
+  --with-tests
 ```
 
-### Context Generation
+**Generated:**
+- Game board component
+- AI opponent (minimax algorithm)
+- Score tracking system
+- Reset functionality
+- Responsive Tailwind design
+- Unit tests
 
-```bash
-mycontext generate context             # Generate PRD and context files
-mycontext generate types               # Generate TypeScript types
-mycontext generate brand               # Generate branding guidelines
-mycontext generate components-list     # Generate component list
-mycontext compile-prd                  # Compile PRD from context files
-```
-
-### Component Development
+### E-Commerce Platform
 
 ```bash
-mycontext generate-components <target> # Generate React components
-mycontext enhance <component>          # Enhance existing components
-mycontext refine <component>           # Refine components with AI
-mycontext preview <type>               # Preview components or brand
+mycontext build-app \
+  --description "E-commerce with product catalog, shopping cart, checkout, and admin dashboard" \
+  --interactive \
+  --complete-architecture
 ```
 
-### Project Management
+**Generated:**
+- Product listing & detail pages
+- Shopping cart with persistence
+- Checkout flow
+- Admin dashboard
+- Server actions for CRUD
+- Next.js App Router routes
+- Full TypeScript types
 
-```bash
-mycontext validate <target>            # Validate PRD or files
-mycontext status                       # Check project status
-mycontext list [type]                  # List components, projects, or files
-mycontext promote                      # Promote components to production
-```
-
-### Build Strategy Planning
+### Todo App with Auth
 
 ```bash
-mycontext build-strategy               # Interactive strategy selection
-mycontext build-strategy --recommend  # Get AI-powered strategy recommendations
-mycontext build-strategy --plan       # Generate detailed build plan
-mycontext build-strategy --tasks      # Generate task list for current phase
-mycontext build-strategy --compare    # Compare all available strategies
-mycontext build-strategy --context    # Show loaded project context
-mycontext build-strategy --list       # List all saved strategy files
-mycontext build-strategy --load <type> # Load saved strategy data
+mycontext build-app \
+  --description "Todo app with user auth, categories, due dates, and dark mode" \
+  --interactive \
+  --with-tests
 ```
 
-## Build Strategy Planning
-
-MyContext's **AI-Powered Build Strategy** feature helps you choose the right development approach for your project through interactive questions and AI-generated recommendations.
-
-### How It Works
+---
 
-1. **Interactive Questions**: Asks about your project type, complexity, timeline, and team size
-2. **AI Processing**: Uses AI to analyze your answers and project context
-3. **Strategic Recommendations**: Generates personalized development strategies
-4. **Strategy Comparison**: Shows different approaches with pros/cons and timelines
+## 🎯 Features
 
-### Available Strategies
+### ✅ 230-Step Validated Workflow
 
-- **🏗️ Foundation First**: Build core infrastructure first (auth, DB, architecture)
-- **🎯 Vertical Slice**: Build complete user journeys end-to-end
-- **📊 Horizontal Slice**: Build feature by feature across the app
-- **🔄 Iterative Scaffolding**: Small chunks everywhere, refine later
-- **⚡ Hybrid Approach**: Combines multiple strategies based on project needs
+Every app goes through **12 validation gates** where you approve:
+1. Features specification
+2. User flows
+3. Edge cases
+4. Technical specs
+5. **PRD (must read entire document)**
+6. TypeScript types
+7. Branding & design system
+8. Build strategy
+9. Component list
+10. Server actions (if full-stack)
+11. Routes (if full-stack)
+12. Final build validation
 
-### Interactive Strategy Selection
+### 🔨 Automatic Build Validation
 
-The system provides:
+**Every component** automatically passes through:
+- ✅ TypeScript check (`tsc --noEmit`)
+- ✅ ESLint validation
+- ✅ Build check (`npm run build`)
+- ✅ Unit tests (if `--with-tests`)
 
-- **Project Type Selection**: Choose from client work, personal projects, team development, etc.
-- **Complexity Assessment**: Simple, medium, or complex application classification
-- **Timeline Planning**: Urgent, moderate, or flexible development timelines
-- **Team Size Consideration**: Solo developer, small team, or large team approaches
-- **AI Recommendations**: Personalized strategy suggestions based on your answers
+**Failed components retry automatically** with error context (max 3 attempts).
 
-### Example Workflow
+### 📊 Real-Time Progress Tracking
 
-```bash
-$ mycontext build-strategy --recommend
-
-🎯 Getting AI-Powered Strategy Recommendations
-
-? What type of project are you building?
-❯ Client Work
-  Personal Project
-  Team Development
-  MVP Development
-  Enterprise Application
+Track build progress via JSON files in `.mycontext/progress/`:
+```json
+{
+  "currentPhase": "component_generation",
+  "currentStep": 95,
+  "totalSteps": 230,
+  "percentComplete": 41.3
+}
+```
 
-? How complex is your application?
-❯ Simple (few features, single user type)
-  Medium (multiple features, some complexity)
-  Complex (many features, multiple user types)
+**Perfect for VS Code extensions & dashboards.**
 
-? What's your timeline?
-❯ Urgent (need demo ASAP)
-  Moderate (balanced approach)
-  Flexible (quality over speed)
+### 🏗️ Complete Architecture Generation
 
-? What's your team size?
-❯ Solo developer
-  Small team (2-5 people)
-  Large team (6+ people)
+Generate full-stack apps with `--complete-architecture`:
+- Next.js 15 App Router routes
+- Server actions with validation
+- Self-documenting components
+- Type-safe throughout
 
-✅ Recommended Strategies:
+---
 
-🎯 Vertical Slice
-   Build complete user journeys end-to-end
-   Time to first demo: 2-3 weeks
-   Complexity: medium
+## 📋 Commands
 
-💡 Reasoning:
-   Vertical slice approach recommended for balanced development with quick user value
+### Build Complete App (Recommended)
 
-💾 Saved to: /path/to/project/.mycontext/build-strategy-recommendations-2025-09-23.json
+```bash
+mycontext build-app --description "Your app" --interactive
+
+# Options:
+  --output <dir>              # Output directory (default: mycontext-app)
+  --interactive               # Interactive mode with validation prompts
+  --with-tests                # Generate unit tests
+  --complete-architecture     # Generate server actions + routes
+  --architecture-type         # nextjs-app-router | nextjs-pages | react-spa
+  --max-retries 3             # Max retry attempts
+  --verbose                   # Show detailed output
 ```
 
-### Strategy Data Management
-
-All generated strategies are automatically saved as JSON files in `.mycontext/` for easy access and project tracking:
+### Step-by-Step Workflow
 
 ```bash
-# List all saved strategy files
-mycontext build-strategy --list
-
-# Load specific strategy data
-mycontext build-strategy --load recommendations
-mycontext build-strategy --load plan
-mycontext build-strategy --load tasks
-mycontext build-strategy --load comparison
-```
+# 1. Initialize project
+mycontext init my-app
 
-**File Structure:**
+# 2. Generate context files (with validation gates)
+mycontext generate-context-files --description "Your app"
 
-```
-.mycontext/
-├── build-strategy-recommendations-2025-09-23.json
-├── build-strategy-plan-2025-09-23.json
-├── build-strategy-tasks-2025-09-23.json
-└── build-strategy-comparison-2025-09-23.json
-```
+# 3. Compile PRD (requires approval)
+mycontext compile-prd
 
-**File Format:**
+# 4. Generate components (with build validation)
+mycontext generate-components all --with-tests
+```
 
-Each saved strategy file contains:
+### Other Commands
 
-```json
-{
-  "type": "recommendations",
-  "generatedAt": "2025-09-23T11:05:52.000Z",
-  "projectPath": "/path/to/project",
-  "data": {
-    "recommended": [...],
-    "reasoning": "...",
-    "alternatives": [...]
-  }
-}
+```bash
+mycontext setup                    # Configure AI providers
+mycontext build-strategy          # Interactive strategy selection
+mycontext analyze                 # Analyze existing project
+mycontext list [type]             # List components/projects
+mycontext preview <type>          # Preview components
 ```
 
-## Configuration
-
-### AI Providers
+---
 
-MyContext supports multiple AI providers with intelligent fallback:
+## ⚙️ Configuration
 
-#### **Recommended (Premium)**
+### API Keys (BYOK Model)
 
-1. **🚀 Claude Agent SDK - Best for Advanced Workflows** (NEW!)
+MyContext uses **your own API keys** - no billing from us.
 
-   ```bash
-   echo 'MYCONTEXT_CLAUDE_API_KEY=sk-ant-xxx' > .mycontext/.env
-   ```
+**Recommended providers:**
 
-   **Features:**
-   - Advanced context management and compaction
-   - Fine-grained tool permissions
-   - MCP (Model Context Protocol) integration
-   - Intelligent agent coordination
-   - Automatic error handling and retry logic
+```bash
+# Claude (best for complex reasoning)
+echo 'MYCONTEXT_CLAUDE_API_KEY=sk-ant-xxx' > .mycontext/.env
 
-2. **X.AI (Grok) - Best for Code Generation**
+# X.AI Grok (best for code generation)
+echo 'MYCONTEXT_XAI_API_KEY=xai-xxx' > .mycontext/.env
 
-   ```bash
-   echo 'MYCONTEXT_XAI_API_KEY=xai-xxx' > .mycontext/.env
-   ```
+# OpenAI (most versatile)
+echo 'MYCONTEXT_OPENAI_API_KEY=sk-xxx' > .mycontext/.env
+```
 
-3. **Claude (Anthropic) - Best for Complex Reasoning**
+**Free tier:**
 
-   ```bash
-   echo 'MYCONTEXT_CLAUDE_API_KEY=sk-ant-xxx' > .mycontext/.env
-   ```
+```bash
+# Qwen3 (free via OpenRouter)
+echo 'MYCONTEXT_QWEN_API_KEY=sk-or-xxx' > .mycontext/.env
+```
 
-4. **OpenAI (GPT-4) - Most Versatile**
-   ```bash
-   echo 'MYCONTEXT_OPENAI_API_KEY=sk-xxx' > .mycontext/.env
-   ```
+### Project Structure
 
-#### **Testing & Fallback**
+```
+my-app/
+├── .mycontext/
+│   ├── 01-prd.md                 # Product Requirements
+│   ├── 02-a-features.md          # Features
+│   ├── 02-b-user-flows.md        # User flows
+│   ├── 02-c-edge-cases.md        # Edge cases
+│   ├── 02-d-technical-specs.md   # Tech specs
+│   ├── 03-types.ts               # TypeScript types
+│   ├── 04-branding.md            # Branding
+│   ├── 05-component-list.json    # Component list
+│   ├── progress/                 # Progress tracking
+│   │   ├── master.json           # Master progress
+│   │   └── 07-components/        # Per-component progress
+│   └── .env                      # API keys
+├── components/                    # Generated components
+├── actions/                       # Server actions (--complete-architecture)
+├── app/                          # Routes (--complete-architecture)
+└── package.json
+```
 
-5. **Qwen3 Coder (FREE)**
+---
 
-   ```bash
-   echo 'MYCONTEXT_QWEN_API_KEY=sk-or-xxx' > .mycontext/.env
-   ```
+## 🎓 How It Works
 
-6. **GitHub Models (Self-hosted)**
-   ```bash
-   echo 'MYCONTEXT_GITHUB_TOKEN=ghp_xxx' > .mycontext/.env
-   ```
+### 1. Context Generation
+AI generates detailed context files based on your description. **You approve each one.**
 
-### Project Structure
+### 2. PRD Compilation
+Context files are compiled into a comprehensive PRD. **You must read and approve.**
 
+### 3. Component Generation
+Components are generated from PRD. **Each component automatically validated:**
 ```
-my-project/
-├── .mycontext/           # MyContext configuration
-│   ├── 01-prd.md        # Product Requirements Document
-│   ├── 02-types.ts      # TypeScript types
-│   ├── 03-branding.md   # Branding guidelines
-│   └── .env             # Environment variables
-├── components/           # Generated components
-└── package.json
+🔨 Generating: LoginForm
+   ✅ Code Generated
+   ✅ TypeScript Check Passed
+   ✅ ESLint Passed
+   ✅ Build Passed
+   ✅ Tests Passed
 ```
 
-## Examples
-
-### Create a Todo App
-
-```bash
-mycontext init todo-app --description "A modern todo application with dark mode"
-cd todo-app
-mycontext generate-context-files
-mycontext compile-prd
-mycontext generate-components all --with-tests
+### 4. Error Recovery
+Failed components retry with error context:
 ```
+❌ TypeScript check failed (3 errors)
+   - LoginForm.tsx:12:5 - TS2322: Type 'string' not assignable to 'number'
 
-### Work with Existing Project
+🔄 Retry 1/3 (with error context)
+   ✅ Fixed and validated
+```
 
+### 5. Production Deploy
 ```bash
-mycontext init . --analyze
-mycontext generate-context-files
-mycontext generate-components authentication
+cd my-app
+npm run build    # ✅ Zero errors guaranteed
+vercel deploy    # 🚀 Deploy
 ```
 
-### Build Complete App
+---
 
-```bash
-mycontext build-app --description "E-commerce platform" --interactive
-```
+## 🔧 Advanced Usage
 
-### Plan Your Development Strategy
+### Build Strategy Selection
 
 ```bash
-# Get AI-powered strategy recommendations
 mycontext build-strategy --recommend
 
-# Generate detailed build plan
-mycontext build-strategy --plan --strategy vertical-slice
-
-# Get task list for current phase
-mycontext build-strategy --tasks --strategy foundation-first --phase 1
+# AI asks about:
+- Project type (client work, personal, MVP, etc.)
+- Complexity (simple, medium, complex)
+- Timeline (urgent, moderate, flexible)
+- Team size (solo, small, large)
 
-# Compare all strategies
-mycontext build-strategy --compare
-
-# Show project context analysis
-mycontext build-strategy --context
+# Recommends best approach:
+🎯 Vertical Slice - Build complete features end-to-end
+⏰ Time to first demo: 2-3 weeks
 ```
 
-## 🚀 **Claude Agent SDK Features**
+### Complete Architecture
 
-### **Advanced Context Management**
+```bash
+mycontext build-app \
+  --description "Blog platform" \
+  --complete-architecture \
+  --architecture-type nextjs-app-router
+
+# Generates:
+# - app/blog/[slug]/page.tsx
+# - actions/createPost.ts
+# - actions/updatePost.ts
+# - components/BlogPost.tsx
+# - Full type system
+```
 
-The Claude Agent SDK provides intelligent context management with automatic compaction:
+### Existing Project Migration
 
 ```bash
-# Context is automatically managed and compacted when it exceeds limits
-mycontext build-app --description "Complex enterprise application"
+mycontext analyze                  # Analyze existing project
+mycontext migrate --all           # Migrate to MyContext structure
 ```
 
-**Features:**
-
-- **Automatic Compaction**: Context is compressed when it exceeds size limits
-- **Smart Preservation**: Recent outputs and important data are preserved
-- **Context Analytics**: Detailed statistics on context size and compression ratios
-- **Memory Management**: Persistent context storage across sessions
+---
 
-### **Fine-Grained Tool Permissions**
+## 📊 Build Metrics
 
-Control exactly what the AI can do with granular permissions:
+After successful build:
 
-```bash
-# Tool permissions are automatically configured based on your project needs
-mycontext setup
+```
+🎉 Workflow Complete!
+
+📊 Summary:
+   Duration: 12m 34s
+   Total Steps: 230/230
+   User Approvals: 12
+   Retries: 3
+
+✅ Build Checks:
+   TypeScript: 30 passed, 0 failed
+   ESLint: 30 passed, 0 failed
+   Build: 30 passed, 0 failed
+   Tests: 28 passed, 0 failed
 ```
 
-**Permission Modes:**
-
-- **Strict**: Deny by default, require explicit permission
-- **Permissive**: Allow by default, block specific tools
-- **Custom**: Fine-grained control over individual tools
+**Zero failures = Production-ready**
 
-**Security Features:**
+---
 
-- File size limits and type restrictions
-- Directory access controls
-- API call rate limiting
-- Tool validation and restrictions
+## 🆚 MyContext vs Others
 
-### **MCP (Model Context Protocol) Integration**
+| Feature | MyContext | Lovable | v0.dev |
+|---------|-----------|---------|--------|
+| **Code Location** | Your machine | Cloud | Cloud |
+| **Validation Gates** | 12+ checkpoints | None | None |
+| **Build Validation** | Every component | None | None |
+| **TypeScript Guarantee** | 100% | No | No |
+| **Pricing** | BYOK ($0-20/mo) | $20-200/mo | Usage-based |
+| **Deployment** | Anywhere | Limited | Vercel only |
+| **Progress Tracking** | JSON files | None | None |
 
-Connect to external tools and services through MCP:
+---
 
-```bash
-# Set up MCP integration
-mycontext setup-mcp --provider instantdb
-```
+## 📚 Documentation
 
-**Supported Providers:**
+- [Complete Workflow](https://github.com/farajabien/mycontext-monorepo/blob/main/docs/BUILD_APP_PROCESS.md) - 230-step process
+- [Integration Guide](https://github.com/farajabien/mycontext-monorepo/blob/main/docs/IMPLEMENTATION_SUMMARY.md) - VS Code integration
+- [Quick Start](https://github.com/farajabien/mycontext-monorepo/blob/main/docs/QUICK_START_BUILD_APP.md) - User guide
 
-- **InstantDB**: Real-time database integration
-- **GitHub**: Repository and issue management
-- **Custom**: Your own MCP servers
+---
 
-### **Enhanced Workflows**
+## 🐛 Troubleshooting
 
-Intelligent agent coordination with automatic error handling:
+**"PRD Validation Failed"**
+```bash
+# Provide feedback and regenerate
+mycontext compile-prd --force
+```
 
+**"Component Build Failed"**
 ```bash
-# Enhanced workflows automatically use Claude Agent SDK when available
-mycontext build-app --interactive
+# Automatic retry with error context (max 3 attempts)
+# Check .mycontext/progress/07-components/<component>.json
 ```
 
-**Workflow Features:**
+**"Progress Not Tracking"**
+```bash
+# Verify progress directory exists
+ls -la .mycontext/progress/
+```
 
-- **Smart Fallbacks**: Seamless fallback to standard clients
-- **Error Recovery**: Automatic retry logic with exponential backoff
-- **Context Awareness**: Each step builds on previous context
-- **Progress Tracking**: Detailed progress reporting and analytics
+---
 
-## Documentation
+## 🤝 Contributing
 
-- [Full Documentation](https://mycontext.fbien.com/docs)
-- [API Reference](https://mycontext.fbien.com/docs/api)
-- [Examples](https://mycontext.fbien.com/docs/examples)
+See [CONTRIBUTING.md](https://github.com/farajabien/mycontext-monorepo/blob/main/CONTRIBUTING.md)
 
-## Support
+## 📄 License
 
-- [GitHub Issues](https://github.com/mycontext/cli/issues)
-- [Discord Community](https://discord.gg/mycontext)
-- [Documentation](https://mycontext.fbien.com/docs)
+MIT © MyContext
 
-## License
+---
 
-MIT © MyContext
+**Built by developers, for developers. Your code stays on your machine.** 🚀