vibefast-cli 0.2.3 → 0.3.0

package/VF-INIT-FLOW.md

@@ -0,0 +1,446 @@
+# `vf init` Command Flow
+
+## High-Level Overview
+
+```
+User runs: vf init [options]
+    ↓
+[Validation] Check if already in VibeFast project
+    ↓
+[Step 1] Choose starter template (clean or main/full)
+    ↓
+[Step 2] Get project name
+    ↓
+[Step 3] Clone repository from GitHub
+    ↓
+[Step 4] Install dependencies (pnpm/npm/yarn/bun)
+    ↓
+[Step 5] Create .env file from template
+    ↓
+[Step 6] Get/validate license key
+    ↓
+[Step 7] Save license key to project
+    ↓
+Success! Show next steps
+```
+
+---
+
+## Detailed Step-by-Step Flow
+
+### Step 0: Pre-Flight Checks
+
+```
+vf init
+  ↓
+Check: Is .vibefast-signature.json in current directory?
+  ├─ YES → Error: "Already in a VibeFast project!"
+  │         Exit with code 1
+  │
+  └─ NO → Continue to Step 1
+```
+
+---
+
+### Step 1: Choose Starter Template
+
+```
+Is --branch flag provided?
+  ├─ YES → Use provided branch (clean or main)
+  │
+  └─ NO → Is --yes flag provided?
+          ├─ YES → Use default (main/full)
+          │
+          └─ NO → Show interactive prompt:
+                  
+                  ? Which starter template would you like?
+                    ❯ Full - All features included
+                      Clean - Minimal setup
+                  
+                  User selects → Continue
+```
+
+**Result:** `branch = 'main'` or `branch = 'clean'`
+
+---
+
+### Step 2: Get Project Name
+
+```
+Is --yes flag provided?
+  ├─ YES → Use default name: "vibefast-app"
+  │
+  └─ NO → Show prompt:
+          
+          ? Project name: (vibefast-app)
+          User enters name → Continue
+
+Check: Does directory with that name already exist?
+  ├─ YES → Error: "Directory already exists!"
+  │         Exit with code 1
+  │
+  └─ NO → Continue to Step 3
+```
+
+**Result:** `projectName = "vibefast-app"` (or user's choice)
+
+---
+
+### Step 3: Clone Repository
+
+```
+Show spinner: "⏳ Cloning VibeFast monorepo (full/clean starter)..."
+
+Git clone from: https://github.com/mzafarr/vibefast-pro.git
+  ├─ Branch: main (if user selected full)
+  │          clean (if user selected clean)
+  │
+  └─ Options: --depth 1 (shallow clone, faster)
+              --single-branch (only clone selected branch)
+
+Clone result:
+  ├─ SUCCESS → Show: "✓ Repository cloned successfully"
+  │            Continue to Step 4
+  │
+  └─ FAILURE (Auth error) → Show helpful error:
+                            "GitHub authentication failed"
+                            "Set up SSH or GitHub CLI"
+                            Exit with code 1
+```
+
+**Result:** Directory `projectName/` created with repo contents
+
+---
+
+### Step 4: Install Dependencies
+
+```
+Is --skip-install flag provided?
+  ├─ YES → Skip to Step 5
+  │
+  └─ NO → Detect package manager:
+          
+          Check for lockfiles in project:
+          ├─ pnpm-lock.yaml → Use pnpm
+          ├─ package-lock.json → Use npm
+          ├─ yarn.lock → Use yarn
+          ├─ bun.lockb → Use bun
+          └─ None found → Default to pnpm
+          
+          Show spinner: "⏳ Installing dependencies..."
+          
+          Run: pnpm install (or npm/yarn/bun install)
+          
+          Result:
+          ├─ SUCCESS → Show: "✓ Dependencies installed"
+          │            Continue to Step 5
+          │
+          └─ FAILURE → Show error message
+                       Exit with code 1
+```
+
+**Result:** `node_modules/` directory created, dependencies installed
+
+---
+
+### Step 5: Create .env File
+
+```
+Check: Does .env.example exist in project?
+  ├─ YES → Copy .env.example → .env
+  │        Show spinner: "⏳ Creating .env file from template..."
+  │        Show: "✓ .env file created"
+  │        Continue to Step 6
+  │
+  └─ NO → Skip this step, continue to Step 6
+```
+
+**Result:** `.env` file created with placeholder values
+
+---
+
+### Step 6: Get/Validate License Key
+
+```
+Is --license flag provided?
+  ├─ YES → Use provided license key
+  │        Skip to Step 7
+  │
+  └─ NO → Check if user already has license key saved:
+          
+          Read from: ~/.vibefast-auth.json
+          ├─ Found → Use existing key
+          │          Show: "✓ Using existing license key"
+          │          Skip to Step 7
+          │
+          └─ Not found → Is --yes flag provided?
+                         ├─ YES → Error: "License key required"
+                         │         Show: "Use --license <key>"
+                         │         Exit with code 1
+                         │
+                         └─ NO → Show prompt:
+                                 
+                                 ? Enter your license key:
+                                 User enters key → Validate
+                                 
+                                 Is key empty?
+                                 ├─ YES → Error: "License key cannot be empty"
+                                 │         Exit with code 1
+                                 │
+                                 └─ NO → Continue to Step 7
+```
+
+**Result:** `licenseKey = "user's-license-key"`
+
+---
+
+### Step 7: Save License Key
+
+```
+Show spinner: "⏳ Saving license key..."
+
+Create file: projectName/.vibefast-auth.json
+Content:
+{
+  "token": "user's-license-key"
+}
+
+Result:
+  ├─ SUCCESS → Show: "✓ License key saved"
+  │            Continue to Success
+  │
+  └─ FAILURE → Show error message
+               Exit with code 1
+```
+
+**Result:** `.vibefast-auth.json` created in project directory
+
+---
+
+### Success! 🎉
+
+```
+Show success message:
+
+✓ Project initialized successfully!
+
+Next steps:
+  1. cd vibefast-app
+  2. vf list  # See available features
+  3. vf add <feature>  # Add features to your project
+
+📚 Documentation: https://vibefast.pro/docs
+💬 Support: support@vibefast.pro
+```
+
+---
+
+## Error Handling Flow
+
+```
+At any step, if error occurs:
+
+Error caught
+  ↓
+Is it a known error?
+  ├─ YES → Show user-friendly message
+  │        Suggest fix
+  │        Show support email
+  │
+  └─ NO → Show generic error
+          Show stack trace (for debugging)
+          Show support email
+
+Exit with code 1
+```
+
+---
+
+## Command-Line Options
+
+### `--license <key>`
+- Skips license key prompt
+- Uses provided key directly
+- Useful for CI/CD automation
+
+### `--branch <branch>`
+- Specifies which branch to clone
+- Options: `clean` or `main`
+- Default: `main` (full starter)
+
+### `--yes`
+- Skips all interactive prompts
+- Uses all defaults
+- Useful for CI/CD automation
+- Requires `--license` if no existing key
+
+### `--skip-install`
+- Skips dependency installation
+- Useful for testing or custom setup
+- Still creates .env and saves license
+
+---
+
+## Example Flows
+
+### Example 1: Interactive Mode (Most Common)
+
+```bash
+$ vf init
+
+🚀 VibeFast Project Initialization
+
+? Which starter template would you like?
+  ❯ Full - All features included
+    Clean - Minimal setup
+
+? Project name: (vibefast-app) my-awesome-app
+
+✓ Using existing license key
+
+⏳ Cloning VibeFast monorepo (full starter)...
+✓ Repository cloned successfully
+
+⏳ Installing dependencies (this may take a few minutes)...
+✓ Dependencies installed
+
+⏳ Creating .env file from template...
+✓ .env file created
+
+⏳ Saving license key...
+✓ License key saved
+
+🎉 Project initialized successfully!
+
+Next steps:
+  1. cd my-awesome-app
+  2. vf list
+  3. vf add <feature>
+```
+
+---
+
+### Example 2: Automated Mode (CI/CD)
+
+```bash
+$ vf init --license abc123def456 --branch clean --yes
+
+🚀 VibeFast Project Initialization
+
+Selected: clean starter
+
+⏳ Cloning VibeFast monorepo (clean starter)...
+✓ Repository cloned successfully
+
+⏳ Installing dependencies...
+✓ Dependencies installed
+
+⏳ Creating .env file from template...
+✓ .env file created
+
+⏳ Saving license key...
+✓ License key saved
+
+🎉 Project initialized successfully!
+```
+
+---
+
+### Example 3: Skip Install (Custom Setup)
+
+```bash
+$ vf init --license abc123 --skip-install
+
+🚀 VibeFast Project Initialization
+
+Selected: full starter
+
+⏳ Cloning VibeFast monorepo (full starter)...
+✓ Repository cloned successfully
+
+⏳ Creating .env file from template...
+✓ .env file created
+
+⏳ Saving license key...
+✓ License key saved
+
+🎉 Project initialized successfully!
+
+Next steps:
+  1. cd vibefast-app
+  2. pnpm install  # Install manually
+  3. vf list
+```
+
+---
+
+## Files Created/Modified
+
+### Created in Project Directory
+
+```
+vibefast-app/
+├── .vibefast-auth.json      ← License key (created by vf init)
+├── .env                      ← Environment variables (copied from .env.example)
+├── .vibefast-signature.json  ← Project signature (from repo)
+├── package.json              ← From cloned repo
+├── node_modules/             ← Installed dependencies
+├── apps/
+│   ├── native/               ← Expo app
+│   └── web/                  ← Next.js app
+└── ... (rest of repo structure)
+```
+
+---
+
+## Key Design Decisions
+
+1. **License Key Required** - Everything in VibeFast is license-gated
+2. **Default to Full Starter** - Most users want all features
+3. **Auto-Detect Package Manager** - Works with pnpm/npm/yarn/bun
+4. **Check for Existing Key** - Don't ask twice if already logged in
+5. **Shallow Clone** - Faster, smaller download (`--depth 1`)
+6. **Helpful Error Messages** - Guide users to solutions
+7. **Spinners for Feedback** - Show progress for long operations
+
+---
+
+## Performance Characteristics
+
+| Step | Time | Notes |
+|------|------|-------|
+| Validation | <100ms | Local checks |
+| Prompts | Variable | User input |
+| Clone | 1-2 min | Network dependent |
+| Install | 2-3 min | First time, cached after |
+| .env | <100ms | File copy |
+| License | <100ms | File write |
+| **Total** | **~5 min** | Mostly clone + install |
+
+---
+
+## Troubleshooting Guide
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| "Already in VibeFast project" | Running in wrong directory | `cd` to empty directory |
+| "Directory already exists" | Project name taken | Choose different name |
+| "GitHub authentication failed" | No Git credentials | Set up SSH or GitHub CLI |
+| "License key required" | No --license flag | Provide `--license KEY` |
+| "License key cannot be empty" | Empty input | Provide valid key |
+| "Dependencies install failed" | Network/permission issue | Check internet, try `--skip-install` |
+
+---
+
+## Summary
+
+`vf init` is a **7-step process** that:
+1. ✅ Validates environment
+2. ✅ Gets user preferences
+3. ✅ Clones repository
+4. ✅ Installs dependencies
+5. ✅ Sets up environment
+6. ✅ Validates license
+7. ✅ Saves configuration
+
+**Result:** A fully working VibeFast project in < 5 minutes! 🚀

package/dist/commands/add.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/commands/add.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4CpC,eAAO,MAAM,UAAU,SAkWnB,CAAC"}
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/commands/add.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+CpC,eAAO,MAAM,UAAU,SA0HnB,CAAC"}