@tokenoftrust/storefront-runner 2.2.89 → 2.2.91

package/agency-kit/tools/lib/catalog-model/files.d.mts

@@ -0,0 +1,48 @@
+// Types for files.mjs. Records are typed structurally here; the platform narrows them to its
+// canonical product types at its own boundary.
+
+export type CatalogFileKind = "product" | "collection";
+export type CatalogRecord = Record<string, unknown>;
+export type InventoryProvider = "mirror" | "live-hydrate" | "tot-authoritative";
+
+export const CATALOG_CONTENT_DIRS: { readonly products: string; readonly collections: string };
+export const CATALOG_ARTIFACT_PREFIX: string;
+export const CATALOG_PRODUCTS_PREFIX: string;
+export const CATALOG_COLLECTIONS_PREFIX: string;
+export const CATALOG_HANDLE_RE: RegExp;
+export const INVENTORY_PROVIDERS: readonly InventoryProvider[];
+
+export function classifyCatalogPath(
+  relative: string,
+): { kind: CatalogFileKind; handle: string } | { kind: "unexpected" } | null;
+
+export function catalogFileRecord<T>(kind: CatalogFileKind, record: T): T;
+export function serializeCatalogRecord(record: unknown): string;
+export function planCatalogFiles(catalog: { products: readonly unknown[]; collections: readonly unknown[] }): {
+  files: Array<{ kind: CatalogFileKind; handle: string; path: string; content: string }>;
+  errors: string[];
+};
+
+export function declaredAvailability(provider: InventoryProvider | undefined): { available: boolean };
+export function catalogFileIssues(relative: string, raw: string): string[];
+
+export class CatalogFileError extends Error {
+  constructor(failures: ReadonlyArray<{ path: string; issues: readonly string[] }>);
+  readonly failures: ReadonlyArray<{ path: string; issues: readonly string[] }>;
+}
+
+export interface CatalogStore {
+  tenantScope: string;
+  inventoryProvider?: InventoryProvider;
+}
+
+export function readCatalogFile(
+  relative: string,
+  raw: string,
+  store: CatalogStore,
+): { kind: CatalogFileKind; record: CatalogRecord };
+
+export function readCatalogFiles(
+  entries: Iterable<{ path: string; raw: string | null }>,
+  store: CatalogStore,
+): { products: CatalogRecord[]; collections: CatalogRecord[] };

package/agency-kit/tools/lib/catalog-model/files.mjs

@@ -0,0 +1,263 @@
+/**
+ * A store's catalog files: where they live, how a record becomes a file, and how a file becomes a
+ * record. The one implementation every reader and writer uses: the kit's tools, the platform's
+ * renderer, its reconcile validator and its migration engine.
+ *
+ * Pure: no filesystem, no network, no dependencies, so it runs in Node, a browser and a Worker.
+ *
+ * Layout, relative to the store checkout:
+ *
+ *   content/catalog/products/<handle>.json      one CatalogProduct
+ *   content/catalog/collections/<handle>.json   one CatalogCollection
+ *
+ * One JSON object per file; the file stem IS the record's `handle`. Each record is the canonical
+ * shape in `./model.mjs`, with three file-level relaxations:
+ *
+ *   - `tenant_id` (product and variant) and `variants[].product_id` are optional and ignored. The
+ *     reader stamps them from the store being read: a file's location is its identity.
+ *   - `created_at` / `updated_at` / `migrated_at` / `source_checksum` are optional.
+ *   - `variants[].inventory` is never read, and writers leave it out. Availability is hot data and
+ *     lives behind the store's declared `inventory.provider`, never in a content file.
+ */
+import { validateRecord } from "./model.mjs";
+
+/** Store-relative directories, one per record kind. */
+export const CATALOG_CONTENT_DIRS = {
+  products: "content/catalog/products",
+  collections: "content/catalog/collections",
+};
+
+/** The same directories relative to the store's `content/` (the platform's artifact paths). */
+export const CATALOG_ARTIFACT_PREFIX = "catalog/";
+export const CATALOG_PRODUCTS_PREFIX = "catalog/products/";
+export const CATALOG_COLLECTIONS_PREFIX = "catalog/collections/";
+
+/** A safe handle, which is also the file stem. */
+export const CATALOG_HANDLE_RE = /^[a-z0-9][a-z0-9-]{0,119}$/;
+
+const PROVENANCE_KEYS = ["created_at", "updated_at", "migrated_at", "source_checksum"];
+
+/** @type {(v: unknown) => v is Record<string, any>} */
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * What a `content/`-relative path is to the catalog: a product or collection file, `unexpected`
+ * (under `catalog/` but not a record file this layout defines), or null (not a catalog path).
+ *
+ * @returns {{ kind: "product" | "collection", handle: string } | { kind: "unexpected" } | null}
+ */
+export function classifyCatalogPath(relative) {
+  const path = String(relative).replace(/^\/+/, "");
+  if (!path.startsWith(CATALOG_ARTIFACT_PREFIX)) return null;
+  /** @type {Array<[string, "product" | "collection"]>} */
+  const kinds = [
+    [CATALOG_PRODUCTS_PREFIX, "product"],
+    [CATALOG_COLLECTIONS_PREFIX, "collection"],
+  ];
+  for (const [prefix, kind] of kinds) {
+    if (!path.startsWith(prefix)) continue;
+    const name = path.slice(prefix.length);
+    if (!name.endsWith(".json")) return { kind: "unexpected" };
+    const handle = name.slice(0, -".json".length);
+    return CATALOG_HANDLE_RE.test(handle) ? { kind, handle } : { kind: "unexpected" };
+  }
+  return { kind: "unexpected" };
+}
+
+// --- Writing ----------------------------------------------------------------------------------
+
+/** A record as its file holds it: every variant's `inventory` left out. */
+export function catalogFileRecord(kind, record) {
+  if (kind !== "product" || !isObject(record) || !Array.isArray(record.variants)) return record;
+  return {
+    ...record,
+    variants: record.variants.map((variant) => {
+      if (!isObject(variant)) return variant;
+      const { inventory: _inventory, ...rest } = variant;
+      return rest;
+    }),
+  };
+}
+
+/** A file's bytes: two-space JSON and a trailing newline. */
+export function serializeCatalogRecord(record) {
+  return JSON.stringify(record, null, 2) + "\n";
+}
+
+/**
+ * Plan a catalog's files, sorted by path so the same catalog always yields the same bytes. Every
+ * planned file passes `catalogFileIssues`; `errors` names each record that cannot become a file
+ * (an unsafe or duplicate handle, or a record the reader would refuse). Non-empty `errors` means
+ * the write must not happen.
+ *
+ * @param {{ products: object[], collections: object[] }} catalog
+ * @returns {{ files: Array<{ kind: "product" | "collection", handle: string, path: string, content: string }>, errors: string[] }}
+ */
+export function planCatalogFiles({ products, collections }) {
+  /** @type {Array<{ kind: "product" | "collection", handle: string, path: string, content: string }>} */
+  const files = [];
+  /** @type {string[]} */
+  const errors = [];
+  /** @type {Array<["product" | "collection", string, readonly unknown[]]>} */
+  const kinds = [
+    ["product", "products", products],
+    ["collection", "collections", collections],
+  ];
+  for (const [kind, dir, records] of kinds) {
+    const seen = new Set();
+    for (const record of records) {
+      const handle = isObject(record) ? record.handle : undefined;
+      if (typeof handle !== "string" || !CATALOG_HANDLE_RE.test(handle)) {
+        errors.push(`${dir}: handle ${JSON.stringify(handle)} is not a safe file name (lowercase letters, digits and "-")`);
+        continue;
+      }
+      if (seen.has(handle)) {
+        errors.push(`${dir}: handle ${handle} appears twice`);
+        continue;
+      }
+      seen.add(handle);
+      const content = serializeCatalogRecord(catalogFileRecord(kind, record));
+      const relative = `catalog/${dir}/${handle}.json`;
+      for (const issue of catalogFileIssues(relative, content)) errors.push(`content/${relative}: ${issue}`);
+      files.push({ kind, handle, path: `content/${relative}`, content });
+    }
+  }
+  files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return { files, errors };
+}
+
+// --- Reading ----------------------------------------------------------------------------------
+
+/** ADR 0033's declared availability providers. Only `mirror` is implemented. */
+export const INVENTORY_PROVIDERS = ["mirror", "live-hydrate", "tot-authoritative"];
+
+/**
+ * The availability a variant carries when its catalog comes from content files: the `mirror`
+ * provider at location `unspecified` with no movement record, which is purchasable with stock
+ * confirmed at checkout. No quantity is claimed, because none is known.
+ */
+export function declaredAvailability(provider) {
+  const effective = provider ?? "mirror";
+  if (effective !== "mirror") {
+    throw new Error(
+      `inventory.provider "${effective}" is declared, but only "mirror" is implemented ` +
+        `(ADR 0033). Declare "mirror" or remove the declaration.`,
+    );
+  }
+  return { available: true };
+}
+
+/** A file's record with its identity, provenance and availability stamped by the reader. */
+function stamp(kind, doc, tenantScope, availability) {
+  if (!isObject(doc)) return doc;
+  /** @type {Record<string, any>} */
+  const out = { ...doc, tenant_id: tenantScope };
+  for (const key of PROVENANCE_KEYS) out[key] = doc[key] ?? "";
+  if (kind === "product" && Array.isArray(doc.variants)) {
+    const productId = typeof doc.id === "string" ? doc.id : "";
+    out.variants = doc.variants.map((variant) =>
+      isObject(variant)
+        ? { ...variant, tenant_id: tenantScope, product_id: productId, inventory: { ...availability } }
+        : variant,
+    );
+  }
+  return out;
+}
+
+function parse(relative, raw, tenantScope, availability) {
+  const where = classifyCatalogPath(relative);
+  if (where === null) return { issues: [] };
+  if (where.kind === "unexpected") {
+    return {
+      issues: [
+        `not a catalog record file: catalog files are ${CATALOG_PRODUCTS_PREFIX}<handle>.json ` +
+          `or ${CATALOG_COLLECTIONS_PREFIX}<handle>.json, with <handle> matching ${CATALOG_HANDLE_RE}`,
+      ],
+    };
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (e) {
+    return { issues: [`not valid JSON: ${e instanceof Error ? e.message : e}`] };
+  }
+  const record = stamp(where.kind, doc, tenantScope, availability);
+  const issues = validateRecord(where.kind === "product" ? "CatalogProduct" : "CatalogCollection", record).map(
+    (i) => (i.path ? `${i.path}: ${i.message}` : i.message),
+  );
+  if (isObject(doc) && typeof doc.handle === "string" && doc.handle !== where.handle) {
+    issues.push(`handle: "${doc.handle}" does not match the file name "${where.handle}.json"`);
+  }
+  return { kind: where.kind, record, issues };
+}
+
+/** The structural problems with one catalog file's text (empty = valid). */
+export function catalogFileIssues(relative, raw) {
+  return parse(relative, raw, "", { available: true }).issues;
+}
+
+/** A catalog file the reader refuses, with every reason it names. */
+export class CatalogFileError extends Error {
+  /** @param {ReadonlyArray<{ path: string, issues: readonly string[] }>} failures */
+  constructor(failures) {
+    super(
+      `catalog: ${failures.length} file(s) in content/catalog/ cannot be served:\n` +
+        failures
+          .map(
+            (f) =>
+              `  content/${f.path}: ${f.issues.slice(0, 5).join("; ")}` +
+              (f.issues.length > 5 ? `; …and ${f.issues.length - 5} more` : ""),
+          )
+          .join("\n"),
+    );
+    this.name = "CatalogFileError";
+    this.failures = failures;
+  }
+}
+
+/**
+ * Parse one catalog file into its canonical record, stamped for the store being read. Throws
+ * `CatalogFileError` naming every issue when the file fails validation.
+ *
+ * @param {string} relative `content/`-relative path
+ * @param {string} raw the file's text
+ * @param {{ tenantScope: string, inventoryProvider?: string }} store
+ */
+export function readCatalogFile(relative, raw, { tenantScope, inventoryProvider }) {
+  const parsed = parse(relative, raw, tenantScope, declaredAvailability(inventoryProvider));
+  if (parsed.issues.length > 0 || !parsed.kind) {
+    throw new CatalogFileError([
+      { path: relative, issues: parsed.issues.length ? parsed.issues : ["not a catalog record file"] },
+    ]);
+  }
+  return { kind: parsed.kind, record: parsed.record };
+}
+
+/**
+ * A whole catalog from its files: every file validated, one bad file refuses the catalog with
+ * every failing path named (never a partial catalog with a product silently missing). Non-catalog
+ * paths are ignored; an unreadable entry (`raw: null`) is a failure.
+ *
+ * @param {Iterable<{ path: string, raw: string | null }>} entries `content/`-relative paths
+ * @param {{ tenantScope: string, inventoryProvider?: string }} store
+ * @returns {{ products: object[], collections: object[] }}
+ */
+export function readCatalogFiles(entries, { tenantScope, inventoryProvider }) {
+  const availability = declaredAvailability(inventoryProvider);
+  const products = [];
+  const collections = [];
+  const failures = [];
+  for (const { path, raw } of entries) {
+    if (classifyCatalogPath(path) === null) continue;
+    if (raw === null) {
+      failures.push({ path, issues: ["listed in the catalog but unreadable"] });
+      continue;
+    }
+    const parsed = parse(path, raw, tenantScope, availability);
+    if (parsed.issues.length > 0) failures.push({ path, issues: parsed.issues });
+    else if (parsed.kind === "product") products.push(parsed.record);
+    else collections.push(parsed.record);
+  }
+  if (failures.length > 0) throw new CatalogFileError(failures);
+  return { products, collections };
+}

package/agency-kit/tools/lib/catalog-model/model.mjs

@@ -0,0 +1,282 @@
+/**
+ * The canonical catalog record shape, vendored into the kit.
+ *
+ * This is a mirror of the platform's product model (`packages/public-runtime/src/product.ts` in the
+ * Storefront repository), written as data so the kit can validate records with no dependency and
+ * no platform checkout. The Storefront repository pins it field for field: its drift test compares
+ * this model to `product.ts` and fails on any added, removed, renamed, retyped, or re-optionalised
+ * field, and on any product-model type this file does not mirror. Change both together.
+ *
+ * Grammar. Each entry is one named type:
+ *   { alias: "<type>" }                     a type alias
+ *   { fields: { "<name>[?]": "<type>" } }   an object; a trailing `?` marks the field optional
+ *   { union: [ { "<name>[?]": "<type>" } ] } a union of inline object shapes
+ * A `<type>` is written exactly as in TypeScript: `string`, `number`, `boolean`, `unknown`,
+ * a string literal (`"csv"`), a named type from this model, `T[]`, `Record<string, T>`, or a
+ * `|`-separated union of those.
+ */
+
+export const CATALOG_MODEL = {
+  ProductStatus: { alias: '"active" | "draft" | "archived"' },
+  Currency: { alias: "string" },
+  SourcePlatform: { alias: '"shopify" | "directory" | "csv" | "manual" | "synthesized"' },
+  SourceRef: {
+    fields: { platform: "SourcePlatform", source_id: "string", "source_handle?": "string" },
+  },
+  SeoFields: { fields: { "title?": "string", "description?": "string" } },
+  PriceRange: { fields: { min: "number", max: "number", currency: "Currency" } },
+  ProductOption: { fields: { name: "string", position: "number", values: "string[]" } },
+  PurchaseOptionKind: { alias: '"one_time" | "subscription"' },
+  OneTimePurchaseOption: {
+    fields: { id: "string", kind: '"one_time"', label: "string", "description?": "string" },
+  },
+  PurchaseOptionPriceAdjustment: {
+    union: [
+      { type: '"percent_off"', value: "number" },
+      { type: '"amount_off"', value: "number" },
+    ],
+  },
+  SubscriptionPurchaseOption: {
+    fields: {
+      id: "string",
+      kind: '"subscription"',
+      label: "string",
+      "description?": "string",
+      "savingsLabel?": "string",
+      "priceAdjustment?": "PurchaseOptionPriceAdjustment",
+      frequency: "string",
+      "startDate?": "string",
+      "endDate?": "string",
+    },
+  },
+  ProductPurchaseOption: { alias: "OneTimePurchaseOption | SubscriptionPurchaseOption" },
+  CatalogImage: {
+    fields: {
+      id: "string",
+      url: "string",
+      "alt?": "string",
+      position: "number",
+      "width?": "number",
+      "height?": "number",
+      "variant_ids?": "string[]",
+      "rehosted?": "boolean",
+      "source_url?": "string",
+    },
+  },
+  Metafield: {
+    fields: { namespace: "string", key: "string", value: "string", "type?": "string" },
+  },
+  InventoryState: {
+    fields: { "quantity?": "number", "policy?": "string", available: "boolean" },
+  },
+  CatalogVariant: {
+    fields: {
+      tenant_id: "string",
+      id: "string",
+      product_id: "string",
+      source: "SourceRef",
+      "sku?": "string",
+      title: "string",
+      price: "number",
+      "compare_at_price?": "number",
+      currency: "Currency",
+      option_values: "Record<string, string>",
+      inventory: "InventoryState",
+      "barcode?": "string",
+      "weight?": "number",
+      "weight_unit?": "string",
+      position: "number",
+      "image_id?": "string",
+    },
+  },
+  CatalogProduct: {
+    fields: {
+      tenant_id: "string",
+      id: "string",
+      source: "SourceRef",
+      handle: "string",
+      title: "string",
+      description_html: "string",
+      description_text: "string",
+      "vendor?": "string",
+      "product_type?": "string",
+      tags: "string[]",
+      status: "ProductStatus",
+      seo: "SeoFields",
+      options: "ProductOption[]",
+      images: "CatalogImage[]",
+      variants: "CatalogVariant[]",
+      "purchase_options?": "ProductPurchaseOption[]",
+      price_range: "PriceRange",
+      collections: "string[]",
+      metafields: "Metafield[]",
+      created_at: "string",
+      updated_at: "string",
+      migrated_at: "string",
+      source_checksum: "string",
+    },
+  },
+  CatalogCollection: {
+    fields: {
+      tenant_id: "string",
+      id: "string",
+      source: "SourceRef",
+      handle: "string",
+      title: "string",
+      "description_html?": "string",
+      "description_text?": "string",
+      "image?": "CatalogImage",
+      seo: "SeoFields",
+      product_handles: "string[]",
+      "rule?": "Record<string, unknown>",
+      "position?": "number",
+      created_at: "string",
+      updated_at: "string",
+      migrated_at: "string",
+      source_checksum: "string",
+    },
+  },
+};
+
+/** Split a type on its top-level `|`, ignoring pipes nested in `<>`, `{}`, `()` or `[]`. */
+export function splitUnion(type) {
+  const parts = [];
+  let depth = 0;
+  let cur = "";
+  let quote = null;
+  for (const ch of type) {
+    if (quote) {
+      cur += ch;
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") quote = ch;
+    else if ("<{([".includes(ch)) depth++;
+    else if (">})]".includes(ch)) depth--;
+    if (ch === "|" && depth === 0) {
+      parts.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  parts.push(cur);
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+
+/** Canonical spelling of a type: single spaces, `'` quotes as `"`, unions joined by ` | `. */
+export function normType(type) {
+  return splitUnion(String(type).replace(/\s+/g, " ").replace(/'/g, '"').replace(/;\s*$/, ""))
+    .map((p) => p.replace(/\s*,\s*/g, ", ").replace(/\s*<\s*/g, "<").replace(/\s*>/g, ">"))
+    .join(" | ");
+}
+
+function normFields(fields) {
+  const out = {};
+  for (const [raw, type] of Object.entries(fields)) {
+    const optional = raw.endsWith("?");
+    out[optional ? raw.slice(0, -1) : raw] = { type: normType(type), optional };
+  }
+  return out;
+}
+
+/**
+ * The comparable form of a model: `{ name: { kind: "alias", type } | { kind: "object", fields }
+ * | { kind: "union", variants: fields[] } }`, where `fields` is `{ name: { type, optional } }`.
+ * The drift test reduces the TypeScript source to the same form and compares the two.
+ */
+export function normalizeModel(model = CATALOG_MODEL) {
+  const out = {};
+  for (const [name, def] of Object.entries(model)) {
+    if ("alias" in def) out[name] = { kind: "alias", type: normType(def.alias) };
+    else if ("fields" in def) out[name] = { kind: "object", fields: normFields(def.fields) };
+    else if ("union" in def) out[name] = { kind: "union", variants: def.union.map(normFields) };
+    else throw new Error(`catalog model entry ${name} has no alias, fields or union`);
+  }
+  return out;
+}
+
+const NORMALIZED = normalizeModel(CATALOG_MODEL);
+
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+function checkObject(fields, value, path, issues) {
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "expected an object" });
+    return;
+  }
+  for (const [key, spec] of Object.entries(fields)) {
+    const at = path ? `${path}.${key}` : key;
+    if (value[key] === undefined) {
+      if (!spec.optional) issues.push({ path: at, message: "required" });
+      continue;
+    }
+    checkType(spec.type, value[key], at, issues);
+  }
+  for (const key of Object.keys(value)) {
+    if (!(key in fields)) issues.push({ path: path ? `${path}.${key}` : key, message: "unknown field" });
+  }
+}
+
+function checkType(type, value, path, issues) {
+  const alts = splitUnion(type);
+  if (alts.length > 1) {
+    if (alts.some((alt) => typeIssues(alt, value, path).length === 0)) return;
+    issues.push({ path, message: `expected ${type}` });
+    return;
+  }
+  const t = alts[0];
+  const literal = /^"(.*)"$/.exec(t);
+  if (literal) {
+    if (value !== literal[1]) issues.push({ path, message: `expected ${t}` });
+    return;
+  }
+  if (t.endsWith("[]")) {
+    if (!Array.isArray(value)) issues.push({ path, message: `expected ${t}` });
+    else value.forEach((v, i) => checkType(t.slice(0, -2), v, `${path}.${i}`, issues));
+    return;
+  }
+  const record = /^Record<string, (.+)>$/.exec(t);
+  if (record) {
+    if (!isPlainObject(value)) issues.push({ path, message: `expected ${t}` });
+    else for (const [k, v] of Object.entries(value)) checkType(record[1], v, `${path}.${k}`, issues);
+    return;
+  }
+  switch (t) {
+    case "unknown":
+      return;
+    case "string":
+    case "boolean":
+      if (typeof value !== t) issues.push({ path, message: `expected ${t}` });
+      return;
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) issues.push({ path, message: "expected number" });
+      return;
+  }
+  const def = NORMALIZED[t];
+  if (!def) throw new Error(`catalog model has no type ${t}`);
+  if (def.kind === "alias") checkType(def.type, value, path, issues);
+  else if (def.kind === "object") checkObject(def.fields, value, path, issues);
+  else if (!def.variants.some((fields) => objectIssues(fields, value, path).length === 0))
+    issues.push({ path, message: `expected ${t}` });
+}
+
+function typeIssues(type, value, path) {
+  const issues = [];
+  checkType(type, value, path, issues);
+  return issues;
+}
+
+function objectIssues(fields, value, path) {
+  const issues = [];
+  checkObject(fields, value, path, issues);
+  return issues;
+}
+
+/**
+ * Structural issues for one record against a named model type. Never throws on bad data; returns
+ * `[{ path, message }]`, empty when the record is valid. Unknown fields are issues.
+ */
+export function validateRecord(typeName, value) {
+  return typeIssues(typeName, value, "");
+}