vibefast-cli 1.2.1 → 1.3.1

package/docs/archive/USER-MODIFICATIONS.md

@@ -1,448 +0,0 @@
-# 🔧 User Modifications & File Management
-
-## What is mini-native?
-
-**mini-native** is a **demo/test feature** used for testing the VibeFast CLI. It's not a real production feature, but rather a minimal example to validate the entire installation flow.
-
-### Purpose
-- Test the CLI installation process
-- Validate the worker API
-- Demonstrate the recipe format
-- Used in E2E tests and documentation examples
-
-### What it contains
-```json
-{
-  "name": "mini-native",
-  "version": "0.1.0",
-  "description": "Demo feature (Expo)",
-  "copy": [
-    {
-      "from": "apps/native/src/app/mini",
-      "to": "apps/native/src/app/(root)/(protected)/mini"
-    }
-  ],
-  "nav": {
-    "href": "/(root)/(protected)/mini",
-    "label": "Mini"
-  },
-  "target": "native"
-}
-```
-
-It's essentially a single screen/page that gets installed to demonstrate that the CLI works correctly.
-
----
-
-## What Happens When Users Modify Files?
-
-This is a **critical question** about the CLI's behavior. Here's the complete breakdown:
-
-### Scenario 1: User Modifies Files After Installation
-
-```
-Day 1: Install charts
-$ vf add charts
-✓ 17 files installed
-
-Day 5: User edits files
-User modifies: apps/native/src/app/(root)/(protected)/charts/index.tsx
-- Adds custom styling
-- Removes some components
-- Adds new features
-
-Day 10: User removes charts
-$ vf remove charts
-```
-
-**What happens?**
-
-### ⚠️ The CLI Will Delete ALL Files - Including User Modifications!
-
-The CLI **does NOT track file modifications**. Here's why:
-
-```typescript
-// From src/core/fsx.ts
-export async function deleteFile(path: string): Promise<void> {
-  try {
-    await rm(path, { recursive: true, force: true });
-  } catch (err: any) {
-    if (err.code !== 'ENOENT') throw err;
-  }
-}
-```
-
-```typescript
-// From src/commands/remove.ts
-// Delete files
-for (const file of entry.files) {
-  log.info(`Deleting ${file}`);
-  if (!options.dryRun) {
-    await deleteFile(file);
-  }
-}
-```
-
-### How It Works
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    FILE DELETION PROCESS                         │
-└─────────────────────────────────────────────────────────────────┘
-
-Step 1: Read Journal
-┌──────────────────────────────────────────────────────────────┐
-│  .vibefast/journal.json contains:                            │
-│  {                                                            │
-│    "feature": "charts",                                      │
-│    "files": [                                                │
-│      "/path/to/apps/native/src/app/charts/index.tsx",       │
-│      "/path/to/apps/native/src/app/charts/chart-card.tsx",  │
-│      ... (15 more files)                                     │
-│    ]                                                         │
-│  }                                                           │
-└──────────────────────────────────────────────────────────────┘
-
-Step 2: Delete Each File
-┌──────────────────────────────────────────────────────────────┐
-│  For each file in the list:                                  │
-│  • No check if file was modified                             │
-│  • No backup created                                         │
-│  • No diff comparison                                        │
-│  • Just: rm -rf <file>                                       │
-│                                                               │
-│  Result: ALL files deleted, regardless of modifications      │
-└──────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Scenario 2: Reinstalling After Modifications
-
-```
-Day 1: Install charts
-$ vf add charts
-✓ 17 files installed
-
-Day 5: User modifies files
-User edits multiple chart files
-
-Day 10: User tries to reinstall
-$ vf add charts
-⚠ charts is already installed for native
-ℹ Use --force to reinstall
-```
-
-### Using --force Flag
-
-```bash
-$ vf add charts --force
-```
-
-**What happens?**
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    FORCE REINSTALL PROCESS                       │
-└─────────────────────────────────────────────────────────────────┘
-
-Step 1: Check Existing Installation
-┌──────────────────────────────────────────────────────────────┐
-│  Journal shows charts is installed                           │
-│  BUT --force flag is present                                 │
-│  → Skip the "already installed" warning                      │
-│  → Proceed with installation                                 │
-└──────────────────────────────────────────────────────────────┘
-
-Step 2: Copy Files (with force)
-┌──────────────────────────────────────────────────────────────┐
-│  From src/core/fsx.ts:                                       │
-│                                                               │
-│  if (destExists && !options?.force) {                        │
-│    throw new Error(`File exists: ${destPath}`);              │
-│  }                                                           │
-│                                                               │
-│  With --force:                                               │
-│  • Existing files are OVERWRITTEN                            │
-│  • User modifications are LOST                               │
-│  • No backup is created                                      │
-│  • Fresh files from recipe replace everything                │
-└──────────────────────────────────────────────────────────────┘
-
-Step 3: Update Journal
-┌──────────────────────────────────────────────────────────────┐
-│  Journal is updated with new file list                       │
-│  (Usually the same files, but fresh timestamps)              │
-└──────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Scenario 3: User Deletes Some Files Manually
-
-```
-Day 1: Install charts (17 files)
-$ vf add charts
-
-Day 5: User manually deletes 3 files
-User removes:
-- chart-card.tsx
-- chart-utils.ts
-- chart-types.ts
-
-Day 10: User removes charts
-$ vf remove charts
-```
-
-**What happens?**
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    PARTIAL FILE DELETION                         │
-└─────────────────────────────────────────────────────────────────┘
-
-The CLI tries to delete ALL 17 files from journal:
-┌──────────────────────────────────────────────────────────────┐
-│  File 1: index.tsx                    → Deleted ✓            │
-│  File 2: chart-card.tsx               → Already gone (OK)    │
-│  File 3: chart-utils.ts               → Already gone (OK)    │
-│  File 4: chart-types.ts               → Already gone (OK)    │
-│  File 5: chart-preview.tsx            → Deleted ✓            │
-│  ... (continue for remaining files)                          │
-│                                                               │
-│  From src/core/fsx.ts:                                       │
-│  catch (err: any) {                                          │
-│    if (err.code !== 'ENOENT') throw err;                     │
-│  }                                                           │
-│                                                               │
-│  ENOENT = "File not found" → Silently ignored               │
-│  Result: No error, removal completes successfully            │
-└──────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Scenario 4: User Adds New Files to Feature Directory
-
-```
-Day 1: Install charts (17 files)
-$ vf add charts
-
-Day 5: User adds custom files
-User creates:
-- apps/native/src/app/charts/my-custom-chart.tsx
-- apps/native/src/app/charts/my-utils.ts
-- apps/native/src/features/charts/my-hook.ts
-
-Day 10: User removes charts
-$ vf remove charts
-```
-
-**What happens?**
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    ORPHANED FILES PROBLEM                        │
-└─────────────────────────────────────────────────────────────────┘
-
-The CLI only deletes tracked files:
-┌──────────────────────────────────────────────────────────────┐
-│  Journal contains 17 original files                          │
-│  CLI deletes those 17 files                                  │
-│                                                               │
-│  User's custom files are NOT in journal:                     │
-│  • my-custom-chart.tsx     → NOT DELETED (orphaned)          │
-│  • my-utils.ts             → NOT DELETED (orphaned)          │
-│  • my-hook.ts              → NOT DELETED (orphaned)          │
-│                                                               │
-│  Result:                                                      │
-│  ✓ Original 17 files deleted                                 │
-│  ⚠ User's 3 custom files remain in the directory             │
-│  ⚠ Empty directories may remain                              │
-└──────────────────────────────────────────────────────────────┘
-```
-
----
-
-## The Problem: No Modification Tracking
-
-### What the CLI Does NOT Do
-
-```
-❌ Does NOT check if files were modified
-❌ Does NOT create backups before deletion
-❌ Does NOT warn about modified files
-❌ Does NOT track user-added files
-❌ Does NOT show diffs
-❌ Does NOT ask for confirmation (except dry-run)
-❌ Does NOT preserve user changes
-```
-
-### What the CLI DOES Do
-
-```
-✓ Tracks original file paths in journal
-✓ Deletes files by path (regardless of content)
-✓ Ignores missing files (ENOENT)
-✓ Supports --dry-run to preview
-✓ Supports --force to overwrite
-```
-
----
-
-## Best Practices for Users
-
-### 1. Use Version Control (Git)
-
-```bash
-# Before installing any feature
-$ git status
-$ git commit -am "Before installing charts"
-
-# Install feature
-$ vf add charts
-
-# Review changes
-$ git diff
-$ git add .
-$ git commit -m "Add charts feature"
-
-# If you modify files
-$ git commit -am "Customize charts"
-
-# If you want to remove
-$ vf remove charts
-$ git diff  # See what was deleted
-$ git checkout -- .  # Restore if needed
-```
-
-### 2. Use --dry-run Before Operations
-
-```bash
-# Preview installation
-$ vf add charts --dry-run
-[DRY RUN] No changes will be made
-ℹ Files that would be added: 17
-
-# Preview removal
-$ vf remove charts --dry-run
-[DRY RUN] No changes will be made
-ℹ Files that would be deleted: 17
-```
-
-### 3. Don't Modify Feature Files Directly
-
-**Instead of modifying feature files:**
-```
-❌ apps/native/src/features/charts/chart-card.tsx
-```
-
-**Create wrapper components:**
-```
-✓ apps/native/src/components/custom-chart-card.tsx
-```
-
-This way:
-- Feature files remain untouched
-- Your customizations are separate
-- Removal doesn't affect your code
-- Updates are easier
-
-### 4. Fork Features Into Your Own Code
-
-If you need heavy customization:
-
-```bash
-# Install feature
-$ vf add charts
-
-# Copy to your own directory
-$ cp -r apps/native/src/features/charts apps/native/src/features/my-charts
-
-# Remove original
-$ vf remove charts
-
-# Now you own the code completely
-```
-
----
-
-## Potential Improvements (Not Currently Implemented)
-
-### Idea 1: Modification Detection
-
-```typescript
-// Hypothetical future feature
-interface JournalEntry {
-  feature: string;
-  files: Array<{
-    path: string;
-    hash: string;  // SHA-256 of original content
-  }>;
-}
-
-// Before removal, check:
-for (const file of entry.files) {
-  const currentHash = await hashFile(file.path);
-  if (currentHash !== file.hash) {
-    log.warn(`${file.path} was modified by user`);
-    // Ask for confirmation or create backup
-  }
-}
-```
-
-### Idea 2: Backup Before Deletion
-
-```typescript
-// Hypothetical future feature
-$ vf remove charts --backup
-
-// Creates:
-.vibefast/backups/charts-2024-11-13/
-  ├── index.tsx
-  ├── chart-card.tsx
-  └── ...
-```
-
-### Idea 3: Smart Merge on Reinstall
-
-```typescript
-// Hypothetical future feature
-$ vf add charts --force --merge
-
-// Would:
-// 1. Detect modifications
-// 2. Create .orig files
-// 3. Install new version
-// 4. Show merge conflicts
-```
-
----
-
-## Summary
-
-### mini-native
-- Demo/test feature for CLI validation
-- Contains minimal code (single screen)
-- Used in examples and tests
-- Not a production feature
-
-### User Modifications
-- **CLI does NOT track modifications**
-- `vf remove` deletes ALL tracked files (modified or not)
-- `vf add --force` overwrites ALL files (losing modifications)
-- User-added files are orphaned (not deleted)
-- **Best practice: Use Git for safety**
-- **Best practice: Don't modify feature files directly**
-
-### Key Takeaway
-
-The VibeFast CLI treats features as **atomic units**:
-- Install = Copy all files
-- Remove = Delete all files
-- No middle ground, no modification tracking
-
-This is simple and predictable, but requires users to:
-1. Use version control
-2. Keep customizations separate
-3. Understand that modifications will be lost on remove/reinstall

package/docs/decisions.md

@@ -1,55 +0,0 @@
-# VibeFast CLI — Decisions & Ground Rules
-
-## Package Details
-- **Package name:** `vibefast-cli`
-- **Binary alias:** `vf`
-- **Default target:** `native` (override with `--target web`)
-
-## Authentication
-- **Method:** Fixed opaque token per customer
-- **Device slots:** 2 by default
-- **Storage:** Cloudflare Worker validates token/seat → issues short-lived signed URL to recipe zip in R2/KV
-
-## Repository Signature
-Requires `.vibefast/starter.json`:
-```json
-{
-  "name": "vibefast",
-  "version": "1.0.0",
-  "targets": ["native", "web"]
-}
-```
-
-## Code Markers
-
-### Native Target
-File: `apps/native/src/app/(root)/(protected)/(tabs)/index.tsx`
-```tsx
-// --- @vibefast:navigation:start ---
-{/* CLI will inject feature links here */}
-// --- @vibefast:navigation:end ---
-```
-
-### Web Target
-File: `apps/web/app/page.tsx`
-```tsx
-{/* @vibefast:nav:start */}
-{/* CLI will inject feature cards here */}
-{/* @vibefast:nav:end */}
-```
-
-## Journal
-- **Location:** `.vibefast/journal.json`
-- **Purpose:** Tracks installed files and nav inserts
-
-## Rate Limits
-- **Daily:** 500 requests per token
-- **Per minute:** 30 requests per token
-- Subject to tuning based on usage patterns
-
-## Delivery Architecture
-1. CLI sends token + device info to Cloudflare Worker
-2. Worker validates token and checks device slots
-3. Worker issues short-lived signed URL to recipe zip in R2/KV
-4. CLI downloads and extracts recipe
-5. CLI applies codemod and updates journal

package/docs/manual-testing.md

@@ -1,91 +0,0 @@
-# Manual Testing Guide
-
-This guide explains how to manually test the `vibefast-cli` during development without affecting your globally installed version (if any).
-
-## Prerequisites
-
-- You are in the `vibefast-cli` directory.
-- You have run `npm install`.
-
-## Method 1: The "Alias" Method (Recommended)
-
-This method allows you to run your local build as `vf-dev` without overwriting your global `vf` command.
-
-1.  **Build the CLI**:
-
-    ```bash
-    npm run build
-    ```
-
-2.  **Create an Alias** (run this in your terminal):
-
-    ```bash
-    # Run this inside the vibefast-cli directory
-    alias vf-dev="node $(pwd)/dist/index.js"
-    ```
-
-3.  **Test in a Sandbox**:
-
-    ```bash
-    # Go to a temporary directory
-    mkdir ~/Desktop/vf-playground
-    cd ~/Desktop/vf-playground
-
-    # Run your local CLI
-    vf-dev init
-    vf-dev add chatbot
-    ```
-
-## Method 2: The "Link" Method
-
-Use this if you want to replace your global `vf` command with your local version.
-
-1.  **Build**:
-
-    ```bash
-    npm run build
-    ```
-
-2.  **Link**:
-
-    ```bash
-    npm link
-    ```
-
-3.  **Test**:
-    Now `vf` runs your local code anywhere.
-
-4.  **Unlink (Revert)**:
-    ```bash
-    npm unlink -g vibefast-cli
-    # Then reinstall the production version if needed
-    npm i -g vibefast-cli
-    ```
-
-## What to Test?
-
-### 1. Initialization
-
-- Run `vf init`.
-- Check if `.vibefast/starter.json` is created.
-- Check if it asks for a license key (if not already saved).
-
-### 2. Adding Features
-
-- Run `vf add <feature>`.
-- **Verify**:
-  - Files are copied to `apps/native` or `apps/web`.
-  - `app.config.ts` (Native) has the plugin added (if applicable).
-  - `package.json` dependencies are updated (or prompted).
-
-### 3. Removing Features
-
-- Run `vf remove <feature>`.
-- **Verify**:
-  - Files are deleted.
-  - `app.config.ts` plugin is removed (if implemented) or you are warned.
-
-### 4. Edge Cases
-
-- Run in a folder that is _not_ a VibeFast project (should fail gracefully).
-- Run with invalid arguments.

package/docs/next-steps.md

@@ -1,12 +0,0 @@
-# CLI Next Steps Backlog
-
-Work on these items is tracked here so contributors can see what remains after the initial implementation. Update the status column when a task is started or complete.
-
-| Status | Task | Details | Owner |
-| --- | --- | --- | --- |
-| 🟡 Open | Test with real features | Create example recipes (charts, Sentry, PostHog, etc.) and run the full install/remove flow against them to validate the experience end-to-end. | TBD |
-| 🟡 Open | Update documentation | Expand `README.md` (and related docs) with the latest commands, flags, and troubleshooting notes captured in version `0.2.2`. | TBD |
-| 🟡 Open | Create example recipes | Publish representative zips that can be shared internally and used in automated tests. | TBD |
-| 🟡 Open | Publish to npm | Bump the package version, run the build pipeline, and push a new release to the npm registry. | TBD |
-| 🟡 Open | Get user feedback | Share the CLI with pilot customers, collect their notes, and iterate on UX/edge cases. | TBD |
-