vibefast-cli 0.2.3 → 0.3.0

package/MANUAL-TEST-CHECKLIST.md

@@ -0,0 +1,264 @@
+# Manual Test Checklist
+
+Before publishing v0.3.0, test these scenarios:
+
+## Setup
+
+```bash
+cd vibefast-cli
+npm run build
+npm link
+```
+
+## ✅ Basic Tests
+
+### 1. Version & Help
+- [ ] `vf --version` shows 0.3.0
+- [ ] `vf --help` shows all commands including `init`
+- [ ] `vf init --help` shows correct options
+
+### 2. Test `vf init` Interactive Mode
+
+```bash
+cd /tmp
+mkdir test-init-interactive
+cd test-init-interactive
+vf init
+```
+
+**Check:**
+- [ ] Prompts for branch selection (clean/full)
+- [ ] Prompts for project name
+- [ ] Shows spinner while cloning
+- [ ] Shows spinner while installing
+- [ ] Creates .env file
+- [ ] Prompts for license key
+- [ ] Shows success message with next steps
+
+**Verify files:**
+- [ ] Project directory created
+- [ ] `.vibefast-signature.json` exists
+- [ ] `.env` file exists
+- [ ] `node_modules` exists (if not --skip-install)
+- [ ] `package.json` exists
+
+### 3. Test `vf init` with Flags
+
+```bash
+cd /tmp
+vf init --license test-key --branch full --yes
+```
+
+**Check:**
+- [ ] No prompts shown
+- [ ] Uses default project name
+- [ ] Clones full branch
+- [ ] Saves license key
+- [ ] Completes successfully
+
+### 4. Test `vf init` Skip Install
+
+```bash
+cd /tmp
+vf init --yes --skip-install
+```
+
+**Check:**
+- [ ] Skips dependency installation
+- [ ] Still creates .env
+- [ ] Completes quickly
+- [ ] No `node_modules` directory
+
+### 5. Test Error Handling
+
+```bash
+cd /tmp
+mkdir existing-project
+cd existing-project
+touch .vibefast-signature.json
+vf init
+```
+
+**Check:**
+- [ ] Shows error: "Already in a VibeFast project"
+- [ ] Exits gracefully
+- [ ] Doesn't overwrite anything
+
+```bash
+cd /tmp
+vf init
+# When prompted for name, enter "existing-project"
+```
+
+**Check:**
+- [ ] Shows error: "Directory already exists"
+- [ ] Suggests choosing different name
+- [ ] Exits gracefully
+
+## ✅ Enhanced Commands
+
+### 6. Test Auto-Detection
+
+First, create a test project:
+```bash
+cd /tmp
+vf init --yes --skip-install
+cd vibefast-app
+```
+
+Then test auto-detection:
+```bash
+vf add charts
+```
+
+**Check:**
+- [ ] Shows: "Auto-detected target: native" (or web)
+- [ ] Doesn't require --target flag
+- [ ] Works correctly
+
+### 7. Test Manual Override
+
+```bash
+vf add chatbot --target native
+```
+
+**Check:**
+- [ ] Still accepts --target flag
+- [ ] Doesn't show auto-detection message
+- [ ] Works as before
+
+### 8. Test `vf list` with Spinner
+
+```bash
+vf list
+```
+
+**Check:**
+- [ ] Shows spinner while fetching
+- [ ] Shows "✓ Features loaded"
+- [ ] Lists features correctly
+
+## ✅ Edge Cases
+
+### 9. Test Without Git
+
+```bash
+# Temporarily hide git (optional, risky!)
+# Only if you're brave:
+sudo mv /usr/bin/git /usr/bin/git.bak
+vf init
+sudo mv /usr/bin/git.bak /usr/bin/git
+```
+
+**Check:**
+- [ ] Shows helpful error about Git
+- [ ] Suggests installation commands
+- [ ] Exits gracefully
+
+### 10. Test in CI Mode
+
+```bash
+CI=true vf init --yes --skip-install
+```
+
+**Check:**
+- [ ] No spinners shown
+- [ ] No interactive prompts
+- [ ] Works in non-TTY environment
+- [ ] Completes successfully
+
+### 11. Test Interruption
+
+```bash
+vf init
+# Press Ctrl+C during clone
+```
+
+**Check:**
+- [ ] Handles interruption gracefully
+- [ ] Doesn't leave broken state
+- [ ] Can retry successfully
+
+## ✅ Backwards Compatibility
+
+### 12. Test Existing Commands Still Work
+
+In an existing VibeFast project:
+
+```bash
+vf status
+vf list
+vf add charts --target native
+vf remove charts --target native
+vf checklist sentry
+vf devices
+```
+
+**Check:**
+- [ ] All commands work as before
+- [ ] No breaking changes
+- [ ] No regressions
+
+## ✅ Performance
+
+### 13. Test Speed
+
+```bash
+time vf init --yes --skip-install
+```
+
+**Check:**
+- [ ] Completes in < 2 minutes (clone time)
+- [ ] Spinners show progress
+- [ ] Feels responsive
+
+## 🎯 Final Checks
+
+- [ ] No TypeScript errors
+- [ ] No console warnings
+- [ ] Clean error messages
+- [ ] Professional output
+- [ ] Works on your OS (macOS/Linux/Windows)
+
+## 📝 Notes
+
+Record any issues found:
+
+```
+Issue 1: [Description]
+Severity: [High/Medium/Low]
+Fix: [What needs to be done]
+
+Issue 2: ...
+```
+
+## ✅ Sign Off
+
+Once all tests pass:
+
+- [ ] All critical tests passed
+- [ ] No blocking issues found
+- [ ] Ready to publish
+
+**Tested by:** _______________
+**Date:** _______________
+**OS:** _______________
+**Node version:** _______________
+
+---
+
+## Quick Test Commands
+
+```bash
+# Full test suite
+./test-locally.sh
+
+# Quick smoke test
+vf --version && vf init --help && echo "✓ Basic tests passed"
+
+# Test init
+cd /tmp && vf init --yes --skip-install && echo "✓ Init works"
+
+# Cleanup
+rm -rf /tmp/vibefast-app
+```

package/OPTIONS-GLOSSARY.md

@@ -0,0 +1,308 @@
+# VibeFast CLI - Options Glossary
+
+Technical definitions for all CLI options.
+
+---
+
+## Global Options
+
+### `-V, --version`
+Output the semantic version of the CLI binary. Useful for debugging version mismatches in CI/CD pipelines.
+
+### `-h, --help`
+Display usage information and available subcommands. Supports hierarchical help (e.g., `vf add --help`).
+
+---
+
+## `vf init` Options
+
+### `--license <key>`
+**Type:** String (required for automation)
+
+VibeFast license token. Skips interactive license prompt. If omitted in interactive mode, checks `~/.vibefast-auth.json` for existing token. Enables license validation against VibeFast API.
+
+### `--branch <branch>`
+**Type:** String (enum: `clean` | `main`)
+**Default:** `main`
+
+Git branch to shallow-clone from the monorepo. `main` = full starter with all features; `clean` = minimal starter. Passed directly to `git clone --branch`.
+
+### `--yes`
+**Type:** Boolean flag
+
+Skips all interactive prompts and uses defaults. Requires `--license` if no existing token. Enables non-interactive mode for CI/CD pipelines. Disables TTY detection.
+
+### `--skip-install`
+**Type:** Boolean flag
+
+Skips `pnpm install` step. Useful for testing or custom dependency management. Still creates `.env` files and saves license key.
+
+---
+
+## `vf login` Options
+
+### `--token <token>`
+**Type:** String (required)
+
+VibeFast license key. Persisted to `~/.vibefast-auth.json` for subsequent CLI invocations. Validated against VibeFast API on first use.
+
+---
+
+## `vf add` Options
+
+### `<feature>`
+**Type:** String (required argument)
+
+Feature name to install. Case-sensitive. Fetched from VibeFast API using license token. Examples: `charts`, `chatbot`, `sentry`.
+
+### `--target <target>`
+**Type:** String (enum: `native` | `web`)
+**Default:** Auto-detected
+
+Deployment target platform. `native` = Expo/React Native; `web` = Next.js. Auto-detection analyzes `apps/native` and `apps/web` directory structure and `package.json` markers. Can be overridden explicitly.
+
+### `--dry-run`
+**Type:** Boolean flag
+
+Preview file operations without applying changes. Displays conflict warnings and file counts. Useful for validating recipes before installation. Skips watermarking and journal updates.
+
+### `--force`
+**Type:** Boolean flag
+
+Overwrites existing files without confirmation prompts. Skips conflict detection. Useful for re-installing or updating features. Implies `--yes` for file operations.
+
+### `--yes`
+**Type:** Boolean flag
+
+Skips all interactive prompts (file conflicts, package installation). Answers "yes" to all confirmations. Enables automation in CI/CD. Does not skip `--dry-run` preview.
+
+---
+
+## `vf remove` Options
+
+### `<feature>`
+**Type:** String (required argument)
+
+Feature name to remove. Must match installed feature name from journal. Reverses file copies and navigation injections.
+
+### `--target <target>`
+**Type:** String (enum: `native` | `web`)
+**Default:** Auto-detected
+
+Target platform for removal. Required to identify correct journal entry. Auto-detection available if omitted.
+
+---
+
+## `vf env` Options
+
+### `--target <target>`
+**Type:** String (enum: `native` | `web`)
+**Default:** `native`
+
+Target platform for environment setup. `native` = `apps/native/.env.local`; `web` = `apps/web/.env.local`. Reads from corresponding `.env.example` file.
+
+---
+
+## `vf checklist` Options
+
+### `<feature>`
+**Type:** String (required argument)
+
+Feature name to display manual setup steps for. Must be installed (found in journal). Reads from recipe manifest `manualSteps` array.
+
+### `--target <target>`
+**Type:** String (enum: `native` | `web`)
+**Default:** `native`
+
+Target platform for checklist. Filters journal entries by target. Useful for features supporting multiple targets.
+
+---
+
+## `vf devices` Options
+
+### `--deactivate <id>`
+**Type:** String (device ID)
+
+Deactivate a specific device by ID. Removes device from license activation list. Useful for freeing up device slots. ID obtained from `vf devices` list output.
+
+---
+
+## `vf health` Options
+
+None. Runs comprehensive health checks on current project.
+
+---
+
+## `vf list` Options
+
+None. Lists all available features for current license.
+
+---
+
+## `vf status` Options
+
+None. Shows installed features and metadata from journal.
+
+---
+
+## `vf logout` Options
+
+None. Clears stored license token.
+
+---
+
+## `vf doctor` Options
+
+None. Validates CLI setup and configuration.
+
+---
+
+## Environment Variables
+
+### `CI`
+**Type:** Boolean (string: `true`)
+
+Disables interactive prompts and TTY detection. Auto-set by GitHub Actions, GitLab CI, CircleCI. Overrides `process.stdin.isTTY` check.
+
+### `NO_COLOR`
+**Type:** Boolean (string: `1`)
+
+Disables ANSI color codes in output. Follows [NO_COLOR](https://no-color.org/) standard. Useful for log aggregation systems.
+
+### `VIBEFAST_API_URL`
+**Type:** String (URL)
+**Default:** `https://api.vibefast.pro`
+
+Override VibeFast API endpoint. Useful for testing or self-hosted deployments.
+
+---
+
+## Common Option Patterns
+
+### Automation (CI/CD)
+```bash
+vf init --license $KEY --yes --skip-install
+vf add charts --yes
+vf env --target native  # Non-interactive if CI=true
+```
+
+### Preview Mode
+```bash
+vf add charts --dry-run
+vf add charts --dry-run --force  # Preview with overwrite
+```
+
+### Force Operations
+```bash
+vf add charts --force              # Skip conflicts
+vf add charts --force --yes        # Full automation
+```
+
+### Explicit Targeting
+```bash
+vf add charts --target native      # Override auto-detection
+vf remove charts --target web      # Specify platform
+vf env --target web                # Setup web env
+```
+
+---
+
+## Option Precedence
+
+1. **Explicit flags** (highest priority)
+   - `--license KEY` overrides stored token
+   - `--target native` overrides auto-detection
+
+2. **Environment variables**
+   - `CI=true` enables non-interactive mode
+   - `NO_COLOR=1` disables colors
+
+3. **Stored configuration**
+   - `~/.vibefast-auth.json` for license token
+   - `.vibefast-signature.json` for project validation
+
+4. **Auto-detection** (lowest priority)
+   - Target detection from directory structure
+   - Package manager detection from lockfiles
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Warnings (e.g., `vf health` with warnings) |
+| 2 | Errors (e.g., `vf health` with critical issues) |
+
+---
+
+## Type Definitions
+
+### String
+Plain text argument. May contain spaces if quoted.
+
+### Boolean flag
+Presence of flag = true. Absence = false. No value required.
+
+### Enum
+Restricted set of values. Invalid values cause error.
+
+### Required
+Must be provided. Missing causes error.
+
+### Optional
+May be omitted. Uses default if provided.
+
+### Default
+Value used if option omitted.
+
+---
+
+## Examples by Use Case
+
+### First-Time Setup
+```bash
+vf init --license YOUR_KEY
+```
+
+### Automated Deployment
+```bash
+vf init --license $LICENSE --yes --skip-install
+pnpm install
+vf env --target native
+vf health
+```
+
+### Feature Development
+```bash
+vf add charts --dry-run
+vf add charts --force
+vf checklist charts
+```
+
+### Troubleshooting
+```bash
+vf health
+vf doctor
+vf status
+```
+
+### CI/CD Pipeline
+```bash
+CI=true vf init --license $KEY --yes
+CI=true vf add charts --yes
+CI=true vf health
+```
+
+---
+
+## Technical Notes
+
+- All options are case-sensitive
+- Flags can be combined: `vf add charts --force --yes`
+- Arguments must precede options: `vf add charts --target native` ✓
+- Arguments after options may fail: `vf add --target native charts` ✗
+- Paths are relative to current working directory
+- License tokens are stored unencrypted in `~/.vibefast-auth.json`
+- Journal entries stored in `.vibefast-journal.json` (project root)