vibefast-cli 0.2.1 → 0.2.3

package/MANUAL-STEPS-GUIDE.md

@@ -0,0 +1,385 @@
+# Manual Steps Guide
+
+## What Are Manual Steps?
+
+Manual steps are instructions shown to users when a feature requires **external service configuration** that can't be automated. This is for features that need:
+
+- API keys from third-party services
+- Account creation on external platforms
+- Environment variables
+- Manual code modifications
+
+## When to Use Manual Steps
+
+### ✅ Use Manual Steps For:
+
+1. **Third-Party Services**
+   - Sentry (error tracking)
+   - PostHog (analytics)
+   - Stripe (payments)
+   - OpenAI (AI APIs)
+   - Firebase (backend services)
+   - Supabase (database)
+
+2. **API Keys & Secrets**
+   - Any feature requiring API keys
+   - OAuth credentials
+   - Webhook URLs
+   - Service tokens
+
+3. **External Accounts**
+   - Features requiring user to sign up elsewhere
+   - Services with manual approval process
+
+### ❌ Don't Use Manual Steps For:
+
+1. **Pure UI Components**
+   - Charts, graphs, visualizations
+   - UI widgets, buttons, forms
+   - Navigation components
+   - Layout components
+
+2. **Self-Contained Features**
+   - Quiz app (no external service)
+   - Tracker app (local storage)
+   - Audio recorder (device only)
+
+## How to Add Manual Steps
+
+### Recipe Format
+
+```json
+{
+  "name": "sentry",
+  "version": "1.0.0",
+  "description": "Error tracking with Sentry",
+  "target": "native",
+  
+  "copy": [
+    {
+      "from": "apps/native/src/features/sentry",
+      "to": "apps/native/src/features/sentry"
+    }
+  ],
+  
+  "dependencies": {
+    "expo": ["@sentry/react-native"]
+  },
+  
+  "env": [
+    {
+      "key": "SENTRY_DSN",
+      "description": "Your Sentry DSN for error tracking",
+      "example": "https://abc123@o123.ingest.sentry.io/456",
+      "link": "https://sentry.io/settings/projects/"
+    },
+    {
+      "key": "SENTRY_ORG",
+      "description": "Your Sentry organization slug",
+      "example": "my-company",
+      "link": "https://sentry.io/settings/"
+    }
+  ],
+  
+  "manualSteps": [
+    {
+      "title": "Create Sentry Account",
+      "description": "Sign up at sentry.io and create a new project for your app",
+      "link": "https://sentry.io/signup/"
+    },
+    {
+      "title": "Get Your DSN",
+      "description": "Copy your DSN from Project Settings > Client Keys (DSN)",
+      "link": "https://sentry.io/settings/"
+    },
+    {
+      "title": "Add Environment Variables",
+      "description": "Add SENTRY_DSN and SENTRY_ORG to your .env file",
+      "file": ".env",
+      "content": "SENTRY_DSN=your-dsn-here\nSENTRY_ORG=your-org-slug"
+    },
+    {
+      "title": "Initialize Sentry",
+      "description": "Import and initialize Sentry in your app entry point",
+      "file": "apps/native/src/app/_layout.tsx",
+      "content": "import { initSentry } from '@/features/sentry';\ninitSentry();"
+    }
+  ],
+  
+  "postInstall": {
+    "message": "Sentry is installed! Complete the manual steps to start tracking errors."
+  }
+}
+```
+
+### Field Descriptions
+
+#### `env` Array
+Each environment variable needs:
+- `key` (required): The env var name (e.g., "SENTRY_DSN")
+- `description` (required): What this variable is for
+- `example` (required): Example value to show format
+- `link` (optional): URL where to get this value
+
+#### `manualSteps` Array
+Each step needs:
+- `title` (required): Short step title
+- `description` (required): Detailed instructions
+- `link` (optional): URL for more info or to perform action
+- `file` (optional): File to modify
+- `content` (optional): Code/text to add to the file
+
+## User Experience
+
+### During Installation
+
+When a user runs `vf add sentry`, they see:
+
+```bash
+✓ sentry installed successfully!
+ℹ Files added: 5
+
+⚠ This feature requires additional packages
+
+📦 Required packages:
+  • @sentry/react-native
+
+Install with:
+  npx expo install @sentry/react-native
+
+💡 Expo will automatically pick compatible versions
+
+⚠ MANUAL STEPS REQUIRED:
+
+This feature requires some manual configuration:
+
+Step 1: Create Sentry Account
+  Sign up at sentry.io and create a new project for your app
+  🔗 https://sentry.io/signup/
+
+Step 2: Get Your DSN
+  Copy your DSN from Project Settings > Client Keys (DSN)
+  🔗 https://sentry.io/settings/
+
+Step 3: Add Environment Variables
+  Add SENTRY_DSN and SENTRY_ORG to your .env file
+  📝 File: .env
+  Add: SENTRY_DSN=your-dsn-here
+       SENTRY_ORG=your-org-slug
+
+Step 4: Initialize Sentry
+  Import and initialize Sentry in your app entry point
+  📝 File: apps/native/src/app/_layout.tsx
+  Add: import { initSentry } from '@/features/sentry';
+       initSentry();
+
+⚠ REQUIRED ENVIRONMENT VARIABLES:
+
+  SENTRY_DSN
+    Your Sentry DSN for error tracking
+    Example: https://abc123@o123.ingest.sentry.io/456
+    Get it: https://sentry.io/settings/projects/
+
+  SENTRY_ORG
+    Your Sentry organization slug
+    Example: my-company
+    Get it: https://sentry.io/settings/
+
+Add these to your .env file
+
+💡 Run 'vf checklist sentry' to see these steps again
+```
+
+### Later Reference
+
+User can run `vf checklist sentry` anytime to see the steps again:
+
+```bash
+$ vf checklist sentry
+
+Manual setup steps for sentry:
+
+Step 1: Create Sentry Account
+  Sign up at sentry.io and create a new project for your app
+  🔗 https://sentry.io/signup/
+
+Step 2: Get Your DSN
+  Copy your DSN from Project Settings > Client Keys (DSN)
+  🔗 https://sentry.io/settings/
+
+...
+```
+
+### Status Command
+
+The status command shows which features have pending manual steps:
+
+```bash
+$ vf status
+
+Installed features:
+
+  ✓ charts (v1.0.0) - native
+    Files: 17
+    Installed: 11/14/2024
+
+  ✓ sentry (v1.2.0) - native
+    Files: 5
+    Installed: 11/14/2024
+    ⚠ Has manual setup steps (run: vf checklist sentry)
+
+Total: 2 feature(s) installed
+```
+
+## Real-World Examples
+
+### Example 1: PostHog Analytics
+
+```json
+{
+  "name": "posthog",
+  "env": [
+    {
+      "key": "POSTHOG_API_KEY",
+      "description": "Your PostHog project API key",
+      "example": "phc_abc123xyz",
+      "link": "https://app.posthog.com/project/settings"
+    },
+    {
+      "key": "POSTHOG_HOST",
+      "description": "PostHog instance URL",
+      "example": "https://app.posthog.com",
+      "link": "https://posthog.com/docs/getting-started/cloud"
+    }
+  ],
+  "manualSteps": [
+    {
+      "title": "Create PostHog Account",
+      "description": "Sign up at posthog.com and create a project",
+      "link": "https://app.posthog.com/signup"
+    },
+    {
+      "title": "Get API Key",
+      "description": "Copy your Project API Key from Settings",
+      "link": "https://app.posthog.com/project/settings"
+    }
+  ]
+}
+```
+
+### Example 2: Stripe Payments
+
+```json
+{
+  "name": "stripe-checkout",
+  "env": [
+    {
+      "key": "STRIPE_PUBLISHABLE_KEY",
+      "description": "Your Stripe publishable key (starts with pk_)",
+      "example": "pk_test_abc123",
+      "link": "https://dashboard.stripe.com/apikeys"
+    },
+    {
+      "key": "STRIPE_SECRET_KEY",
+      "description": "Your Stripe secret key (starts with sk_) - KEEP SECRET!",
+      "example": "sk_test_xyz789",
+      "link": "https://dashboard.stripe.com/apikeys"
+    }
+  ],
+  "manualSteps": [
+    {
+      "title": "Create Stripe Account",
+      "description": "Sign up at stripe.com and complete account setup",
+      "link": "https://dashboard.stripe.com/register"
+    },
+    {
+      "title": "Get API Keys",
+      "description": "Get your test keys from the Stripe Dashboard",
+      "link": "https://dashboard.stripe.com/apikeys"
+    },
+    {
+      "title": "Configure Webhooks",
+      "description": "Set up webhook endpoint for payment events",
+      "link": "https://dashboard.stripe.com/webhooks"
+    }
+  ]
+}
+```
+
+### Example 3: OpenAI Integration
+
+```json
+{
+  "name": "ai-chat",
+  "env": [
+    {
+      "key": "OPENAI_API_KEY",
+      "description": "Your OpenAI API key",
+      "example": "sk-proj-abc123xyz",
+      "link": "https://platform.openai.com/api-keys"
+    }
+  ],
+  "manualSteps": [
+    {
+      "title": "Create OpenAI Account",
+      "description": "Sign up at platform.openai.com",
+      "link": "https://platform.openai.com/signup"
+    },
+    {
+      "title": "Add Payment Method",
+      "description": "Add a payment method to enable API access",
+      "link": "https://platform.openai.com/account/billing"
+    },
+    {
+      "title": "Generate API Key",
+      "description": "Create a new API key from your account settings",
+      "link": "https://platform.openai.com/api-keys"
+    }
+  ]
+}
+```
+
+## Best Practices
+
+### 1. Be Specific
+❌ Bad: "Get your API key"
+✅ Good: "Copy your Project API Key from Settings > API Keys"
+
+### 2. Include Links
+Always provide direct links to:
+- Sign up pages
+- Settings pages
+- Documentation
+- API key pages
+
+### 3. Show Examples
+Always include example values so users know the format:
+```json
+{
+  "example": "https://abc123@o123.ingest.sentry.io/456"
+}
+```
+
+### 4. Order Steps Logically
+1. Create account
+2. Get credentials
+3. Add to .env
+4. Initialize in code
+
+### 5. Warn About Secrets
+For sensitive keys, add warnings:
+```json
+{
+  "description": "Your Stripe secret key (starts with sk_) - KEEP SECRET! Never commit to Git!"
+}
+```
+
+## Summary
+
+- **Use manual steps** for features requiring external services, API keys, or accounts
+- **Don't use** for pure UI components or self-contained features
+- **Be specific** with instructions and always include links
+- **Show examples** so users know what format to expect
+- Users can run `vf checklist <feature>` anytime to see steps again
+
+Your current features (charts, chatbot, quiz, etc.) don't need manual steps because they're self-contained UI components!

package/MANUAL-STEPS-USER-FLOW.md

@@ -0,0 +1,231 @@
+# How Users Access Manual Steps
+
+## The User Journey
+
+### Step 1: User Installs a Feature
+
+```bash
+$ vf add sentry
+```
+
+### Step 2: CLI Shows Manual Steps Automatically
+
+After installation completes, the CLI **automatically displays** manual steps:
+
+```bash
+✓ sentry installed successfully!
+ℹ Files added: 5
+
+⚠ This feature requires additional packages
+
+📦 Required packages:
+  • @sentry/react-native
+
+Install with:
+  npx expo install @sentry/react-native
+
+💡 Expo will automatically pick compatible versions
+
+
+⚠ MANUAL STEPS REQUIRED:
+
+This feature requires some manual configuration:
+
+Step 1: Create Sentry Account
+  Sign up at sentry.io and create a new project for your app
+  🔗 https://sentry.io/signup/
+
+Step 2: Get Your DSN
+  Copy your DSN from Project Settings > Client Keys (DSN)
+  🔗 https://sentry.io/settings/
+
+Step 3: Add Environment Variables
+  Add SENTRY_DSN to your .env file
+  📝 File: .env
+  Add: SENTRY_DSN=your-dsn-here
+
+⚠ REQUIRED ENVIRONMENT VARIABLES:
+
+  SENTRY_DSN
+    Your Sentry DSN for error tracking
+    Example: https://abc123@o123.ingest.sentry.io/456
+    Get it: https://sentry.io/settings/projects/
+
+Add these to your .env file
+
+💡 Run 'vf checklist sentry' to see these steps again
+```
+
+**Key Point:** Users see manual steps **immediately** after installation. They don't need to look for them!
+
+---
+
+### Step 3: User Forgets Steps (Later)
+
+A week later, user wants to see the steps again:
+
+```bash
+$ vf checklist sentry
+```
+
+Output:
+```bash
+Manual setup steps for sentry:
+
+Step 1: Create Sentry Account
+  Sign up at sentry.io and create a new project for your app
+  🔗 https://sentry.io/signup/
+
+Step 2: Get Your DSN
+  Copy your DSN from Project Settings > Client Keys (DSN)
+  🔗 https://sentry.io/settings/
+
+Step 3: Add Environment Variables
+  Add SENTRY_DSN to your .env file
+  📝 File: .env
+  Add: SENTRY_DSN=your-dsn-here
+
+⚠ REQUIRED ENVIRONMENT VARIABLES:
+
+  SENTRY_DSN
+    Your Sentry DSN for error tracking
+    Example: https://abc123@o123.ingest.sentry.io/456
+    Get it: https://sentry.io/settings/projects/
+
+Add these to your .env file
+```
+
+---
+
+### Step 4: User Checks Status
+
+User can see which features have pending manual steps:
+
+```bash
+$ vf status
+```
+
+Output:
+```bash
+Installed features:
+
+  ✓ charts (v1.0.0) - native
+    Files: 17
+    Installed: 11/14/2024
+
+  ✓ sentry (v1.2.0) - native
+    Files: 5
+    Installed: 11/14/2024
+    ⚠ Has manual setup steps (run: vf checklist sentry)
+
+Total: 2 feature(s) installed
+```
+
+The warning `⚠ Has manual setup steps` reminds them!
+
+---
+
+## Discovery Methods
+
+Users can discover manual steps through **3 ways**:
+
+### 1. Automatic Display (Primary)
+✅ **Shown immediately after `vf add`**
+- User can't miss it
+- Displayed in a clear, formatted way
+- Includes helpful links
+
+### 2. Checklist Command (Reference)
+✅ **Run `vf checklist <feature>` anytime**
+- See steps again later
+- No need to reinstall
+- Stored in journal
+
+### 3. Status Command (Discovery)
+✅ **Run `vf status` to see which features need setup**
+- Shows warning indicator
+- Tells user to run checklist command
+- Quick overview
+
+---
+
+## Example: Complete User Flow
+
+### Scenario: User installs Sentry
+
+```bash
+# 1. Install feature
+$ vf add sentry
+
+# Output shows manual steps immediately
+⚠ MANUAL STEPS REQUIRED:
+Step 1: Create Sentry Account...
+💡 Run 'vf checklist sentry' to see these steps again
+
+# 2. User follows steps, creates account, gets DSN
+
+# 3. User adds to .env
+$ echo "SENTRY_DSN=https://abc@xyz.ingest.sentry.io/123" >> .env
+
+# 4. Week later, user forgets DSN format
+$ vf checklist sentry
+
+# Shows steps again with example format
+Example: https://abc123@o123.ingest.sentry.io/456
+
+# 5. User checks all installed features
+$ vf status
+
+Installed features:
+  ✓ sentry (v1.2.0) - native
+    ⚠ Has manual setup steps (run: vf checklist sentry)
+```
+
+---
+
+## For Features WITHOUT Manual Steps
+
+Most features (charts, chatbot, quiz) don't need manual steps:
+
+```bash
+$ vf add charts
+
+✓ charts installed successfully!
+ℹ Files added: 17
+
+⚠ This feature requires additional packages
+
+📦 Required packages:
+  • @shopify/react-native-skia
+  • react-native-svg
+
+Install with:
+  npx expo install @shopify/react-native-skia react-native-svg
+
+# No manual steps shown - just install packages and you're done!
+```
+
+---
+
+## Summary
+
+**Users access manual steps through:**
+
+1. **Automatic display** - Shown right after `vf add` (can't miss it!)
+2. **`vf checklist <feature>`** - See steps again anytime
+3. **`vf status`** - Reminder that steps exist
+
+**No searching required!** The CLI guides users through the entire process.
+
+---
+
+## For Recipe Creators
+
+When you create a recipe with manual steps:
+
+1. Add `manualSteps` and `env` to recipe.json
+2. CLI automatically shows them after installation
+3. CLI stores them in journal for later reference
+4. Users can access them anytime with `vf checklist`
+
+See [MANUAL-STEPS-GUIDE.md](MANUAL-STEPS-GUIDE.md) for details on creating recipes with manual steps.