vibefast-cli 0.2.4 → 0.3.1

package/RECIPES-GUIDE.md

@@ -0,0 +1,325 @@
+# VibeFast Service Recipes Guide
+
+## Overview
+
+Service recipes are JSON configuration files that define setup instructions and environment variables for third-party services like Sentry, PostHog, Stripe, Auth0, and Firebase.
+
+## What's Included
+
+### Service Recipes Created
+
+1. **Sentry** (`recipes/sentry.json`)
+   - Error tracking and performance monitoring
+   - 6 setup steps
+   - 3 environment variables
+
+2. **PostHog** (`recipes/posthog.json`)
+   - Product analytics and feature flags
+   - 6 setup steps
+   - 3 environment variables
+
+3. **Stripe** (`recipes/stripe.json`)
+   - Payment processing
+   - 6 setup steps
+   - 3 environment variables
+
+4. **Auth0** (`recipes/auth0.json`)
+   - Authentication and authorization
+   - 6 setup steps
+   - 4 environment variables
+
+5. **Firebase** (`recipes/firebase.json`)
+   - Backend services (Auth, Firestore, Storage)
+   - 6 setup steps
+   - 6 environment variables
+
+## How to Use
+
+### View Setup Instructions
+
+```bash
+# View Sentry setup steps
+vf checklist sentry
+
+# View PostHog setup steps
+vf checklist posthog
+
+# View Stripe setup steps
+vf checklist stripe
+
+# View Auth0 setup steps
+vf checklist auth0
+
+# View Firebase setup steps
+vf checklist firebase
+```
+
+### List All Available Services
+
+```bash
+vf list
+```
+
+Shows all available services including native features, web features, and service integrations.
+
+### Setup Environment Variables
+
+```bash
+# Interactive environment setup
+vf env
+
+# Setup for specific target
+vf env --target native
+vf env --target web
+```
+
+## Recipe Structure
+
+Each recipe includes:
+
+### Manual Setup Steps
+- Clear, actionable instructions
+- Links to official documentation
+- File locations to edit
+- Example values to add
+
+### Environment Variables
+- Variable name and description
+- Example values
+- Required vs optional
+- Links to where to get values
+
+### Post-Installation Message
+- Success confirmation
+- Next steps guidance
+
+## Example: Setting Up Sentry
+
+```bash
+# 1. View setup steps
+vf checklist sentry
+
+# Output shows:
+# Step 1: Create Sentry Account
+# Step 2: Create a New Project
+# Step 3: Get Your DSN
+# Step 4: Add DSN to Environment
+# Step 5: Initialize Sentry in Your App
+# Step 6: Test Integration
+
+# 2. Setup environment variables
+vf env
+
+# When prompted for SENTRY_DSN:
+# Enter your DSN from Sentry dashboard
+
+# 3. Initialize in your app
+# Follow the documentation link provided
+```
+
+## Integration with CLI
+
+### How It Works
+
+1. **User runs command**
+   ```bash
+   vf checklist sentry
+   ```
+
+2. **CLI fetches recipe from API**
+   - Looks up recipe by name
+   - Retrieves setup steps and env vars
+
+3. **CLI displays information**
+   - Shows all setup steps
+   - Lists required environment variables
+   - Provides documentation links
+
+4. **User follows steps**
+   - Creates service account
+   - Gets credentials
+   - Adds to .env file
+   - Initializes in app
+
+## Adding New Recipes
+
+### Step 1: Create Recipe File
+
+Create `recipes/service-name.json`:
+
+```json
+{
+  "name": "service-name",
+  "version": "1.0.0",
+  "description": "Service description",
+  "target": "service",
+  "manualSteps": [
+    {
+      "title": "Step 1",
+      "description": "Description",
+      "link": "https://docs.example.com"
+    }
+  ],
+  "env": [
+    {
+      "key": "SERVICE_API_KEY",
+      "description": "API key for service",
+      "example": "example-key",
+      "required": true,
+      "link": "https://dashboard.example.com"
+    }
+  ],
+  "postInstall": {
+    "message": "✅ Service configured!"
+  }
+}
+```
+
+### Step 2: Test Locally
+
+```bash
+vf checklist service-name
+```
+
+### Step 3: Deploy to Backend
+
+Add recipe to VibeFast API so it's available to all users.
+
+## Best Practices
+
+### Setup Steps
+- ✅ Be specific and actionable
+- ✅ Include official documentation links
+- ✅ Specify which files to edit
+- ✅ Provide example values
+- ❌ Don't include real secrets
+- ❌ Don't assume user knowledge
+
+### Environment Variables
+- ✅ Use clear, descriptive names
+- ✅ Include example values
+- ✅ Mark required vs optional
+- ✅ Provide links to get values
+- ❌ Never include real API keys
+- ❌ Don't use vague descriptions
+
+### Documentation
+- ✅ Link to official docs
+- ✅ Link to setup guides
+- ✅ Link to dashboards
+- ✅ Keep links up-to-date
+- ❌ Don't link to outdated docs
+- ❌ Don't assume users know the service
+
+## Troubleshooting
+
+### Recipe Not Found
+
+```bash
+$ vf checklist unknown-service
+
+✗ unknown-service not found
+ℹ Run "vf list" to see available features
+ℹ Run "vf status" to see installed features
+```
+
+**Solution:** Check the service name with `vf list`
+
+### Missing Environment Variables
+
+```bash
+$ vf env
+
+# Prompts for each variable
+# Shows description and example
+# Marks required vs optional
+```
+
+**Solution:** Run `vf env` to set up variables interactively
+
+### Documentation Links Not Working
+
+**Solution:** Check the recipe file and update links if service documentation has moved
+
+## File Structure
+
+```
+vibefast-cli/
+├── recipes/
+│   ├── README.md              # Recipes documentation
+│   ├── sentry.json            # Sentry recipe
+│   ├── posthog.json           # PostHog recipe
+│   ├── stripe.json            # Stripe recipe
+│   ├── auth0.json             # Auth0 recipe
+│   └── firebase.json          # Firebase recipe
+└── RECIPES-GUIDE.md           # This file
+```
+
+## CLI Commands Reference
+
+### View Recipe Steps
+```bash
+vf checklist <service-name>
+vf checklist sentry
+vf checklist posthog
+```
+
+### List All Services
+```bash
+vf list
+```
+
+### Setup Environment Variables
+```bash
+vf env
+vf env --target native
+vf env --target web
+```
+
+### Check Project Health
+```bash
+vf health
+```
+
+## Next Steps
+
+1. **Test recipes locally**
+   ```bash
+   vf checklist sentry
+   vf checklist posthog
+   ```
+
+2. **Setup environment variables**
+   ```bash
+   vf env
+   ```
+
+3. **Add more recipes**
+   - Create new recipe files
+   - Test with `vf checklist`
+   - Deploy to backend
+
+4. **Update documentation**
+   - Keep recipe links current
+   - Update as services change
+   - Add new services as needed
+
+## Support
+
+- 📧 Email: support@vibefast.pro
+- 📚 Docs: https://vibefast.pro/docs
+- 🐛 Issues: https://github.com/vibefast/vibefast-cli/issues
+
+## Summary
+
+Service recipes provide a structured way to guide users through setting up third-party services. They include:
+
+- ✅ Clear setup instructions
+- ✅ Environment variable definitions
+- ✅ Documentation links
+- ✅ Example values
+- ✅ Required vs optional fields
+
+Users can view recipes with `vf checklist <service>` and setup environment variables with `vf env`.
+
+All recipes are available through `vf list` and integrated with the CLI for a seamless experience.

package/RELEASE-CHECKLIST.md

@@ -0,0 +1,269 @@
+# Release Checklist for v0.3.0
+
+## ✅ Implementation (Complete)
+
+- [x] Phase 1: Foundation
+  - [x] Smart target detection
+  - [x] Better progress indicators
+  - [x] Better prompts
+- [x] Phase 2: MVP Init
+  - [x] `vf init` command
+- [x] Enhanced existing commands
+  - [x] `vf add` with auto-detection
+  - [x] `vf list` with spinner
+- [x] Unit tests (9 tests, all passing)
+- [x] Build successful (no errors)
+- [x] Version bumped to 0.3.0
+- [x] CHANGELOG updated
+
+---
+
+## 🧪 Testing (Before Release)
+
+### Manual Testing
+- [ ] Test `vf init` interactive mode
+  - [ ] Clean branch
+  - [ ] Full branch
+  - [ ] With license key
+  - [ ] Without license key
+- [ ] Test `vf init` with flags
+  - [ ] `--license KEY --branch full`
+  - [ ] `--yes --skip-install`
+- [ ] Test `vf add` auto-detection
+  - [ ] In native project
+  - [ ] In web project
+  - [ ] In project with both
+- [ ] Test `vf add` manual override
+  - [ ] `--target native`
+  - [ ] `--target web`
+- [ ] Test `vf list` with spinner
+- [ ] Test in CI environment (non-TTY)
+  - [ ] GitHub Actions
+  - [ ] GitLab CI
+  - [ ] CircleCI
+
+### Edge Cases
+- [ ] Test with no Git installed
+- [ ] Test with no internet connection
+- [ ] Test with invalid license key
+- [ ] Test in directory that already exists
+- [ ] Test with permission errors
+- [ ] Test with slow network
+- [ ] Test interruption (Ctrl+C)
+
+### Compatibility
+- [ ] Test on macOS
+- [ ] Test on Linux
+- [ ] Test on Windows
+- [ ] Test with Node 18
+- [ ] Test with Node 20
+- [ ] Test with Node 22
+
+---
+
+## 📚 Documentation (Before Release)
+
+### Update Main README
+- [ ] Add `vf init` to command list
+- [ ] Update "Getting Started" section
+- [ ] Add examples for auto-detection
+- [ ] Update feature list
+- [ ] Add Phase 1 & 2 highlights
+
+### Update CLI Docs
+- [ ] Document `vf init` command
+- [ ] Document auto-detection behavior
+- [ ] Document new flags
+- [ ] Add troubleshooting section
+- [ ] Update examples
+
+### Create Migration Guide
+- [ ] Explain new features
+- [ ] Show before/after examples
+- [ ] Highlight breaking changes (none!)
+- [ ] Provide upgrade instructions
+
+### Update Website
+- [ ] Update CLI documentation page
+- [ ] Add "Quick Start" guide
+- [ ] Update feature comparison
+- [ ] Add demo video/GIF
+
+---
+
+## 🔍 Code Review
+
+- [ ] Review all new code
+- [ ] Check for security issues
+- [ ] Verify error handling
+- [ ] Check for memory leaks
+- [ ] Review TypeScript types
+- [ ] Check for unused imports
+- [ ] Verify all paths are safe
+- [ ] Check for hardcoded values
+
+---
+
+## 🚀 Pre-Release
+
+### Build & Test
+- [ ] Run `npm run build`
+- [ ] Run `npm test`
+- [ ] Test built CLI locally
+  ```bash
+  npm link
+  vf init
+  ```
+- [ ] Verify all commands work
+- [ ] Check bundle size
+
+### Version & Changelog
+- [x] Bump version to 0.3.0
+- [x] Update CHANGELOG.md
+- [ ] Update README.md
+- [ ] Git commit all changes
+- [ ] Git tag v0.3.0
+
+### Security
+- [ ] Run `npm audit`
+- [ ] Fix any vulnerabilities
+- [ ] Review dependencies
+- [ ] Check for outdated packages
+
+---
+
+## 📦 Publishing
+
+### NPM
+- [ ] Login to npm: `npm login`
+- [ ] Dry run: `npm publish --dry-run`
+- [ ] Publish: `npm publish`
+- [ ] Verify on npmjs.com
+- [ ] Test install: `npx vibefast-cli@latest init`
+
+### GitHub
+- [ ] Push to main branch
+- [ ] Create GitHub release
+- [ ] Add release notes
+- [ ] Attach binaries (if any)
+- [ ] Tag release as v0.3.0
+
+---
+
+## 📢 Announcement
+
+### Internal
+- [ ] Notify team
+- [ ] Update internal docs
+- [ ] Share in Slack/Discord
+
+### External
+- [ ] Tweet announcement
+- [ ] Post on Product Hunt
+- [ ] Update website
+- [ ] Send email to users
+- [ ] Post in relevant communities
+
+### Content
+- [ ] Write blog post
+- [ ] Create demo video
+- [ ] Update screenshots
+- [ ] Share on social media
+
+---
+
+## 🐛 Post-Release Monitoring
+
+### First 24 Hours
+- [ ] Monitor npm downloads
+- [ ] Watch for error reports
+- [ ] Check GitHub issues
+- [ ] Monitor support email
+- [ ] Check social media mentions
+
+### First Week
+- [ ] Gather user feedback
+- [ ] Track adoption rate
+- [ ] Monitor error logs
+- [ ] Identify common issues
+- [ ] Plan hotfixes if needed
+
+---
+
+## 🎯 Success Metrics
+
+Track these metrics:
+- [ ] npm downloads (target: 100+ in first week)
+- [ ] GitHub stars (target: +10)
+- [ ] Support tickets (target: <5)
+- [ ] User satisfaction (target: 90%+)
+- [ ] Setup time (target: <5 min)
+
+---
+
+## 🔄 Rollback Plan
+
+If critical issues are found:
+
+1. **Immediate:**
+   - [ ] Unpublish from npm (if <24 hours)
+   - [ ] Or publish hotfix version
+   - [ ] Notify users via Twitter/email
+
+2. **Investigation:**
+   - [ ] Identify root cause
+   - [ ] Create fix
+   - [ ] Test thoroughly
+   - [ ] Document issue
+
+3. **Recovery:**
+   - [ ] Publish fixed version
+   - [ ] Update changelog
+   - [ ] Notify users
+   - [ ] Post-mortem
+
+---
+
+## 📝 Notes
+
+### Known Issues
+- None currently
+
+### Future Improvements (Phase 3)
+- Auto-install dependencies after `vf add`
+- Environment setup command
+- Project health check command
+
+### Feedback Collection
+- Create feedback form
+- Monitor GitHub issues
+- Track support emails
+- Analyze usage patterns
+
+---
+
+## ✅ Final Checklist
+
+Before hitting publish:
+- [ ] All tests passing
+- [ ] Build successful
+- [ ] Documentation updated
+- [ ] Changelog complete
+- [ ] Version bumped
+- [ ] Git tagged
+- [ ] Team notified
+- [ ] Rollback plan ready
+
+---
+
+## 🎉 Ready to Ship?
+
+Once all items are checked:
+```bash
+npm run build
+npm test
+npm publish
+git push --tags
+```
+
+Then celebrate! 🚀