vibefast-cli 1.3.0 → 1.3.1

package/docs/archive/GOTCHAS-AND-RISKS.md

@@ -1,801 +0,0 @@
-# ⚠️ Gotchas, Risks, and Difficult Problems
-
-## 🔴 HIGH RISK Issues
-
-### 1. Monorepo Package Installation - VERY TRICKY
-
-**The Problem:**
-VibeFast is a monorepo with multiple workspaces:
-```
-vibefast-monorepo/
-├── package.json (root)
-├── apps/
-│   ├── native/
-│   │   └── package.json (workspace)
-│   └── web/
-│       └── package.json (workspace)
-└── packages/
-    └── ui/
-        └── package.json (workspace)
-```
-
-**Where do we install packages?**
-
-```bash
-# If we run this in apps/native/:
-$ pnpm add react-native-chart-kit
-
-# It might:
-# ❌ Install in apps/native/node_modules (wrong!)
-# ❌ Install in root node_modules (maybe wrong!)
-# ✅ Install in root + update apps/native/package.json (correct!)
-```
-
-**The Issue:**
-- pnpm workspaces install at ROOT but update workspace package.json
-- yarn workspaces behave differently
-- npm workspaces behave differently again
-- Turborepo adds another layer of complexity
-
-**Example of What Can Go Wrong:**
-
-```bash
-# User is in: /Users/john/vibefast-monorepo/apps/native/
-$ vf add charts
-
-# CLI detects: pnpm
-# CLI runs: pnpm add react-native-chart-kit
-
-# What happens?
-# - pnpm sees we're in a workspace
-# - pnpm installs at ROOT
-# - pnpm updates apps/native/package.json
-# - BUT: If we run from wrong directory, it fails!
-```
-
-**Solution (Complex):**
-
-```typescript
-export async function installInMonorepo(
-  packages: Record<string, string>,
-  currentDir: string
-): Promise<{ success: boolean; error?: string }> {
-  // 1. Find workspace root
-  const workspaceRoot = await findWorkspaceRoot(currentDir);
-  
-  // 2. Find which workspace we're in
-  const workspaceName = await findWorkspaceName(currentDir, workspaceRoot);
-  
-  // 3. Detect package manager
-  const pm = await detectPackageManager(workspaceRoot);
-  
-  // 4. Build correct command based on PM
-  let command: string;
-  
-  if (pm === 'pnpm') {
-    // pnpm needs --filter flag for workspaces
-    command = `pnpm add ${pkgList} --filter ${workspaceName}`;
-  } else if (pm === 'yarn') {
-    // yarn workspaces needs to run from workspace dir
-    command = `yarn workspace ${workspaceName} add ${pkgList}`;
-  } else if (pm === 'npm') {
-    // npm workspaces needs -w flag
-    command = `npm install ${pkgList} -w ${workspaceName}`;
-  }
-  
-  // 5. Run from workspace root
-  return await executeBash(command, { cwd: workspaceRoot });
-}
-```
-
-**Gotchas:**
-- Different package managers have different workspace commands
-- Need to detect workspace name (from package.json name field)
-- Need to run from correct directory
-- Turborepo might interfere
-- User might have custom workspace config
-
-**Risk Level:** 🔴 HIGH - This WILL cause issues for some users
-
----
-
-### 2. TypeScript Configuration Variations - MESSY
-
-**The Problem:**
-
-Every project has different tsconfig.json:
-
-```json
-// Project A
-{
-  "extends": "@tsconfig/react-native/tsconfig.json",
-  "compilerOptions": {
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  }
-}
-
-// Project B
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "@/features/*": ["src/features/*"],
-      "@/components/*": ["src/components/*"]
-    }
-  }
-}
-
-// Project C (broken)
-{
-  "extends": "./tsconfig.base.json", // File doesn't exist!
-  "compilerOptions": {}
-}
-```
-
-**What Can Go Wrong:**
-
-```bash
-$ vf add charts
-🔍 Running type check...
-$ pnpm tsc --noEmit
-
-# Error 1: tsconfig.json not found
-# Error 2: tsconfig.json extends missing file
-# Error 3: Type check takes 5 minutes (huge project)
-# Error 4: Type check fails for unrelated reasons
-# Error 5: Multiple tsconfig files (which one to use?)
-```
-
-**Real Example:**
-
-```typescript
-// User's project has this:
-// tsconfig.json (for IDE)
-// tsconfig.build.json (for building)
-// apps/native/tsconfig.json (for native app)
-// apps/web/tsconfig.json (for web app)
-
-// Which one do we run?
-$ tsc --noEmit  // Uses tsconfig.json (might be wrong one!)
-```
-
-**Solution (Defensive):**
-
-```typescript
-export async function runTypeCheck(cwd: string): Promise<TypeCheckResult> {
-  // 1. Find the right tsconfig
-  const tsconfigPath = await findTsConfig(cwd);
-  
-  if (!tsconfigPath) {
-    log.warn('No tsconfig.json found, skipping type check');
-    return { success: true, missingPackages: [], errors: [] };
-  }
-  
-  // 2. Set timeout (don't hang forever)
-  const timeout = 60000; // 60 seconds max
-  
-  // 3. Run with timeout
-  try {
-    const result = await executeBashWithTimeout(
-      `tsc --noEmit --project ${tsconfigPath}`,
-      { cwd, timeout }
-    );
-    
-    // 4. Handle timeout
-    if (result.timedOut) {
-      log.warn('Type check timed out (project too large)');
-      log.info('Skipping automatic dependency detection');
-      return { success: true, missingPackages: [], errors: [] };
-    }
-    
-    // 5. Parse errors (but ignore non-dependency errors)
-    return parseTypeScriptErrors(result.stderr);
-    
-  } catch (error) {
-    // Don't fail the whole installation if type check fails
-    log.warn('Type check failed, skipping dependency detection');
-    return { success: true, missingPackages: [], errors: [] };
-  }
-}
-```
-
-**Risk Level:** 🟡 MEDIUM - Can be handled with good error handling
-
----
-
-### 3. File Hashing Performance - SLOW
-
-**The Problem:**
-
-Hashing 100+ files can be slow:
-
-```typescript
-// Feature with 150 files
-const files = [
-  'file1.tsx', 'file2.tsx', ... // 150 files
-];
-
-// Hash each file
-for (const file of files) {
-  const hash = await hashFile(file); // 10-50ms per file
-}
-
-// Total: 1.5 - 7.5 seconds just for hashing!
-```
-
-**What Makes It Worse:**
-
-```typescript
-// Large files are slow
-const largeFile = 'bundle.js'; // 5MB
-await hashFile(largeFile); // 500ms+
-
-// Binary files are pointless to hash
-const image = 'logo.png';
-await hashFile(image); // Waste of time
-
-// Many files = many disk reads
-// On slow HDDs: 100ms+ per file
-```
-
-**Solution (Optimized):**
-
-```typescript
-export async function hashFiles(
-  filePaths: string[],
-  options?: { showProgress?: boolean }
-): Promise<Map<string, string>> {
-  const hashes = new Map<string, string>();
-  
-  // 1. Filter out files we don't need to hash
-  const filesToHash = filePaths.filter(path => {
-    // Skip binary files
-    if (/\.(png|jpg|jpeg|gif|ico|woff|woff2|ttf|eot)$/.test(path)) {
-      return false;
-    }
-    
-    // Skip large files (>1MB)
-    try {
-      const stats = statSync(path);
-      if (stats.size > 1024 * 1024) {
-        return false;
-      }
-    } catch {
-      return false;
-    }
-    
-    return true;
-  });
-  
-  // 2. Process in parallel batches
-  const batchSize = 10;
-  const batches = [];
-  
-  for (let i = 0; i < filesToHash.length; i += batchSize) {
-    batches.push(filesToHash.slice(i, i + batchSize));
-  }
-  
-  // 3. Process batches with progress
-  for (let i = 0; i < batches.length; i++) {
-    const batch = batches[i];
-    
-    await Promise.all(
-      batch.map(async (path) => {
-        const hash = await hashFile(path);
-        hashes.set(path, hash);
-      })
-    );
-    
-    if (options?.showProgress && filesToHash.length > 20) {
-      const progress = Math.min((i + 1) * batchSize, filesToHash.length);
-      process.stdout.write(`\r  Hashing files: ${progress}/${filesToHash.length}`);
-    }
-  }
-  
-  if (options?.showProgress && filesToHash.length > 20) {
-    process.stdout.write('\n');
-  }
-  
-  return hashes;
-}
-```
-
-**Risk Level:** 🟡 MEDIUM - Solvable with optimization
-
----
-
-### 4. Journal Migration - BREAKING CHANGE
-
-**The Problem:**
-
-Existing journals look like this:
-
-```json
-{
-  "entries": [
-    {
-      "feature": "charts",
-      "files": [
-        "/path/to/file1.tsx",
-        "/path/to/file2.tsx"
-      ]
-    }
-  ]
-}
-```
-
-New format needs hashes:
-
-```json
-{
-  "entries": [
-    {
-      "feature": "charts",
-      "files": [
-        { "path": "/path/to/file1.tsx", "hash": "abc123..." },
-        { "path": "/path/to/file2.tsx", "hash": "def456..." }
-      ]
-    }
-  ]
-}
-```
-
-**What Can Go Wrong:**
-
-```bash
-# User has old journal
-$ vf remove charts
-
-# CLI tries to read journal
-# Expects: files[0].path
-# Gets: files[0] (string)
-# Result: CRASH!
-```
-
-**Solution (Migration):**
-
-```typescript
-export async function readJournal(path: string): Promise<Journal> {
-  try {
-    const content = await readFileContent(path);
-    const journal = JSON.parse(content) as any;
-    
-    // Detect old format
-    const needsMigration = journal.entries.some((entry: any) => {
-      return entry.files.length > 0 && typeof entry.files[0] === 'string';
-    });
-    
-    if (needsMigration) {
-      log.info('Migrating journal to new format...');
-      
-      // Migrate each entry
-      for (const entry of journal.entries) {
-        if (typeof entry.files[0] === 'string') {
-          // Old format: array of strings
-          const oldFiles = entry.files as string[];
-          
-          // Hash existing files
-          const newFiles = [];
-          for (const filePath of oldFiles) {
-            const hash = await hashFile(filePath);
-            newFiles.push({ path: filePath, hash });
-          }
-          
-          entry.files = newFiles;
-        }
-      }
-      
-      // Save migrated journal
-      await writeJournal(path, journal);
-      log.success('Journal migrated successfully');
-    }
-    
-    return journal;
-    
-  } catch (err: any) {
-    if (err.code === 'ENOENT') {
-      return { entries: [] };
-    }
-    throw err;
-  }
-}
-```
-
-**Gotcha:**
-- Migration happens on first read
-- If files were deleted, we can't hash them (use empty hash)
-- Need to handle corrupted journals
-
-**Risk Level:** 🟡 MEDIUM - Need careful migration logic
-
----
-
-### 5. Interactive Prompts in CI/CD - HANGS
-
-**The Problem:**
-
-```bash
-# In CI/CD (GitHub Actions, etc.)
-$ vf add charts
-
-# CLI tries to prompt:
-Overwrite file? (y/N): _
-
-# But there's no TTY!
-# Result: Hangs forever, CI times out
-```
-
-**What Happens:**
-
-```typescript
-// This hangs in CI:
-const answer = readlineSync.question('Continue? (y/N): ');
-
-// Because:
-// - process.stdin.isTTY === false
-// - No user to answer
-// - readline waits forever
-```
-
-**Solution (Detection):**
-
-```typescript
-export function promptUser(question: string): string {
-  // Check if we're in a non-interactive environment
-  if (!process.stdin.isTTY) {
-    // CI/CD, piped input, etc.
-    log.warn('Non-interactive environment detected');
-    log.info('Use --yes flag to auto-confirm or --force to skip prompts');
-    return 'n'; // Default to safe option
-  }
-  
-  // Check for CI environment variables
-  const isCI = process.env.CI === 'true' || 
-               process.env.GITHUB_ACTIONS === 'true' ||
-               process.env.GITLAB_CI === 'true' ||
-               process.env.CIRCLECI === 'true';
-  
-  if (isCI) {
-    log.warn('CI environment detected');
-    return 'n';
-  }
-  
-  return readlineSync.question(question);
-}
-```
-
-**Risk Level:** 🟡 MEDIUM - Easy to detect and handle
-
----
-
-### 6. Navigation Markers Missing or Modified - BREAKS INJECTION
-
-**The Problem:**
-
-CLI expects these markers:
-
-```typescript
-// apps/native/src/app/(root)/(protected)/(tabs)/index.tsx
-
-const features = [
-  // --- @vibefast:navigation:start ---
-  // --- @vibefast:navigation:end ---
-];
-```
-
-**What If User:**
-
-1. **Deletes markers:**
-```typescript
-const features = [
-  // User removed the markers!
-];
-```
-
-2. **Modifies markers:**
-```typescript
-const features = [
-  // --- @vibefast:navigation:start --- (extra space)
-  // --- @vibefast:navigation:end ---
-];
-```
-
-3. **Moves markers:**
-```typescript
-// Markers are now in a different file!
-```
-
-**Result:**
-
-```bash
-$ vf add charts
-✗ Navigation markers not found!
-✗ Cannot inject navigation link
-```
-
-**Solution (Defensive):**
-
-```typescript
-export async function insertNavLinkNative(
-  navFile: string,
-  navData: any,
-  options?: { dryRun?: boolean }
-): Promise<boolean> {
-  // 1. Check if file exists
-  if (!await exists(navFile)) {
-    log.error(`Navigation file not found: ${navFile}`);
-    log.info('This feature requires navigation injection');
-    log.info('You may need to add the navigation link manually');
-    return false;
-  }
-  
-  // 2. Read file
-  const content = await readFileContent(navFile);
-  
-  // 3. Find markers (flexible regex)
-  const startMarker = /\/\/\s*---\s*@vibefast:navigation:start\s*---/;
-  const endMarker = /\/\/\s*---\s*@vibefast:navigation:end\s*---/;
-  
-  const hasStart = startMarker.test(content);
-  const hasEnd = endMarker.test(content);
-  
-  if (!hasStart || !hasEnd) {
-    log.error('Navigation markers not found in file');
-    log.info('Expected markers:');
-    log.plain('  // --- @vibefast:navigation:start ---');
-    log.plain('  // --- @vibefast:navigation:end ---');
-    log.plain('');
-    log.warn('⚠ Navigation link will NOT be added automatically');
-    log.info('You can add it manually:');
-    log.plain('');
-    log.plain(JSON.stringify(navData, null, 2));
-    log.plain('');
-    
-    // Don't fail the installation, just skip nav injection
-    return false;
-  }
-  
-  // 4. Inject navigation
-  // ... rest of logic
-  
-  return true;
-}
-```
-
-**Risk Level:** 🟢 LOW - Can be handled gracefully
-
----
-
-### 7. Package Version Conflicts - DEPENDENCY HELL
-
-**The Problem:**
-
-```bash
-# User's project has:
-"react-native-svg": "^12.0.0"
-
-# Feature needs:
-"react-native-svg": "^13.9.0"
-
-# What happens?
-$ pnpm add react-native-svg@^13.9.0
-
-# Result: Upgrades to 13.9.0
-# But: User's other code might break!
-```
-
-**Real Example:**
-
-```json
-// User's package.json
-{
-  "dependencies": {
-    "react-native-reanimated": "^2.0.0",
-    "react-native-svg": "^12.0.0"
-  }
-}
-
-// Feature needs:
-{
-  "dependencies": {
-    "react-native-svg": "^13.9.0"
-  }
-}
-
-// After install:
-{
-  "dependencies": {
-    "react-native-reanimated": "^2.0.0", // Might break with svg 13!
-    "react-native-svg": "^13.9.0"
-  }
-}
-```
-
-**Solution (Detection + Warning):**
-
-```typescript
-export async function checkVersionConflicts(
-  newPackages: Record<string, string>,
-  cwd: string
-): Promise<Array<{ package: string; current: string; new: string }>> {
-  const conflicts = [];
-  
-  const installed = await getInstalledPackages(cwd);
-  const packageJson = await readPackageJson(cwd);
-  
-  for (const [pkg, newVersion] of Object.entries(newPackages)) {
-    const currentVersion = packageJson.dependencies?.[pkg] || 
-                          packageJson.devDependencies?.[pkg];
-    
-    if (currentVersion && currentVersion !== newVersion) {
-      // Check if it's a major version change
-      const currentMajor = currentVersion.match(/\d+/)?.[0];
-      const newMajor = newVersion.match(/\d+/)?.[0];
-      
-      if (currentMajor !== newMajor) {
-        conflicts.push({
-          package: pkg,
-          current: currentVersion,
-          new: newVersion,
-        });
-      }
-    }
-  }
-  
-  return conflicts;
-}
-
-// Usage:
-const conflicts = await checkVersionConflicts(manifest.dependencies.npm, paths.cwd);
-
-if (conflicts.length > 0) {
-  log.warn('⚠ VERSION CONFLICTS DETECTED:');
-  log.plain('');
-  
-  conflicts.forEach(c => {
-    log.plain(`  ${c.package}`);
-    log.plain(`    Current: ${c.current}`);
-    log.plain(`    Required: ${c.new}`);
-  });
-  
-  log.plain('');
-  log.warn('Installing this feature will UPGRADE these packages');
-  log.warn('This might break existing code!');
-  log.plain('');
-  
-  const shouldContinue = promptYesNo('Continue anyway? (y/N): ', false);
-  if (!shouldContinue) {
-    log.info('Installation cancelled');
-    return;
-  }
-}
-```
-
-**Risk Level:** 🔴 HIGH - Can break user's app
-
----
-
-## 🟡 MEDIUM RISK Issues
-
-### 8. Watermark Breaks Syntax
-
-**Problem:**
-
-```typescript
-// Original file:
-export default function Chart() {
-  return <View />;
-}
-
-// After watermark:
-// vibefast license: abc-123
-export default function Chart() {
-  return <View />;
-}
-
-// Result: Syntax error! (no import for comment)
-```
-
-**Solution:** Always add watermark as first line
-
----
-
-### 9. Git Conflicts
-
-**Problem:**
-
-```bash
-# User has uncommitted changes
-$ vf add charts
-
-# CLI copies files
-# User's git status is now messy
-```
-
-**Solution:** Check git status first, warn user
-
----
-
-### 10. Disk Space
-
-**Problem:**
-
-```bash
-# Feature is 50MB
-# User has 10MB free
-$ vf add large-feature
-
-# Result: Disk full error mid-installation
-```
-
-**Solution:** Check available space before downloading
-
----
-
-## Summary: What's Actually Difficult?
-
-### 🔴 VERY DIFFICULT (Need Careful Implementation)
-
-1. **Monorepo package installation** - Different PMs, different commands
-2. **Version conflicts** - Can break user's app
-
-### 🟡 MODERATELY DIFFICULT (Need Good Error Handling)
-
-3. **TypeScript config variations** - Many edge cases
-4. **File hashing performance** - Need optimization
-5. **Journal migration** - Breaking change
-
-### 🟢 EASY (Standard Error Handling)
-
-6. **CI/CD detection** - Check TTY
-7. **Missing markers** - Graceful degradation
-8. **Watermark syntax** - Always prepend
-9. **Git conflicts** - Warn user
-10. **Disk space** - Check before download
-
----
-
-## Mitigation Strategy
-
-### For High-Risk Issues:
-
-1. **Extensive testing** with different monorepo setups
-2. **Dry-run mode** to preview changes
-3. **Clear warnings** about version conflicts
-4. **Rollback capability** (future feature)
-5. **Good documentation** for edge cases
-
-### For Medium-Risk Issues:
-
-1. **Defensive programming** (try/catch everywhere)
-2. **Graceful degradation** (skip features that fail)
-3. **Clear error messages** with solutions
-4. **Timeout handling** for slow operations
-
-### For Low-Risk Issues:
-
-1. **Standard error handling**
-2. **User-friendly messages**
-3. **Fallback options**
-
----
-
-## Recommendation
-
-**Start with MVP that avoids the hardest problems:**
-
-1. ✅ Require recipe.json dependencies (skip auto-detection initially)
-2. ✅ Warn about monorepos (let user install packages manually)
-3. ✅ Skip type checking if it fails (don't block installation)
-4. ✅ Gracefully handle missing markers (manual nav injection)
-
-**Then add advanced features:**
-
-1. Auto-detection with type checking
-2. Smart monorepo handling
-3. Version conflict detection
-4. Automatic rollback
-
-This way we ship fast and iterate based on real user feedback.