@storifycli/cli 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# Storify Theme CLI
+
+Unified CLI for developing, validating, packaging, and uploading Storify themes.
+
+**Documentation:**
+
+- **External developers:** [docs/theme-developer-guide/13-CLI-DEV-PREVIEW.md](../../docs/theme-developer-guide/13-CLI-DEV-PREVIEW.md)
+- **Internal / platform team:** [docs/theme/STORIFY_CLI_DEV_PREVIEW.md](../../docs/theme/STORIFY_CLI_DEV_PREVIEW.md)
+
+---
+
+## Quick start
+
+```bash
+# 1. Build CLI (once per clone / after CLI changes)
+cd packages/storify-cli && npm install && npm run build
+
+# 2. Start platform services (separate terminals)
+cd shared/backend && npm run dev          # :3001
+cd shared/storefront && npm run dev       # :3004
+cd shared/admin-central && npm run dev    # :3003 (optional)
+
+# 3. Develop theme with live storefront preview
+cd themes/storify-templatesrap
+npm install
+npm run dev
+```
+
+Follow prompts: **email → password → choose store** (first run only).
+
+---
+
+## Install
+
+**From npm (recommended for theme developers):**
+
+```bash
+npm install -g @storifycli/cli
+storify --help
+```
+
+Or run without global install:
+
+```bash
+npx @storifycli/cli theme dev
+```
+
+Do **not** use bare `npx storify` — it resolves to an unrelated legacy npm package.
+
+**From the Storify monorepo (platform team):**
+
+```bash
+cd packages/storify-cli && npm install && npm run build
+npm link   # optional global `storify` command
+```
+
+Theme folders can also call the local build directly:
+
+```json
+"dev": "node ../../packages/storify-cli/dist/cli.js theme dev"
+```
+
+---
+
+## Authentication
+
+```bash
+storify login
+```
+
+Interactive flow:
+
+1. Email
+2. Password
+3. Pick store by **name**
+
+Saves `~/.storify/config.json`:
+
+| Key | Default (local) |
+|-----|-----------------|
+| `apiUrl` | `http://localhost:3001/api` |
+| `storefrontUrl` | `http://localhost:3004` |
+| `adminUrl` | `http://localhost:3003` |
+
+Requires backend `LEGACY_TOKEN_RESPONSE=true` for bearer token in login response.
+
+Environment overrides: `STORIFY_API_URL`, `STORIFY_AUTH_TOKEN`, `STORIFY_STORE_ID`, `STORIFY_STOREFRONT_URL`, `STORIFY_ADMIN_URL`.
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `storify` | Interactive menu |
+| `storify login` | Save credentials |
+| `storify status` | Config + theme folder |
+| `storify theme dev` | Vite + live storefront preview (default) |
+| `storify theme validate` | Manifest + section checks |
+| `storify theme build` | Vite build + generated manifest |
+| `storify theme pack` | Upload-ready zip |
+| `storify theme upload` | POST to `/api/uploaded-themes` |
+| `storify theme new <name>` | Copy starter template |
+
+Aliases: `storify theme check`, `storify theme zip`.
+
+---
+
+## `storify theme dev`
+
+Starts Vite, registers **dev theme link** on the platform, prints preview URLs.
+
+```bash
+storify theme dev
+storify theme dev --local          # force localhost (no tunnel)
+storify theme dev --remote         # production storefront + cloudflared
+storify theme dev --no-link-store  # Vite only
+storify theme dev --open-storefront
+storify theme dev --port 3000
+```
+
+**Startup order:** Vite starts first → dev-link PATCH → preview URLs printed.
+
+**Preview URLs:**
+
+| Label | Example |
+|-------|---------|
+| Storefront | `http://localhost:3004/demo-dev-store/` |
+| Theme (Vite) | `http://localhost:3006` |
+| Admin editor | `http://localhost:3003/demo-dev-store/admin/theme/edit` |
+
+On Ctrl+C, dev link is disabled automatically.
+
+---
+
+## Recommended workflow
+
+```bash
+storify login
+cd themes/storify-templatesrap
+storify theme dev
+storify theme validate
+storify theme pack
+storify theme upload
+```
+
+---
+
+## Development
+
+```bash
+cd packages/storify-cli
+npm run dev      # run CLI via tsx (development)
+npm run build    # tsup → dist/cli.js
+npm run typecheck
+```