@feeef.dev/cli 0.2.0 → 0.2.2

package/README.md

@@ -1,94 +1,188 @@
-# @feeef.dev/cli
+# `@feeef.dev/cli`
 
-Standalone TypeScript CLI for Feeef theme authors.
+Official Feeef developer CLI for **template** authors. Install once, scaffold templates, preview drafts on your live store without touching what customers see, then publish when ready.
 
 ```bash
 npm install -g @feeef.dev/cli
 feeef --help
 ```
 
-Config: `~/.config/feeef/config.json` (directory `0700`, file `0600`)
+| | |
+|---|---|
+| Package | [`@feeef.dev/cli`](https://www.npmjs.com/package/@feeef.dev/cli) |
+| Binary | `feeef` |
+| Config | `~/.config/feeef/config.json` (dir `0700`, file `0600`) |
+| SDK | depends on [`feeef`](https://www.npmjs.com/package/feeef) `^0.12.1` |
+
+You do **not** need the private Lithium Next.js storefront repo to build or preview templates.
+
+---
+
+## Quick start
+
+```bash
+npm install -g @feeef.dev/cli
+feeef signin                          # browser OAuth (no client secret)
+feeef template init my-template --blank
+cd my-template
+feeef use                             # pick a store you own
+npm run build
+npm run dev                           # draft preview URL opens in browser
+# …edit pages/… then refresh the preview tab…
+npm run publish -- --apply            # go live (explicit)
+```
+
+---
 
 ## Auth
 
-Default sign-in is **browser OAuth** (PKCE, public client — no client secret):
+Default sign-in is **browser OAuth** with PKCE (public client — **no** `FEEEF_OAUTH_CLIENT_SECRET`).
 
-- Redirect URI: `http://localhost.feeef.org:7777/oauth/callback` (**http**, not https)
-- Callback binds **127.0.0.1** only (`localhost.feeef.org` must resolve to loopback)
-- Client id is built-in
+| Detail | Value |
+|---|---|
+| Redirect | `http://localhost.feeef.org:7777/oauth/callback` (**http**) |
+| Callback bind | `127.0.0.1` only |
+| DNS | `localhost.feeef.org` must resolve to `127.0.0.1` |
+| Scopes | `auth`, `store`, `store.settings`, `store_templates`, `store_templates.read` (not `*`) |
 
 ```bash
 feeef signin                    # opens browser → consent → token saved
-feeef signin --password-auth    # email/password fallback (interactive prompt)
+feeef signin --password-auth    # email/password (interactive prompt; no -p on argv)
 feeef whoami
 feeef signout
 feeef config show
-feeef config set apiUrl http://127.0.0.1:3333/api/v1
+feeef config set apiUrl https://api.feeef.org/v1
 ```
 
-## Theme workflow
+Optional env (see [`.env.example`](./.env.example)):
+
+- `FEEEF_OAUTH_CLIENT_ID` — override built-in CLI client id
+- `FEEEF_OAUTH_CLIENT_SECRET` — only for confidential apps / local overrides
+- `FEEEF_ACCOUNTS_URL` / `FEEEF_API_BASE_URL`
+
+---
+
+## Template workflow
 
-Themes are **Node.js packages** (`package.json` + scripts). Scripts wrap the global `feeef` CLI.
+Templates are **Node.js packages**. Scripts wrap the global `feeef` binary. All kit commands live under `feeef template …`.
 
 ```bash
-feeef template init my-theme
-cd my-theme
-feeef use                             # pick one of your stores
+feeef template init my-template       # blank scaffold (bundled) or marketplace / --git
+cd my-template
+feeef use <slug>                      # writes .feeefrc
 
 feeef template add page products
 feeef template add component products grid --title "Product grid"
 
-npm run build                         # or: feeef template build
+npm run build                         # → dist/data.json (+ schema, locales)
 npm run check
-npm run dev                           # remote draft preview on your store
-npm run publish -- --apply            # go live (explicit)
+npm run dev                           # remote draft preview
+npm run publish -- --apply            # catalog upload + install on store
 ```
 
-### Preview (`feeef template dev`)
+### Source layout (blank kit)
 
-Pushes a **draft** theme to your bound store and opens the hosted storefront with a signed `?preview=` token.
+```
+schema.ts                 # template-owned editor schema
+pages/<page>/components/  # preferred → published sections.main
+shared/ | library/        # reusable custom components
+locales/*.json
+feeef.template.json
+dist/data.json            # TemplateData (build output)
+dist/schema.json          # merged editor schema
+```
 
-- Live customers keep seeing `metadata.templateData` (unchanged)
-- You navigate the full shop in draft mode (cookie keeps the session)
-- Exit: banner **Exit preview**, or visit `/?preview=0`
-- Stopping the CLI clears the server draft
+Authoring: flat `hero.tsx` with `export const meta` + `function App()`. See scaffold docs under `scaffolds/blank/docs/`.
 
-```bash
-feeef signin
-feeef use my-store
-feeef template dev
+---
+
+## Preview (`feeef template dev`)
+
+Default preview is **remote draft** — not a local Next.js clone.
+
+```mermaid
+flowchart LR
+  Watch["CLI watch + build"]
+  Dist["dist/data.json"]
+  API["PUT /stores/:id/template-preview"]
+  Host["Hosted shop ?preview=token"]
+  Live["Customers → live templateData"]
+  Watch --> Dist --> API --> Host
+  Live -.-> Host
 ```
 
-Going live is only via `feeef template publish --apply` (or the merchant editor).
+| | Draft preview | Live shop |
+|---|---|---|
+| Written by | `feeef template dev` | `publish --apply` / merchant editor |
+| Storage | `metadata.templatePreview` | `metadata.templateData` |
+| Who sees it | You (and anyone with the preview link/cookie) | Customers |
+
+**Session UX**
+
+1. CLI builds → `PUT …/template-preview` → opens `https://{slug}.…/?preview={token}`
+2. Middleware sets httpOnly cookie `feeef_preview` so you can navigate home → PLP → PDP → checkout with the **draft template**
+3. Catalog (products, prices) is still the **real store**
+4. Thin banner: **Previewing draft template — Exit**
+5. Exit: banner, or `/?preview=0` / `/?preview=exit`, or stop the CLI (clears draft), or wait for token TTL (~24h)
+
+**Hard rule:** `dev` never overwrites live `templateData`.
 
 ### Local Next (employees only)
 
 ```bash
 feeef template dev --local
-# or: feeef config set storefrontPath /path/to/storefront && feeef template dev --local
+# implies storefront on disk: FEEEF_STOREFRONT_PATH or config storefrontPath
 ```
 
-Not required for public theme authors.
+Not documented for public authors; not required for npm installs.
+
+---
+
+## Publish (go live)
 
-## Publish uploads
+```bash
+feeef template publish --apply
+# or: npm run publish -- --apply
+```
 
 | Target | Source |
-|--------|--------|
-| `store_templates` | `dist/data.json` (i18n stripped) + schema |
+|---|---|
+| `store_templates` | `dist/data.json` (i18n stripped) + `dist/schema.json` |
 | `template_components` | `shared/` + `library/` |
 | `store_template_locales` | `dist/locales/*.json` |
+| Install (`--apply`) | Links `store.templateId` + clones data → live `metadata.templateData` |
+
+Without `--apply`, the marketplace row updates but the storefront customers see does not change until install/editor save.
+
+---
+
+## Commands cheat sheet
+
+| Command | Purpose |
+|---|---|
+| `feeef signin` | OAuth (or `--password-auth`) |
+| `feeef use [store]` | Bind template ↔ store (`.feeefrc`) |
+| `feeef template init` | Scaffold blank / git / marketplace |
+| `feeef template add\|remove page\|component` | Scaffold edits |
+| `feeef template build\|check\|watch` | Compile / validate |
+| `feeef template dev` | Remote draft preview |
+| `feeef template publish [--apply]` | Upload (+ optional install) |
+| `feeef config show\|set` | Global config |
+
+---
 
 ## License
 
 UNLICENSED — proprietary Feeef software. See [LICENSE](./LICENSE).
 
-## Develop (monorepo)
+## Monorepo develop
 
 ```bash
 cd cli
 npm install
-npm run typecheck
 npm test
 npm run build
 npm run link:global
 ```
+
+Release notes for maintainers: [RELEASE.md](./RELEASE.md).