@onexapis/cli 1.1.44 → 1.1.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onexapis/cli",
-  "version": "1.1.44",
+  "version": "1.1.46",
   "description": "CLI tool for OneX theme development - scaffolds themes using @onexapis/core",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -49,8 +49,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.470.0",
-    "@onexapis/core": "^1.0.9",
+    "@onexapis/core": "^1.0.12",
     "@tanstack/react-query": "^5.90.16",
     "adm-zip": "^0.5.16",
     "archiver": "^7.0.1",

package/templates/default/.cursorrules

@@ -0,0 +1,126 @@
+# CLAUDE.md — Routing rules for AI agents
+
+This is an **OneX theme project**. It ships with the `onexthm` MCP server,
+which provides tools that **write section files for you**. You must use those
+tools as your first move on every theme task.
+
+For deep reference (component types, hooks, animation tokens, color system,
+dark mode, locale, full architecture), read **`THEME_REFERENCE.md`** in this
+directory or call the relevant `onexthm_*` tool.
+
+---
+
+## Before you start
+
+At the start of every session, confirm the `onexthm_*` tools are available
+in your tool list. If they are not, STOP and tell the user:
+
+> "The onexthm MCP server is not loaded. Restart your AI client after
+> verifying `.mcp.json` registers `@onexapis/theme-mcp`."
+
+Do not silently fall back to writing files by hand.
+
+---
+
+## Routing rules — what tool to call when
+
+| When the user says… | Call this tool | Notes |
+|---|---|---|
+| "add / create / scaffold a section" (hero, header, footer, pricing, FAQ, testimonials, gallery, CTA, features, contact, newsletter, product grid, blog list, anything) | **`onexthm_create_section`** | Pass `projectDir` (this directory). Writes 3 files + patches `sections-registry.ts` in one call. |
+| "add / create a page" (home, about, product detail, blog detail, checkout, order lookup, custom) | **`onexthm_create_page`** | Pass `projectDir`. Writes page config + patches `bundle-entry.ts`. |
+| "convert / port / turn this HTML into a section", user pastes markup | **`onexthm_from_html`** | Pass `projectDir` + the source markup. |
+| "convert Figma to a section", user references a Figma design | **`figma:get_metadata`** + **`figma:get_variable_defs`** → **`onexthm_from_figma`** | Call the figma tools first, then pass output to `onexthm_from_figma`. |
+| "validate / lint / check my theme" | **`onexthm_validate`** | Run automatically after every write. |
+| "fix / auto-fix / repair errors" | **`onexthm_fix`** | Auto-fixes: missing "use client", unregistered sections, schema mismatches, invalid page refs. Call `onexthm_validate` after to confirm. |
+| "build / compile / bundle my theme" | **`onexthm_build`** | Returns structured errors with file:line. Run after code changes. |
+| "what hooks can I use?" | **`onexthm_list_hooks`** | Filter by category. 44 hooks across 8 categories. |
+| Anything else (architecture, animation, dark mode, locale, blocks, components) | Read `THEME_REFERENCE.md` first | Do not improvise. |
+
+`projectDir` is **the directory containing `theme.config.ts` and `sections-registry.ts`**. In a fresh session opened in this folder, that's the current working directory.
+
+---
+
+## Forbidden behaviors
+
+These break the editor and storefront. Never do them.
+
+1. **Never hand-write a section's `.tsx`, `.schema.ts`, or `index.ts`** when adding a new section. Call `onexthm_create_section`. The tool already produces correct file structure, schema shape, data attributes, imports, and registry entry. Hand-writing one-offs causes drift.
+2. **Never edit `sections-registry.ts` by hand** to add a new section. The tools patch it for you.
+3. **Never use raw `<h1>`, `<p>`, `<button>`** for *content* inside a section. Content goes through `ComponentRenderer` from `@onexapis/core/renderers`. Section components define **layout only**.
+4. **Never skip `data-section-id`, `data-section-type`, `data-block-id`, `data-block-type`** on wrapper elements. Without them, the visual editor cannot select or edit the section.
+5. **Never use `useEffect` for data fetching, never hardcode API URLs, never import from `@onexapis/core/internal`**. Use the documented hooks (`useProducts`, `useBlogs`, `useCart`, `useAuth`, `useCheckout`).
+
+---
+
+## Calling the tools — minimal examples
+
+```jsonc
+// Create a new section
+onexthm_create_section({
+  projectDir: "<absolute path to this directory>",
+  name: "pricing-table",
+  description: "Three-tier pricing table with featured tier"
+})
+
+// Convert pasted HTML/JSX to a section
+onexthm_from_html({
+  projectDir: "<absolute path to this directory>",
+  sectionName: "hero-banner",
+  htmlCode: "<div>...the user's markup...</div>"
+})
+
+// Convert a Figma frame (after calling figma:get_metadata first)
+onexthm_from_figma({
+  projectDir: "<absolute path to this directory>",
+  sectionName: "feature-grid",
+  figmaMetadata: "<output of figma:get_metadata>",
+  figmaVariables: "<output of figma:get_variable_defs>"
+})
+
+// Create a page
+onexthm_create_page({
+  projectDir: "<absolute path to this directory>",
+  handle: "product-detail",
+  path: "/products/[slug]",
+  isDynamic: true,
+  dynamicSegments: ["slug"]
+})
+
+// Validate after any write
+onexthm_validate({ projectDir: "<absolute path to this directory>" })
+
+// Auto-fix validation errors
+onexthm_fix({ projectDir: "<absolute path to this directory>" })
+
+// Build the theme
+onexthm_build({ projectDir: "<absolute path to this directory>" })
+```
+
+All tools default to writing files on disk. Pass `dryRun: true` if the user
+explicitly asks to preview without writing. Pass `force: true` to overwrite
+existing files.
+
+---
+
+## After a tool call
+
+1. Read the tool's response — it lists what was written and warns about anything skipped.
+2. Run `onexthm_validate` if the tool didn't already.
+3. Show the user the new file paths so they know where to edit further.
+4. Only edit the generated files **after** they exist on disk — never re-generate by hand.
+
+---
+
+## When the answer isn't here
+
+If the user's question is about hooks, components, blocks, animation, dark
+mode, locale, dynamic pages, payments, the cart, or any deep API question,
+either:
+
+- Read `THEME_REFERENCE.md` (lives next to this file), or
+- Call `onexthm_list_hooks` for hook signatures, or
+- Read the `onexthm://components`, `onexthm://blocks`, `onexthm://field-types`,
+  `onexthm://hooks`, or `onexthm://rules` MCP resources.
+
+`THEME_REFERENCE.md` is the canonical reference document for everything not
+covered by these routing rules.

package/templates/default/AGENTS.md

@@ -0,0 +1,126 @@
+# CLAUDE.md — Routing rules for AI agents
+
+This is an **OneX theme project**. It ships with the `onexthm` MCP server,
+which provides tools that **write section files for you**. You must use those
+tools as your first move on every theme task.
+
+For deep reference (component types, hooks, animation tokens, color system,
+dark mode, locale, full architecture), read **`THEME_REFERENCE.md`** in this
+directory or call the relevant `onexthm_*` tool.
+
+---
+
+## Before you start
+
+At the start of every session, confirm the `onexthm_*` tools are available
+in your tool list. If they are not, STOP and tell the user:
+
+> "The onexthm MCP server is not loaded. Restart your AI client after
+> verifying `.mcp.json` registers `@onexapis/theme-mcp`."
+
+Do not silently fall back to writing files by hand.
+
+---
+
+## Routing rules — what tool to call when
+
+| When the user says… | Call this tool | Notes |
+|---|---|---|
+| "add / create / scaffold a section" (hero, header, footer, pricing, FAQ, testimonials, gallery, CTA, features, contact, newsletter, product grid, blog list, anything) | **`onexthm_create_section`** | Pass `projectDir` (this directory). Writes 3 files + patches `sections-registry.ts` in one call. |
+| "add / create a page" (home, about, product detail, blog detail, checkout, order lookup, custom) | **`onexthm_create_page`** | Pass `projectDir`. Writes page config + patches `bundle-entry.ts`. |
+| "convert / port / turn this HTML into a section", user pastes markup | **`onexthm_from_html`** | Pass `projectDir` + the source markup. |
+| "convert Figma to a section", user references a Figma design | **`figma:get_metadata`** + **`figma:get_variable_defs`** → **`onexthm_from_figma`** | Call the figma tools first, then pass output to `onexthm_from_figma`. |
+| "validate / lint / check my theme" | **`onexthm_validate`** | Run automatically after every write. |
+| "fix / auto-fix / repair errors" | **`onexthm_fix`** | Auto-fixes: missing "use client", unregistered sections, schema mismatches, invalid page refs. Call `onexthm_validate` after to confirm. |
+| "build / compile / bundle my theme" | **`onexthm_build`** | Returns structured errors with file:line. Run after code changes. |
+| "what hooks can I use?" | **`onexthm_list_hooks`** | Filter by category. 44 hooks across 8 categories. |
+| Anything else (architecture, animation, dark mode, locale, blocks, components) | Read `THEME_REFERENCE.md` first | Do not improvise. |
+
+`projectDir` is **the directory containing `theme.config.ts` and `sections-registry.ts`**. In a fresh session opened in this folder, that's the current working directory.
+
+---
+
+## Forbidden behaviors
+
+These break the editor and storefront. Never do them.
+
+1. **Never hand-write a section's `.tsx`, `.schema.ts`, or `index.ts`** when adding a new section. Call `onexthm_create_section`. The tool already produces correct file structure, schema shape, data attributes, imports, and registry entry. Hand-writing one-offs causes drift.
+2. **Never edit `sections-registry.ts` by hand** to add a new section. The tools patch it for you.
+3. **Never use raw `<h1>`, `<p>`, `<button>`** for *content* inside a section. Content goes through `ComponentRenderer` from `@onexapis/core/renderers`. Section components define **layout only**.
+4. **Never skip `data-section-id`, `data-section-type`, `data-block-id`, `data-block-type`** on wrapper elements. Without them, the visual editor cannot select or edit the section.
+5. **Never use `useEffect` for data fetching, never hardcode API URLs, never import from `@onexapis/core/internal`**. Use the documented hooks (`useProducts`, `useBlogs`, `useCart`, `useAuth`, `useCheckout`).
+
+---
+
+## Calling the tools — minimal examples
+
+```jsonc
+// Create a new section
+onexthm_create_section({
+  projectDir: "<absolute path to this directory>",
+  name: "pricing-table",
+  description: "Three-tier pricing table with featured tier"
+})
+
+// Convert pasted HTML/JSX to a section
+onexthm_from_html({
+  projectDir: "<absolute path to this directory>",
+  sectionName: "hero-banner",
+  htmlCode: "<div>...the user's markup...</div>"
+})
+
+// Convert a Figma frame (after calling figma:get_metadata first)
+onexthm_from_figma({
+  projectDir: "<absolute path to this directory>",
+  sectionName: "feature-grid",
+  figmaMetadata: "<output of figma:get_metadata>",
+  figmaVariables: "<output of figma:get_variable_defs>"
+})
+
+// Create a page
+onexthm_create_page({
+  projectDir: "<absolute path to this directory>",
+  handle: "product-detail",
+  path: "/products/[slug]",
+  isDynamic: true,
+  dynamicSegments: ["slug"]
+})
+
+// Validate after any write
+onexthm_validate({ projectDir: "<absolute path to this directory>" })
+
+// Auto-fix validation errors
+onexthm_fix({ projectDir: "<absolute path to this directory>" })
+
+// Build the theme
+onexthm_build({ projectDir: "<absolute path to this directory>" })
+```
+
+All tools default to writing files on disk. Pass `dryRun: true` if the user
+explicitly asks to preview without writing. Pass `force: true` to overwrite
+existing files.
+
+---
+
+## After a tool call
+
+1. Read the tool's response — it lists what was written and warns about anything skipped.
+2. Run `onexthm_validate` if the tool didn't already.
+3. Show the user the new file paths so they know where to edit further.
+4. Only edit the generated files **after** they exist on disk — never re-generate by hand.
+
+---
+
+## When the answer isn't here
+
+If the user's question is about hooks, components, blocks, animation, dark
+mode, locale, dynamic pages, payments, the cart, or any deep API question,
+either:
+
+- Read `THEME_REFERENCE.md` (lives next to this file), or
+- Call `onexthm_list_hooks` for hook signatures, or
+- Read the `onexthm://components`, `onexthm://blocks`, `onexthm://field-types`,
+  `onexthm://hooks`, or `onexthm://rules` MCP resources.
+
+`THEME_REFERENCE.md` is the canonical reference document for everything not
+covered by these routing rules.