vibefast-cli 1.2.1 → 1.3.1

package/docs/archive/PLAN.md

@@ -1,453 +0,0 @@
-# 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
-}
-```