@zohofinance/commerce 1.0.1 → 1.1.0

package/README.md

@@ -4,8 +4,6 @@ A command-line tool for developing and building themes for Zoho Commerce stores.
 
 ## Installation
 
-Global installs (`npm i -g`) are not recommended. Prefer `npx` so you always run the package version resolved for the current project:
-
 ```bash
 # From a theme (or monorepo) that depends on the CLI:
 npx @zohofinance/commerce <command>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zohofinance/commerce",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "main": "ts-dist/index.js",
   "bin": {
     "zcommerce": "ts-dist/index.js"

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/SKILL.md

@@ -116,7 +116,7 @@ The skill runs these checks before Stage 0. If any fail, stop and surface to the
 
 1. **Ask developer for `storeUrl`.** Do not hardcode a demo store. Record in `dev-config.json`. See `dev-server-and-urls.md`.
 2. **Confirm page URLs before any browser navigation.** Home is often `/home` not `/`. Product/collection handles vary by store. Ask once; write confirmed URLs to `dev-config.json`.
-3. **Dev server.** Ask developer to start it, or start it yourself: `yarn run dev --storeUrl=<confirmed>`. Notify developer either way.
+3. **Dev server.** Ask the developer to start the local theme preview, or start it yourself with `npx @zohofinance/commerce theme dev --storeUrl=<your store url>` (value from `dev-config.json`). Notify the developer either way. Without `--storeUrl`, preview uses mock data only.
 4. **`npx @zohofinance/commerce --version` works from inside the theme folder.** If not, run `npm install @zohofinance/commerce` in the theme directory.
 5. **Figma MCP authenticated.** Otherwise: ask user to open Figma desktop with the first frame selected.
 6. **Chrome DevTools MCP available** (`.cursor/mcp.json`). See `.cursor/skills/browser-verify.md`.
@@ -228,7 +228,7 @@ The pipeline is the right tool for: building a new theme from scratch with full
 
 It is the **wrong** tool for, and should not be used for:
 - **Bug fix in an existing theme** → just open the file and fix it. No skill needed.
-- **One-off section change** → edit the section directly, then `cd <theme> && yarn run dev` to verify visually. No skill needed.
+- **One-off section change** → edit the section directly, then `cd <theme> && npx @zohofinance/commerce theme dev --storeUrl=<your store url>` to verify visually. No skill needed.
 - **Adding a theme setting** → edit `settings/schema.json` + `theme.json` directly.
 - **A new section that doesn't fit any of the 5 pages this skill handles** → also direct edit; the lint rules in `code-quality.md` still apply, but you don't need the orchestration.
 

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/ask-developer.md

@@ -22,7 +22,7 @@ When the answer IS in any of those three sources — look it up. Don't ask.
   - Product: `http://localhost:3000/products/item-1`
   - Collection: `http://localhost:3000/collections/all-products`
   Write confirmed URLs to `dev-config.json`.
-- **Dev server not running** → ask developer to start it, or start it yourself with their `storeUrl` and notify them.
+- **Dev server not running** → ask developer to start it, or start it yourself with `npx @zohofinance/commerce theme dev --storeUrl=<your store url>` (their confirmed value) and notify them.
 
 ### Section identification (page orchestrator Phase 2)
 

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/dev-server-and-urls.md

@@ -11,14 +11,14 @@ URL paths vary by store and dev setup. **Never assume** `/` is home or `/collect
 Before starting or requesting the dev server, ask:
 
 > What is your **storeUrl** for local dev?
-> Example: `https://yourstore.zohocommerce.com`
+> Example: `<your store url>`
 
 Record it in scratchpad:
 
 ```json
 // .claude/scratchpad/<theme>/dev-config.json
 {
-  "store_url": "https://yourstore.zohocommerce.com",
+  "store_url": "<your store url>",
   "dev_server_port": 3000,
   "page_urls": {},
   "confirmed_by_developer": false
@@ -31,11 +31,15 @@ Do not hardcode a demo store URL unless the developer confirms it.
 
 ## Step 2 — Dev server (ask or start)
 
+Pass the developer's store URL into `theme dev` via `--storeUrl`. Without it, the preview uses mock data only.
+
+Use the value from Step 1 (`dev-config.json` → `store_url`) as `<your store url>`.
+
 **Option A — Developer starts it (preferred if already running):**
 
 ```bash
 cd <theme_name>
-yarn run dev --storeUrl=<store_url_from_developer>
+npx @zohofinance/commerce theme dev --storeUrl=<your store url>
 ```
 
 Ask: *"Is the dev server already running on port 3000? If not, please start it with the command above (or tell me to start it)."*
@@ -43,9 +47,14 @@ Ask: *"Is the dev server already running on port 3000? If not, please start it w
 **Option B — Agent starts it:**
 
 1. Check: `lsof -i :3000`
-2. If not running, start in background from theme folder with developer's `storeUrl`
+2. If not running, start in background from the theme folder:
+
+```bash
+npx @zohofinance/commerce theme dev --storeUrl=<your store url>
+```
+
 3. Wait for "Preview theme in http://localhost:3000" (up to 30s)
-4. Tell the developer: *"Dev server started with storeUrl …"*
+4. Tell the developer: *"Dev server started with your storeUrl."*
 
 If the server fails to start → stop and ask the developer to fix CLI/network issues. Do not proceed to visual verify.
 

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/subagent-escalation.md

@@ -10,7 +10,7 @@ Every question, blocker, or notification from a **page orchestrator** or **secti
 |---|---|
 | `needs-developer.md` written | Surface immediately in chat with section/page name |
 | `unresolved.md` with `blocking: true` | Batch into `AskUserQuestion` before continuing |
-| Dev server not running | Ask developer to start OR start with confirmed `storeUrl` |
+| Dev server not running | Ask developer to start OR start with `npx @zohofinance/commerce theme dev --storeUrl=<your store url>` (confirmed `store_url`) |
 | Page URLs not confirmed | Pause build; run URL confirmation flow (`dev-server-and-urls.md`) |
 | Visual verify stuck after 3 iterations | Show CRITICAL items from `visual-diff.md` |
 | Subagent aborted / timed out | Report which page/section; parent takes over or re-spawns |

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/visual-verify-loop.md

@@ -29,7 +29,7 @@ Also always run:
 
 ### 1. Preconditions
 - `dev-config.json` exists with `confirmed_by_developer: true` — see `dev-server-and-urls.md`
-- Dev server running with developer's `storeUrl` (ask them to start, or start and notify)
+- Dev server running with developer's `storeUrl`: `npx @zohofinance/commerce theme dev --storeUrl=<your store url>` (ask them to start, or start and notify; value from `dev-config.json`)
 - Chrome DevTools MCP connected
 - Figma node ID in `figma-spec.json`
 - **Do not `navigate_page` until page URLs are confirmed with the developer**

package/ts-dist/mocks/init-theme/.cursor/agents/visual-compare.md

@@ -30,9 +30,9 @@ lsof -i :3000 2>/dev/null || lsof -i :9292 2>/dev/null
 **If NOT running**, start it in background:
 ```bash
 cd <theme_name>
-yarn run dev --storeUrl=<store_url> &
+npx @zohofinance/commerce theme dev --storeUrl=<your store url> &
 ```
-Wait for "compiled" or "ready" in output (up to 30 seconds).
+Wait for "compiled" or "ready" in output (up to 30 seconds). Use `store_url` from the inputs / `dev-config.json` for `<your store url>`. Without `--storeUrl`, the preview uses mock data only.
 
 **If already running**, skip to Step 2.
 

package/ts-dist/mocks/init-theme/.cursor/commands/build-theme.md

@@ -292,7 +292,7 @@ NEXT STEPS:
   1. Review unresolved items above
   2. /compare-section <theme_name> <section>  — only if unresolved items exist
   3. /qa-theme <theme_name>                   — full QA after any manual fixes
-  4. yarn run dev --storeUrl=<url>            — preview in browser
+  4. npx @zohofinance/commerce theme dev --storeUrl=<your store url>  — preview in browser (live store data; omit `--storeUrl` for mock only)
 ```
 
 ---

package/ts-dist/mocks/init-theme/.cursor/commands/compare-section.md

@@ -36,7 +36,7 @@ ensuring consistency between what was built and what is verified.
 **Default mode (code compare):** Extracts values from code and Figma MCP data, compares numerically. Fast and precise for CSS/Tailwind property matching.
 
 **Visual mode (`--visual`):** Launches the `visual-compare` subagent (see `.cursor/agents/visual-compare.md`). This mode:
-1. Ensures the dev server is running (`yarn run dev --storeUrl=<url>`)
+1. Ensures the dev server is running (`npx @zohofinance/commerce theme dev --storeUrl=<your store url>` — from `--store-url` / `dev-config.json`; without `--storeUrl`, preview uses mock data only)
 2. Uses Claude in Chrome to navigate to the page and screenshot the rendered section (desktop + mobile)
 3. Fetches the Figma screenshot via Figma MCP (`get_screenshot`)
 4. Visually compares both screenshots and reports differences

package/ts-dist/mocks/init-theme/.cursor/skills/browser-verify.md

@@ -12,7 +12,7 @@ Single source of truth for browser automation during theme development.
 
 1. **Developer confirmed `storeUrl`** — recorded in `.claude/scratchpad/<theme>/dev-config.json`
 2. **Developer confirmed page URLs** — same file, `confirmed_by_developer: true`
-3. Dev server running: `yarn run dev --storeUrl=<store_url>` (developer starts OR agent starts and notifies)
+3. Dev server running: `npx @zohofinance/commerce theme dev --storeUrl=<your store url>` (developer starts OR agent starts and notifies). Use `store_url` from `dev-config.json` for `<your store url>`. Without `--storeUrl`, the preview uses mock data only.
 4. Chrome DevTools MCP connected
 5. Figma node ID known for visual compare