vibefast-cli 0.1.1

package/PLAN.md

@@ -0,0 +1,453 @@
+# VibeFast CLI — A–Z Plan (Public CLI + Token Auth)
+
+Monorepo: **apps/native (Expo SDK 54)** + **apps/web (Next.js)**. CLI installs shadcn-style feature code into either target.
+
+---
+
+## Phase 0 — Decisions & Ground Rules
+
+**Goal:** Freeze choices so the build stays simple and predictable.
+
+**Decide:**
+
+- **CLI package:** `vibefast-cli` (binary alias: `vf`).
+- **Auth:** fixed opaque **token** per customer; **2 device slots** by default.
+- **Delivery:** Cloudflare **Worker** validates token/seat → issues short‑lived **signed URL** to recipe **zip** in **R2/KV**.
+- **Repo signature:** require `.vibefast/starter.json` with `{ "name": "vibefast", "version": "1.0.0", "targets": ["native","web"] }`.
+- **Markers:**
+
+  - Native: `apps/native/src/app/(root)/(tabs)/index.tsx`
+
+    ```tsx
+    // --- @vibefast:navigation:start ---
+    {
+      /* CLI will inject feature links here */
+    }
+    // --- @vibefast:navigation:end ---
+    ```
+
+  - Web: `apps/web/app/page.tsx`
+
+    ```tsx
+    {
+      /* @vibefast:nav:start */
+    }
+    {
+      /* CLI will inject feature cards here */
+    }
+    {
+      /* @vibefast:nav:end */
+    }
+    ```
+
+- **Journal:** `.vibefast/journal.json` (tracks files & nav inserts).
+- **Default target:** `native` (override with `--target web`).
+- **Rate limits:** 500/day, 30/min per token (tune later).
+
+**Deliverable:** `/docs/decisions.md` summarizing the above.
+
+**Accept:** Decisions doc exists; everyone agrees.
+
+---
+
+## Phase 1 — Prepare VibeFast (one-time repo changes)
+
+**Goal:** Make the monorepo detectable and codemods deterministic.
+
+**Tasks:**
+
+1. Add `.vibefast/starter.json` with the JSON above.
+2. Add nav **markers** in the two files above (native + web).
+3. Ensure TS path alias `@/` resolves correctly for both apps (or use relative imports in templates).
+
+**Checklist:**
+
+- [ ] Signature file present & valid JSON
+- [ ] Markers present once in each target
+- [ ] Both apps build
+
+**Accept:** `grep` finds markers; both apps compile.
+
+---
+
+## Phase 2 — Create the CLI (public npm package)
+
+**Goal:** Scaffold a clean TypeScript CLI.
+
+**Folder structure:**
+
+```
+/vibefast-cli
+  package.json
+  tsconfig.json
+  src/
+    index.ts                 # command router
+    commands/
+      add.ts
+      remove.ts
+      list.ts
+      doctor.ts
+      login.ts
+      devices.ts
+      logout.ts
+    core/
+      log.ts
+      paths.ts
+      fsx.ts
+      journal.ts
+      validate.ts
+      codemod.ts
+      http.ts
+      auth.ts
+```
+
+**package.json:**
+
+- name: `vibefast-cli`
+- bin: `{ "vf": "dist/index.js" }`
+- scripts: `build (tsc)`, `dev (tsx src/index.ts)`
+- deps: `commander`, `picocolors`
+- optional: `keytar` (secure token storage) — fallback to `~/.vibefast/config.json`
+
+**Checklist:**
+
+- [ ] `vf --help` runs locally
+- [ ] Commands load without throwing
+
+**Accept:** CLI starts and shows help.
+
+---
+
+## Phase 3 — Implement Core Utilities
+
+**Goal:** Reusable helpers with tests.
+
+- `log.ts` — success/info/warn/error with nice colors
+- `paths.ts` — CWD, signature, journal, nav file paths for each target
+- `fsx.ts` — `ensureDir`, `writeFile(force)`, `copyTree(dry,force)`, `exists`, `readFile`
+- `journal.ts` — `{ feature, target, files[], insertedNav, ts }` CRUD at `.vibefast/journal.json`
+- `validate.ts` — assert signature name `vibefast`; parse targets; semver gate if needed
+- `codemod.ts` — `insertNavLinkNative`, `removeNavLinkNative`, `insertNavLinkWeb`, `removeNavLinkWeb` (string markers; idempotent via href check)
+- `http.ts` — POST JSON to Worker; download signed zips to temp; unzip
+- `auth.ts` — save/read token (keytar or file); generate stable `device_id` (username|hostname|os + persisted uuid)
+
+**Checklist:**
+
+- [ ] Unit tests for happy paths & basic errors
+- [ ] `device_id` stable across runs
+
+**Accept:** Tests pass locally.
+
+---
+
+## Phase 4 — Recipe Format & First Recipes (mini-native, mini-web)
+
+**Goal:** Define manifests and ship two demo zips.
+
+### mini-native `recipe.json`
+
+```json
+{
+  "name": "mini-native",
+  "version": "0.1.0",
+  "description": "Demo feature (Expo)",
+  "copy": [
+    {
+      "from": "apps/native/src/app/(root)/(tabs)/mini",
+      "to": "apps/native/src/app/(root)/(tabs)/mini"
+    },
+    {
+      "from": "apps/native/src/components/mini",
+      "to": "apps/native/src/components/mini"
+    },
+    { "from": "apps/native/src/lib/mini", "to": "apps/native/src/lib/mini" }
+  ],
+  "nav": { "href": "/(root)/(tabs)/mini", "label": "Mini" },
+  "target": "native"
+}
+```
+
+**Templates:**
+
+- `apps/native/src/app/(root)/(tabs)/mini/index.tsx`
+- `apps/native/src/components/mini/MiniCard.tsx`
+- `apps/native/src/lib/mini/useMini.ts`
+
+### mini-web `recipe.json`
+
+```json
+{
+  "name": "mini-web",
+  "version": "0.1.0",
+  "description": "Demo feature (Next.js)",
+  "copy": [
+    { "from": "apps/web/app/mini", "to": "apps/web/app/mini" },
+    { "from": "apps/web/components/mini", "to": "apps/web/components/mini" },
+    { "from": "apps/web/lib/mini", "to": "apps/web/lib/mini" }
+  ],
+  "nav": { "href": "/mini", "label": "Mini" },
+  "target": "web"
+}
+```
+
+**Packaging:** Zip each recipe folder → `mini-native@0.1.0.zip`, `mini-web@0.1.0.zip`. Upload to R2 (or KV).
+
+**Checklist:**
+
+- [ ] Zips contain manifest + templates
+- [ ] Destinations match VibeFast paths
+
+**Accept:** Manual unzip matches tree.
+
+---
+
+## Phase 5 — Cloudflare Worker Gateway (Auth + Signed URL)
+
+**Goal:** Token validation, seat control, rate limit, signed URL issuance.
+
+**POST /api/recipe/fetch**
+
+- Request body:
+
+```json
+{
+  "token": "OPAQ_32CHARS",
+  "device": {
+    "id": "abc123…",
+    "os": "darwin",
+    "arch": "arm64",
+    "version": "1.0.0"
+  },
+  "feature": "mini-native",
+  "target": "native",
+  "starter": { "name": "vibefast", "version": "1.0.0" }
+}
+```
+
+- Response:
+
+```json
+{
+  "ok": true,
+  "signedUrl": "https://…/mini-native@0.1.0.zip?...",
+  "expiresIn": 180,
+  "watermark": "…"
+}
+```
+
+**Storage:**
+
+- KV: `lic:<sha256(token)>` → `{ status, max_devices, devices[], rate }`
+- R2: recipe zips per feature@version
+
+**Checklist:**
+
+- [ ] Worker deployed; KV & R2 bound
+- [ ] Seeded token returns a signed URL
+
+**Accept:** Invalid token → 403; seat limit → 403; valid → 200.
+
+---
+
+## Phase 6 — Auth & Device Commands (CLI)
+
+**Goal:** Token storage + seat management.
+
+- `vf login --token <TOKEN>` — store token (keytar or `~/.vibefast/config.json`)
+- `vf devices` — list activations from Worker
+- `vf devices --deactivate <id>` — free a slot
+- `vf logout` — clear local token
+
+**Checklist:**
+
+- [ ] Token saved & retrieved
+- [ ] Device list/deactivate works
+
+**Accept:** Bad token errors are friendly.
+
+---
+
+## Phase 7 — doctor / list / add / remove (Core Flow)
+
+**Goal:** End-to-end installation experience for each target.
+
+**doctor**
+
+- Verify `.vibefast/starter.json` name `vibefast`
+- Detect monorepo; default `native`, allow `--target web`
+
+**list**
+
+- Get catalog from Worker; group by `native` / `web`
+
+**add <feature> [--target native|web] [--dry-run] [--force]**
+
+- Validate signature
+- Fetch signed URL → download to temp → unzip
+- Read `recipe.json`; copy files (respect `--dry-run`/`--force`)
+- Insert nav link (native or web variant)
+- Record journal
+- Print next steps
+
+**remove <feature> [--target native|web] [--dry-run]**
+
+- Read journal; delete files; remove nav link; update journal
+
+**Checklist:**
+
+- [ ] Re‑add is no‑op unless `--force`
+- [ ] Remove leaves repo clean
+
+**Accept:** E2E on fresh clone: `vf doctor` → `vf add mini-native` → app shows link → `vf remove mini-native` cleans up.
+
+---
+
+## Phase 8 — Watermarking & Anti‑Sharing
+
+**Goal:** Trace leaks and deter casual sharing.
+
+- Worker returns `watermark` (token hash suffix + device suffix)
+- CLI injects `// vibefast license: <watermark>` at top of each copied file
+- Handle `429` with friendly cooldown message
+
+**Accept:** Files contain watermark; rate limit enforced.
+
+---
+
+## Phase 9 — Testing (Unit + E2E)
+
+**Goal:** Confidence before publish.
+
+**Unit:** fsx, codemod (with/without markers), journal, auth.deviceId
+
+**E2E (CI):**
+
+1. Clone VibeFast fixture
+2. `vf doctor` ✓
+3. `vf add mini-native` → files + nav + journal ✓; re‑run is no‑op ✓
+4. `vf remove mini-native` → clean ✓
+5. invalid token → blocked ✓
+6. seat limit → friendly error ✓
+
+**Accept:** Tests pass; snapshot diff clean.
+
+---
+
+## Phase 10 — Packaging & Release
+
+**Goal:** Publish the public CLI; recipes remain private.
+
+- `package.json`: `"bin": { "vf": "dist/index.js" }`
+- `npm run build` (tsc)
+- Publish to npm (public)
+- README usage:
+
+```bash
+npx vibefast-cli login --token <YOUR_TOKEN>
+vf doctor
+vf list
+vf add mini-native
+vf add mini-web --target web
+```
+
+**Accept:** Fresh machine + fresh VibeFast clone → full flow works.
+
+---
+
+## Phase 11 — Add Real Recipes (charts, chatbot, voice, images)
+
+**Goal:** Expand library using same manifest pattern.
+
+For each feature:
+
+- Place templates under app‑specific folders (`apps/native/...` or `apps/web/...`)
+- Include `recipe.json` with `target`, `copy[]`, `nav`, optional `env/config` notes
+- Zip & upload; update catalog
+- E2E test install/remove
+
+**Accept:** Templates compile; route reachable; removal clean.
+
+---
+
+## Phase 12 — Nice‑to‑Haves (Post‑MVP)
+
+- `vf diff` — preview changes before apply
+- `vf update <feature>` — migration runner between versions
+- `vf doctor --fix` — auto‑add missing markers
+- Config mutations (marker blocks in `app.config.ts` if needed)
+- Optional telemetry (opt‑in)
+
+---
+
+## Phase 13 — Security & Ops
+
+- **Revoke:** set `status=revoked` → 403 immediately
+- **Rotate:** issue new token; optionally migrate active devices
+- **Anomalies:** auto‑lock if unusual device churn; notify
+- **Backups:** nightly KV export to R2; version recipe zips
+- **Monitoring:** token counts, error rates, p95 latency
+
+---
+
+## Phase 14 — Junior Dev Daily Checklist
+
+- Pull latest; `npm run build`
+- Run unit tests; run E2E on fixture
+- Manual sanity: `doctor`, `add`, `remove`
+- Verify Worker with staging token
+- Update docs if CLI surface changes
+
+---
+
+## Acceptance Criteria Summary (MVP)
+
+- Public CLI on npm; `vf` works
+- `login`, `devices`, `logout`, `doctor`, `list`, `add`, `remove` implemented
+- Token + 2‑device enforcement works
+- Signed URL delivery working
+- Idempotent add/remove; watermark injected
+- Unit + E2E tests green in CI
+
+---
+
+## Appendix — Data Shapes
+
+**CLI → Worker `recipe.fetch`**
+
+```json
+{
+  "token": "OPAQ_32CHARS",
+  "device": {
+    "id": "abc123…",
+    "os": "darwin",
+    "arch": "arm64",
+    "version": "1.0.0"
+  },
+  "feature": "mini-native",
+  "target": "native",
+  "starter": { "name": "vibefast", "version": "1.0.0" }
+}
+```
+
+**Worker response**
+
+```json
+{
+  "ok": true,
+  "signedUrl": "https://…/mini-native@0.1.0.zip?...",
+  "expiresIn": 180,
+  "watermark": "…"
+}
+```
+
+**Journal entry**
+
+```json
+{
+  "feature": "mini-native",
+  "target": "native",
+  "files": ["/abs/apps/native/src/app/(root)/(tabs)/mini/index.tsx"],
+  "insertedNav": true,
+  "ts": 1731300000000
+}
+```

package/README.md

@@ -0,0 +1,129 @@
+# VibeFast CLI
+
+Official CLI for installing VibeFast features into your monorepo.
+
+## Installation
+
+```bash
+npm install -g vibefast-cli
+```
+
+Or use directly with npx:
+
+```bash
+npx vibefast-cli <command>
+```
+
+## Quick Start
+
+1. **Login with your token:**
+```bash
+vf login --token YOUR_TOKEN_HERE
+```
+
+2. **Verify your setup:**
+```bash
+vf doctor
+```
+
+3. **List available features:**
+```bash
+vf list
+```
+
+4. **Install a feature:**
+```bash
+vf add mini-native
+vf add mini-web --target web
+```
+
+5. **Remove a feature:**
+```bash
+vf remove mini-native
+```
+
+## Commands
+
+### `vf login --token <TOKEN>`
+Authenticate with your VibeFast license token.
+
+### `vf logout`
+Clear your stored token.
+
+### `vf devices`
+List your active device activations.
+
+**Options:**
+- `--deactivate <id>` - Free up a device slot
+
+### `vf doctor`
+Check your VibeFast setup and verify all requirements.
+
+### `vf list`
+Show all available features for your license.
+
+### `vf add <feature>`
+Install a feature into your project.
+
+**Options:**
+- `--target <native|web>` - Target platform (default: native)
+- `--dry-run` - Preview changes without applying
+- `--force` - Overwrite existing files
+
+**Example:**
+```bash
+vf add charts --target native
+vf add chatbot --target web --force
+```
+
+### `vf remove <feature>`
+Remove an installed feature.
+
+**Options:**
+- `--target <native|web>` - Target platform (default: native)
+- `--dry-run` - Preview changes without applying
+
+**Example:**
+```bash
+vf remove charts --target native
+```
+
+## Requirements
+
+- Node.js 18+
+- A VibeFast monorepo with `.vibefast/starter.json`
+- Valid VibeFast license token
+
+## Device Limits
+
+Each license includes 2 device slots by default. A device is identified by a stable ID based on your machine's username, hostname, and OS. You can manage your devices with:
+
+```bash
+vf devices                    # List active devices
+vf devices --deactivate <id>  # Free a slot
+```
+
+## Troubleshooting
+
+**"Not a VibeFast repo"**
+- Make sure you're in the root of your VibeFast monorepo
+- Check that `.vibefast/starter.json` exists
+
+**"Not logged in"**
+- Run `vf login --token <YOUR_TOKEN>`
+
+**"Device limit reached"**
+- Run `vf devices` to see active devices
+- Deactivate unused devices with `vf devices --deactivate <id>`
+
+**"Missing navigation markers"**
+- Ensure your nav files have the required marker comments
+- Run `vf doctor` to check
+
+## Environment Variables
+
+- `VIBEFAST_WORKER_URL` - Override the API endpoint (default: https://api.vibefast.com)
+
+## Support
+
+For issues or questions, contact support@vibefast.com