vibefast-cli 1.3.0 → 1.3.1

package/docs/archive/FINAL-PACKAGE-STRATEGY.md

@@ -1,583 +0,0 @@
-# 📦 Final Package Management Strategy
-
-## The Brilliant Solution: Let Expo Handle Versions!
-
-### The Problem We Were Overcomplicating
-
-**What we were thinking:**
-```bash
-# Manually specify versions in recipe.json
-"dependencies": {
-  "react-native-chart-kit": "^6.12.0",  // ← We manage versions
-  "react-native-svg": "^13.9.0"         // ← Version conflicts!
-}
-
-# Then worry about:
-# - Version conflicts
-# - Peer dependencies
-# - React Native compatibility
-# - Expo SDK compatibility
-```
-
-### The Simple Solution: Use Expo Install
-
-**What we should do:**
-```bash
-# Just list package NAMES (no versions!)
-"dependencies": {
-  "npm": [
-    "react-native-chart-kit",
-    "react-native-svg"
-  ]
-}
-
-# Then run:
-npx expo install react-native-chart-kit react-native-svg
-
-# Expo automatically:
-# ✅ Picks compatible versions
-# ✅ Handles peer dependencies
-# ✅ Resolves conflicts
-# ✅ Works with current Expo SDK
-```
-
----
-
-## Updated Recipe Format
-
-### For Native Apps (Expo)
-
-```json
-{
-  "name": "charts",
-  "version": "1.0.0",
-  "description": "Beautiful data visualization",
-  "target": "native",
-  
-  "copy": [...],
-  "nav": {...},
-  
-  "dependencies": {
-    "expo": [
-      "react-native-chart-kit",
-      "react-native-svg",
-      "react-native-gesture-handler"
-    ]
-  },
-  
-  "postInstall": {
-    "message": "Charts installed! Run your dev server to see it."
-  }
-}
-```
-
-### For Web Apps (Next.js)
-
-```json
-{
-  "name": "charts-web",
-  "version": "1.0.0",
-  "description": "Charts for web",
-  "target": "web",
-  
-  "copy": [...],
-  
-  "dependencies": {
-    "npm": [
-      "recharts",
-      "d3"
-    ]
-  },
-  
-  "postInstall": {
-    "message": "Charts installed!"
-  }
-}
-```
-
----
-
-## Implementation
-
-### Step 1: Update Recipe Schema
-
-**File:** `src/commands/add.ts`
-
-```typescript
-interface RecipeManifest {
-  name: string;
-  version: string;
-  description: string;
-  copy: Array<{ from: string; to: string }>;
-  nav: { href: string; label: string };
-  target: 'native' | 'web';
-  
-  // SIMPLIFIED: Just array of package names
-  dependencies?: {
-    expo?: string[];  // For native (use expo install)
-    npm?: string[];   // For web (use npm/pnpm/yarn)
-  };
-  
-  postInstall?: {
-    message?: string;
-    commands?: string[];
-  };
-}
-```
-
-### Step 2: Show Install Command
-
-**File:** `src/commands/add.ts`
-
-```typescript
-// After copying files
-
-if (manifest.dependencies) {
-  log.plain('');
-  log.warn('⚠ This feature requires additional packages');
-  log.plain('');
-  
-  if (manifest.target === 'native' && manifest.dependencies.expo) {
-    // Native app - use expo install
-    const packages = manifest.dependencies.expo;
-    
-    log.info('📦 Required packages:');
-    packages.forEach(pkg => {
-      log.plain(`  • ${pkg}`);
-    });
-    log.plain('');
-    
-    log.info('Install with:');
-    log.plain(`  npx expo install ${packages.join(' ')}`);
-    log.plain('');
-    
-    log.info('💡 Expo will automatically pick compatible versions');
-    
-  } else if (manifest.target === 'web' && manifest.dependencies.npm) {
-    // Web app - use package manager
-    const packages = manifest.dependencies.npm;
-    const pm = await detectPackageManager(paths.cwd);
-    
-    log.info('📦 Required packages:');
-    packages.forEach(pkg => {
-      log.plain(`  • ${pkg}`);
-    });
-    log.plain('');
-    
-    log.info('Install with:');
-    if (pm === 'pnpm') {
-      log.plain(`  pnpm add ${packages.join(' ')}`);
-    } else if (pm === 'yarn') {
-      log.plain(`  yarn add ${packages.join(' ')}`);
-    } else {
-      log.plain(`  npm install ${packages.join(' ')}`);
-    }
-  }
-  
-  log.plain('');
-}
-```
-
----
-
-## User Experience
-
-### Installing a Native Feature
-
-```bash
-$ vf add charts
-
-ℹ Fetching charts for native...
-ℹ Downloading recipe...
-ℹ Installing charts v1.0.0...
-ℹ Copying files...
-✓ Navigation link added
-✓ charts installed successfully!
-ℹ Files added: 17
-
-⚠ This feature requires additional packages
-
-📦 Required packages:
-  • react-native-chart-kit
-  • react-native-svg
-
-Install with:
-  npx expo install react-native-chart-kit react-native-svg
-
-💡 Expo will automatically pick compatible versions
-
-✓ Installation complete!
-```
-
-### Installing a Web Feature
-
-```bash
-$ vf add charts-web --target web
-
-✓ charts-web installed successfully!
-ℹ Files added: 12
-
-⚠ This feature requires additional packages
-
-📦 Required packages:
-  • recharts
-  • d3
-
-Install with:
-  pnpm add recharts d3
-
-✓ Installation complete!
-```
-
----
-
-## Advantages of This Approach
-
-### 1. No Version Management ✅
-```json
-// Before (complex):
-{
-  "dependencies": {
-    "react-native-svg": "^13.9.0"  // ← What if user has Expo SDK 48?
-  }
-}
-
-// After (simple):
-{
-  "dependencies": {
-    "expo": ["react-native-svg"]  // ← Expo figures it out!
-  }
-}
-```
-
-### 2. No Conflicts ✅
-```bash
-# Expo handles everything:
-$ npx expo install react-native-svg
-
-# If user has Expo SDK 49:
-# → Installs react-native-svg@13.9.0
-
-# If user has Expo SDK 50:
-# → Installs react-native-svg@14.1.0
-
-# Always compatible!
-```
-
-### 3. No Peer Dependency Hell ✅
-```bash
-# Package needs react-native-gesture-handler
-# Expo installs it automatically with compatible version
-$ npx expo install react-native-reanimated
-# → Also installs react-native-gesture-handler@2.x
-```
-
-### 4. Simpler Recipe Creation ✅
-```json
-// Recipe creator just lists packages:
-{
-  "dependencies": {
-    "expo": [
-      "react-native-chart-kit",
-      "react-native-svg"
-    ]
-  }
-}
-
-// No need to:
-// ❌ Check versions
-// ❌ Test compatibility
-// ❌ Update when Expo SDK changes
-```
-
----
-
-## For Services with Manual Steps
-
-### Sentry Example
-
-```json
-{
-  "name": "sentry",
-  "version": "1.0.0",
-  "target": "native",
-  
-  "copy": [...],
-  
-  "dependencies": {
-    "expo": [
-      "@sentry/react-native"
-    ]
-  },
-  
-  "env": {
-    "required": [
-      {
-        "key": "SENTRY_DSN",
-        "description": "Your Sentry DSN from sentry.io",
-        "example": "https://xxx@xxx.ingest.sentry.io/xxx",
-        "link": "https://sentry.io/settings/projects/"
-      }
-    ]
-  },
-  
-  "manualSteps": [
-    {
-      "step": 1,
-      "title": "Create Sentry Project",
-      "description": "Go to sentry.io and create a new React Native project",
-      "link": "https://sentry.io/signup/"
-    },
-    {
-      "step": 2,
-      "title": "Add DSN to .env",
-      "description": "Copy your DSN and add it to your .env file",
-      "file": ".env",
-      "content": "SENTRY_DSN=your-dsn-here"
-    }
-  ],
-  
-  "postInstall": {
-    "message": "Sentry installed! Complete the manual steps above.",
-    "commands": [
-      "npx expo install @sentry/react-native"
-    ]
-  }
-}
-```
-
-**User sees:**
-
-```bash
-$ vf add sentry
-
-✓ sentry installed successfully!
-ℹ Files added: 5
-
-📦 Required packages:
-  • @sentry/react-native
-
-Install with:
-  npx expo install @sentry/react-native
-
-⚠ MANUAL STEPS REQUIRED:
-
-┌─────────────────────────────────────────────────────────────┐
-│ Step 1: Create Sentry Project                               │
-│                                                             │
-│ Go to sentry.io and create a new React Native project      │
-│ 🔗 https://sentry.io/signup/                                │
-└─────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────┐
-│ Step 2: Add DSN to .env                                     │
-│                                                             │
-│ Copy your DSN and add it to your .env file:                │
-│ SENTRY_DSN=your-dsn-here                                    │
-│                                                             │
-│ 📝 File: .env                                               │
-└─────────────────────────────────────────────────────────────┘
-
-💡 Run 'vf checklist sentry' to see these steps again
-```
-
----
-
-## Edge Cases Handled
-
-### 1. Monorepo Workspaces
-```bash
-# User is in: apps/native/
-$ vf add charts
-
-# Shows:
-Install with:
-  npx expo install react-native-chart-kit react-native-svg
-
-# User runs it from apps/native/
-# Expo handles workspace detection automatically!
-```
-
-### 2. Different Package Managers
-```bash
-# For native (always use expo install):
-npx expo install package-name
-
-# For web (detect package manager):
-pnpm add package-name  # or yarn add, or npm install
-```
-
-### 3. No Expo CLI Installed
-```bash
-# npx downloads it automatically!
-$ npx expo install package-name
-# → Downloads expo-cli if needed
-# → Runs install
-```
-
----
-
-## Type Checking Integration
-
-### Optional: Verify Packages Were Installed
-
-```typescript
-// After showing install command
-
-if (!options.skipVerify) {
-  log.plain('');
-  const shouldVerify = promptYesNo(
-    'Verify packages after installation? (Y/n): ',
-    true
-  );
-  
-  if (shouldVerify) {
-    log.info('Waiting for you to install packages...');
-    log.plain('Press Enter when done: ');
-    readlineSync.question('');
-    
-    // Run type check to verify
-    log.info('Verifying installation...');
-    const typeCheck = await runTypeCheck(paths.cwd);
-    
-    if (typeCheck.missingPackages.length > 0) {
-      log.warn('⚠ Some packages are still missing:');
-      typeCheck.missingPackages.forEach(pkg => {
-        log.plain(`  • ${pkg}`);
-      });
-      log.info('Make sure you ran the install command');
-    } else {
-      log.success('✓ All packages installed correctly!');
-    }
-  }
-}
-```
-
----
-
-## Complete Flow
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    SIMPLIFIED PACKAGE FLOW                       │
-└─────────────────────────────────────────────────────────────────┘
-
-Step 1: User Installs Feature
-┌──────────────────────────────────────────────────────────────┐
-│  $ vf add charts                                             │
-└──────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-Step 2: CLI Copies Files
-┌──────────────────────────────────────────────────────────────┐
-│  ✓ 17 files copied                                           │
-│  ✓ Navigation added                                          │
-└──────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-Step 3: CLI Shows Package Command
-┌──────────────────────────────────────────────────────────────┐
-│  📦 Required packages:                                       │
-│    • react-native-chart-kit                                  │
-│    • react-native-svg                                        │
-│                                                               │
-│  Install with:                                               │
-│    npx expo install react-native-chart-kit react-native-svg │
-│                                                               │
-│  💡 Expo will pick compatible versions                       │
-└──────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-Step 4: User Runs Command
-┌──────────────────────────────────────────────────────────────┐
-│  $ npx expo install react-native-chart-kit react-native-svg │
-│                                                               │
-│  Expo automatically:                                          │
-│  ✓ Detects Expo SDK version                                 │
-│  ✓ Picks compatible package versions                         │
-│  ✓ Installs peer dependencies                                │
-│  ✓ Updates package.json                                      │
-└──────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-Step 5: Done!
-┌──────────────────────────────────────────────────────────────┐
-│  ✓ Feature installed                                         │
-│  ✓ Packages installed                                        │
-│  ✓ Ready to use!                                             │
-└──────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Summary
-
-### What Changed
-
-**Before (Complex):**
-- ❌ Specify versions in recipe.json
-- ❌ Worry about conflicts
-- ❌ Update recipes when Expo SDK changes
-- ❌ Handle peer dependencies
-- ❌ Test compatibility
-
-**After (Simple):**
-- ✅ Just list package names
-- ✅ Let `expo install` handle versions
-- ✅ No conflicts ever
-- ✅ Always compatible
-- ✅ No maintenance
-
-### Recipe Format
-
-```json
-{
-  "dependencies": {
-    "expo": [
-      "package-name-1",
-      "package-name-2"
-    ]
-  }
-}
-```
-
-### CLI Output
-
-```bash
-Install with:
-  npx expo install package-name-1 package-name-2
-
-💡 Expo will automatically pick compatible versions
-```
-
-### For Web Apps
-
-```json
-{
-  "dependencies": {
-    "npm": [
-      "package-name-1",
-      "package-name-2"
-    ]
-  }
-}
-```
-
-```bash
-Install with:
-  pnpm add package-name-1 package-name-2
-```
-
----
-
-## This Solves EVERYTHING
-
-1. ✅ No version management
-2. ✅ No conflicts
-3. ✅ No peer dependency issues
-4. ✅ No Expo SDK compatibility issues
-5. ✅ No monorepo complexity
-6. ✅ Simple recipe creation
-7. ✅ Always works
-
-**This is the way!** 🎉