@zalify/cli 0.9.1 → 0.10.0

package/dist/cli.js

@@ -11293,7 +11293,7 @@ function updateNotifier(options) {
 
 // src/cli.ts
 import { createRequire as createRequire2 } from "node:module";
-import { dirname as dirname2, join as join7 } from "node:path";
+import { dirname as dirname2, join as join8 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/auth.ts
@@ -12910,10 +12910,333 @@ async function shopifyUploadImages(storeDir) {
   await maybeRevalidateStorefront(auth, dir2);
 }
 
+// src/store.ts
+import { existsSync as existsSync7, mkdirSync as mkdirSync3, readdirSync as readdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync6 } from "node:fs";
+import { basename as basename4, join as join7, resolve as resolve6 } from "node:path";
+var AUTHORING_MD = `# Store authoring guide
+
+The rules for filling in this folder. An author — human or AI agent —
+should be able to produce a complete, import-ready store from this file
+alone. Validate anytime with \`zalify store validate .\`.
+
+## Files
+
+| File | Role |
+| ---- | ---- |
+| store.json | identity: name, slug, vertical, currency; storeDomain filled in once the Shopify dev store exists |
+| brand.md | brand voice guide — tone, audience, naming, price band. Written FIRST; everything else follows it |
+| catalog.json | canonical catalog (products + collections) — the single source the pipeline imports |
+| images/manifest.json | one entry per shot + shared style/modelStyle art-direction prefixes |
+| images/*.png | generated masters (NOT committed — they live in the Zalify asset library; images/assets.json is the committed index) |
+
+## catalog.json rules
+
+- 10–14 products is the sweet spot for a demo store; every product needs
+  \`handle\` (unique, kebab-case, no SKU-speak), \`title\`, \`descriptionHtml\`
+  (brand voice; simple HTML: p/ul/li/em only), \`type\`, \`tags\`, \`variants\`.
+- **Collections are smart collections driven by tags**: a product joins
+  collection \`x\` by carrying tag \`collection:x\`, and the collection's
+  \`rule\` is \`{ "tag": "collection:x" }\`. Every product belongs to at
+  least one collection.
+- **Mandatory collections**: \`best-sellers\` and \`sale\`. Sale products
+  carry a real \`compareAtPrice\` AND the \`collection:sale\` tag.
+- \`options\` is 0–3 option names; each variant's \`options\` array matches
+  that length and order. Single-variant products omit \`options\` and give
+  one variant with \`"options": []\`.
+- Prices are strings with 2 decimals, in the store currency. Honest
+  markdowns only (15–25% off typical).
+- Colors and variants get evocative names per brand.md — never "Gray 02".
+
+## images/manifest.json rules
+
+- Three shots per hero product: packshot (\`<handle>.png\`), macro detail
+  (\`<handle>-detail.png\`), lifestyle/model (\`<handle>-model.png\`,
+  \`"type": "model"\`). ~33–36 entries total. Every \`handle\` must exist in
+  catalog.json; every entry needs \`alt\` text.
+- \`style\` prefixes packshot/detail prompts; \`modelStyle\` prefixes
+  \`type: "model"\` prompts. Keep prompts concrete: materials, colors,
+  camera angle, light.
+- **Prompt safety (gpt-image-2 rejects [sexual] otherwise)** — for
+  human-model shots: say "woman"/"man", never "young …"; keep fitted
+  garments layered or covered (blazer / cardigan / cover-up); crop at
+  the chin or shoot from behind; prefer wider framing. Swimwear: show
+  the garment via flat-lay + detail; make the model shot a cover-up
+  scene. Pet/object products: no such constraints.
+
+## Pipeline (after authoring)
+
+\`\`\`sh
+zalify store validate .                # lint this folder
+# create the Shopify dev store + Zalify workspace, then:
+zalify workspace set <workspace-slug>
+zalify storefront create <slug>        # repo + Vercel + domain + token + scaffold
+zalify shopify import <this-dir> --prune
+zalify images generate <this-dir>
+zalify shopify upload-images <this-dir>
+\`\`\`
+`;
+var BRAND_MD = (name) => `# ${name} — brand voice guide
+
+## Who we are
+
+<2–3 sentences: what the brand makes, for whom, and the feeling it sells.>
+
+## Audience
+
+<Who buys: age band, habits, what they care about. Name the customer the
+way the brand would ("pet parents", not "owners").>
+
+## Tone
+
+- <3–5 bullets: adjectives with teeth, plus what the brand NEVER sounds like.>
+- <How to address the reader (second person? playful? expert-calm?).>
+
+## Naming conventions
+
+- <Pattern for product names, with 2–3 examples.>
+- <How colors/variants are named (evocative, never "Gray 02").>
+
+## Price band
+
+- <Floor–ceiling and what anchors each end. Markdown policy.>
+
+## Quick sniff test
+
+<One sentence: how to tell a line of copy is (or isn't) this brand.>
+`;
+var STORE_JSON = (name, slug, vertical, currency) => JSON.stringify({
+  name,
+  slug,
+  vertical,
+  currency,
+  storeDomain: null,
+  notes: "Standalone-copy deployment — fill storeDomain when the Shopify dev store exists; no siteUrl on purpose."
+}, null, 2) + `
+`;
+var CATALOG_JSON = (vendor, currency) => JSON.stringify({
+  vendor,
+  currency,
+  products: [
+    {
+      handle: "example-product",
+      title: "The Example Product",
+      descriptionHtml: "<p>Two short paragraphs in the brand voice: lead with the moment the customer uses it, then the practical facts.</p><ul><li>Material / composition</li><li>Care instructions</li><li>Size guidance</li></ul>",
+      type: "Category",
+      tags: ["example", "collection:best-sellers"],
+      options: ["Color"],
+      variants: [
+        {
+          options: ["Oat Cream"],
+          sku: "EXM-001-OAT",
+          price: "29.00",
+          compareAtPrice: null,
+          grams: 500,
+          inventory: 50
+        }
+      ],
+      seo: {
+        title: "The Example Product — Brand",
+        description: "One-sentence meta description in the brand voice."
+      }
+    }
+  ],
+  collections: [
+    {
+      handle: "best-sellers",
+      title: "Best Sellers",
+      descriptionHtml: "<p>The ones everyone comes back for.</p>",
+      rule: { tag: "collection:best-sellers" }
+    },
+    {
+      handle: "sale",
+      title: "Sale",
+      descriptionHtml: "<p>Real markdowns on favorites.</p>",
+      rule: { tag: "collection:sale" }
+    }
+  ]
+}, null, 2) + `
+`;
+var MANIFEST_JSON = JSON.stringify({
+  style: "<shared prefix for packshot/detail prompts: photography style, background, light, 'no text, no watermark. Square 1:1 composition.'>",
+  modelStyle: "<shared prefix for type:'model' lifestyle prompts — scene, mood, framing. Mind the prompt-safety rules in AUTHORING.md for human models.>",
+  images: [
+    {
+      handle: "example-product",
+      file: "example-product.png",
+      alt: "The Example Product in Oat Cream, front three-quarter view",
+      prompt: "<concrete packshot prompt: the product, materials, colors, camera angle>"
+    },
+    {
+      handle: "example-product",
+      file: "example-product-detail.png",
+      alt: "Macro detail of the Example Product's texture",
+      prompt: "<extreme macro close-up prompt: texture, seam, hardware>"
+    },
+    {
+      handle: "example-product",
+      file: "example-product-model.png",
+      type: "model",
+      alt: "The Example Product in use",
+      prompt: "<lifestyle prompt: who/what uses it, where, light>"
+    }
+  ]
+}, null, 2) + `
+`;
+function storeInit(dir2, opts) {
+  const target = resolve6(dir2);
+  const slug = basename4(target).toLowerCase().replaceAll(/[^a-z0-9-]+/g, "-").replaceAll(/^-+|-+$/g, "");
+  if (existsSync7(target) && readdirSync3(target).length > 0) {
+    throw new Error(`${dir2} already exists and is not empty`);
+  }
+  const name = opts.name ?? slug.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+  const currency = (opts.currency ?? "USD").toUpperCase();
+  mkdirSync3(join7(target, "images"), { recursive: true });
+  writeFileSync6(join7(target, "AUTHORING.md"), AUTHORING_MD);
+  writeFileSync6(join7(target, "brand.md"), BRAND_MD(name));
+  writeFileSync6(join7(target, "store.json"), STORE_JSON(name, slug, opts.vertical ?? "<vertical>", currency));
+  writeFileSync6(join7(target, "catalog.json"), CATALOG_JSON(name, currency));
+  writeFileSync6(join7(target, "images", "manifest.json"), MANIFEST_JSON);
+  console.log(`Scaffolded store data in ${dir2}:`);
+  for (const f of ["AUTHORING.md", "brand.md", "store.json", "catalog.json", "images/manifest.json"]) {
+    console.log(`  + ${f}`);
+  }
+  console.log(`
+Author in this order: brand.md → catalog.json → images/manifest.json` + `
+(rules + worked examples in AUTHORING.md; lint with \`zalify store validate ${dir2}\`)`);
+}
+function storeValidate(dir2) {
+  const target = resolve6(dir2);
+  const problems = [];
+  const warnings = [];
+  const readJson2 = (rel) => {
+    const path9 = join7(target, rel);
+    if (!existsSync7(path9)) {
+      problems.push(`missing ${rel}`);
+      return null;
+    }
+    try {
+      return JSON.parse(readFileSync7(path9, "utf8"));
+    } catch (err) {
+      problems.push(`${rel}: invalid JSON — ${err instanceof Error ? err.message : err}`);
+      return null;
+    }
+  };
+  if (!existsSync7(join7(target, "brand.md")))
+    problems.push("missing brand.md");
+  const store = readJson2("store.json");
+  if (store && (!store.name || !store.slug))
+    problems.push("store.json: name and slug are required");
+  const catalog = readJson2("catalog.json");
+  const handles = new Set;
+  if (catalog) {
+    const products = catalog.products ?? [];
+    if (!products.length)
+      problems.push("catalog.json: no products");
+    if (products.some((p) => p.handle === "example-product")) {
+      warnings.push("catalog.json still contains the example-product stub");
+    }
+    const collectionTags = new Set((catalog.collections ?? []).map((c) => c.rule?.tag).filter(Boolean));
+    for (const c of ["best-sellers", "sale"]) {
+      if (!(catalog.collections ?? []).some((col) => col.handle === c)) {
+        problems.push(`catalog.json: mandatory collection "${c}" missing`);
+      }
+    }
+    for (const p of products) {
+      const where = `product "${p.handle ?? p.title ?? "?"}"`;
+      if (!p.handle || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(p.handle)) {
+        problems.push(`${where}: handle must be kebab-case`);
+      } else if (handles.has(p.handle)) {
+        problems.push(`${where}: duplicate handle`);
+      } else {
+        handles.add(p.handle);
+      }
+      if (!p.title || !p.descriptionHtml || !p.type) {
+        problems.push(`${where}: title, descriptionHtml, and type are required`);
+      }
+      const tags = p.tags ?? [];
+      const colTags = tags.filter((t) => t.startsWith("collection:"));
+      if (!colTags.length)
+        problems.push(`${where}: no collection:<handle> tag`);
+      for (const t of colTags) {
+        if (!collectionTags.has(t)) {
+          problems.push(`${where}: tag "${t}" matches no collection rule`);
+        }
+      }
+      const optionCount = p.options?.length ?? 0;
+      if (optionCount > 3)
+        problems.push(`${where}: more than 3 options`);
+      if (!p.variants?.length) {
+        problems.push(`${where}: at least one variant required`);
+      } else {
+        const hasSale = tags.includes("collection:sale");
+        let anyCompareAt = false;
+        for (const v of p.variants) {
+          if ((v.options?.length ?? 0) !== optionCount) {
+            problems.push(`${where}: variant options length must match options (${optionCount})`);
+          }
+          if (!v.price || !/^\d+\.\d{2}$/.test(v.price)) {
+            problems.push(`${where}: price must be a string with 2 decimals`);
+          }
+          if (v.compareAtPrice != null) {
+            anyCompareAt = true;
+            if (!/^\d+\.\d{2}$/.test(v.compareAtPrice)) {
+              problems.push(`${where}: compareAtPrice must be a string with 2 decimals`);
+            } else if (v.price && Number(v.compareAtPrice) <= Number(v.price)) {
+              problems.push(`${where}: compareAtPrice must exceed price`);
+            }
+          }
+        }
+        if (hasSale && !anyCompareAt) {
+          problems.push(`${where}: in collection:sale but no variant has compareAtPrice`);
+        }
+        if (anyCompareAt && !hasSale) {
+          warnings.push(`${where}: has compareAtPrice but not tagged collection:sale`);
+        }
+      }
+    }
+  }
+  const manifest = readJson2("images/manifest.json");
+  if (manifest) {
+    const images = manifest.images ?? [];
+    if (!images.length)
+      problems.push("images/manifest.json: no images");
+    if (!manifest.style || manifest.style.startsWith("<")) {
+      warnings.push("images/manifest.json: style prefix not filled in");
+    }
+    const files = new Set;
+    for (const entry of images) {
+      const where = `image "${entry.file ?? "?"}"`;
+      if (!entry.file || !entry.prompt)
+        problems.push(`${where}: file and prompt required`);
+      if (!entry.alt)
+        problems.push(`${where}: alt text required`);
+      if (entry.file) {
+        if (files.has(entry.file))
+          problems.push(`${where}: duplicate file`);
+        files.add(entry.file);
+      }
+      if (entry.handle && handles.size && !handles.has(entry.handle)) {
+        problems.push(`${where}: handle "${entry.handle}" not in catalog.json`);
+      }
+      if (entry.type === "model" && (!manifest.modelStyle || manifest.modelStyle.startsWith("<"))) {
+        warnings.push("images/manifest.json: modelStyle prefix not filled in (model shots present)");
+      }
+    }
+  }
+  for (const w of [...new Set(warnings)])
+    console.log(`  ! ${w}`);
+  if (problems.length) {
+    for (const p of problems)
+      console.log(`  ✗ ${p}`);
+    throw new Error(`${problems.length} problem(s) — fix and re-run \`zalify store validate\``);
+  }
+  console.log(`✓ valid: ${handles.size} product(s), ${catalog?.collections?.length ?? 0} collection(s), ${manifest?.images?.length ?? 0} image entries` + (warnings.length ? ` — ${warnings.length} warning(s)` : ""));
+}
+
 // src/cli.ts
 var __dirname4 = dirname2(fileURLToPath3(import.meta.url));
 var require2 = createRequire2(import.meta.url);
-var pkg = require2(join7(__dirname4, "..", "package.json"));
+var pkg = require2(join8(__dirname4, "..", "package.json"));
 try {
   updateNotifier({ pkg }).notify({
     isGlobal: true,
@@ -12968,6 +13291,13 @@ shopify.command("import <store-dir>").description("Import <store-dir>/catalog.js
 shopify.command("upload-images <store-dir>").description("Upload <store-dir>/images/* to matching products per images/manifest.json (skips files already attached)").action(async (storeDir) => {
   await shopifyUploadImages(storeDir);
 });
+var store = program2.command("store").description("Author store data (catalog, brand voice, image manifest) — step zero, no login needed");
+store.command("init <dir>").description("Scaffold a store-data folder: store.json, brand.md, catalog.json, images/manifest.json + AUTHORING.md (the rules)").option("--name <name>", "brand name (default: derived from the directory)").option("--vertical <vertical>", "e.g. womens-fast-fashion, pet-supplies").option("--currency <code>", "ISO currency", "USD").action((dir2, options) => {
+  storeInit(dir2, options);
+});
+store.command("validate <dir>").description("Lint the store-data folder against the authoring rules (schema, collection tags, sale pricing, image manifest)").action((dir2) => {
+  storeValidate(dir2);
+});
 var storefront = program2.command("storefront").description("Provision and manage fully-hosted standalone storefronts (repo + Vercel via Zalify)");
 storefront.command("create <dir>").description("One-command launch: Zalify provisions the GitHub repo + Vercel project (env, domain, storefront token), then scaffolds locally and pushes").option("-t, --theme <name>", "theme", "nextjs").option("--editor", "include the Zalify canvas-editor (z1) wiring").option("--to <version>", "template version (default: latest)").option("--no-install", "skip dependency install").option("--no-git", "skip git init/push").action(async (dir2, options) => {
   await storefrontCreate(dir2, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalify/cli",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Zalify CLI - command-line interface for Zalify",
   "type": "module",
   "main": "dist/cli.js",