@feeef.dev/cli 0.2.0 → 0.2.1

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@feeef.dev/cli",
-  "version": "0.2.0",
-  "description": "Feeef developer CLI — themes, auth, and cloud tools",
+  "version": "0.2.1",
+  "description": "Feeef developer CLI — templates, auth, and cloud tools",
   "type": "module",
   "bin": {
-    "feeef": "./dist/bin.js"
+    "feeef": "dist/bin.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -38,7 +38,7 @@
     "feeef",
     "cli",
     "ecommerce",
-    "theme",
+    "template",
     "storefront"
   ],
   "license": "UNLICENSED",
@@ -52,14 +52,14 @@
     "dotenv": "^16.4.7",
     "esbuild": "^0.25.0",
     "feeef": "^0.12.1",
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
   },
   "devDependencies": {
     "@types/node": "^20.12.10",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
     "tsup": "^8.5.0",
     "tsx": "^4.19.3",
     "typescript": "^5.4.5"

package/scaffolds/blank/AGENTS.md

@@ -1,13 +1,13 @@
-# AGENTS — Feeef Theme (READ BEFORE EDITING)
+# AGENTS — Feeef Template (READ BEFORE EDITING)
 
-You are editing a **Feeef theme package** (this folder). Mistakes break the merchant
+You are editing a **Feeef template package** (this folder). Mistakes break the merchant
 editor, the storefront preview, and published stores. Follow this file exactly.
 
 ## Mandatory mental model
 
 1. **One JSON contract** — `TemplateData` (built into `dist/data.json`) is what Feeef stores and renders. `dist/schema.json` is the editor schema.
 2. **Source vs dist** — edit `schema.ts`, `pages/`, `shared/`, `library/`, `locales/`, `props.json`; run `npm run build`. Do not hand-edit large `dist/*` as the source of truth.
-3. **Theme schema is yours** — `schema.ts` (`satisfies FeeefThemeSchema`) controls pages/layouts/root `propsSchema`. Build merges Lithium built-ins into `dist/schema.json` for publish.
+3. **Template schema is yours** — `schema.ts` (`satisfies FeeefThemeSchema`) controls pages/layouts/root `propsSchema`. Build merges Lithium built-ins into `dist/schema.json` for publish.
 4. **`type: "custom"` is react-live** — published `code` is a **string** evaluated in a sandbox. It must expose top-level `function App() { … }`. Author with a flat file like `hero.tsx`: `export const meta` (include `propsSchema`) + `App`. Type props via `FeeefLivePropsOf<typeof propsSchema>`. Local/`npm` imports are **bundled at build time** (see `docs/16-AUTHORING-TS-IMPORTS.md`). Use a folder (`hero/component.tsx`) only when you need `slots/` / `children/` or colocated modules.
 5. **`code` / `propsSchema` / `slotsSchema` / `slots` / `slotsLayout` are TOP-LEVEL** on the component object — never nest them under `props`.
 6. **Planes stay separate** — schema (editable fields) ≠ merchant content (`props`) ≠ renderer.
@@ -23,7 +23,7 @@ editor, the storefront preview, and published stores. Follow this file exactly.
 7. Dark/light → [`docs/12-DARK-LIGHT-THEME.md`](./docs/12-DARK-LIGHT-THEME.md).
 8. Multilang → [`docs/13-TEMPLATE-I18N.md`](./docs/13-TEMPLATE-I18N.md).
 9. Product grids / filters → [`docs/14-FILTERATOR.md`](./docs/14-FILTERATOR.md).
-10. After edits: `npm run build` (or `npm run check`), then hard-refresh `npm run dev`.
+10. After edits: `npm run build` (or `npm run check`), then refresh the draft preview (`npm run dev`).
 
 ## Hard rules (never violate)
 
@@ -44,10 +44,10 @@ editor, the storefront preview, and published stores. Follow this file exactly.
 | Do not invent unknown registry `type` strings | Prefer `custom` or built-ins |
 | Do not bypass order anti-abuse checks | Honeypot, dwell, in-flight lock |
 
-## Theme layout
+## Template layout
 
 ```
-schema.ts                    # theme-owned schema overlay
+schema.ts                    # template-owned schema overlay
 props.json                   # default root props
 pages/<page>/components/     # preferred — builds to sections.main
   <name>.tsx
@@ -65,6 +65,7 @@ Prefer a single `main` stack + component **slots** for chrome. Do not mix flat `
 ## Local commands
 
 ```bash
+npm install -g @feeef.dev/cli   # once
 feeef signin
 feeef use                 # bind a store
 npm install               # once — React/TS types for the editor
@@ -78,13 +79,15 @@ feeef template remove component <pageId> <name> --yes
 npm run build             # → dist/data.json
 npm run check
 npm run typecheck         # optional IDE/tsc
-npm run dev               # preview
+npm run dev               # remote draft preview (does NOT change live shop)
 npm run publish -- --apply
 ```
 
+**Preview:** `npm run dev` pushes `metadata.templatePreview` and opens `?preview=…`. Customers keep live `templateData`. Exit via banner or `/?preview=0`. Go live only with `publish --apply`.
+
 **AI / agents:** use `feeef template add page|component` (and `remove`) instead of inventing folder trees by hand. New pages are flat `components/` → published `sections.main`. Do not mix flat `components/` with `sections/` on the same page.
 
-Editor: `tsconfig.json` + `types/feeef-live-scope.d.ts` + `types/feeef-template-schema.d.ts` explain react-live globals and `FeeefThemeSchema` to VS Code / Cursor.
+Editor: `tsconfig.json` + `types/feeef-live-scope.d.ts` + `types/feeef-template-schema.d.ts` explain react-live globals and `FeeefThemeSchema` (template schema type) to VS Code / Cursor.
 
 ## Companion docs
 
@@ -95,10 +98,10 @@ Editor: `tsconfig.json` + `types/feeef-live-scope.d.ts` + `types/feeef-template-
 | [`docs/05-ANTI-PATTERNS.md`](./docs/05-ANTI-PATTERNS.md) | Common AI mistakes |
 | [`docs/07-SHARED-COMPONENTS.md`](./docs/07-SHARED-COMPONENTS.md) | `$ref` / shared |
 | [`docs/08-ORDER-FORM.md`](./docs/08-ORDER-FORM.md) | COD / checkout contract |
-| [`docs/09-THEME-PORTING.md`](./docs/09-THEME-PORTING.md) | Full-theme craft lessons |
-| [`docs/10-SCHEMA-LIBRARY.md`](./docs/10-SCHEMA-LIBRARY.md) | Theme library catalog |
+| [`docs/09-THEME-PORTING.md`](./docs/09-THEME-PORTING.md) | Full-template craft lessons |
+| [`docs/10-SCHEMA-LIBRARY.md`](./docs/10-SCHEMA-LIBRARY.md) | Template library catalog |
 | [`docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md`](./docs/11-PAGES-CHECKOUT-THANKS-PRODUCT.md) | Special pages |
-| [`docs/12-DARK-LIGHT-THEME.md`](./docs/12-DARK-LIGHT-THEME.md) | Theme mode + tokens |
+| [`docs/12-DARK-LIGHT-THEME.md`](./docs/12-DARK-LIGHT-THEME.md) | Dark/light/system mode + tokens |
 | [`docs/13-TEMPLATE-I18N.md`](./docs/13-TEMPLATE-I18N.md) | `locales` + `t()` |
 | [`docs/14-FILTERATOR.md`](./docs/14-FILTERATOR.md) | Product/category lists |
 | [`docs/16-AUTHORING-TS-IMPORTS.md`](./docs/16-AUTHORING-TS-IMPORTS.md) | TSX + npm imports |

package/scaffolds/blank/README.md

@@ -1,6 +1,10 @@
-# Feeef theme
+# Feeef template
 
-This folder is a **Node.js package** (see `package.json`). Scripts wrap the global `feeef` CLI — install it once (`npm link` from the Feeef `cli/` package, or `npm install -g @feeef.dev/cli`).
+This folder is a **Node.js package** (see `package.json`). Scripts wrap the global `feeef` CLI:
+
+```bash
+npm install -g @feeef.dev/cli
+```
 
 **AI / Cursor:** read [`AGENTS.md`](./AGENTS.md) and [`docs/00-INDEX.md`](./docs/00-INDEX.md) first. Rules and skills live under [`.cursor/`](./.cursor/).
 
@@ -14,8 +18,8 @@ feeef use                 # or: feeef use <store-id-or-slug>
 
 npm run build             # → dist/data.json
 npm run check
-npm run dev               # → http://{slug}.localhost.feeef.org:3456
+npm run dev               # remote draft preview (?preview=…) — live shop unchanged
 npm run publish -- --apply
 ```
 
-See `feeef template --help`.
+See [`docs/04-WORKFLOW.md`](./docs/04-WORKFLOW.md) and `feeef template --help`.

package/scaffolds/blank/docs/00-INDEX.md

@@ -1,4 +1,4 @@
-# Theme docs — index
+# Template docs — index
 
 Read [`../AGENTS.md`](../AGENTS.md) first. Jump by task below.
 
@@ -11,13 +11,15 @@ Read [`../AGENTS.md`](../AGENTS.md) first. Jump by task below.
 | 07 | [SHARED-COMPONENTS](./07-SHARED-COMPONENTS.md) | `shared/` + `$ref` |
 | 08 | [ORDER-FORM](./08-ORDER-FORM.md) | COD / checkout contract |
 | 09 | [THEME-PORTING](./09-THEME-PORTING.md) | Craft / cart / search / PLP lessons |
-| 10 | [SCHEMA-LIBRARY](./10-SCHEMA-LIBRARY.md) | Drag-drop theme library |
+| 10 | [SCHEMA-LIBRARY](./10-SCHEMA-LIBRARY.md) | Drag-drop template library |
 | 11 | [PAGES](./11-PAGES-CHECKOUT-THANKS-PRODUCT.md) | checkout / thanks / product |
 | 12 | [DARK-LIGHT](./12-DARK-LIGHT-THEME.md) | Dark / light / system |
 | 13 | [I18N](./13-TEMPLATE-I18N.md) | `locales/*.json` + `t()` |
 | 14 | [FILTERATOR](./14-FILTERATOR.md) | Product / category lists |
 | 16 | [TS-IMPORTS](./16-AUTHORING-TS-IMPORTS.md) | TypeScript + npm imports |
 
+CLI install: `npm install -g @feeef.dev/cli` — see [04-WORKFLOW](./04-WORKFLOW.md) for draft preview vs live.
+
 ## Task cheat-sheet
 
 | Task | Read |
@@ -29,5 +31,5 @@ Read [`../AGENTS.md`](../AGENTS.md) first. Jump by task below.
 | Dark / light | **12** |
 | Translations | **13** |
 | Product grids / filters | **14** |
-| Port / polish a full theme | **09** |
-| Build / preview / publish | **04** |
+| Port / polish a full template | **09** |
+| Build / preview / publish | **04** (draft preview ≠ live) |

package/scaffolds/blank/docs/04-WORKFLOW.md

@@ -1,20 +1,26 @@
-# Theme workflow (this package)
+# Template workflow (this package)
 
-This folder is a **Node.js theme package**. Scripts wrap the Feeef CLI (`feeef`).
+This folder is a **Node.js template package**. Scripts wrap the Feeef CLI (`feeef`).
+
+Install the CLI once:
+
+```bash
+npm install -g @feeef.dev/cli
+```
 
 ## Setup (once)
 
 ```bash
-# Install Feeef CLI globally (or npm link from the Feeef cli package)
-feeef signin
+feeef signin              # browser OAuth — no client secret
 feeef use                 # pick one of your stores
+npm install               # React/TS types for the editor
 ```
 
 ## Everyday loop
 
 1. Add pages/components with the CLI (or edit under `pages/`, `shared/`, `library/`, `locales/`).
-2. `npm run build` → writes `dist/data.json` (+ locales).
-3. `npm run dev` → pushes a **draft** preview to your store and opens `https://{slug}.…/?preview=…` (live theme unchanged).
+2. `npm run build` → writes `dist/data.json` (+ locales, schema).
+3. `npm run dev` → pushes a **draft** to your store and opens `https://{slug}.…/?preview=…`.
 4. Ship: `npm run publish -- --apply` (or `feeef template publish --apply`).
 
 | Script / command | Effect |
@@ -25,10 +31,15 @@ feeef use                 # pick one of your stores
 | `feeef template remove component <page> <name>` | Delete component file/folder |
 | `npm run build` | Compile source → `dist/` |
 | `npm run check` | Validate without relying on a dirty dist |
-| `npm run dev` | Watch/build + remote draft preview (never overwrites live) |
-| `npm run publish` | Upload template + locales (+ optional install) |
+| `npm run dev` | Watch/build + **remote draft preview** (never overwrites live) |
+| `npm run publish` | Upload template + locales (+ optional `--apply` install) |
+
+### Draft preview vs live
 
-Exit draft preview in the browser via the banner (**Exit preview**) or `/?preview=0`.
+- **`npm run dev`** writes `metadata.templatePreview` only. Customers still see live `metadata.templateData`.
+- Browse the full shop (home, products, cart, checkout) while the preview cookie is set.
+- **Exit preview:** banner → **Exit**, or visit `/?preview=0`. Stopping the CLI clears the draft.
+- **Go live:** only `publish --apply` (or merchant editor Save / install).
 
 ### Scaffold examples
 
@@ -39,13 +50,13 @@ feeef template remove component products grid --yes
 feeef template remove page products --yes
 ```
 
-Legacy themes that already use `sections/`: `add component` writes under `sections/main/components/` (or pass `--section header`).
+Legacy templates that already use `sections/`: `add component` writes under `sections/main/components/` (or pass `--section header`).
 
 ## Source layout
 
 ```
 feeef.template.json
-schema.ts                           # theme-owned schema overlay (typed)
+schema.ts                           # template-owned schema overlay (typed)
 props.json                          # default root props (data)
 pages/<page>/page.json
 pages/<page>/components/            # preferred (→ published sections.main)
@@ -62,16 +73,16 @@ locales/en.json
 
 Do **not** mix `pages/<page>/components/` and `pages/<page>/sections/` on the same page.
 
-### Theme schema (`schema.ts`)
+### Template schema (`schema.ts`)
 
-Controls what the merchant editor sees for **this** theme (pages, layouts, root `propsSchema`). Build merges it with Lithium built-ins → `dist/schema.json` (publish uploads that as `StoreTemplate.schema`).
+Controls what the merchant editor sees for **this** template (pages, layouts, root `propsSchema`). Build merges it with Lithium built-ins → `dist/schema.json` (publish uploads that as `StoreTemplate.schema`).
 
 ```ts
 export const schema = {
-  name: "my-theme",
+  name: "my-template",
   version: "0.1.0",
   schema: "1.0",
-  propsSchema: { theme: { type: "object", /* … */ } },
+  propsSchema: { theme: { type: "object", /* light/dark mode props */ } },
   pages: {
     home: {
       name: "Home",
@@ -80,18 +91,11 @@ export const schema = {
       layout: { sm: [{ type: "column", children: ["main"] }] },
     },
   },
-} as const satisfies FeeefThemeSchema;
+} as const satisfies FeeefThemeSchema; // type name is historical; this is the template schema
 ```
 
 Types: `types/feeef-template-schema.d.ts`. Fallback: `schema.json` (same shape).
 
-## Custom components
-locales/en.json
-feeef.template.json
-```
-
-Do **not** mix `pages/<page>/components/` and `pages/<page>/sections/` on the same page.
-
 ## Custom components
 
 - Prefer page-level `components/hero.tsx` — `export const meta` + `function App() { … }`
@@ -126,4 +130,5 @@ function App() {
 - Commit hand-tweaked `dist/data.json` as the only source of truth
 - Put `code` / schemas under `props`
 - Call `ff.orders.send` from custom checkout (use `POST /api/orders/create` — [08](./08-ORDER-FORM.md))
-- Set production env overrides meant for local preview only
+- Expect `npm run dev` to update what customers see (it does not)
+- Clone the Lithium storefront just to preview (remote draft is the default)

package/scaffolds/blank/docs/05-ANTI-PATTERNS.md

@@ -46,8 +46,10 @@ High-signal mistakes AIs and humans make in this system.
 | Hand-edit `dist/data.json` as primary workflow | Edit `pages/` / `shared/`, then `npm run build` |
 | Use Node APIs inside component source | Use `utils/get-template.ts` |
 | Arbitrary filesystem preview paths | Only `feeef template dev` / CLI override |
+| Treating `npm run dev` as “go live” | Draft only — use `publish --apply` for customers |
+| Cloning Lithium storefront just to preview | Default is remote draft (`?preview=`) |
 | Expect Shopify reference dumps to render | They are not Feeef themes |
-| Skip `npm run check` after edits | Rebuild and hard-refresh preview |
+| Skip `npm run check` after edits | Rebuild and refresh draft preview |
 | Commit `dist/` as source | Source is the folder tree |
 | Duplicate the same footer/navbar JSX on every page | Promote to `shared/components/<id>/` + `$ref` |
 | Copy dawn-order-form as “complete” checkout | Follow `docs/08-ORDER-FORM.md` + native `order-form.tsx` |

package/scaffolds/blank/package.json

@@ -1,8 +1,8 @@
 {
-  "name": "feeef-theme",
+  "name": "feeef-template",
   "private": true,
   "version": "0.1.0",
-  "description": "Feeef Lithium theme",
+  "description": "Feeef Lithium template",
   "type": "module",
   "engines": {
     "node": ">=18"
@@ -10,6 +10,7 @@
   "scripts": {
     "build": "feeef template build",
     "check": "feeef template check",
+    "test": "feeef template smoke",
     "dev": "feeef template dev",
     "publish": "feeef template publish",
     "typecheck": "tsc --noEmit"

package/vendor/template-kit/bin/feeef-template.mjs

@@ -25,6 +25,7 @@ Usage:
   feeef-template unpack <data.json> -o <outDir> [--force]
   feeef-template build  <srcDir> [-o <data.json>]
   feeef-template check  <srcDir>
+  feeef-template smoke  <srcDir>   # build + SSR-eval every custom App
   feeef-template watch  <srcDir> [-o <data.json>]
 
 Examples (from storefront/):
@@ -148,6 +149,37 @@ async function main() {
       return;
     }
 
+    if (cmd === "smoke") {
+      const src = positional[0];
+      if (!src) {
+        console.error("Usage: smoke <srcDir>");
+        process.exit(1);
+      }
+      const srcDir = resolveFromCwd(src);
+      const { smokeTheme } = await import("../lib/smoke.mjs");
+      const result = await smokeTheme({ srcDir, build: true });
+      for (const f of result.failed) {
+        const label =
+          f.item.sourcePath || f.item.instanceId || f.item.loc || "?";
+        console.error(`✗ ${label}`);
+        console.error(`  ${f.error.message}`);
+        if (f.error.stack) {
+          const lines = String(f.error.stack).split("\n").slice(1, 4);
+          for (const line of lines) console.error(`  ${line.trim()}`);
+        }
+      }
+      if (result.failed.length) {
+        console.error(
+          `smoke failed — ${result.failed.length}/${result.total} components`,
+        );
+        process.exit(1);
+      }
+      console.log(
+        `✓ smoke ok — ${result.passed}/${result.total} custom components rendered`,
+      );
+      return;
+    }
+
     if (cmd === "watch") {
       const src = positional[0];
       if (!src) {

package/vendor/template-kit/lib/build.mjs

@@ -56,9 +56,10 @@ function readJson(filePath) {
  * Nested slots/children only apply to folder entries.
  * @param {string} root Absolute folder or flat file path
  * @param {string[]} fileStack
+ * @param {string} srcDir Theme root (for relative `sourcePath`)
  * @returns {Record<string, any>}
  */
-function readComponentRaw(root, fileStack) {
+function readComponentRaw(root, fileStack, srcDir) {
   const loaded = loadComponentMeta(root);
   const track = loaded.jsonPath || loaded.entry || root;
   fileStack.push(track);
@@ -70,9 +71,24 @@ function readComponentRaw(root, fileStack) {
   delete component.order;
   delete component.$schema;
 
+  const toPosix = (p) => p.split(path.sep).join("/");
+  const absSource = loaded.entry || root;
+  try {
+    component.sourcePath = toPosix(path.relative(srcDir, absSource));
+  } catch {
+    component.sourcePath = toPosix(absSource);
+  }
+
   const compiled = compileComponentSource(root);
   if (compiled) {
     component.code = compiled.code;
+    if (compiled.entry) {
+      try {
+        component.sourcePath = toPosix(path.relative(srcDir, compiled.entry));
+      } catch {
+        /* keep prior sourcePath */
+      }
+    }
   }
 
   // Flat leaves cannot host children/slots folders.
@@ -85,7 +101,7 @@ function readComponentRaw(root, fileStack) {
     const childEntries = listComponentEntries(childrenDir);
     if (childEntries.length > 0) {
       component.children = childEntries.map((d) =>
-        readComponentRaw(d, fileStack),
+        readComponentRaw(d, fileStack, srcDir),
       );
     }
   }
@@ -97,7 +113,7 @@ function readComponentRaw(root, fileStack) {
     for (const slotId of listDirs(slotsDir)) {
       const slotChildren = listComponentEntries(path.join(slotsDir, slotId));
       slotsFromDirs[slotId] = slotChildren.map((d) =>
-        readComponentRaw(d, fileStack),
+        readComponentRaw(d, fileStack, srcDir),
       );
     }
   }
@@ -133,7 +149,7 @@ function buildSharedCatalog(srcDir) {
   const entries = listComponentEntries(sharedRoot);
   const ids = entries.map((p) => componentIdFromPath(p));
   for (let i = 0; i < entries.length; i++) {
-    catalog.set(ids[i], readComponentRaw(entries[i], fileStack));
+    catalog.set(ids[i], readComponentRaw(entries[i], fileStack, srcDir));
   }
 
   // Expand nested shared refs inside library definitions.
@@ -229,7 +245,7 @@ export function buildTemplate({ srcDir, outPath, write = true }) {
     if (flatEntries.length > 0) {
       sections.main = {
         components: flatEntries.map((entryPath) => {
-          const raw = readComponentRaw(entryPath, fileStack);
+          const raw = readComponentRaw(entryPath, fileStack, srcDir);
           if (sharedIdFromComponent(raw)) sharedPlacementCount += 1;
           return resolveSharedInTree(
             raw,
@@ -245,7 +261,7 @@ export function buildTemplate({ srcDir, outPath, write = true }) {
         const componentEntries = listComponentEntries(componentsDir);
         sections[sectionId] = {
           components: componentEntries.map((entryPath) => {
-            const raw = readComponentRaw(entryPath, fileStack);
+            const raw = readComponentRaw(entryPath, fileStack, srcDir);
             if (sharedIdFromComponent(raw)) sharedPlacementCount += 1;
             return resolveSharedInTree(
               raw,

package/vendor/template-kit/lib/library.mjs

@@ -41,7 +41,7 @@ const CATALOG_KEYS = new Set([
  *
  * @param {object} opts
  * @param {string} opts.srcDir
- * @param {(dir: string, fileStack: string[]) => Record<string, any>} opts.readComponentRaw
+ * @param {(dir: string, fileStack: string[], srcDir: string) => Record<string, any>} opts.readComponentRaw
  * @param {(node: any, catalog: Map<string, any>, resolving: Set<string>, hint: string) => any} [opts.resolveSharedInTree]
  * @param {Map<string, any>} [opts.sharedCatalog]
  */
@@ -68,7 +68,7 @@ export function buildSchemaLibrary({
 
   for (const entryPath of listComponentEntries(libraryRoot)) {
     const folderName = componentIdFromPath(entryPath);
-    let raw = readComponentRaw(entryPath, fileStack);
+    let raw = readComponentRaw(entryPath, fileStack, srcDir);
 
     if (resolveSharedInTree && catalog.size > 0) {
       raw = resolveSharedInTree(