@osimart/create-storefront 0.0.0-stage → 1.0.1

package/app/utils/device.js

@@ -0,0 +1,50 @@
+const STORAGE_KEY = "osimart_device_id";
+
+export function getDeviceId() {
+  try {
+    let deviceId = localStorage.getItem(STORAGE_KEY);
+    if (!deviceId) {
+      deviceId = crypto.randomUUID();
+      localStorage.setItem(STORAGE_KEY, deviceId);
+    }
+    return deviceId;
+  } catch {
+    return crypto.randomUUID();
+  }
+}
+
+export function getDeviceName() {
+  if (typeof navigator === "undefined") return "Unknown Device";
+  const uaData = navigator.userAgentData;
+  const ua = navigator.userAgent;
+
+  let browser = "Unknown Browser";
+  if (uaData?.brands?.length) {
+    const brand = uaData.brands.find(
+      (b) => !/Not.?A.?Brand|Chromium/i.test(b.brand)
+    );
+    if (brand) browser = brand.brand.replace(/^Google |^Microsoft /, "");
+  }
+  if (browser === "Unknown Browser") {
+    if (/EdgiOS|Edg\//.test(ua)) browser = "Edge";
+    else if (/CriOS|Chrome\//.test(ua)) browser = "Chrome";
+    else if (/FxiOS|Firefox\//.test(ua)) browser = "Firefox";
+    else if (/Safari\//.test(ua)) browser = "Safari";
+  }
+
+  let os = uaData?.platform || "Unknown OS";
+  if (os === "Unknown OS") {
+    if (/Windows/.test(ua)) os = "Windows";
+    else if (/Android/.test(ua)) os = "Android";
+    else if (/iPhone|iPad|iPod/.test(ua)) os = "iOS";
+    else if (/Mac OS X/.test(ua)) os = "macOS";
+    else if (/Linux/.test(ua)) os = "Linux";
+  }
+  if (os === "macOS" && navigator.maxTouchPoints > 1) os = "iPadOS";
+
+  return `${browser} on ${os}`;
+}
+
+export function getDeviceInfo() {
+  return { device_id: getDeviceId(), device_name: getDeviceName() };
+}

package/app/utils/eventBus.js

@@ -0,0 +1,24 @@
+import { reactive } from "vue";
+
+export const eventBus = reactive({
+  events: {},
+
+  on(event, callback) {
+    if (!this.events[event]) {
+      this.events[event] = [];
+    }
+    this.events[event].push(callback);
+  },
+
+  off(event, callback) {
+    if (this.events[event]) {
+      this.events[event] = this.events[event].filter(cb => cb !== callback);
+    }
+  },
+
+  emit(event, data) {
+    if (this.events[event]) {
+      this.events[event].forEach(callback => callback(data));
+    }
+  },
+});

package/app/utils/icon-presets.js

@@ -0,0 +1,24 @@
+export const ICON_PRESETS = [
+  { name: "Truck", svg: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M3 6h11v9H3zM14 9h4l3 3v3h-7z"/><circle cx="7" cy="18" r="1.6"/><circle cx="17.5" cy="18" r="1.6"/></svg>` },
+  { name: "Shield", svg: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3l7 3v5c0 4.5-3 7.5-7 9-4-1.5-7-4.5-7-9V6z"/><path d="M9 12l2 2 4-4"/></svg>` },
+  { name: "Return", svg: `<svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 48 48">
+
+<path d="M0 0h48v48H0z" fill="none"/>
+<g id="Shopicon">
+	<path d="M10,22v2c0,7.72,6.28,14,14,14s14-6.28,14-14s-6.28-14-14-14h-4V4l-8,8l8,8v-6h4c5.514,0,10,4.486,10,10s-4.486,10-10,10   s-10-4.486-10-10v-2H10z"/>
+</g>
+</svg>` },
+  { name: "Headset", svg: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M4 13v-1a8 8 0 0 1 16 0v1"/><rect x="3" y="13" width="4" height="6" rx="1"/><rect x="17" y="13" width="4" height="6" rx="1"/><path d="M20 19a4 4 0 0 1-4 3h-2"/></svg>` },
+  { name: "Gift", svg: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><rect x="4" y="10" width="16" height="10" rx="1"/><path d="M4 14h16M12 10v10"/><path d="M12 10S9 4 6.5 5.5 9 10 12 10zM12 10s3-6 5.5-4.5S15 10 12 10z"/></svg>` },
+  { name: "Tag", svg: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M4 4h7l9 9-7 7-9-9z"/><circle cx="8" cy="8" r="1.3"/></svg>` },
+  { name: "Credit card", svg: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="6" width="18" height="12" rx="2"/><path d="M3 10h18M7 15h4"/></svg>` },
+  { name: "Leaf", svg: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M5 19c0-8 5-14 14-14 0 9-5 14-14 14z"/><path d="M5 19c3-5 6-8 10-10"/></svg>` },
+  { name: "Star", svg: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3l2.6 5.6 6 .8-4.4 4.2 1.1 6-5.3-3-5.3 3 1.1-6L3.4 9.4l6-.8z"/></svg>` },
+  { name: "Clock", svg: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/></svg>` },
+  { name: "Globe", svg: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+<path d="M3 12H21M3 12C3 16.9706 7.02944 21 12 21M3 12C3 7.02944 7.02944 3 12 3M21 12C21 16.9706 16.9706 21 12 21M21 12C21 7.02944 16.9706 3 12 3M12 21C4.75561 13.08 8.98151 5.7 12 3M12 21C19.2444 13.08 15.0185 5.7 12 3" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>` },
+  { name: "Heart", svg: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M12 6.00019C10.2006 3.90317 7.19377 3.2551 4.93923 5.17534C2.68468 7.09558 2.36727 10.3061 4.13778 12.5772C5.60984 14.4654 10.0648 18.4479 11.5249 19.7369C11.6882 19.8811 11.7699 19.9532 11.8652 19.9815C11.9483 20.0062 12.0393 20.0062 12.1225 19.9815C12.2178 19.9532 12.2994 19.8811 12.4628 19.7369C13.9229 18.4479 18.3778 14.4654 19.8499 12.5772C21.6204 10.3061 21.3417 7.07538 19.0484 5.17534C16.7551 3.2753 13.7994 3.90317 12 6.00019Z" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>` },
+];

package/app/utils/productOffers.js

@@ -0,0 +1,118 @@
+/**
+ * Product sales, applied the way Shopify applies discounts — shared by the
+ * product cards (block-built card via useProductItems, and ProductCard).
+ * The product page applies the same rules in useProductDetail.
+ *
+ *  - A 1-item sale (required_quantity 1) is a markdown on every item: the
+ *    unit price itself drops.
+ *  - A quantity tier (required_quantity 2+) comes off the total once the
+ *    quantity reaches it, once per order — so it never changes the unit price
+ *    and shows as its own box ("Buy 12, save $4 on the total").
+ *  - Discounts don't combine; the biggest saving wins.
+ *
+ * The API's discounted_price_range treats every tier as a per-item price, so
+ * it isn't used when the variants carry their sales.
+ */
+
+const round2 = (n) => Math.round(n * 100) / 100;
+const requiredOf = (v) => Math.max(1, Number(Array.isArray(v) ? v[0] : v) || 1);
+
+/** Sales running now with a real discount. */
+export function activeSales(variant, now = Date.now()) {
+  return (variant?.sales ?? []).filter(
+    (sale) =>
+      Number(sale.discount_value) > 0 &&
+      (!sale.start_date || Date.parse(sale.start_date) <= now) &&
+      (!sale.end_date || Date.parse(sale.end_date) > now)
+  );
+}
+
+/** A variant's price for one item: its price less the best 1-item markdown. */
+export function unitPrice(variant) {
+  const price = Number(variant?.price);
+  if (!(price > 0)) return 0;
+  let best = 0;
+  for (const sale of activeSales(variant)) {
+    if (requiredOf(sale.required_quantity) > 1) continue;
+    const value = Number(sale.discount_value);
+    const off = sale.sale_type === "Percentage" ? price * Math.min(value, 100) / 100 : Math.min(value, price);
+    best = Math.max(best, off);
+  }
+  const d = variant.discount;
+  if (d?.discounted_price != null && requiredOf(d.required_quantity) <= 1) {
+    best = Math.max(best, price - Number(d.discounted_price));
+  }
+  return round2(price - Math.max(0, best));
+}
+
+/**
+ * A variant's price for one item and the struck-through price before it:
+ * { now, was, sale }. `was` is what gets struck through: the variant's
+ * compare_at_price when it is above the price, else the pre-sale price.
+ * `sale` is true only for a real sale — compare_at_price is display only and
+ * never makes a sale (no badge, no sale colour).
+ */
+export function variantPrices(variant) {
+  const price = Number(variant?.price) || 0;
+  const now = unitPrice(variant) || price;
+  const sale = now < price;
+  const compare = Number(variant?.compare_at_price) || 0;
+  const was = compare > now ? compare : sale ? price : null;
+  return { now, was, sale };
+}
+
+/** A variant's quantity tiers (2+ items): { id, required, pct, value } */
+export function tiersOf(variant) {
+  const price = Number(variant?.price);
+  if (!(price > 0)) return [];
+  const tiers = activeSales(variant)
+    .filter((sale) => requiredOf(sale.required_quantity) > 1)
+    .map((sale) => ({
+      id: sale.id,
+      required: requiredOf(sale.required_quantity),
+      pct: sale.sale_type === "Percentage",
+      value: Number(sale.discount_value),
+    }));
+  const d = variant.discount;
+  if (d?.discounted_price != null && requiredOf(d.required_quantity) > 1 && Number(d.discounted_price) < price) {
+    tiers.push({ id: `discount-${variant.id}`, required: requiredOf(d.required_quantity), pct: false, value: round2(price - Number(d.discounted_price)) });
+  }
+  return tiers;
+}
+
+/**
+ * "Buy 12, save $4 on the total" / "Buy 3, save 10% on the total";
+ * short: "Buy 12, save $4" (a badge on a card image).
+ */
+export function tierText(tier, formatMoney, { short = false } = {}) {
+  const amount = tier.pct ? `${tier.value}%` : formatMoney(tier.value);
+  return `Buy ${tier.required}, save ${amount}${short ? "" : " on the total"}`;
+}
+
+/**
+ * A card's price at one item, and its tier boxes:
+ * { now: {min, max}, was: {min, max} | null, tiers: [tier] }.
+ * Null when the payload doesn't carry the variants' sales (older rows) —
+ * the caller keeps its price_range / discounted_price_range then.
+ */
+export function cardOffers(product) {
+  const variants = (product?.product_variants ?? []).filter((v) => Number(v?.price) > 0);
+  if (!variants.length || !variants.some((v) => "sales" in v || "discount" in v)) return null;
+
+  const pairs = variants.map((v) => variantPrices(v));
+  const units = pairs.map((p) => p.now);
+  const originals = pairs.map((p) => p.was ?? p.now);
+  const now = { min: Math.min(...units), max: Math.max(...units) };
+  const base = { min: Math.min(...originals), max: Math.max(...originals) };
+  const was = pairs.some((p) => p.was) ? base : null;
+  const sale = pairs.some((p) => p.sale);
+
+  const seen = new Map();
+  for (const v of variants) for (const tier of tiersOf(v)) if (!seen.has(tier.id)) seen.set(tier.id, tier);
+  const tiers = [...seen.values()].sort((a, b) => a.required - b.required);
+
+  return { now, was, sale, tiers };
+}
+
+/** {min, max} as the "min - max" string the cards' formatters take. */
+export const rangeString = (r) => (r.min === r.max ? String(r.min) : `${r.min} - ${r.max}`);

package/app/utils/requestCache.js

@@ -0,0 +1,36 @@
+
+const store = new Map();
+
+export function cachedRequest(key, fetcher, { ttl = 60_000, maxAge = 30 * 60_000 } = {}) {
+  if (import.meta.server) return fetcher();
+
+  const hit = store.get(key);
+  const now = Date.now();
+  if (hit && "value" in hit && now - hit.at < maxAge) {
+    if (!hit.promise && now - hit.at >= ttl) refresh(key, fetcher, hit);
+    return Promise.resolve(hit.value);
+  }
+  if (hit?.promise) return hit.promise;
+  return refresh(key, fetcher, null);
+}
+
+function refresh(key, fetcher, previous) {
+  const promise = Promise.resolve()
+    .then(fetcher)
+    .then((value) => {
+      store.set(key, { value, at: Date.now() });
+      return value;
+    })
+    .catch((error) => {
+      if (previous) store.set(key, { value: previous.value, at: previous.at });
+      else store.delete(key);
+      throw error;
+    });
+  store.set(key, previous ? { value: previous.value, at: previous.at, promise } : { promise });
+  if (previous) promise.catch(() => {});
+  return promise;
+}
+
+export function clearRequestCache(prefix = "") {
+  for (const key of store.keys()) if (key.startsWith(prefix)) store.delete(key);
+}

package/app/utils/scrollToError.js

@@ -0,0 +1,59 @@
+// Scrolls to the first invalid checkout field and focuses it.
+//
+// Fields mark themselves with data-field="<key>" using the same keys
+// validateForm() writes into formErrors, so this stays a pure lookup — no
+// per-field refs, no coupling to the form's markup order beyond DOM order.
+//
+// FIELD_ORDER exists because Object.keys(formErrors) follows insertion order,
+// not visual order: a missing payment method inserted before a missing city
+// would otherwise scroll past the address block.
+
+const FIELD_ORDER = [
+  "email",
+  "email_required",
+  "first_name",
+  "last_name",
+  "mobile_number",
+  "mobile_number_required",
+  "country",
+  "zone",
+  "city",
+  "address",
+  "payment_method_id",
+];
+
+// _required variants share a single DOM node with their base field.
+const domField = (key) => key.replace(/_required$/, "");
+
+export function scrollToFirstError(formErrors = {}) {
+  if (typeof document === "undefined") return;
+
+  const keys = Object.keys(formErrors).filter((key) => formErrors[key]);
+  if (!keys.length) return;
+
+  const ordered = [
+    ...FIELD_ORDER.filter((key) => keys.includes(key)),
+    ...keys.filter((key) => !FIELD_ORDER.includes(key)),
+  ];
+
+  for (const key of ordered) {
+    const el = document.querySelector(`[data-field="${domField(key)}"]`);
+    if (!el) continue;
+
+    el.scrollIntoView({ behavior: "smooth", block: "center" });
+
+    // Focus the input inside the row rather than the row itself, so the caret
+    // lands where the user has to type. Skipped for checkbox/radio groups
+    // (payment methods) where focusing the first option would look like a pick.
+    const input = el.querySelector(
+      'input:not([type="checkbox"]):not([type="radio"]), textarea',
+    );
+    if (input) {
+      // Defer past the smooth scroll — focus() on its own jumps the viewport.
+      setTimeout(() => input.focus({ preventScroll: true }), 350);
+    }
+    return;
+  }
+}
+
+export default scrollToFirstError;

package/app/utils/toPlainError.js

@@ -0,0 +1,30 @@
+/**
+ * Turn anything thrown into a plain object safe to put in `useState`.
+ *
+ * Nuxt serializes every `useState` value into the SSR payload so the client can
+ * hydrate from it. That serializer only handles plain data — an `Error`, a class
+ * instance, a `Response`, a `Proxy` all fail with:
+ *
+ *     Cannot stringify arbitrary non-POJOs
+ *
+ * The trap is that this error replaces the one you were trying to report, so a
+ * failed API call surfaces as an opaque serialization crash instead of
+ * "HTTP 404". Anything stored for display goes through here first.
+ *
+ * `useAsyncData`'s own `error` does not need this — Nuxt normalises that one
+ * itself. This is only for errors you park in state by hand.
+ */
+export function toPlainError(e) {
+  if (e === null || e === undefined) return null;
+
+  // Already plain.
+  if (typeof e === "string") return { message: e, status: null, data: null };
+
+  return {
+    message: e.message ?? e.detail ?? "Something went wrong",
+    // apiService attaches these; $fetch/ofetch uses statusCode.
+    status: e.status ?? e.statusCode ?? null,
+    // Response bodies from DRF are plain JSON, so they serialize fine.
+    data: e.data ?? e.response?._data ?? null,
+  };
+}

package/bin/osimart-theme.mjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+/**
+ * osimart-theme — the theme repo's link to its store, like the Shopify CLI.
+ *
+ *   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]
+ *   osimart-theme publish <id>                 make a theme the live one
+ *
+ * Files (theme repo):
+ *   theme/config/settings_data.json            theme settings
+ *   theme/sections/header-group.json           header group sections
+ *   theme/sections/footer-group.json           footer group sections
+ *   theme/templates/<type>[.<suffix>].json     index.json, product.json, product.alternate.json, page.contact.json …
+ *   app/sections/<Name>Section.schema.json     schema of a section type the theme adds
+ *   .osimart/state.json                        what was last pulled (git-ignored)
+ *   .osimart/schemas.json                      every section schema, for reference (git-ignored)
+ *
+ * Env (read from .env too):
+ *   OSIMART_THEME_TOKEN     Theme access token (dashboard → Theme access)
+ *   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 { basename, join, resolve } from "node:path";
+
+const ROOT = process.cwd();
+const THEME_DIR = join(ROOT, "theme");
+const TEMPLATES_DIR = join(THEME_DIR, "templates");
+const GROUPS_DIR = join(THEME_DIR, "sections");
+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");
+
+/* ---------------------------------------------------------------- env */
+
+function loadDotenv() {
+  const file = join(ROOT, ".env");
+  if (!existsSync(file)) return;
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+    if (m && process.env[m[1]] === undefined) process.env[m[1]] = m[2].replace(/^["']|["']$/g, "");
+  }
+}
+loadDotenv();
+
+function fail(message) {
+  console.error(`✖ ${message}`);
+  process.exit(1);
+}
+
+/**
+ * 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/.
+ */
+const BUILDER_PATH = "/store/apis/theme-dev/";
+
+function baseUrl() {
+  const override = process.env.OSIMART_THEME_DEV_URL;
+  if (override) return override.endsWith("/") ? override : `${override}/`;
+  const api = process.env.NUXT_PUBLIC_STORE_API_BASE;
+  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).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 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: `not a theme-dev endpoint: ${url}` }; }
+  if (!res.ok) {
+    const err = new Error(data?.detail || data?.message || `HTTP ${res.status}`);
+    err.status = res.status;
+    err.data = data;
+    throw err;
+  }
+  return data;
+}
+
+/* ---------------------------------------------------------------- files */
+
+const readJson = (file) => {
+  try { return JSON.parse(readFileSync(file, "utf8")); }
+  catch (e) { fail(`${file.replace(ROOT + "/", "")}: ${e.message}`); }
+};
+const writeJson = (file, data) => {
+  mkdirSync(resolve(file, ".."), { recursive: true });
+  writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+};
+const listJson = (dir) => (existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith(".json")) : []);
+
+/** {type: "PRODUCT", suffix: "alternate"} <-> product.alternate.json */
+const templateFile = ({ type, suffix }) => `${String(type).toLowerCase()}${suffix ? `.${suffix}` : ""}.json`;
+function templateKey(file) {
+  const name = basename(file, ".json");
+  const dot = name.indexOf(".");
+  return dot === -1
+    ? { type: name.toUpperCase(), suffix: "" }
+    : { type: name.slice(0, dot).toUpperCase(), suffix: name.slice(dot + 1) };
+}
+
+/** header <-> header-group.json */
+const groupFile = (name) => `${name}-group.json`;
+const groupName = (file) => basename(file, ".json").replace(/-group$/, "");
+
+/** LookbookGridSection.schema.json -> LOOKBOOK_GRID */
+const typeFromSchemaFile = (file) =>
+  basename(file, ".schema.json").replace(/Section$/, "").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
+
+function readLocalTheme() {
+  return {
+    settings: existsSync(SETTINGS_FILE) ? readJson(SETTINGS_FILE) : undefined,
+    groups: Object.fromEntries(listJson(GROUPS_DIR).map((f) => [groupName(f), readJson(join(GROUPS_DIR, f))])),
+    templates: listJson(TEMPLATES_DIR).map((f) => ({ ...templateKey(f), data: readJson(join(TEMPLATES_DIR, f)) })),
+  };
+}
+
+function readLocalSchemas() {
+  if (!existsSync(SECTIONS_DIR)) return [];
+  return readdirSync(SECTIONS_DIR)
+    .filter((f) => f.endsWith(".schema.json"))
+    .map((f) => {
+      const json = readJson(join(SECTIONS_DIR, f));
+      const type = typeFromSchemaFile(f);
+      if (!existsSync(join(SECTIONS_DIR, f.replace(/\.schema\.json$/, ".vue")))) {
+        fail(`${f}: no matching ${f.replace(/\.schema\.json$/, ".vue")}`);
+      }
+      return {
+        type,
+        name: json.name || type,
+        ...(json.group ? { group: json.group } : {}),
+        allowed_templates: json.templates || json.allowed_templates || [],
+        schema: { settings: json.settings || [], blocks: json.blocks || [], ...(json.max_blocks ? { max_blocks: json.max_blocks } : {}) },
+      };
+    });
+}
+
+const state = () => (existsSync(STATE_FILE) ? readJson(STATE_FILE) : {});
+const saveState = (patch) => writeJson(STATE_FILE, { ...state(), ...patch });
+
+function flag(args, name, fallback) {
+  const i = args.indexOf(name);
+  return i === -1 ? fallback : args[i + 1];
+}
+
+/* ---------------------------------------------------------------- commands */
+
+async function themes() {
+  const list = await request("GET", "themes/");
+  const pulled = state().theme_id;
+  for (const t of list) {
+    console.log(`${String(t.id).padEnd(38)} ${String(t.role).padEnd(9)} ${t.name}${t.id === pulled ? "   ← pulled" : ""}`);
+  }
+}
+
+async function pull(args) {
+  const theme = flag(args, "--theme", "live");
+  const data = await request("GET", `theme/?theme=${encodeURIComponent(theme)}`);
+
+  if (data.settings) writeJson(SETTINGS_FILE, data.settings);
+
+  const groups = data.groups || {};
+  for (const [name, value] of Object.entries(groups)) writeJson(join(GROUPS_DIR, groupFile(name)), value);
+
+  const wanted = new Set();
+  for (const t of data.templates || []) {
+    const file = templateFile(t);
+    wanted.add(file);
+    writeJson(join(TEMPLATES_DIR, file), t.data);
+  }
+
+  // Local templates the theme no longer has.
+  const stale = listJson(TEMPLATES_DIR).filter((f) => !wanted.has(f));
+  if (stale.length) {
+    if (args.includes("--delete")) stale.forEach((f) => rmSync(join(TEMPLATES_DIR, f)));
+    else console.log(`  not on the store (kept; --delete removes): ${stale.join(", ")}`);
+  }
+
+  try {
+    writeJson(join(STATE_DIR, "schemas.json"), await request("GET", "schemas/"));
+  } catch (e) {
+    console.log(`  (schemas not saved: ${e.message})`);
+  }
+
+  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");
+
+  // 1. Section types the theme adds (their schemas), so the editor can place them.
+  const sections = readLocalSchemas();
+  if (sections.length || prune) {
+    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;
+    }
+    console.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(", ")}`);
+    }
+  }
+
+  // 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;
+  }
+  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}) 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.preview_url) console.log(`  preview: ${res.preview_url}`);
+    if (!dryRun && res.theme.id === theme_id) saveState({ version: res.theme.version });
+  } 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.");
+    }
+    if (e.status === 400 && e.data) fail(`Rejected:\n${JSON.stringify(e.data, null, 2)}`);
+    throw e;
+  }
+}
+
+async function publish(args) {
+  const id = args[0];
+  if (!id) fail("Usage: osimart-theme publish <theme-id>  (see: osimart-theme themes)");
+  const res = await request("POST", `themes/${encodeURIComponent(id)}/publish/`);
+  console.log(`✔ "${res.name}" is now live`);
+}
+
+/* ---------------------------------------------------------------- main */
+
+const [command, ...args] = process.argv.slice(2);
+const commands = { themes, pull, push, publish };
+
+if (!commands[command]) {
+  console.log(`Usage:
+  osimart-theme themes
+  osimart-theme pull    [--theme live|<id>] [--delete]
+  osimart-theme push    [--theme draft|live|<id>] [--force] [--prune] [--dry-run]
+  osimart-theme publish <id>`);
+  process.exit(command ? 1 : 0);
+}
+
+commands[command](args).catch((e) => fail(e.status ? `${e.status} ${e.message}` : e.message));