@osimart/create-storefront 1.0.0 → 1.0.2

package/README.md

@@ -1,4 +1,4 @@
-# @osimart/osimart-storefront
+# @osimart/create-storefront
 
 The Osimart storefront **platform**, published as a private Nuxt layer. It has no look of
 its own. Every theme repo extends it:
@@ -77,5 +77,5 @@ developer (read).
 ## Working on the platform and a theme together
 
 ```bash
-cd osimart-theme-base && npm link ../osimart-storefront && npm run dev
+cd osimart-theme-base && npm link ../create-storefront && npm run dev
 ```

package/THEME_DEV_API.md

@@ -1,80 +1,69 @@
-# Theme dev API (backend contract for `osimart-theme`)
+# Theme dev API (what `osimart-theme` calls)
 
-All under `theme-dev/` on the store's API host. The host picks the store, as for every
-storefront call.
+Implemented in the backend's `builder/theme_dev.py`. Routes:
 
-**Auth:** `Authorization: ThemeToken <token>`. The `ThemeAccessToken` belongs to one store
-(hashed, revocable, created in the dashboard). Anything else gets `401`.
+- **Store host** (what the CLI uses): `builder/theme_dev.py` (its `urlpatterns`), included in the storefront
+  URL config as `store/apis/theme-dev/`. The CLI calls `<origin of NUXT_PUBLIC_STORE_API_BASE>/store/apis/theme-dev/`.
+- **Dashboard host**: `builder/urls.py` registers the same viewset as `online-store/apis/theme-dev/`,
+  plus `online-store/apis/theme-access-tokens/` for the dashboard's Theme access page.
 
-`<theme>` is either a theme id, `live` (the published theme) or `draft`.
+The store comes from the token, never the host. `OSIMART_THEME_DEV_URL` overrides the CLI's address.
 
-## Existing (from the theme access work)
+**Auth:** `Authorization: ThemeToken osit_…`. A `ThemeAccessToken` belongs to one store; only
+its SHA-256 is stored. Issue one with `python manage.py create_theme_token --store <uuid>` or
+`POST theme-access-tokens/ {store, name}` (dashboard auth; the response has `token` once).
+`DELETE theme-access-tokens/<id>/` revokes it.
 
-| Method | Path | Used by |
-|---|---|---|
-| GET | `theme-dev/schemas/` | `pull` → `.osimart/schemas.json` |
-| POST | `theme-dev/sections/sync/` | `push`: the theme's `*Section.schema.json` → `StoreSection` (`managed_by=CODE`) |
-
-`sections/sync/` body: `{ sections: [{ type, name, group?, allowed_templates, schema: { settings, blocks, max_blocks? } }], prune, dry_run }`.
-Response: `{ created, updated, unchanged, deleted, kept_in_use }` (lists of types).
+`<theme>` is `live`, `draft` or a theme id. `draft` is the token's own draft (an UNPUBLISHED theme): the
+first push creates it by duplicating the live theme, and publishing it clears it, so the next
+push starts a new one.
 
-## New
+| Method | Path | |
+|---|---|---|
+| GET | `themes/` | `[{id, name, role, version}]`; role is `LIVE`, `DRAFT` (this token's), `DEVELOPMENT` or `UNPUBLISHED` |
+| GET | `theme/?theme=<theme>` | `{theme, settings, groups: {header, footer}, templates: [{type, suffix, data}]}` |
+| PUT | `theme/` | `{theme, base_version?, dry_run?, settings?, groups?, templates?}` |
+| POST | `themes/<id>/publish/` | makes it live |
+| POST | `dev-session/` | `{theme, preview: {theme, preview_token}}` — this token's draft (created if missing), for `osimart-theme dev` |
+| GET | `schemas/` | `{sections: {TYPE: schema}, theme: [groups]}` |
+| POST | `sections/sync/` | `{sections: [{type, name, group?, allowed_templates, schema}], prune?, dry_run?}` |
 
-### `GET theme-dev/themes/`
+**Template data** (`theme/templates/*.json`, `theme/sections/*-group.json`):
 ```json
-[{ "id": "uuid", "name": "Base", "role": "LIVE", "updated_at": "…" },
- { "id": "uuid", "name": "Base (draft)", "role": "DRAFT", "updated_at": "…" }]
+{ "settings": {},
+  "sections": [
+    { "key": "hero-1a2b3c", "type": "SLIDESHOW", "name": "…", "disabled": false,
+      "starts_at": "…", "ends_at": "…",
+      "settings": { },
+      "blocks": [ { "key": "…", "type": "GROUP", "parent_key": "", "disabled": false,
+                    "settings": { }, "relations": { "product": "<uuid>" } } ] } ] }
 ```
+Blocks may also nest under a `blocks` key instead of using `parent_key`. A section or block
+without a `key` gets one generated.
 
-### `GET theme-dev/theme/?theme=<theme>`
-The theme's JSON exactly as stored, so a push of the same data is a no-op.
-```json
-{
-  "theme": { "id": "uuid", "name": "Base", "role": "LIVE", "version": "2026-10-12T13:40:11.120Z" },
-  "settings": { "PRIMARY_COLOR": "#20336b" },
-  "groups": {
-    "header": { "sections": [ { "key": "…", "type": "HEADER", "settings": {}, "blocks": [], "disabled": false } ] },
-    "footer": { "sections": [ … ] }
-  },
-  "templates": [
-    { "type": "INDEX", "suffix": "", "data": { "sections": [ … ] } },
-    { "type": "PRODUCT", "suffix": "alternate", "data": { "sections": [ … ] } },
-    { "type": "PAGE", "suffix": "contact", "data": { "sections": [ … ] } }
-  ]
-}
-```
-- `version` is any value that changes on every save of the theme, its templates or its groups
-  (`updated_at` of the newest row works).
-- `data` holds what the template stores (section order, settings, blocks); media stay as the
-  ids the dashboard saves, not resolved URLs.
+**Push rules:**
+- Each template file is diffed against what's stored and applied as the editor's own ops, so it
+  gets the dashboard's validation: allowed sections, unknown settings, max blocks, static
+  blocks, locked branding, relations belonging to the store.
+- Only changed values are sent, so pulling and pushing back unchanged is a no-op.
+- Templates in the push are created or updated, never deleted. Sections and blocks missing
+  from a file are removed.
+- A key reused with a different type is refused. Give the new section or block a new key.
+- New sections get exactly the blocks the file lists; default blocks aren't seeded.
+- `base_version` that doesn't match the theme's current version → `409`. The merchant
+  edited it in the dashboard after the pull.
+- Errors → `400 {"INDEX": {"<section or block key>": {"SETTING": "message"}}}`. One bad
+  template means nothing is saved.
+- `dry_run` validates and reports, then rolls back.
 
-### `PUT theme-dev/theme/`
-```json
-{
-  "theme": "draft",
-  "base_version": "2026-10-12T13:40:11.120Z",
-  "dry_run": false,
-  "settings": { … },
-  "groups": { "header": { … }, "footer": { … } },
-  "templates": [ { "type": "PRODUCT", "suffix": "alternate", "data": { … } } ]
-}
-```
-- `theme: "draft"`: use the store's draft. If there is none, copy the live theme into a new
-  draft first (the same as a theme update, so the live theme stays as the rollback).
-- `base_version` not null and different from the theme's current `version` → `409`
-  (the merchant changed it in the dashboard after the pull). `null` = overwrite.
-- Any key left out (`settings`, `groups`, a template) is left as it is. Templates are
-  created or replaced by `(type, suffix)` and never deleted here.
-- Validate everything the dashboard validates (`get_section_schemas(store)`: section types,
-  setting ids, block types, `visible_if`) and answer `400` with field errors. On `dry_run`,
-  validate and report only.
-- Response:
-```json
-{ "theme": { "id": "uuid", "name": "…", "role": "DRAFT", "version": "…" },
-  "created": ["PRODUCT.alternate"], "updated": ["INDEX"], "unchanged": ["PRODUCT"],
-  "preview_url": "https://store.com/?preview_theme=<id>" }
-```
+**Section sync:** creates or updates `StoreSection` rows marked `managed_by=CODE`. A built-in
+type can't be redefined; to restyle one, override its `.vue` file instead. `prune` deletes CODE
+rows missing from the repo, except ones still placed on a template (reported as `kept_in_use`).
 
-### `POST theme-dev/themes/<id>/publish/`
-Makes that theme live (the previous live one becomes unpublished). Returns the theme
-(`{ id, name, role }`).
+**Local dev (`osimart-theme dev`):** starts `nuxt dev`, opens a `dev-session/`, and on every save
+under `theme/` pushes to the draft (a PUT `theme/` response for a non-live theme carries
+`preview: {theme, preview_token}`). It writes `.osimart/dev.json`; `nuxt/osi-dev-theme.ts` reads it
+on each server render and the storefront sends `?theme=<id>&preview_token=<t>` to
+`store/apis/theme/bootstrap/` and `render/` (`theme_views.StorefrontThemeViewSet`), which then serve
+that theme, uncached and with the preview headers. The browser reloads after each push. Live is
+never touched; `push --theme live` or publishing the draft makes it live.

package/app/composables/useStoreInit.js

@@ -4,6 +4,9 @@ export function useStoreInit() {
   const bootstrapData = useState('bootstrap-data', () => null);
   const storeData = useState('store-data', () => null);
   const baseUrl = useState('base-url', () => '');
+  // `osimart-theme dev` only: the draft to render instead of the live theme.
+  // Null otherwise (nuxt/osi-dev-theme.ts).
+  const devTheme = useState('osi-dev-theme', () => null);
 
   const reqHeaders = import.meta.server ? useRequestHeaders(['host', 'x-forwarded-host', 'x-forwarded-proto']) : {};
   const browserHost =
@@ -36,6 +39,7 @@ const API_ROOT = storeApiBase
       const data = await storefrontService.bootstrap({
         baseUrl: API_ROOT,
         host: browserHost,
+        preview: devTheme.value,
       });
 
       bootstrapData.value = data;
@@ -48,5 +52,5 @@ const API_ROOT = storeApiBase
     return bootstrapData.value;
   }
 
-  return { storeData, baseUrl, bootstrapData, init };
+  return { storeData, baseUrl, bootstrapData, devTheme, init };
 }

package/app/composables/useStorefront.js

@@ -165,7 +165,7 @@ export function useStorefront() {
   // Refs survive an await fine — it's CREATING one that needs context. So
   // capture the ref now and read .value later.
   // ---------------------------------------------------------------------
-  const { init, baseUrl, bootstrapData } = useStoreInit();
+  const { init, baseUrl, bootstrapData, devTheme } = useStoreInit();
 
   let requestHost = "";
   if (import.meta.server) {
@@ -214,8 +214,11 @@ export function useStorefront() {
    */
   async function render(path) {
     if (!baseUrl.value) await init();
-    const args = { baseUrl: baseUrl.value, host: requestHost, path };
-    return cachedRequest(`render:${args.baseUrl}:${path}`, () => storefrontService.render(args));
+    const preview = devTheme.value;
+    const args = { baseUrl: baseUrl.value, host: requestHost, path, preview };
+    // The draft's revision is in the key: a push must not be answered from cache.
+    const rev = preview ? `:${preview.theme}:${preview.rev ?? ""}` : "";
+    return cachedRequest(`render:${args.baseUrl}${rev}:${path}`, () => storefrontService.render(args));
   }
 
   /** A menu by handle, with a safe empty shape so layouts never have to guard. */

package/app/composables/useTextStyles.js

@@ -40,6 +40,18 @@ const TEXT_TRANSFORMS = {
   CAPITALIZE: "capitalize",
 };
 
+/**
+ * A weight setting -> CSS font-weight. The schemas store numbers as strings
+ * ("700", FontWeight's values); older settings used names ("BOLD"). Before
+ * this accepted only names, so every "700" silently fell back to 400.
+ */
+function toWeight(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (FONT_WEIGHTS[value]) return FONT_WEIGHTS[value];
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 100 && n <= 900 ? n : undefined;
+}
+
 export function useTextStyle(settings, options = {}) {
   const { prefix = "TEXT", defaults = {} } = options;
   const {
@@ -69,7 +81,7 @@ export function useTextStyle(settings, options = {}) {
       // Falls back to the desktop size, not to a constant: an unset mobile size
       // means "same as desktop", not "16px".
       "--osi-fs-mobile": `${num(get("SIZE_MOBILE"), base)}px`,
-      "--osi-fw": FONT_WEIGHTS[get("WEIGHT")] ?? FONT_WEIGHTS[weight] ?? 400,
+      "--osi-fw": toWeight(get("WEIGHT")) ?? toWeight(weight) ?? 400,
       "--osi-lh": `${num(get("LINE_HEIGHT"), lineHeight) / 100}`,
       "--osi-ls": `${num(get("LETTER_SPACING"), 0) / 100}em`,
       "--osi-ff": FONT_FAMILIES[get("FONT")] ?? FONT_FAMILIES[font],

package/app/logic/components/ClassificationFeatured.js

@@ -21,7 +21,7 @@ export default function useLogic({ props }) {
     SMALL: "320px",
     MEDIUM: "460px",
     LARGE: "620px",
-    FULL: "100svh",
+    FULL: "100vh",
   };
 
   const position = computed(() =>

package/app/logic/sections/MediaContentSection.js

@@ -16,7 +16,7 @@ export default function useLogic({ props }) {
 
   /* --------------------------------------------------------- section shell */
 
-  const HEIGHTS = { SMALL: "40vh", MEDIUM: "60vh", LARGE: "80vh", FULL: "100svh" };
+  const HEIGHTS = { SMALL: "40vh", MEDIUM: "60vh", LARGE: "80vh", FULL: "100vh" };
   const background = computed(() => backgroundOf(s.value));
 
   const sectionStyle = computed(() => {

package/app/logic/sections/SlideshowSection.js

@@ -91,7 +91,7 @@ export default function useLogic({ props }) {
 
   /* ------------------------------------------------------------------ sizing */
 
-  const HEIGHTS = { SMALL: "320px", MEDIUM: "480px", LARGE: "640px", FULL: "100svh", ADAPT: "auto" };
+  const HEIGHTS = { SMALL: "320px", MEDIUM: "480px", LARGE: "640px", FULL: "100vh", ADAPT: "auto" };
 
   const vars = computed(() => {
     const v = s.value;

package/app/logic/sections/VideoSection.js

@@ -174,7 +174,7 @@ export default function useLogic({ props }) {
   /* ------------------------------------------------------------------ sizing */
 
   const RATIOS = { WIDE: "16 / 9", CLASSIC: "4 / 3", SQUARE: "1 / 1", PORTRAIT: "4 / 5", VERTICAL: "9 / 16", CINEMA: "21 / 9" };
-  const HEIGHTS = { SMALL: "40vh", MEDIUM: "60vh", LARGE: "80vh", FULL: "100svh" };
+  const HEIGHTS = { SMALL: "40vh", MEDIUM: "60vh", LARGE: "80vh", FULL: "100vh" };
 
   const frameVars = computed(() => {
     const v = s.value;

package/app/plugins/{geo.ts → geo.js}

@@ -21,4 +21,4 @@ export default defineNuxtPlugin(async () => {
       console.error('[GEO] Client-side fetch error:', err)
     }
   }
-})
+})

package/app/plugins/{vue-query.ts → vue-query.js}

@@ -2,4 +2,4 @@ import { VueQueryPlugin } from '@tanstack/vue-query'
 
 export default defineNuxtPlugin((nuxtApp) => {
   nuxtApp.vueApp.use(VueQueryPlugin)
-})
+})

package/bin/osimart-theme.mjs

@@ -2,6 +2,7 @@
 /**
  * osimart-theme — the theme repo's link to its store, like the Shopify CLI.
  *
+ *   osimart-theme dev [nuxt dev args]          run the site on your draft; every save in theme/ is pushed to it
  *   osimart-theme themes                       list the store's themes (id, name, role)
  *   osimart-theme pull [--theme live|<id>] [--delete]
  *   osimart-theme push [--theme draft|live|<id>] [--force] [--prune] [--dry-run]
@@ -18,11 +19,13 @@
  *
  * Env (read from .env too):
  *   OSIMART_THEME_TOKEN     Theme access token (dashboard → Theme access)
- *   OSIMART_THEME_DEV_URL   default: ${NUXT_PUBLIC_STORE_API_BASE}theme-dev/
+ *   NUXT_PUBLIC_STORE_API_BASE   the store's API (already set for `npm run dev`); the CLI calls
+ *                                <its origin>/store/apis/theme-dev/
  *
  * Backend contract: THEME_DEV_API.md in @ositcom/osimart-storefront.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, watch, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 
 const ROOT = process.cwd();
@@ -33,6 +36,7 @@ const SETTINGS_FILE = join(THEME_DIR, "config", "settings_data.json");
 const SECTIONS_DIR = join(ROOT, "app", "sections");
 const STATE_DIR = join(ROOT, ".osimart");
 const STATE_FILE = join(STATE_DIR, "state.json");
+const DEV_FILE = join(STATE_DIR, "dev.json");
 
 /* ---------------------------------------------------------------- env */
 
@@ -46,32 +50,43 @@ function loadDotenv() {
 }
 loadDotenv();
 
+/** Thrown, not exit(): `dev` reports it and keeps watching. */
+class CliError extends Error {}
 function fail(message) {
-  console.error(`✖ ${message}`);
-  process.exit(1);
+  throw new CliError(message);
 }
 
+/**
+ * The builder API's theme-dev route, on the same backend the storefront
+ * already talks to (NUXT_PUBLIC_STORE_API_BASE). OSIMART_THEME_DEV_URL only
+ * overrides it if the routes are mounted somewhere other than /store/apis/theme-dev/.
+ */
+// Relative, like the storefront's own `${storeApiBase}store/apis/...` calls, so a
+// base with a path (https://x.myosimart.com/api/) keeps it.
+const BUILDER_PATH = "store/apis/theme-dev/";
+
 function baseUrl() {
-  const explicit = process.env.OSIMART_THEME_DEV_URL;
+  const override = process.env.OSIMART_THEME_DEV_URL;
+  if (override) return override.endsWith("/") ? override : `${override}/`;
   const api = process.env.NUXT_PUBLIC_STORE_API_BASE;
-  const url = explicit || (api ? `${api.replace(/\/+$/, "")}/theme-dev/` : "");
-  if (!url) fail("Set OSIMART_THEME_DEV_URL or NUXT_PUBLIC_STORE_API_BASE in .env");
-  return url.endsWith("/") ? url : `${url}/`;
+  if (!api) fail("Set NUXT_PUBLIC_STORE_API_BASE in .env (the store's API, e.g. http://test6.192.168.1.12.nip.io:8000/)");
+  return new URL(BUILDER_PATH, api.endsWith("/") ? api : `${api}/`).toString();
 }
 
 async function request(method, path, body) {
   const token = process.env.OSIMART_THEME_TOKEN;
   if (!token) fail("Set OSIMART_THEME_TOKEN in .env (dashboard → Theme access)");
-  const res = await fetch(new URL(path, baseUrl()), {
+  const url = new URL(path, baseUrl());
+  const res = await fetch(url, {
     method,
     headers: { Authorization: `ThemeToken ${token}`, "Content-Type": "application/json", Accept: "application/json" },
     body: body === undefined ? undefined : JSON.stringify(body),
   });
   const text = await res.text();
   let data = null;
-  try { data = text ? JSON.parse(text) : null; } catch { data = { detail: text.slice(0, 300) }; }
+  try { data = text ? JSON.parse(text) : null; } catch { data = { detail: `not a theme-dev endpoint: ${url}` }; }
   if (!res.ok) {
-    const err = new Error(data?.detail || data?.message || `HTTP ${res.status}`);
+    const err = new Error(`${data?.detail || data?.message || `HTTP ${res.status}`} (${method} ${url})`);
     err.status = res.status;
     err.data = data;
     throw err;
@@ -184,48 +199,69 @@ async function pull(args) {
     console.log(`  (schemas not saved: ${e.message})`);
   }
 
-  saveState({ theme_id: data.theme.id, theme_name: data.theme.name, role: data.theme.role, version: data.theme.version, pulled_at: new Date().toISOString() });
-  console.log(`✔ pulled "${data.theme.name}" (${data.theme.role}) — ${data.templates?.length ?? 0} templates, ${Object.keys(groups).length} groups`);
+  saveState({
+    store_id: data.theme.store?.id, store_name: data.theme.store?.name,
+    theme_id: data.theme.id, theme_name: data.theme.name, role: data.theme.role,
+    version: data.theme.version, pulled_at: new Date().toISOString(),
+  });
+  console.log(`✔ pulled "${data.theme.name}" (${data.theme.role}) from ${data.theme.store?.name ?? "the store"} — ${data.templates?.length ?? 0} templates, ${Object.keys(groups).length} groups`);
 }
 
 async function push(args) {
-  const dryRun = args.includes("--dry-run");
-  const force = args.includes("--force");
-  const prune = args.includes("--prune");
-  const theme = flag(args, "--theme", "draft");
+  await pushOnce({
+    dryRun: args.includes("--dry-run"),
+    force: args.includes("--force"),
+    prune: args.includes("--prune"),
+    theme: flag(args, "--theme", "draft"),
+  });
+}
+
+/** Returns the PUT theme/ response, or null when theme/ is empty. */
+async function pushOnce({ dryRun = false, force = false, prune = false, theme = "draft", quiet = false } = {}) {
+  const log = quiet ? () => {} : console.log;
 
   // 1. Section types the theme adds (their schemas), so the editor can place them.
   const sections = readLocalSchemas();
   if (sections.length || prune) {
-    const report = await request("POST", "sections/sync/", { sections, prune, dry_run: dryRun });
-    console.log(`${dryRun ? "◌" : "✔"} section schemas: ${sections.length}`);
+    let report;
+    try {
+      report = await request("POST", "sections/sync/", {
+        sections, prune, dry_run: dryRun, expected_store: force ? null : state().store_id ?? null,
+      });
+    } catch (e) {
+      if (e.status === 400 && e.data) fail(`Section schemas rejected:\n${JSON.stringify(e.data, null, 2)}`);
+      throw e;
+    }
+    log(`${dryRun ? "◌" : "✔"} section schemas: ${sections.length}`);
     for (const key of ["created", "updated", "unchanged", "deleted", "kept_in_use"]) {
-      if (report?.[key]?.length) console.log(`  ${key.padEnd(11)} ${report[key].join(", ")}`);
+      if (report?.[key]?.length) log(`  ${key.padEnd(11)} ${report[key].join(", ")}`);
     }
   }
 
   // 2. Templates, groups, settings.
   const local = readLocalTheme();
   if (!local.templates.length && !Object.keys(local.groups).length && local.settings === undefined) {
-    console.log("  nothing in theme/ to push (run pull first)");
-    return;
+    log("  nothing in theme/ to push (run pull first)");
+    return null;
   }
-  const { version, theme_id, role } = state();
+  const { version, theme_id, role, store_id } = state();
   const sameTheme = theme === theme_id || theme === String(role || "").toLowerCase();
   try {
     const res = await request("PUT", "theme/", {
       theme,
       // The merchant may have edited the theme in the dashboard since the pull.
       base_version: force || !sameTheme ? null : version ?? null,
+      // Files pulled from another store (token swapped)? The backend refuses.
+      expected_store: force ? null : store_id ?? null,
       dry_run: dryRun,
       ...local,
     });
-    console.log(`${dryRun ? "◌ dry run" : "✔ pushed"} to "${res.theme.name}" (${res.theme.role}) — ${local.templates.length} templates`);
+    log(`${dryRun ? "◌ dry run" : "✔ pushed"} to "${res.theme.name}" (${res.theme.role}) on ${res.theme.store?.name ?? "the store"} — ${local.templates.length} templates`);
     for (const key of ["created", "updated", "unchanged"]) {
-      if (res[key]?.length) console.log(`  ${key.padEnd(9)} ${res[key].join(", ")}`);
+      if (res[key]?.length) log(`  ${key.padEnd(9)} ${res[key].join(", ")}`);
     }
-    if (res.preview_url) console.log(`  preview: ${res.preview_url}`);
     if (!dryRun && res.theme.id === theme_id) saveState({ version: res.theme.version });
+    return res;
   } catch (e) {
     if (e.status === 409) {
       fail("The theme changed on the store since your last pull (edited in the dashboard).\n  Run `osimart-theme pull`, merge with git, then push — or push --force to overwrite.");
@@ -235,6 +271,105 @@ async function push(args) {
   }
 }
 
+/* ---------------------------------------------------------------- dev */
+
+/**
+ * `npm run dev`: Nuxt on your draft instead of the live theme, like
+ * `shopify theme dev`.
+ *
+ *   1. starts `nuxt dev` (any args are passed on, e.g. --host);
+ *   2. gets this token's draft (created from live the first time);
+ *   3. on every save under theme/ (or a section .schema.json), pushes to the
+ *      draft and writes .osimart/dev.json; the site reloads itself.
+ *
+ * The live theme is never touched. When it looks right:
+ *   npm run theme:push -- --theme live      (or publish the draft in the dashboard)
+ *
+ * No OSIMART_THEME_TOKEN: just `nuxt dev` on the live theme.
+ */
+async function dev(args) {
+  rmSync(DEV_FILE, { force: true });
+  const nuxt = spawn("nuxt", ["dev", ...args], { stdio: "inherit", shell: true });
+  const stop = (code = 0) => {
+    rmSync(DEV_FILE, { force: true });
+    if (nuxt.exitCode === null) nuxt.kill();
+    process.exit(code);
+  };
+  nuxt.on("exit", (code) => stop(code ?? 0));
+  process.on("SIGINT", () => stop(0));
+  process.on("SIGTERM", () => stop(0));
+
+  if (!process.env.OSIMART_THEME_TOKEN) {
+    console.log("◌ OSIMART_THEME_TOKEN not set: showing the live theme, theme/ changes are not synced.");
+    return;
+  }
+
+  let rev = 0;
+  let preview = null;
+  const writeDev = () => writeJson(DEV_FILE, { ...preview, rev: ++rev });
+
+  try {
+    const session = await request("POST", "dev-session/");
+    preview = session.preview;
+    console.log(`✔ dev: showing your draft "${session.theme.name}"; saves in theme/ are pushed to it. Live is untouched.`);
+  } catch (e) {
+    console.error(`✖ dev: could not open the draft (${e.message}). Showing the live theme.`);
+    return;
+  }
+
+  let running = false;
+  let again = false;
+  const sync = async () => {
+    if (running) { again = true; return; }
+    running = true;
+    try {
+      const bad = invalidJsonFiles();
+      if (bad.length) {
+        console.log(`… waiting for valid JSON: ${bad.join(", ")}`);
+        return;
+      }
+      const res = await pushOnce({ quiet: true });
+      if (res?.preview) preview = res.preview;
+      const changed = [...(res?.created ?? []), ...(res?.updated ?? [])];
+      console.log(`✔ ${new Date().toLocaleTimeString()} synced${changed.length ? `: ${changed.join(", ")}` : " (no changes)"}`);
+      writeDev();
+    } catch (e) {
+      const detail = e.status === 400 && e.data ? `\n${JSON.stringify(e.data, null, 2)}` : "";
+      console.error(`✖ ${new Date().toLocaleTimeString()} not synced: ${e.status ? `${e.status} ` : ""}${e.message}${detail}`);
+    } finally {
+      running = false;
+      if (again) { again = false; schedule(); }
+    }
+  };
+
+  // Autosave writes often; push once the saves stop for a moment.
+  let timer;
+  const schedule = () => { clearTimeout(timer); timer = setTimeout(sync, 700); };
+
+  await sync();
+  if (existsSync(THEME_DIR)) watch(THEME_DIR, { recursive: true }, (_e, name) => {
+    if (!name || name.endsWith(".json")) schedule();
+  });
+  if (existsSync(SECTIONS_DIR)) watch(SECTIONS_DIR, (_e, name) => {
+    if (!name || name.endsWith(".schema.json")) schedule();
+  });
+}
+
+/** Files under theme/ (and section schemas) that don't parse yet — mid-edit. */
+function invalidJsonFiles() {
+  const files = [
+    ...(existsSync(SETTINGS_FILE) ? [SETTINGS_FILE] : []),
+    ...listJson(GROUPS_DIR).map((f) => join(GROUPS_DIR, f)),
+    ...listJson(TEMPLATES_DIR).map((f) => join(TEMPLATES_DIR, f)),
+    ...(existsSync(SECTIONS_DIR)
+      ? readdirSync(SECTIONS_DIR).filter((f) => f.endsWith(".schema.json")).map((f) => join(SECTIONS_DIR, f))
+      : []),
+  ];
+  return files.filter((file) => {
+    try { JSON.parse(readFileSync(file, "utf8")); return false; } catch { return true; }
+  }).map((file) => file.slice(ROOT.length + 1));
+}
+
 async function publish(args) {
   const id = args[0];
   if (!id) fail("Usage: osimart-theme publish <theme-id>  (see: osimart-theme themes)");
@@ -245,10 +380,11 @@ async function publish(args) {
 /* ---------------------------------------------------------------- main */
 
 const [command, ...args] = process.argv.slice(2);
-const commands = { themes, pull, push, publish };
+const commands = { dev, themes, pull, push, publish };
 
 if (!commands[command]) {
   console.log(`Usage:
+  osimart-theme dev     [nuxt dev args]
   osimart-theme themes
   osimart-theme pull    [--theme live|<id>] [--delete]
   osimart-theme push    [--theme draft|live|<id>] [--force] [--prune] [--dry-run]
@@ -256,4 +392,7 @@ if (!commands[command]) {
   process.exit(command ? 1 : 0);
 }
 
-commands[command](args).catch((e) => fail(e.status ? `${e.status} ${e.message}` : e.message));
+commands[command](args).catch((e) => {
+  console.error(`✖ ${e.status ? `${e.status} ` : ""}${e.message}`);
+  process.exit(1);
+});

package/nuxt/osi-dev-theme.ts

@@ -0,0 +1,67 @@
+import { existsSync, mkdirSync, watch } from "node:fs";
+import { join } from "node:path";
+import { addPluginTemplate, defineNuxtModule } from "@nuxt/kit";
+
+/**
+ * `osimart-theme dev` support (dev server only; does nothing in a build).
+ *
+ * The CLI pushes the theme repo's `theme/` files to the developer's draft on
+ * every save and writes `.osimart/dev.json`:
+ *
+ *   { "theme": "<draft id>", "preview_token": "…", "rev": 3 }
+ *
+ * This module
+ *   - reads that file on every server render into useState("osi-dev-theme"),
+ *     so bootstrap/ and render/ ask the backend for the draft instead of the
+ *     live theme (composables/useStoreInit.js, useStorefront.js);
+ *   - reloads the open browser tabs when it changes, i.e. after each push.
+ *
+ * No file (plain `nuxt dev`, or the CLI isn't running): the live theme, as before.
+ */
+export default defineNuxtModule({
+  meta: { name: "osi-dev-theme" },
+  setup(_options, nuxt) {
+    if (!nuxt.options.dev) return;
+
+    const dir = join(nuxt.options.rootDir, ".osimart");
+    const file = join(dir, "dev.json");
+
+    addPluginTemplate({
+      filename: "osi-dev-theme.server.mjs",
+      mode: "server",
+      getContents: () => `
+import { readFileSync } from "node:fs";
+import { defineNuxtPlugin, useState } from "#imports";
+
+const FILE = ${JSON.stringify(file)};
+
+export default defineNuxtPlugin({
+  name: "osi-dev-theme",
+  enforce: "pre",
+  setup() {
+    let value = null;
+    try {
+      const data = JSON.parse(readFileSync(FILE, "utf8"));
+      if (data && data.theme && data.preview_token) value = data;
+    } catch {}
+    useState("osi-dev-theme", () => null).value = value;
+  },
+});
+`,
+    });
+
+    // Reload the browser after a push. Vite only reloads for files in its
+    // module graph, and dev.json isn't one, so tell its client directly.
+    nuxt.hook("vite:serverCreated", (server, { isClient }) => {
+      if (!isClient) return;
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const watcher = watch(dir, (_event, name) => {
+        if (name && name !== "dev.json") return;
+        clearTimeout(timer);
+        timer = setTimeout(() => server.ws.send({ type: "full-reload", path: "*" }), 150);
+      });
+      nuxt.hook("close", () => watcher.close());
+    });
+  },
+});

package/nuxt.config.ts

@@ -1,5 +1,6 @@
 import { fileURLToPath } from "node:url";
 import osiSections from "./nuxt/osi-sections";
+import osiDevTheme from "./nuxt/osi-dev-theme";
 
 /**
  * @ositcom/osimart-storefront — the platform. Extended by every theme repo:
@@ -31,7 +32,7 @@ export default defineNuxtConfig({
   // creating a component with the same file name anywhere in its components/.
   components: [{ path: `${appDir}/components`, pathPrefix: false }],
 
-  modules: ["@nuxtjs/sitemap", "@pinia/nuxt", osiSections],
+  modules: ["@nuxtjs/sitemap", "@pinia/nuxt", osiSections, osiDevTheme],
 
   ssr: true,
 
@@ -50,6 +51,8 @@ export default defineNuxtConfig({
 
   runtimeConfig: {
     public: {
+      // Empty in production: the API is same-origin at https://<host>/api/.
+      // Set NUXT_PUBLIC_STORE_API_BASE in dev, e.g. https://api.offsiders.myosimart.com/
       storeApiBase: "",
     },
   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@osimart/create-storefront",
-  "version": "1.0.0",
-  "description": "Osimart storefront platform \u2014 logic, platform pages and CLI; extended by every theme repo",
+  "version": "1.0.2",
+  "description": "Osimart storefront platform — logic, platform pages and CLI; extended by every theme repo",
   "type": "module",
   "main": "./nuxt.config.ts",
   "bin": {
@@ -43,4 +43,4 @@
   },
   "license": "UNLICENSED",
   "homepage": "https://osimart.com"
-}
+}