vibefast-cli 1.2.1 → 1.3.1

package/docs/archive/PRODUCTION-READINESS.md

@@ -1,684 +0,0 @@
-# 🚀 Production Readiness Assessment
-
-## Current Status: ⚠️ ALMOST READY (Needs Critical Improvements)
-
----
-
-## ✅ What's Working Well
-
-### Core Functionality
-- ✅ Authentication with license tokens
-- ✅ Device management (2 device limit)
-- ✅ Recipe fetching from Cloudflare R2
-- ✅ File installation with watermarking
-- ✅ Navigation injection
-- ✅ Journal tracking for clean removal
-- ✅ Path security (prevents directory traversal)
-- ✅ Dry-run mode for previewing changes
-- ✅ Error handling and user-friendly messages
-
-### Infrastructure
-- ✅ Cloudflare Worker deployed and tested
-- ✅ KV storage for licenses
-- ✅ R2 storage for recipes
-- ✅ Token hashing (SHA-256)
-- ✅ Device tracking
-
-### Developer Experience
-- ✅ Simple commands (`vf add`, `vf remove`, etc.)
-- ✅ Good error messages
-- ✅ Doctor command for validation
-- ✅ List command to see available features
-
----
-
-## ❌ Critical Issues (MUST FIX Before Production)
-
-### 1. **File Overwrite Without Confirmation** 🔴 CRITICAL
-
-**Problem:**
-```bash
-$ vf add charts --force
-# Silently overwrites ALL files - user modifications LOST!
-```
-
-**Current Behavior:**
-- No warning about existing files
-- No confirmation prompt
-- No backup created
-- User modifications destroyed
-
-**What Users See:**
-```
-muhammadzafar~$ vf add charts --dry-run
-ℹ [DRY RUN] No changes will be made
-ℹ Fetching charts for native...
-ℹ Downloading recipe...
-ℹ Installing charts v1.0.0...
-ℹ Copying apps/native/src/app/charts → apps/native/src/app/(root)/(protected)/charts
-ℹ Copying apps/native/src/features/charts → apps/native/src/features/charts
-ℹ Adding navigation link...
-✓ Navigation link added
-✓ charts installed successfully!
-ℹ Files added: 17
-⚠ This was a dry run. Run without --dry-run to apply changes.
-```
-
-**Issue:** Dry-run shows files will be added, but doesn't warn if files ALREADY EXIST and will be overwritten!
-
-**Solution Needed:**
-```bash
-$ vf add charts --force
-⚠ Warning: The following files will be OVERWRITTEN:
-  • apps/native/src/app/(root)/(protected)/charts/index.tsx (modified)
-  • apps/native/src/features/charts/chart-card.tsx (modified)
-  
-⚠ Your changes will be LOST. Make sure you have committed to Git!
-
-Continue? (y/N): _
-```
-
----
-
-### 2. **No Package Dependency Management** 🔴 CRITICAL
-
-**Problem:**
-Features require npm packages, but CLI doesn't handle them.
-
-**Example:**
-```bash
-$ vf add charts
-✓ charts installed successfully!
-# User runs app
-# ERROR: Cannot find module 'react-native-chart-kit'
-```
-
-**What Should Happen:**
-```bash
-$ vf add charts
-✓ charts installed successfully!
-ℹ Files added: 17
-
-⚠ This feature requires the following packages:
-  • react-native-chart-kit@^6.12.0
-  • react-native-svg@^13.9.0
-  
-📦 Install them with:
-  npm install react-native-chart-kit@^6.12.0 react-native-svg@^13.9.0
-  
-  OR
-  
-  yarn add react-native-chart-kit@^6.12.0 react-native-svg@^13.9.0
-
-Would you like to install them now? (Y/n): _
-```
-
-**Solution:** Add `dependencies` field to recipe.json
-
----
-
-### 3. **No Modification Detection** 🟡 HIGH PRIORITY
-
-**Problem:**
-```bash
-$ vf remove charts
-# Deletes ALL files, even if user modified them
-# No warning, no backup
-```
-
-**Solution:**
-Track file hashes in journal, warn on removal if modified.
-
----
-
-### 4. **Remove mini-native Demo** 🟢 LOW PRIORITY
-
-**Problem:**
-Test/demo feature shouldn't be in production.
-
-**Solution:**
-Remove all mini-native references and test recipe.
-
----
-
-## 🔧 Required Enhancements
-
-### Enhancement 1: Interactive Confirmation for Overwrites
-
-**Implementation:**
-
-```typescript
-// src/core/fsx.ts
-export async function copyTree(
-  src: string,
-  dest: string,
-  options?: { 
-    dryRun?: boolean; 
-    force?: boolean;
-    interactive?: boolean; // NEW
-  }
-): Promise<{ files: string[]; conflicts: string[] }> {
-  const copied: string[] = [];
-  const conflicts: string[] = [];
-  
-  async function copyRecursive(srcPath: string, destPath: string) {
-    const stats = await stat(srcPath);
-    
-    if (stats.isDirectory()) {
-      if (!options?.dryRun) {
-        await ensureDir(destPath);
-      }
-      const entries = await readdir(srcPath);
-      for (const entry of entries) {
-        await copyRecursive(join(srcPath, entry), join(destPath, entry));
-      }
-    } else {
-      const destExists = await exists(destPath);
-      
-      if (destExists) {
-        conflicts.push(destPath);
-        
-        if (!options?.force && !options?.interactive) {
-          throw new Error(`File exists: ${destPath}. Use --force to overwrite.`);
-        }
-        
-        if (options?.interactive && !options?.dryRun) {
-          // Prompt user for this specific file
-          const answer = await promptUser(
-            `Overwrite ${destPath}? (y/N): `
-          );
-          if (answer.toLowerCase() !== 'y') {
-            log.info(`Skipped: ${destPath}`);
-            return;
-          }
-        }
-      }
-      
-      if (!options?.dryRun) {
-        await ensureDir(dirname(destPath));
-        await copyFile(srcPath, destPath);
-      }
-      copied.push(destPath);
-    }
-  }
-  
-  await copyRecursive(src, dest);
-  return { files: copied, conflicts };
-}
-```
-
-**Usage:**
-```typescript
-// src/commands/add.ts
-const result = await copyTree(srcPath, destPath, {
-  dryRun: options.dryRun,
-  force: options.force,
-  interactive: !options.force && !options.dryRun, // NEW
-});
-
-if (result.conflicts.length > 0 && options.dryRun) {
-  log.warn(`⚠ ${result.conflicts.length} files will be overwritten:`);
-  result.conflicts.forEach(f => log.plain(`  • ${f}`));
-  log.warn('Make sure you have committed your changes to Git!');
-}
-```
-
----
-
-### Enhancement 2: Package Dependency Management
-
-**Recipe Format Update:**
-
-```json
-{
-  "name": "charts",
-  "version": "1.0.0",
-  "description": "Beautiful data visualization",
-  "target": "native",
-  "copy": [...],
-  "nav": {...},
-  "dependencies": {
-    "npm": {
-      "react-native-chart-kit": "^6.12.0",
-      "react-native-svg": "^13.9.0"
-    },
-    "expo": {
-      "expo-linear-gradient": "~12.1.2"
-    }
-  },
-  "postInstall": {
-    "message": "Run 'npx pod-install' if you're on iOS",
-    "commands": [
-      "npx pod-install"
-    ]
-  }
-}
-```
-
-**Implementation:**
-
-```typescript
-// src/commands/add.ts
-
-// After copying files
-if (manifest.dependencies) {
-  log.info('');
-  log.warn('⚠ This feature requires additional packages:');
-  
-  const npmDeps = manifest.dependencies.npm || {};
-  const expoDeps = manifest.dependencies.expo || {};
-  
-  if (Object.keys(npmDeps).length > 0) {
-    log.plain('');
-    log.plain('  NPM packages:');
-    Object.entries(npmDeps).forEach(([pkg, version]) => {
-      log.plain(`    • ${pkg}@${version}`);
-    });
-  }
-  
-  if (Object.keys(expoDeps).length > 0) {
-    log.plain('');
-    log.plain('  Expo packages:');
-    Object.entries(expoDeps).forEach(([pkg, version]) => {
-      log.plain(`    • ${pkg}@${version}`);
-    });
-  }
-  
-  log.plain('');
-  log.info('📦 Install with:');
-  
-  // Generate install commands
-  const npmPackages = Object.entries(npmDeps)
-    .map(([pkg, version]) => `${pkg}@${version}`)
-    .join(' ');
-  
-  if (npmPackages) {
-    log.plain(`  npm install ${npmPackages}`);
-    log.plain(`  OR`);
-    log.plain(`  yarn add ${npmPackages}`);
-  }
-  
-  // Ask if user wants to install now
-  if (!options.dryRun && !options.skipInstall) {
-    const answer = await promptUser('\nInstall packages now? (Y/n): ');
-    if (answer.toLowerCase() !== 'n') {
-      log.info('Installing packages...');
-      await installPackages(npmDeps, expoDeps);
-    }
-  }
-  
-  // Post-install instructions
-  if (manifest.postInstall) {
-    log.plain('');
-    log.info('📝 Post-install steps:');
-    log.plain(`  ${manifest.postInstall.message}`);
-  }
-}
-```
-
----
-
-### Enhancement 3: Modification Detection
-
-**Journal Format Update:**
-
-```json
-{
-  "entries": [
-    {
-      "feature": "charts",
-      "target": "native",
-      "files": [
-        {
-          "path": "/abs/path/to/file.tsx",
-          "hash": "sha256-hash-of-original-content"
-        }
-      ],
-      "insertedNav": true,
-      "ts": 1762912823535
-    }
-  ]
-}
-```
-
-**Implementation:**
-
-```typescript
-// src/commands/remove.ts
-
-// Before deleting files
-const modifiedFiles: string[] = [];
-
-for (const fileEntry of entry.files) {
-  const currentHash = await hashFile(fileEntry.path);
-  if (currentHash !== fileEntry.hash) {
-    modifiedFiles.push(fileEntry.path);
-  }
-}
-
-if (modifiedFiles.length > 0) {
-  log.warn('⚠ The following files were modified by you:');
-  modifiedFiles.forEach(f => log.plain(`  • ${f}`));
-  log.warn('');
-  log.warn('These changes will be LOST if you continue!');
-  log.info('Make sure you have committed to Git.');
-  log.plain('');
-  
-  const answer = await promptUser('Continue with removal? (y/N): ');
-  if (answer.toLowerCase() !== 'y') {
-    log.info('Removal cancelled');
-    return;
-  }
-}
-```
-
----
-
-## 🎯 Features That Should Be CLI-Managed
-
-### ✅ Good Candidates for CLI
-
-These can be fully automated:
-
-1. **UI Components**
-   - Charts, graphs, data visualization
-   - Form components
-   - Card layouts
-   - Modal dialogs
-   - Bottom sheets
-
-2. **Standalone Features**
-   - Image picker/camera
-   - QR code scanner
-   - PDF viewer
-   - Audio/video player
-   - Maps integration
-
-3. **Self-Contained Screens**
-   - Profile screen
-   - Settings screen
-   - About screen
-   - Help/FAQ screen
-
-4. **Utilities**
-   - Date/time formatters
-   - Currency formatters
-   - Validation helpers
-   - API clients (typed)
-
----
-
-### ⚠️ Partial CLI Support (Needs Manual Steps)
-
-These need user intervention:
-
-1. **Sentry** 🔴
-   - CLI can: Install files, add provider
-   - User must: Add DSN to .env, configure release tracking
-   
-   ```json
-   {
-     "name": "sentry",
-     "manualSteps": [
-       {
-         "step": 1,
-         "title": "Add Sentry DSN to .env",
-         "description": "Add SENTRY_DSN=your-dsn-here to .env file",
-         "file": ".env",
-         "example": "SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx"
-       },
-       {
-         "step": 2,
-         "title": "Configure Sentry in app config",
-         "description": "Update app.json with Sentry project info",
-         "file": "app.json"
-       }
-     ]
-   }
-   ```
-
-2. **PostHog** 🔴
-   - CLI can: Install files, add provider
-   - User must: Add API key to .env
-   
-3. **RevenueCat** 🔴
-   - CLI can: Install files, add provider
-   - User must: Add API keys, configure products
-   
-4. **Firebase** 🔴
-   - CLI can: Install files
-   - User must: Download google-services.json, add to project
-
-5. **Supabase** 🔴
-   - CLI can: Install client, types
-   - User must: Add URL and anon key to .env
-
----
-
-### ❌ Should NOT Be CLI-Managed
-
-These are too complex or require deep customization:
-
-1. **Authentication System**
-   - Too many variations (email, social, phone)
-   - Requires backend integration
-   - User-specific flows
-
-2. **Payment Processing**
-   - Requires merchant accounts
-   - Legal compliance varies
-   - Too many providers
-
-3. **Custom Business Logic**
-   - User-specific requirements
-   - Can't be templated
-
----
-
-## 📋 Recipe Format for Services with Manual Steps
-
-```json
-{
-  "name": "sentry",
-  "version": "1.0.0",
-  "description": "Error tracking with Sentry",
-  "target": "native",
-  "copy": [...],
-  "dependencies": {
-    "npm": {
-      "@sentry/react-native": "^5.15.0"
-    }
-  },
-  "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 .env file",
-      "file": ".env",
-      "action": "add",
-      "content": "SENTRY_DSN=your-dsn-here"
-    },
-    {
-      "step": 3,
-      "title": "Test Error Tracking",
-      "description": "Trigger a test error to verify Sentry is working",
-      "command": "npm run test:sentry"
-    }
-  ],
-  "postInstall": {
-    "message": "Sentry installed! Complete the manual steps above to finish setup.",
-    "checklist": true
-  }
-}
-```
-
-**CLI Output:**
-
-```bash
-$ vf add sentry
-
-✓ sentry installed successfully!
-ℹ Files added: 8
-
-📦 Installing packages...
-✓ @sentry/react-native@^5.15.0 installed
-
-⚠ MANUAL STEPS REQUIRED:
-
-This feature requires some manual configuration:
-
-┌─────────────────────────────────────────────────────────────┐
-│ 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 .env file:                     │
-│ SENTRY_DSN=your-dsn-here                                    │
-│                                                             │
-│ 📝 File: .env                                               │
-└─────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────┐
-│ Step 3: Test Error Tracking                                 │
-│                                                             │
-│ Trigger a test error to verify Sentry is working:          │
-│ $ npm run test:sentry                                       │
-└─────────────────────────────────────────────────────────────┘
-
-✓ Installation complete!
-⚠ Don't forget to complete the manual steps above.
-
-💡 Tip: Run 'vf checklist sentry' to see these steps again.
-```
-
----
-
-## 🎯 New CLI Commands Needed
-
-### 1. `vf checklist <feature>`
-Show manual steps for a feature
-
-```bash
-$ vf checklist sentry
-```
-
-### 2. `vf update <feature>`
-Update a feature to latest version
-
-```bash
-$ vf update charts
-```
-
-### 3. `vf status`
-Show installed features and their status
-
-```bash
-$ vf status
-
-Installed features:
-✓ charts (v1.0.0) - Up to date
-⚠ sentry (v1.2.0) - Update available (v1.3.0)
-✓ chatbot (v2.0.0) - Up to date
-
-Manual steps pending:
-⚠ sentry - 2 of 3 steps completed
-```
-
-### 4. `vf install-deps <feature>`
-Install only the dependencies for a feature
-
-```bash
-$ vf install-deps charts
-```
-
----
-
-## 🚦 Production Readiness Checklist
-
-### Before Launch
-
-- [ ] **Add interactive confirmation for overwrites**
-- [ ] **Add package dependency management**
-- [ ] **Add modification detection**
-- [ ] **Remove mini-native demo**
-- [ ] **Add `vf checklist` command**
-- [ ] **Add `vf status` command**
-- [ ] **Add `vf update` command**
-- [ ] **Test with real features (charts, sentry, posthog)**
-- [ ] **Write user documentation**
-- [ ] **Add telemetry (optional, with opt-out)**
-
-### Nice to Have
-
-- [ ] Backup before deletion
-- [ ] Rollback command
-- [ ] Feature templates (create your own recipes)
-- [ ] Recipe validation tool
-- [ ] Auto-update CLI
-
----
-
-## 💡 Recommendations
-
-### For Simple Features (UI Components)
-✅ **Fully automate** - No manual steps needed
-
-### For Service Integrations (Sentry, PostHog, etc.)
-⚠️ **Partial automation** - CLI installs code, user adds credentials
-
-### For Complex Systems (Auth, Payments)
-❌ **Don't automate** - Too complex, provide documentation instead
-
----
-
-## 🎯 Priority Order
-
-1. **🔴 CRITICAL:** Interactive confirmation for overwrites
-2. **🔴 CRITICAL:** Package dependency management  
-3. **🟡 HIGH:** Modification detection
-4. **🟡 HIGH:** Manual steps support in recipes
-5. **🟢 MEDIUM:** `vf checklist` command
-6. **🟢 MEDIUM:** `vf status` command
-7. **🟢 LOW:** Remove mini-native
-8. **🟢 LOW:** `vf update` command
-
----
-
-## Final Answer: Is It Production Ready?
-
-### Current State: **70% Ready**
-
-**Can ship now with:**
-- Clear documentation about limitations
-- Warning users to use Git
-- Only simple features (UI components)
-
-**Should NOT ship until:**
-- Interactive confirmation added
-- Package management added
-- At least basic modification detection
-
-**Timeline:**
-- 2-3 days of work to make it production-ready
-- 1 week to add all nice-to-have features