vibefast-cli 0.2.4 → 0.3.0

package/CLI-ROADMAP.md

@@ -0,0 +1,415 @@
+# VibeFast CLI Roadmap - Finalized Features
+
+## Vision
+User runs ONE command and gets a fully working project with zero manual setup.
+
+```bash
+npx vibefast-cli init --license YOUR_KEY
+```
+
+---
+
+## 🚀 Essential Features (7 Total)
+
+### 1. Project Initialization (`vf init`)
+**Difficulty:** 🔴 **HIGH** (8/10)
+**Status:** 🔴 NOT STARTED
+
+**What it does:**
+- Ask: "Start fresh or with all features?" (clean/full branch)
+- Clone the appropriate branch automatically
+- Run `pnpm install`
+- Set up `.env` files with placeholders
+- Login with license key
+
+**Why it matters:**
+- THE critical feature - everything starts here
+- Removes all manual setup steps
+- Gets users to working project in < 2 minutes
+
+**Implementation notes:**
+- Use `simple-git` or `isomorphic-git` for git operations
+- Detect OS and handle paths correctly
+- Provide rollback on failure
+- Show real-time progress
+
+---
+
+### 2. Auto-Install Dependencies (After `vf add`)
+**Difficulty:** � **MEDIUM*3* (4/10)
+**Status:** � ENOT STARTED
+
+**What it does:**
+- After `vf add <feature>`, automatically run `npx expo install` or `pnpm install`
+- No manual copy-paste needed
+- Show progress and errors
+
+**Why it matters:**
+- Removes one manual step per feature install
+- Users expect this to happen automatically
+
+**Why it's harder than it looks:**
+- Monorepo lockfile conflicts
+- Handling install failures gracefully
+- Different package managers (pnpm, npm, yarn, bun)
+- Cache invalidation issues
+- Rollback on partial failure
+
+**Implementation notes:**
+- Detect if native or web project
+- Detect package manager (pnpm.lock, package-lock.json, yarn.lock)
+- Run `npx expo install` for native
+- Run appropriate package manager for web
+- Show progress and errors
+- Suggest fixes for common issues
+- Handle edge cases: missing lockfile, conflicting versions
+
+---
+
+### 3. Smart Target Detection (Auto-detect native/web)
+**Difficulty:** 🟢 **LOW** (2/10)
+**Status:** � NOT STIARTED
+
+**What it does:**
+```bash
+vf add charts  # Detects if you're in native/web automatically
+```
+
+**Why it matters:**
+- Saves users from typing `--target native` every time
+- Obvious UX improvement
+
+**Implementation notes:**
+- Look for `apps/native` or `apps/web` directories
+- Check `package.json` for Expo vs Next.js markers
+- Cache detection result
+- Allow override with `--target` flag
+
+---
+
+### 4. Better Progress Indicators
+**Difficulty:** 🟡 **MEDIUM** (5/10)
+**Status:** 🟡 IN PROGRESS
+
+**What it does:**
+```
+✓ Downloading feature...
+✓ Extracting files...
+⠋ Installing dependencies... (2/5)
+```
+
+**Why it matters:**
+- Makes CLI feel professional and responsive
+- Users know something is happening
+- Reduces perceived wait time
+
+**Implementation notes:**
+- Use `ora` for spinners
+- Use `progress` for progress bars
+- Track operation steps
+- Show ETA if possible
+- Handle terminal resize
+
+---
+
+### 5. Better Prompts (Multi-select with descriptions)
+**Difficulty:** 🟡 **MEDIUM** (5/10)
+**Status:** 🟡 IN PROGRESS
+
+**What it does:**
+```
+? Select features to install: (Space to select, Enter to confirm)
+  ◯ Charts - Beautiful data visualizations
+  ◉ Chatbot - AI-powered conversations
+  ◯ Audio Recorder - Record and process audio
+  ◯ Image Generator - AI image generation
+```
+
+**Why it matters:**
+- Makes feature selection clear and intuitive
+- Users understand what each feature does
+- Better UX than plain text prompts
+
+**Implementation notes:**
+- Use `inquirer` with custom rendering
+- Show feature descriptions
+- Highlight dependencies
+- Show file count and size
+- Warn about conflicts
+
+---
+
+### 6. Environment Setup (`vf env setup`)
+**Difficulty:** 🟡 **MEDIUM** (6/10)
+**Status:** � NOT S*TARTED
+
+**What it does:**
+- Detect missing env vars
+- Prompt for values with descriptions
+- Validate API keys (test connections)
+- Support for multiple environments (dev/staging/prod)
+
+**Why it matters:**
+- Most common pain point for users
+- Removes manual `.env` file editing
+- Validates setup before user starts coding
+
+**Implementation notes:**
+- Create schema for env vars (required, optional, type, description)
+- Use `.env.example` as source of truth
+- Test API keys with actual calls
+- Never log sensitive values
+- Support `.env.local`, `.env.staging`, `.env.production`
+
+---
+
+### 7. Project Health Check (`vf health`)
+**Difficulty:** � **HIGH** ( 7/10)
+**Status:** 🔴 NOT STARTED
+
+**What it does:**
+- Check all env vars are set
+- Verify all dependencies installed
+- Test API connections
+- Show what's missing/broken
+
+**Why it matters:**
+- Quick diagnostic tool
+- Catches issues early
+- Helps users debug problems
+
+**Why it's harder than expected:**
+- Orchestrating multiple async checks
+- Dependency tree parsing
+- Network calls with timeouts
+- Deterministic exit codes
+- Actionable fix suggestions
+- High regression risk (touches everything)
+
+**Implementation notes:**
+- Create health check modules
+- Run checks in parallel (with timeout)
+- Show results in table format
+- Provide fix suggestions with commands
+- Cache results with TTL (5 minutes)
+- Handle partial failures gracefully
+- Exit code: 0 = healthy, 1 = warnings, 2 = errors
+
+---
+
+## 🗑️ Removed Features (Not Worth It)
+
+These were considered but removed because they're either redundant, overcomplicated, or users can achieve the same result with existing commands:
+
+- **`vf update`** - Users can just `vf remove <feature> && vf add <feature>` to get latest
+- **Configuration Profiles** - Niche use case, not worth the complexity
+- **Interactive Mode (TUI)** - Overkill, good CLI prompts are enough
+- **Setup Wizard** - Redundant if `vf init` is interactive
+- **Deploy Prep** - Just a checklist, can be documentation
+- **Templates & Presets** - Keep it simple: just "clean" or "full" branch
+- **`vf fix`** - Most issues are user-specific, not worth auto-fixing
+- **Service Configuration** - Users can edit `.env` manually if needed
+
+---
+
+## 📊 Implementation Phases (REVISED)
+
+### Phase 1: Foundation (Week 1)
+**Total Difficulty: 🟢 LOW**
+
+1. 🔴 **Smart Target Detection** (2/10) - NOT STARTED
+2. 🔴 **Better Progress Indicators** (5/10) - NOT STARTED
+3. � **Better  Prompts** (5/10) - NOT STARTED
+
+**Why this order:**
+- Build UI foundation first
+- Test on existing commands (`vf add`, `vf list`)
+- Low risk, immediate UX improvement
+- No dependencies on other features
+
+---
+
+### Phase 2: MVP Init (Weeks 2-3)
+**Total Difficulty: � HIGH**
+
+4. � ***Minimal `vf init`** (6/10) - NOT STARTED
+   - Clone repo (clean/full branch)
+   - Run `pnpm install`
+   - Create `.env` from `.env.example`
+   - Login with license key
+   - **Skip:** API validation, multi-env, advanced prompts
+
+**Why moved up:**
+- Validates the core promise early
+- Enables real user testing
+- Unblocks feedback loop
+- Other features can iterate on this
+- **Critical:** Don't wait until Phase 3 to test the main feature
+
+---
+
+### Phase 3: Polish & Automation (Weeks 4-5)
+**Total Difficulty: 🟡 MEDIUM-HIGH**
+
+5. 🔴 **Auto-Install Dependencies** (4/10) - NOT STARTED
+6. 🔴 **Environment Setup** (7/10) - NOT STARTED
+7. 🔴 **Project Health** (7/10) - NOT STARTED
+
+**Why this order:**
+- Build on working `vf init`
+- Add automation layer by layer
+- Test with real users
+- Handle edge cases discovered in Phase 2
+- Iterate based on feedback
+
+---
+
+## 🎯 Success Metrics
+
+**Assumptions:**
+- User has stable internet (10+ Mbps)
+- Git and Node.js already installed
+- License key ready
+
+**Metrics:**
+- **Time to first working project:** < 5 minutes (including clone + install)
+  - _Breakdown: Clone (1-2 min) + Install (2-3 min) + Setup (30s)_
+- **Manual steps required:** 0 (after `vf init`)
+- **Manual steps eliminated:** 15+ (clone, install, env setup, login, etc.)
+- **User satisfaction:** 90%+ (realistic target)
+- **Support tickets reduced:** 60%+ (first 3 months)
+
+---
+
+## 💡 Key Principles
+
+1. **Zero Manual Setup** - Everything automated
+2. **Smart Defaults** - Detect and decide for user
+3. **Clear Feedback** - Show what's happening
+4. **Fast Execution** - Minimize wait time
+5. **Beautiful UX** - Make it enjoyable to use
+6. **Keep It Simple** - No unnecessary features
+
+---
+
+## 🎨 Color Scheme & UI Guidelines
+
+**Philosophy:** Use colors strategically to guide attention, not overwhelm. Keep it clean and professional.
+
+### Status Indicators
+- ✅ **Success** - `green` (#22c55e) - Feature installed, command completed
+- ❌ **Error** - `red` (#ef4444) - Something failed, needs attention
+- ⚠️ **Warning** - `yellow` (#eab308) - Caution, might need review
+- ℹ️ **Info** - `blue` (#3b82f6) - Informational, no action needed
+- ⏳ **Loading** - `cyan` (#06b6d4) - In progress, be patient
+
+### Text Styling
+- **Headers/Titles** - `bold + cyan` - Makes sections stand out
+- **Command names** - `bold + white` - Easy to spot what to run
+- **File paths** - `dim + gray` - Less important, doesn't distract
+- **Values/URLs** - `bold + blue` - Important data, clickable-looking
+- **Errors** - `bold + red` - Demands attention
+
+### Examples
+
+```
+✅ Feature installed successfully
+   Location: apps/native/src/features/charts
+
+❌ Failed to install dependencies
+   Error: EACCES permission denied
+   💡 Try: sudo chown -R $USER ~/.npm
+
+⚠️  File already exists and was modified
+   Path: apps/native/src/app.tsx
+   Action: Backup created at .backup/app.tsx.bak
+
+ℹ️  3 manual setup steps required
+   Run: vf checklist sentry
+
+⏳ Installing dependencies... (2/5)
+```
+
+### Progress Bars
+```
+Downloading feature...
+████████░░░░░░░░░░░░ 40% (2.1 MB / 5.2 MB)
+
+Installing packages...
+████████████████████ 100% ✓
+```
+
+### Multi-Select Prompts
+```
+? Select features to install: (Space to select, Enter to confirm)
+  ◯ Charts - Beautiful data visualizations
+  ◉ Chatbot - AI-powered conversations (selected)
+  ◯ Audio Recorder - Record and process audio
+  ◯ Image Generator - AI image generation
+```
+
+### Table Output (vf status, vf health)
+```
+Feature          Version  Target   Status    Installed
+─────────────────────────────────────────────────────
+charts           1.0.0    native   ✅ OK     11/13/2024
+chatbot          1.2.0    native   ✅ OK     11/13/2024
+sentry           1.0.0    native   ⚠️  WARN  11/12/2024
+```
+
+### Color Usage Rules
+1. **Don't overdo it** - Max 3 colors per output
+2. **Consistency** - Same meaning = same color everywhere
+3. **Accessibility** - Don't rely on color alone (use symbols too)
+4. **Contrast** - Ensure readable on both light and dark terminals
+5. **Dimming** - Use `dim` for less important info (paths, timestamps)
+6. **Fallback** - Always work without colors (CI, TTY detection)
+
+### Implementation
+- Use `chalk` library for colors (already in dependencies)
+- Create color constants in `src/core/colors.ts`
+- Apply consistently across all commands
+- Test on both light and dark terminal themes
+- **Auto-detect TTY:** `process.stdout.isTTY`
+- **Support `--no-color` flag** for CI/CD
+- **Respect `NO_COLOR` env var** (standard)
+- **Fallback:** Use symbols only when colors disabled
+
+---
+
+## 📝 Implementation Notes
+
+### General
+- All features should support `--yes` flag for CI/CD
+- All features should support `--dry-run` to preview
+- All features should have helpful `--help` output
+- All features should log operations for debugging
+- All features should handle interruption gracefully (SIGINT)
+
+### Output & Colors
+- All output should use the color scheme defined above
+- Never use color for critical information (always include symbols)
+- Auto-detect TTY and disable colors in non-interactive environments
+- Support `--no-color` flag and `NO_COLOR` env var
+
+### Error Handling
+- Provide rollback on failure (where possible)
+- Show actionable error messages with fix suggestions
+- Include support email in all error messages
+- Log full stack traces to debug file (not stdout)
+
+### Edge Cases to Test
+- Monorepo layouts (nested packages)
+- Different package managers (pnpm, npm, yarn, bun)
+- Slow/unstable network connections
+- Rate-limited API calls
+- Conflicting lockfiles
+- Missing permissions
+- Interrupted operations (Ctrl+C)
+- Non-TTY environments (CI, scripts)
+
+### Performance
+- Cache network calls (with TTL)
+- Run checks in parallel (with timeout)
+- Show progress for operations > 2 seconds
+- Optimize for fast feedback (< 500ms for local operations)