@cimplify/cli 0.6.11 → 0.6.14

package/dist/dispatcher.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { TEMPLATES } from './chunk-OLZMA2TM.mjs';
-import { package_default } from './chunk-KOJZB3S4.mjs';
+import { TEMPLATES } from './chunk-RIOQDUQO.mjs';
+import { package_default } from './chunk-RGF2RSSR.mjs';
 
 // src/dispatcher.ts
 var VERSION = package_default.version ?? "unknown";
@@ -19,6 +19,7 @@ Project:
   cimplify link <project-id>                 Link CWD to a Cimplify project (writes .cimplify/project.json)
   cimplify unlink                            Remove the local project link
   cimplify introspect                        Snapshot the current storefront: auth, link, brand, mock, env, git
+  cimplify inspect [catalogue]               Read-only snapshot of the live catalogue (products + collections + gaps)
   cimplify doctor [--offline]                Run pre-flight checks; verdicts + fix hints (exit 1 on any fail)
   cimplify explain [topic]                   Print canonical guidance on cart, products, bundles, errors, \u2026
   cimplify assets upload <dir>               Upload storefront brand assets to the Cimplify CDN
@@ -137,15 +138,16 @@ var COMMANDS = {
   logs: () => import('./logs-YNN2PQ24.mjs'),
   status: () => import('./status-JSYXM5RT.mjs'),
   dev: () => import('./dev-ONW2S77K.mjs'),
-  introspect: () => import('./introspect-77SUZ5X5.mjs'),
-  doctor: () => import('./doctor-3UOTPOJ6.mjs'),
-  explain: () => import('./explain-DXJ3R52F.mjs'),
-  assets: () => import('./assets-EBEMMENZ.mjs'),
+  introspect: () => import('./introspect-4LD27NVX.mjs'),
+  inspect: () => import('./inspect-CGYX4DDF.mjs'),
+  doctor: () => import('./doctor-726TVOXT.mjs'),
+  explain: () => import('./explain-6BWR5MCK.mjs'),
+  assets: () => import('./assets-74SK63TR.mjs'),
   repo: () => import('./repo-KNQMSPVV.mjs'),
-  list: () => import('./list-QX7RM3P3.mjs'),
-  add: () => import('./add-5G7UZ6DA.mjs'),
-  update: () => import('./update-UHKPFT6F.mjs'),
-  upgrade: () => import('./update-UHKPFT6F.mjs'),
+  list: () => import('./list-2YRVKBXY.mjs'),
+  add: () => import('./add-6SPMUMSJ.mjs'),
+  update: () => import('./update-J65Z6Q7E.mjs'),
+  upgrade: () => import('./update-J65Z6Q7E.mjs'),
   "auth-step-up": () => import('./auth-step-up-BIUYQJP6.mjs')
 };
 var COMMAND_PREFIXES = {

package/dist/{doctor-3UOTPOJ6.mjs → doctor-726TVOXT.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { gatherIntrospection } from './chunk-SNDMYYOK.mjs';
+import { gatherIntrospection } from './chunk-CNIFXKZV.mjs';
 import './chunk-K5464A3L.mjs';
 import './chunk-DBZ3UOQ2.mjs';
-import './chunk-KOJZB3S4.mjs';
+import './chunk-RGF2RSSR.mjs';
 import { parseArgs, flagBool } from './chunk-C4M3DXKC.mjs';
 import { ApiClient } from './chunk-MAOO6ZZ5.mjs';
 import { readAuthOrNull } from './chunk-UBAI443T.mjs';

package/dist/{explain-DXJ3R52F.mjs → explain-6BWR5MCK.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { package_default } from './chunk-KOJZB3S4.mjs';
+import { package_default } from './chunk-RGF2RSSR.mjs';
 import { parseArgs } from './chunk-C4M3DXKC.mjs';
 import { bold, dim, info, result, CliError, CLI_ERROR_CODE } from './chunk-E2T2SBP5.mjs';
 
@@ -138,6 +138,34 @@ var TOPICS = [
     "source_url": "https://cimplify.dev/docs/cli#exit-codes",
     "body": "## Exit codes\nDistinct per error class so callers can branch on `$?` without parsing output:\n\n| Code | Name | Meaning |\n| --- | --- | --- |\n| `0` | OK | Success. For `deploy`, deployment is `active`. |\n| `1` | FAILED | Generic failure (build failed, deploy errored). |\n| `2` | SUPERSEDED | A newer push raced this deploy; usually fine. |\n| `3` | ABORTED | User canceled (Ctrl-C) or `cimplify_cancel_deployment`. |\n| `4` | NOT_LINKED | `.cimplify/project.json` missing. Run `cimplify link <id>`. |\n| `7` | INTERACTIVE_REQUIRED | A prompt was needed but `--yes` not passed and stdin is non-TTY. |\n| `9` | NOT_FOUND | Resource (project, domain, deploy) does not exist. |\n| `10` | NETWORK_ERROR | Could not reach `api.cimplify.io`. |\n| `12` | TIMEOUT | Long-poll exceeded its window; the underlying job may still be running. |\n| `20` | NOT_LOGGED_IN | No saved token. Run `cimplify login` or pass `--api-key`. |\n| `21` | AUTH_FAILED | Token expired or revoked. Re-login. |\n| `30` | INVALID_INPUT | Argument/flag validation failed. |\n\nFull list in `@cimplify/cli/errors`.\n"
   },
+  {
+    "name": "inspect-json",
+    "title": 'Inspect \u2014 The JSON envelope (locked contract, `schema_version: "1"`)',
+    "description": "The locked JSON envelope cimplify inspect emits",
+    "source_url": "https://cimplify.dev/docs/cli/inspect#the-json-envelope-locked-contract-schema_version-1",
+    "body": '## The JSON envelope (locked contract, `schema_version: "1"`)\n```jsonc\n{\n  "ok": true,\n  "schema_version": "1",\n  "data": {\n    "business": {\n      "handle": "bakeryco",\n      "name": "Bakery & Co.",\n      "currencies": ["USD", "GHS"],\n      "locations": 2\n    },\n    "totals": {\n      "products": 142,\n      "collections": 8,\n      "categories": 12,\n      "distinct_tags": 24\n    },\n    "gaps": {\n      "no_image": 11,\n      "no_description": 7,\n      "no_price": 0,\n      "no_collection": 23,\n      "no_tags": 56,\n      "empty_collections": [{ "id": "col_seasonal", "name": "Seasonal" }],\n      "empty_categories":  [{ "id": "cat_specials", "name": "Specials" }]\n    },\n    "products": {\n      "sample": [\n        {\n          "id": "prod_abc1",\n          "name": "Croissant",\n          "slug": "croissant",\n          "price": { "amount": "3.50", "currency": "USD" },\n          "has_image": true,\n          "has_description": true,\n          "tags": ["vegan", "bestseller"],\n          "collection_ids": ["col_featured"],\n          "category_ids": ["cat_breakfast"],\n          "variant_count": 3\n        }\n      ],\n      "next_cursor": "eyJpZCI6IjE5In0",\n      "returned": 20\n    },\n    "collections": [\n      {\n        "id": "col_featured",\n        "name": "Featured",\n        "slug": "featured",\n        "product_count": 12,\n        "sample_product_ids": ["prod_abc1", "prod_abc2", "prod_abc3"]\n      }\n    ],\n    "categories": {\n      "tree": [\n        { "id": "cat_breakfast", "name": "Breakfast", "slug": "breakfast", "product_count": 24, "children": [] }\n      ]\n    },\n    "tags": {\n      "top": [{ "tag": "vegan", "count": 18 }, { "tag": "bestseller", "count": 12 }]\n    }\n  },\n  "meta": {\n    "fetched_at": "2026-05-23T10:15:32Z",\n    "source": "hosted",\n    "sampled": true,\n    "sample_size": 20,\n    "gaps_method": "sample",\n    "shape_hints": ["medium_catalogue", "uses_collections", "has_empty_collection", "untagged_majority", "has_image_gaps"],\n    "suggestions": [\n      { "kind": "fix_no_image", "count": 11 },\n      { "kind": "fix_no_collection", "count": 23 },\n      { "kind": "merchandise_empty_collection", "collection_id": "col_seasonal", "name": "Seasonal" }\n    ],\n    "suggested_commands": ["cimplify inspect catalogue --all"]\n  }\n}\n```\n\n### Error envelope\n\n```jsonc\n{\n  "ok": false,\n  "schema_version": "1",\n  "error": {\n    "code": "NO_PUBLIC_KEY",\n    "message": "Set NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY in .env or pass --public-key.",\n    "remediation": "Get one at desk.cimplify.io/settings/api."\n  }\n}\n```\n\n### Field rules\n\n- `ok` is always present.\n- `schema_version` is a contract over the whole document; bump on **removal**, **rename**, or **type change** of any field, `shape_hints` token, or `suggestions[].kind`. **Adding** is non-breaking.\n- `data.gaps.empty_collections` / `empty_categories` are always arrays (return `[]`, never omit).\n- `data.products.sample` is **always page-ordered** (never randomized).\n- `next_cursor` is `null` when the walk is exhausted.\n- `meta.source` is `"hosted"` or `"mock"`. Locked.\n- `meta.gaps_method` is `"sample"` or `"exact"`. Locked.\n- `meta.shape_hints` is **sorted alphabetically** (deterministic, diffable).\n- `meta.suggestions` is ordered by impact (most actionable first).\n- `meta.fetched_at` is the only timestamp; nothing in `data` carries time.\n'
+  },
+  {
+    "name": "shape-hints",
+    "title": "Inspect \u2014 `shape_hints` vocabulary",
+    "description": "The canonical shape_hints vocabulary for cimplify inspect",
+    "source_url": "https://cimplify.dev/docs/cli/inspect#shape_hints-vocabulary",
+    "body": "## `shape_hints` vocabulary\nFlat string tokens for agents to branch on. Adding tokens is non-breaking; removing/renaming bumps `schema_version`.\n\n### Catalogue size\n\n| Token | Meaning |\n| --- | --- |\n| `empty_catalogue` | 0 products. Whole storefront needs an empty-state. |\n| `tiny_catalogue` | 1\u20139 products. Skip search, deep filters. |\n| `small_catalogue` | 10\u201399 products. Default UX. |\n| `medium_catalogue` | 100\u2013999 products. Search nice-to-have. |\n| `large_catalogue` | 1000+ products. Search + facets required. |\n\n### Feature presence\n\n| Token | Meaning |\n| --- | --- |\n| `has_variants` | At least one product has variants \u2192 variant picker UI. |\n| `has_addons` | At least one product has add-on options \u2192 modifier UI. |\n| `has_subscriptions` | Billing plans exist \u2192 recurring pricing toggle. |\n| `has_composites` | Bundle / composite products exist. |\n| `has_recipes` | Products linked to `ProductComponent` (restaurant / manufacturing). |\n| `has_time_profiles` | Products have time-of-day windows \u2192 hours-aware UI. |\n| `has_input_fields` | Buyer-supplied inputs (engraving, message). |\n| `has_custom_attributes` | Custom attribute schemas defined. |\n| `per_location_pricing` | Prices vary by location. |\n| `multi_currency` | >1 currency configured. |\n| `multi_location` | >1 location configured. |\n\n### Merchandising state\n\n| Token | Meaning |\n| --- | --- |\n| `uses_collections` | \u22651 non-empty collection exists. |\n| `uses_categories` | \u22651 non-empty category. |\n| `has_empty_collection` | \u22651 collection has 0 products. |\n| `has_empty_category` | \u22651 category has 0 products. |\n| `untagged_majority` | >50% of products are untagged. |\n| `unmerchandised_majority` | >50% of products aren't in any collection. |\n\n### Data quality\n\n| Token | Meaning |\n| --- | --- |\n| `has_image_gaps` | \u22651 product missing image. |\n| `has_description_gaps` | \u22651 product missing description. |\n| `has_price_gaps` | \u22651 product missing price. |\n\n### Environment\n\n| Token | Meaning |\n| --- | --- |\n| `mock_data` | Reading from `cimplify-mock` (key isn't `cpk_live_*` / `cpk_test_*`). |\n"
+  },
+  {
+    "name": "revalidation-tags",
+    "title": "Revalidation",
+    "description": "Canonical cimplify:* cache-tag vocabulary + revalidate helpers",
+    "source_url": "https://cimplify.dev/docs/sdk/revalidation",
+    "body": 'Cimplify storefronts cache catalogue reads with Next 16\'s `\'use cache\'` + `cacheTag`. When the merchant edits a product, collection, or brand asset, Cimplify POSTs to your storefront\'s `/api/revalidate` with the canonical tag set, and your handler calls `revalidateTag(tag)` for each.\n\nThis page is the canonical contract between Cimplify and your storefront. Use the typed helpers \u2014 never hand-write tag strings \u2014 so the scheme stays in one place.\n\n## Tags\n\nAll tags are namespaced under `cimplify:` so they can\'t collide with consumer tags. Build them via `tags` from `@cimplify/sdk/server`:\n\n```ts\n\n// In a cached server function:\nasync function getProducts() {\n  "use cache";\n  cacheTag(tags.products());\n  cacheLife("hours");\n  // \u2026\n}\n```\n\n### Catalogue\n\n| Helper | Tag |\n| --- | --- |\n| `tags.products()` | `cimplify:products` |\n| `tags.product(id)` | `cimplify:product:{id}` |\n| `tags.categories()` | `cimplify:categories` |\n| `tags.category(id)` | `cimplify:category:{id}` |\n| `tags.categoryProducts(id)` | `cimplify:category:{id}:products` |\n| `tags.collections()` | `cimplify:collections` |\n| `tags.collection(id)` | `cimplify:collection:{id}` |\n| `tags.collectionProducts(id)` | `cimplify:collection:{id}:products` |\n| `tags.tag(name)` | `cimplify:tag:{name}` (product tag, e.g. "vegan") |\n| `tags.addons()` | `cimplify:addons` |\n| `tags.addon(id)` | `cimplify:addon:{id}` |\n| `tags.stock()` | `cimplify:stock` |\n| `tags.stockFor(productId)` | `cimplify:stock:{productId}` |\n\n### Brand / business\n\n| Helper | Tag |\n| --- | --- |\n| `tags.business()` | `cimplify:business` |\n| `tags.brand()` | `cimplify:brand` |\n| `tags.locations()` | `cimplify:locations` |\n| `tags.location(id)` | `cimplify:location:{id}` |\n| `tags.locale()` | `cimplify:locale` |\n\n### Pricing / subscriptions\n\n| Helper | Tag |\n| --- | --- |\n| `tags.pricing()` | `cimplify:pricing` |\n| `tags.subscriptions()` | `cimplify:subscriptions` |\n| `tags.subscription(id)` | `cimplify:subscription:{id}` |\n\n### Customer-scoped (Server Actions only)\n\n| Helper | Tag |\n| --- | --- |\n| `tags.orders(customerId)` | `cimplify:orders:{customerId}` |\n| `tags.order(id)` | `cimplify:order:{id}` |\n\n## Granularity\n\nTag with **both** a broad and a precise tag on every read so either-flavour invalidation works:\n\n```ts\ncacheTag(tags.products(), tags.product(id));\n```\n\nThe broad tag (`products`) catches "I changed something product-related, invalidate everything." The precise tag (`product:{id}`) catches "I changed exactly this one product, invalidate only its entries."\n\n## Revalidating from a Server Action\n\n```ts\n\nexport async function saveProduct(id: string, data: ProductInput) {\n  await client.catalogue.updateProduct(id, data);\n  await revalidateProduct(id);\n}\n```\n\nHelpers:\n\n| Helper | Invalidates |\n| --- | --- |\n| `revalidateProducts()` | `products` |\n| `revalidateProduct(id)` | `product:{id}` + `products` |\n| `revalidateCategories()` | `categories` |\n| `revalidateCategory(id)` | `category:{id}` + `category:{id}:products` + `categories` |\n| `revalidateCollections()` | `collections` |\n| `revalidateCollection(id)` | `collection:{id}` + `collection:{id}:products` + `collections` |\n| `revalidateBusiness()` | `business` |\n| `revalidateBrand()` | `brand` |\n| `revalidateLocations()` | `locations` |\n| `revalidateLocation(id)` | `location:{id}` + `locations` |\n| `revalidatePricing()` | `pricing` + `products` |\n| `revalidateAddOns()` | `addons` |\n| `revalidateAddOn(id)` | `addon:{id}` + `addons` |\n| `revalidateSubscriptions()` | `subscriptions` |\n| `revalidateSubscription(id)` | `subscription:{id}` + `subscriptions` |\n| `revalidateStock(productId?)` | `stock:{productId}` + `stock` (or just `stock` if no id) |\n| `revalidateByTag(tag)` | escape hatch for a raw tag |\n\n## The Cimplify \u2192 storefront contract\n\nWhen a merchant edits something in the dashboard, Cimplify POSTs to your storefront\'s `/api/revalidate` with the matching tag set:\n\n```http\nPOST /api/revalidate\nx-cimplify-timestamp: 1716480000000\nx-cimplify-signature: sha256=<hex>\ncontent-type: application/json\n\n{ "tags": ["cimplify:products", "cimplify:product:p_abc123"] }\n```\n\nYour handler verifies the HMAC (shared secret in `CIMPLIFY_REVALIDATE_SECRET`), iterates `revalidateTag(tag)` for each, and returns 200. The route handler ships in every Cimplify storefront template \u2014 you don\'t write it.\n\nThe tags Cimplify sends use the **exact strings** from this table. If you\'ve tagged your caches with the helpers above, your storefront stays in sync automatically.\n\n## Tag taxonomy is locked\n\nThe vocabulary above is the v1 contract. Adding new tag helpers is non-breaking; removing or renaming any of them bumps the SDK major version. Agents that bake these strings into prompts can pin to v0.x of `@cimplify/sdk`.\n'
+  },
+  {
+    "name": "inspect-suggestions",
+    "title": "Inspect \u2014 `suggestions[].kind` vocabulary",
+    "description": "The canonical suggestions[].kind vocabulary for cimplify inspect",
+    "source_url": "https://cimplify.dev/docs/cli/inspect#suggestionskind-vocabulary",
+    "body": '## `suggestions[].kind` vocabulary\nEach entry is a stable `kind` + typed payload. Copy lives here (and in `cimplify explain inspect-suggestions`) so agents don\'t invent phrasing.\n\n| Kind | Payload | Implied prompt |\n| --- | --- | --- |\n| `add_first_product` | `{}` | Catalogue is empty \u2014 seed or add a product. |\n| `add_first_collection` | `{}` | Products exist but no collections \u2014 group some. |\n| `fix_no_image` | `{ count }` | N products without images \u2014 add placeholders. |\n| `fix_no_description` | `{ count }` | N products lack descriptions \u2014 generate copy. |\n| `fix_no_price` | `{ count }` | N products have no price \u2014 open the editor. |\n| `fix_no_collection` | `{ count }` | N products not in any collection \u2014 suggest "Featured". |\n| `fix_no_tags` | `{ count }` | N untagged products \u2014 suggest tags from name/category. |\n| `merchandise_empty_collection` | `{ collection_id, name }` | Collection "X" is empty \u2014 pick products to feature. |\n| `merchandise_empty_category` | `{ category_id, name }` | Category "X" has no products \u2014 fill or remove. |\n| `tag_uncategorized_products` | `{ count }` | Majority untagged \u2014 bulk-tag from category. |\n| `enable_search_ui` | `{ product_count }` | Large catalogue \u2014 add search + filters. |\n'
+  },
   {
     "name": "agent-prompts",
     "title": "Agent prompts",

package/dist/inspect-CGYX4DDF.mjs

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+import { parseEnvFile } from './chunk-DBZ3UOQ2.mjs';
+import { parseArgs, flagString, flagBool } from './chunk-C4M3DXKC.mjs';
+import { CliError, CLI_ERROR_CODE, isJsonMode, result, info, bold, dim, yellow, green, red } from './chunk-E2T2SBP5.mjs';
+import { promises } from 'fs';
+import path from 'path';
+import { createCimplifyClient } from '@cimplify/sdk';
+
+var SCHEMA_VERSION = "1";
+var HOSTED_URL = "https://storefronts.cimplify.io";
+var MOCK_URL = "http://127.0.0.1:8787";
+var DEFAULT_LIMIT = 20;
+var COLLECTION_SAMPLE_SIZE = 3;
+var TAG_TOP_N = 10;
+var ENV_FILE_CANDIDATES = [".env.local", ".env", ".env.production", ".env.example"];
+var PUBLIC_KEY_ENV = "NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY";
+var FLAG_ALL = "all";
+var FLAG_LIMIT = "limit";
+var FLAG_CURSOR = "cursor";
+var FLAG_PUBLIC_KEY = "public-key";
+async function run(argv) {
+  const args = parseArgs(argv);
+  const sub = args.positional[0] ?? "catalogue";
+  if (sub !== "catalogue") {
+    throw new CliError(
+      CLI_ERROR_CODE.INVALID_INPUT,
+      `Unknown subcommand: ${sub}. Try \`cimplify inspect catalogue\`.`
+    );
+  }
+  await runCatalogue(args);
+}
+async function runCatalogue(args) {
+  const publicKey = await resolvePublicKey(args);
+  const source = isHostedKey(publicKey) ? "hosted" : "mock";
+  const baseUrl = source === "hosted" ? HOSTED_URL : MOCK_URL;
+  const limit = parseLimit(flagString(args, FLAG_LIMIT));
+  const walkAll = flagBool(args, FLAG_ALL);
+  const cursor = flagString(args, FLAG_CURSOR);
+  const client = createCimplifyClient({
+    baseUrl,
+    publicKey,
+    suppressPublicKeyWarning: true
+  });
+  const data = await fetchCatalogue(client, { limit, walkAll, cursor });
+  const meta = buildMeta({
+    data,
+    source,
+    sampled: !walkAll,
+    sampleSize: data.products.returned,
+    gapsMethod: walkAll ? "exact" : "sample"
+  });
+  if (isJsonMode()) {
+    result({ schema_version: SCHEMA_VERSION, data, meta });
+    return;
+  }
+  renderHuman(data, meta);
+}
+async function resolvePublicKey(args) {
+  const fromFlag = flagString(args, FLAG_PUBLIC_KEY);
+  if (fromFlag) return fromFlag;
+  const fromProc = process.env[PUBLIC_KEY_ENV]?.trim();
+  if (fromProc) return fromProc;
+  for (const name of ENV_FILE_CANDIDATES) {
+    const filePath = path.join(process.cwd(), name);
+    try {
+      const text = await promises.readFile(filePath, "utf8");
+      const entries = parseEnvFile(text);
+      const hit = entries.find((e) => e.key === PUBLIC_KEY_ENV);
+      const value = hit?.value.trim();
+      if (value) return value;
+    } catch {
+    }
+  }
+  throw new CliError(
+    CLI_ERROR_CODE.INVALID_INPUT,
+    `Set ${PUBLIC_KEY_ENV} in .env or pass --public-key. Get one at desk.cimplify.io/settings/api.`
+  );
+}
+function isHostedKey(key) {
+  return key.startsWith("cpk_live_") || key.startsWith("cpk_test_");
+}
+function parseLimit(raw) {
+  if (!raw) return DEFAULT_LIMIT;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new CliError(CLI_ERROR_CODE.INVALID_INPUT, `--limit must be a positive integer.`);
+  }
+  return n;
+}
+async function fetchCatalogue(client, opts) {
+  const [productsPage, collectionsList, categoriesList] = await Promise.all([
+    fetchProducts(client, opts),
+    unwrap(client.catalogue.getCollections(), "list collections"),
+    unwrap(client.catalogue.getCategories(), "list categories")
+  ]);
+  const collections = await Promise.all(
+    collectionsList.map(async (c) => buildCollectionSummary(client, c))
+  );
+  const collectionMembers = /* @__PURE__ */ new Set();
+  for (const c of collections) {
+    for (const pid of c.sample_product_ids) collectionMembers.add(pid);
+  }
+  const tagFreq = countTags(productsPage.items);
+  const distinctTags = tagFreq.size;
+  const topTags = [...tagFreq.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, TAG_TOP_N).map(([tag, count]) => ({ tag, count }));
+  const sample = productsPage.items.map((p) => productToSampleRow(p));
+  const gaps = computeGaps(productsPage.items, collections, categoriesList, collectionMembers);
+  return {
+    business: await fetchBusiness(client),
+    totals: {
+      products: productsPage.total ?? productsPage.items.length,
+      collections: collectionsList.length,
+      categories: categoriesList.length,
+      distinct_tags: distinctTags
+    },
+    gaps,
+    products: {
+      sample,
+      next_cursor: productsPage.nextCursor,
+      returned: productsPage.items.length
+    },
+    collections,
+    categories: { tree: buildCategoryTree(categoriesList) },
+    tags: { top: topTags }
+  };
+}
+async function fetchProducts(client, opts) {
+  const first = await unwrap(
+    client.catalogue.getProducts({ limit: opts.limit, cursor: opts.cursor }),
+    "list products"
+  );
+  if (!opts.walkAll) {
+    return {
+      items: first.items,
+      total: first.total_available ?? null,
+      nextCursor: extractCursor(first)
+    };
+  }
+  const all = [...first.items];
+  let cursor = extractCursor(first);
+  while (cursor) {
+    const page = await unwrap(
+      client.catalogue.getProducts({ limit: opts.limit, cursor }),
+      "walk products"
+    );
+    all.push(...page.items);
+    cursor = extractCursor(page);
+  }
+  return { items: all, total: first.total_available ?? all.length, nextCursor: null };
+}
+function extractCursor(page) {
+  return page.pagination?.next_cursor ?? null;
+}
+async function buildCollectionSummary(client, c) {
+  const r = await client.catalogue.getCollectionProducts(c.id);
+  const products = r.ok ? Array.isArray(r.value) ? r.value : r.value.items ?? [] : [];
+  return {
+    id: c.id,
+    name: c.name,
+    slug: c.slug ?? "",
+    product_count: products.length,
+    sample_product_ids: products.slice(0, COLLECTION_SAMPLE_SIZE).map((p) => p.id)
+  };
+}
+async function fetchBusiness(client) {
+  const maybe = client.business.getBusiness;
+  if (typeof maybe !== "function") {
+    return { handle: null, name: null, currencies: [], locations: 0 };
+  }
+  try {
+    const r = await maybe.call(client.business);
+    if (!r?.ok || !r.value) return { handle: null, name: null, currencies: [], locations: 0 };
+    return {
+      handle: r.value.handle ?? null,
+      name: r.value.name ?? null,
+      currencies: r.value.currencies ?? [],
+      locations: r.value.locations?.length ?? 0
+    };
+  } catch {
+    return { handle: null, name: null, currencies: [], locations: 0 };
+  }
+}
+function productToSampleRow(p) {
+  return {
+    id: p.id,
+    name: p.name,
+    slug: p.slug,
+    price: priceShape(p),
+    has_image: hasImage(p),
+    has_description: !!p.description?.trim(),
+    tags: p.tags ?? [],
+    collection_ids: [],
+    category_ids: p.category_id ? [p.category_id] : [],
+    variant_count: 0
+  };
+}
+function hasImage(p) {
+  if (p.image_url && p.image_url.trim().length > 0) return true;
+  if (p.images && p.images.length > 0) return true;
+  return false;
+}
+function hasPrice(p) {
+  const price = p.default_price;
+  if (!price) return false;
+  const amt = price.amount;
+  if (amt == null) return false;
+  const n = typeof amt === "number" ? amt : Number.parseFloat(String(amt));
+  return Number.isFinite(n) && n > 0;
+}
+function priceShape(p) {
+  const price = p.default_price;
+  if (!price || price.amount == null) return null;
+  return { amount: String(price.amount), currency: price.currency ?? "" };
+}
+function countTags(products) {
+  const m = /* @__PURE__ */ new Map();
+  for (const p of products) {
+    for (const t of p.tags ?? []) {
+      m.set(t, (m.get(t) ?? 0) + 1);
+    }
+  }
+  return m;
+}
+function computeGaps(products, collections, categories, collectionMembers) {
+  let no_image = 0;
+  let no_description = 0;
+  let no_price = 0;
+  let no_collection = 0;
+  let no_tags = 0;
+  for (const p of products) {
+    if (!hasImage(p)) no_image++;
+    if (!p.description?.trim()) no_description++;
+    if (!hasPrice(p)) no_price++;
+    if (!collectionMembers.has(p.id)) no_collection++;
+    if (!p.tags?.length) no_tags++;
+  }
+  const empty_collections = collections.filter((c) => c.product_count === 0).map((c) => ({ id: c.id, name: c.name }));
+  const productCountsByCategory = /* @__PURE__ */ new Map();
+  for (const p of products) {
+    if (p.category_id) {
+      productCountsByCategory.set(
+        p.category_id,
+        (productCountsByCategory.get(p.category_id) ?? 0) + 1
+      );
+    }
+  }
+  const empty_categories = categories.filter((c) => (productCountsByCategory.get(c.id) ?? 0) === 0).map((c) => ({ id: c.id, name: c.name }));
+  return { no_image, no_description, no_price, no_collection, no_tags, empty_collections, empty_categories };
+}
+function buildCategoryTree(categories) {
+  const byParent = /* @__PURE__ */ new Map();
+  for (const c of categories) {
+    const key = c.parent_id ?? null;
+    if (!byParent.has(key)) byParent.set(key, []);
+    byParent.get(key).push(c);
+  }
+  const build = (parent) => (byParent.get(parent) ?? []).map((c) => ({
+    id: c.id,
+    name: c.name,
+    slug: c.slug ?? "",
+    product_count: 0,
+    children: build(c.id)
+  }));
+  return build(null);
+}
+function buildMeta(input) {
+  return {
+    fetched_at: (/* @__PURE__ */ new Date()).toISOString(),
+    source: input.source,
+    sampled: input.sampled,
+    sample_size: input.sampleSize,
+    gaps_method: input.gapsMethod,
+    shape_hints: shapeHints(input.data, input.source).sort(),
+    suggestions: suggestions(input.data),
+    suggested_commands: suggestedCommands(input.sampled)
+  };
+}
+function shapeHints(d, source) {
+  const hints = [];
+  const total = d.totals.products;
+  if (total === 0) hints.push("empty_catalogue");
+  else if (total < 10) hints.push("tiny_catalogue");
+  else if (total < 100) hints.push("small_catalogue");
+  else if (total < 1e3) hints.push("medium_catalogue");
+  else hints.push("large_catalogue");
+  if (d.collections.some((c) => c.product_count > 0)) hints.push("uses_collections");
+  if (d.categories.tree.length > 0) hints.push("uses_categories");
+  if (d.gaps.empty_collections.length > 0) hints.push("has_empty_collection");
+  if (d.gaps.empty_categories.length > 0) hints.push("has_empty_category");
+  const sampleSize = d.products.sample.length;
+  if (sampleSize > 0 && d.gaps.no_tags / sampleSize > 0.5) hints.push("untagged_majority");
+  if (sampleSize > 0 && d.gaps.no_collection / sampleSize > 0.5) hints.push("unmerchandised_majority");
+  if (d.gaps.no_image > 0) hints.push("has_image_gaps");
+  if (d.gaps.no_description > 0) hints.push("has_description_gaps");
+  if (d.gaps.no_price > 0) hints.push("has_price_gaps");
+  if (d.business.currencies.length > 1) hints.push("multi_currency");
+  if (d.business.locations > 1) hints.push("multi_location");
+  if (source === "mock") hints.push("mock_data");
+  return hints;
+}
+function suggestions(d) {
+  const out = [];
+  if (d.totals.products === 0) {
+    out.push({ kind: "add_first_product" });
+    return out;
+  }
+  if (d.totals.collections === 0) out.push({ kind: "add_first_collection" });
+  if (d.gaps.no_image > 0) out.push({ kind: "fix_no_image", count: d.gaps.no_image });
+  if (d.gaps.no_description > 0)
+    out.push({ kind: "fix_no_description", count: d.gaps.no_description });
+  if (d.gaps.no_price > 0) out.push({ kind: "fix_no_price", count: d.gaps.no_price });
+  if (d.gaps.no_collection > 0)
+    out.push({ kind: "fix_no_collection", count: d.gaps.no_collection });
+  if (d.gaps.no_tags > 0) out.push({ kind: "fix_no_tags", count: d.gaps.no_tags });
+  for (const c of d.gaps.empty_collections) {
+    out.push({ kind: "merchandise_empty_collection", collection_id: c.id, name: c.name });
+  }
+  for (const c of d.gaps.empty_categories) {
+    out.push({ kind: "merchandise_empty_category", category_id: c.id, name: c.name });
+  }
+  if (d.totals.products >= 1e3) {
+    out.push({ kind: "enable_search_ui", product_count: d.totals.products });
+  }
+  return out;
+}
+function suggestedCommands(sampled) {
+  return sampled ? ["cimplify inspect catalogue --all", "cimplify inspect catalogue --json"] : ["cimplify inspect catalogue --json"];
+}
+function renderHuman(d, m) {
+  info("");
+  info(
+    `  ${bold(d.business.name ?? "(unnamed business)")}` + (d.business.handle ? dim(`  \xB7  @${d.business.handle}`) : "") + (d.business.locations ? dim(`  \xB7  ${d.business.locations} location${d.business.locations === 1 ? "" : "s"}`) : "") + (d.business.currencies.length ? dim(`  \xB7  ${d.business.currencies.join(", ")}`) : "")
+  );
+  info("");
+  info(`  Products      ${pad(d.totals.products, 5)}  ${gapBadges(d.gaps)}`);
+  info(`  Collections   ${pad(d.totals.collections, 5)}  ${emptyBadge(d.gaps.empty_collections, "empty")}`);
+  info(`  Categories    ${pad(d.totals.categories, 5)}  ${emptyBadge(d.gaps.empty_categories, "empty")}`);
+  info(`  Tags          ${pad(d.totals.distinct_tags, 5)}  ${tagBadge(d.gaps.no_tags)}`);
+  info("");
+  if (d.tags.top.length > 0) {
+    info(`  ${dim("Top tags")}     ${d.tags.top.map((t) => `${t.tag} (${t.count})`).join(" \xB7 ")}`);
+    info("");
+  }
+  if (d.collections.length > 0) {
+    info(`  ${dim("Collections")}`);
+    for (const c of d.collections.slice(0, 5)) {
+      const tag = c.product_count === 0 ? `  ${yellow("\u26A0 empty")}` : "";
+      info(`    ${green("\u25B8")} ${c.name.padEnd(20)} ${dim(`${c.product_count} items`)}${tag}`);
+    }
+    if (d.collections.length > 5) info(`    ${dim(`\u2026${d.collections.length - 5} more`)}`);
+    info("");
+  }
+  if (d.products.sample.length > 0) {
+    info(`  ${dim(`Sample products (first ${d.products.sample.length} of ${d.totals.products})`)}`);
+    for (const p of d.products.sample.slice(0, 10)) {
+      const id = p.id.slice(0, 8).padEnd(10);
+      const name = truncate(p.name, 24).padEnd(24);
+      const price = p.price ? `${p.price.currency} ${p.price.amount}` : dim("\u2014");
+      const img = p.has_image ? green("img \u2713") : red("img \u2717");
+      const tags = p.tags.length ? p.tags.slice(0, 2).join(", ") : dim("\u2014");
+      info(`    ${dim(id)}${name} ${price.padEnd(12)} ${img}  ${tags}`);
+    }
+    info("");
+  }
+  if (m.sampled) {
+    info(`  ${dim(`Gaps computed from first ${m.sample_size} products. Add --all for exact counts.`)}`);
+  } else {
+    info(`  ${dim("Gaps are exact (walked the full catalogue).")}`);
+  }
+  info("");
+  if (m.suggested_commands.length > 0) {
+    info(`  ${dim("Try")}`);
+    for (const c of m.suggested_commands) info(`    ${c}`);
+    info("");
+  }
+}
+function gapBadges(g, _kind) {
+  const bits = [];
+  if (g.no_image > 0) bits.push(`${g.no_image} no image`);
+  if (g.no_description > 0) bits.push(`${g.no_description} no description`);
+  if (g.no_collection > 0) bits.push(`${g.no_collection} not in any collection`);
+  if (bits.length === 0) return dim("no gaps");
+  return yellow(`\u26A0 ${bits.join(" \xB7 ")}`);
+}
+function emptyBadge(items, label) {
+  if (items.length === 0) return dim("no gaps");
+  const names = items.slice(0, 3).map((i) => i.name).join(", ");
+  const more = items.length > 3 ? `, \u2026${items.length - 3} more` : "";
+  return yellow(`\u26A0 ${items.length} ${label} (${names}${more})`);
+}
+function tagBadge(untagged) {
+  if (untagged === 0) return dim("all tagged");
+  return yellow(`\u26A0 ${untagged} products untagged`);
+}
+function pad(n, width) {
+  return String(n).padStart(width);
+}
+function truncate(s, width) {
+  if (s.length <= width) return s;
+  return s.slice(0, width - 1) + "\u2026";
+}
+async function unwrap(p, label) {
+  const r = await p;
+  if (!r.ok || r.value == null) {
+    const msg = r.error?.message ?? `failed to ${label}`;
+    throw new CliError(CLI_ERROR_CODE.NETWORK_ERROR, msg);
+  }
+  return r.value;
+}
+
+export { computeGaps, run as default, isHostedKey, parseLimit, shapeHints, suggestions };

package/dist/{introspect-77SUZ5X5.mjs → introspect-4LD27NVX.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-export { run as default, extractMockSeed, gatherIntrospection, renderIntrospection } from './chunk-SNDMYYOK.mjs';
+export { run as default, extractMockSeed, gatherIntrospection, renderIntrospection } from './chunk-CNIFXKZV.mjs';
 import './chunk-K5464A3L.mjs';
 import './chunk-DBZ3UOQ2.mjs';
-import './chunk-KOJZB3S4.mjs';
+import './chunk-RGF2RSSR.mjs';
 import './chunk-C4M3DXKC.mjs';
 import './chunk-UBAI443T.mjs';
 import './chunk-E2T2SBP5.mjs';

package/dist/{list-QX7RM3P3.mjs → list-2YRVKBXY.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { REGISTRY_INDEX } from './chunk-OLZMA2TM.mjs';
+import { REGISTRY_INDEX } from './chunk-RIOQDUQO.mjs';
 import { parseArgs, flagBool } from './chunk-C4M3DXKC.mjs';
 import { CliError, CLI_ERROR_CODE, info, bold, dim, green, result } from './chunk-E2T2SBP5.mjs';
 

package/dist/{update-UHKPFT6F.mjs → update-J65Z6Q7E.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { package_default } from './chunk-KOJZB3S4.mjs';
+import { package_default } from './chunk-RGF2RSSR.mjs';
 import { promptYesNo } from './chunk-ITAFAORS.mjs';
 import { parseArgs, flagBool, flagString } from './chunk-C4M3DXKC.mjs';
 import { success, bold, info, dim, result, failure, CliError, CLI_ERROR_CODE, step, isJsonMode } from './chunk-E2T2SBP5.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cimplify/cli",
-  "version": "0.6.11",
+  "version": "0.6.14",
   "description": "Cimplify CLI — deploy, manage env vars, link projects, and scaffold storefronts",
   "keywords": [
     "cimplify",
@@ -43,5 +43,8 @@
     "tsup": "^8.5.1",
     "typescript": "5.9.3",
     "vitest": "^4.1.5"
+  },
+  "dependencies": {
+    "@cimplify/sdk": "^0.49.0"
   }
 }

package/templates/storefront-auto/app/api/revalidate/route.ts

@@ -0,0 +1,5 @@
+import { revalidateRouteHandler } from "@cimplify/sdk/server";
+
+export async function POST(req: Request): Promise<Response> {
+  return revalidateRouteHandler(req);
+}