@omega.js/web 0.1.0

package/dist/pricing.js

@@ -0,0 +1,301 @@
+/**
+ * Pricing view-model composer — `payment.products` (omega.json5) is the ONLY
+ * source for pricing pages (C2). The engine derives `site.pricing` from the
+ * catalog and every theme renders that; consumer page frontmatter can still
+ * override presentation per-page through the resolved cascade (frontmatter is
+ * the consumer surface, never the framework's). No catalog → null → themes
+ * render an honest empty state instead of fictional plans.
+ *
+ * A feature is DEFINED once, in the config's top-level `features` catalog
+ * (name, icon, definition, and a `usage` block on the metered ones), and each
+ * product names only its VALUE
+ * ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)). So this
+ * composer reads BOTH halves: the catalog decides row order and copy, the
+ * product decides what its tier promises. There is nothing left to backfill —
+ * a definition cannot disagree with itself when it exists in one place.
+ *
+ * Product presentation fields (optional, alongside the backend-shaped
+ * id/name/type/prices/trial):
+ *   tagline    - short line under the plan name
+ *   popular    - highlight badge on the plan card
+ *   enterprise - the "talk to us" tier: leaves BOTH card lanes (plans and
+ *                one-time, whatever its type) and renders as its own
+ *                full-width row (no enterprise product in the catalog → no
+ *                row, never invented)
+ *   url        - CTA href (defaults to /signup for free plans; /contact for
+ *                the enterprise tier; paid plans without a url get a
+ *                checkout button instead)
+ *   features   - the values map { <catalog id>: value }: a number on a counted
+ *                feature (-1 renders as Unlimited), true/a string on a perk,
+ *                and `false` (or absent) means the tier does not include it
+ *   hidden     - presentation-only exclusion (#348): the product is still
+ *                created on every provider and purchasable by id (QA tiers,
+ *                grandfathered plans), but the composer drops it before any
+ *                lane reads the catalog — no card, no comparison row, no vote
+ *                on the page's universal numbers
+ */
+
+const Logger = require('./vendor/devkit/logger.js');
+
+const logger = new Logger('pricing');
+
+/**
+ * Normalize a feature value for display: -1 is the catalog's "unlimited"
+ * sentinel; undefined stays null so templates can render name-only features.
+ * @param {*} value - raw feature/limit value
+ * @returns {*} display value or null
+ */
+function normalizeValue(value) {
+  if (value === undefined || value === null) return null;
+  if (value === -1) return 'Unlimited';
+  return value;
+}
+
+/**
+ * Compose a product's display features: the FEATURES CATALOG supplies the row
+ * order, the name, the icon and the definition; the product supplies only the
+ * value. A feature the product does not name — or names `false` — is not part
+ * of that tier and renders nowhere.
+ * @param {object} product - catalog entry (payment.products)
+ * @param {object} catalog - the top-level `features` catalog
+ * @returns {Array<object>} [{ id, name, icon, definition, value }]
+ * @throws {Error} on the pre-#647 features LIST, naming the migration
+ */
+function composeFeatures(product, catalog) {
+  const values = (product && product.features) || {};
+
+  // The pre-#647 display LIST is a shape this composer stopped understanding
+  // the day the catalog became the one home of a feature's copy — every key
+  // lookup below misses, so an unmigrated brand would get cards with no
+  // bullets and an empty comparison matrix. Say so instead (the config
+  // validator refuses the same shape earlier; this is the backstop for the
+  // readers that reach the composer without it).
+  if (Array.isArray(values)) {
+    throw new Error(
+      `payment.products "${(product && product.id) || 'unnamed'}" carries the pre-#647 features LIST — `
+      + 'write `features: { requests: 100, support: true }` and define each feature ONCE in the '
+      + 'top-level `features` catalog (docs/shared/breaking-changes.md § Plan limits become the features catalog)',
+    );
+  }
+
+  return Object.keys(catalog)
+    .filter((id) => values[id] !== undefined && values[id] !== false)
+    .map((id) => ({
+      id: id,
+      name: catalog[id].name || id,
+      icon: catalog[id].icon || null,
+      definition: catalog[id].definition || null,
+      value: normalizeValue(values[id]),
+    }));
+}
+
+/**
+ * Compose one subscription plan card model.
+ * @param {object} product - catalog entry (type subscription)
+ * @returns {object} plan view-model
+ */
+function composePlan(product, catalog) {
+  const prices = product.prices || {};
+  const monthly = typeof prices.monthly === 'number' ? prices.monthly : 0;
+  const annually = typeof prices.annually === 'number' ? prices.annually : 0;
+  const free = monthly <= 0 && annually <= 0;
+
+  return {
+    id: product.id,
+    name: product.name,
+    tagline: product.tagline || null,
+    popular: product.popular === true,
+    free: free,
+    url: product.url || (free ? '/signup' : null),
+    trialDays: (product.trial && product.trial.days) || 0,
+    prices: {
+      monthly: monthly,
+      annually: annually,
+      // What the card shows in "$N /month" while the annual toggle is active.
+      // FLOORS (#477 — legacy parity): the monthly equivalent never claims
+      // more than a twelfth of what is actually charged.
+      annuallyPerMonth: annually > 0 ? Math.floor(annually / 12) : 0,
+    },
+    features: composeFeatures(product, catalog),
+  };
+}
+
+/**
+ * Compose the enterprise tier: the "talk to us" product, priced by
+ * conversation instead of by card — no prices, no billing cadence, a contact
+ * CTA. It never enters the plan grid or the comparison matrix.
+ * @param {object} product - catalog entry flagged `enterprise: true`
+ * @returns {object} enterprise view-model
+ */
+function composeEnterprise(product, catalog) {
+  return {
+    id: product.id,
+    name: product.name,
+    tagline: product.tagline || null,
+    url: product.url || '/contact',
+    features: composeFeatures(product, catalog),
+  };
+}
+
+/**
+ * Split each plan's features into the set common to ALL plans (rendered with
+ * per-plan values) and the plan's extras (rendered under "Everything in
+ * <previous>, and more").
+ * @param {Array<object>} plans - composed plans
+ */
+function splitCommonFeatures(plans) {
+  const withFeatures = plans.filter((plan) => plan.features.length > 0);
+  const commonIds = withFeatures.length === plans.length && plans.length > 0
+    ? plans[0].features
+      .filter((feature) => plans.every((plan) => plan.features.some((f) => f.id === feature.id)))
+      .map((feature) => feature.id)
+    : [];
+
+  for (const plan of plans) {
+    plan.commonFeatures = plan.features.filter((feature) => commonIds.includes(feature.id));
+    plan.extraFeatures = plan.features.filter((feature) => !commonIds.includes(feature.id));
+  }
+}
+
+/**
+ * Build the feature-comparison matrix: the union of plan features in first-
+ * appearance order, with per-plan values. A plan that doesn't declare a
+ * feature inherits the value from the closest EARLIER plan that does (tiers
+ * accumulate) — null means genuinely not included.
+ * @param {Array<object>} plans - composed plans
+ * @returns {{ features: Array<object> }}
+ */
+function composeComparison(plans) {
+  const features = [];
+  const byId = new Map();
+
+  for (const plan of plans) {
+    for (const feature of plan.features) {
+      if (byId.has(feature.id)) continue;
+      const entry = {
+        id: feature.id,
+        name: feature.name,
+        icon: feature.icon,
+        definition: feature.definition,
+        values: {},
+      };
+      byId.set(feature.id, entry);
+      features.push(entry);
+    }
+  }
+
+  for (const entry of features) {
+    let inherited = null;
+    for (const plan of plans) {
+      const own = plan.features.find((feature) => feature.id === entry.id);
+      if (own) inherited = own.value !== null ? own.value : true;
+      entry.values[plan.id] = own ? (own.value !== null ? own.value : true) : inherited;
+    }
+  }
+
+  return { features: features };
+}
+
+/**
+ * The catalog a page may show: `hidden: true` is presentation-only (#348), so
+ * it drops here ONCE and every reader — the composer below, the `omega build`
+ * empty-catalog warning — asks this one question.
+ * @param {object} payment - resolved config `payment` section
+ * @returns {Array<object>} the non-hidden products, in catalog order
+ */
+function visibleProducts(payment) {
+  const catalog = payment && Array.isArray(payment.products) ? payment.products : [];
+  return catalog.filter((product) => product.hidden !== true);
+}
+
+/**
+ * Compose the pricing view-model from the shared payment section and the
+ * features catalog.
+ * @param {object} payment - resolved config `payment` section
+ * @param {object} [features] - resolved config `features` catalog (#647)
+ * @returns {object|null} { plans, oneTime, enterprise, billing, savingsPercent, comparison } or null when the catalog is empty
+ */
+function composePricing(payment, features) {
+  // Every lane below composes from what the page may show (a catalog of
+  // nothing else renders the empty state)
+  const products = visibleProducts(payment);
+  if (products.length === 0) return null;
+
+  // The one home of what a feature IS. A brand with products but no catalog
+  // renders cards with no bullets rather than inventing copy for them.
+  const catalog = (features && typeof features === 'object' && !Array.isArray(features)) ? features : {};
+
+  // The enterprise tier is a product like any other, marked `enterprise: true`
+  // — it leaves the grid so the cards stay peers of each other
+  const enterpriseProduct = products.find((product) => product.enterprise === true);
+  const enterprise = enterpriseProduct ? composeEnterprise(enterpriseProduct, catalog) : null;
+
+  const plans = products
+    .filter((product) => (product.type || 'subscription') === 'subscription' && product.enterprise !== true)
+    .map((product) => composePlan(product, catalog));
+
+  const oneTime = products
+    .filter((product) => product.type === 'one-time' && product.enterprise !== true)
+    .map((product) => ({
+      id: product.id,
+      name: product.name,
+      tagline: product.tagline || null,
+      price: (product.prices && typeof product.prices.once === 'number') ? product.prices.once : 0,
+      features: composeFeatures(product, catalog),
+    }));
+
+  // The comparison inherits feature values by catalog position (tiers
+  // accumulate), so `payment.products` must be authored lowest tier first —
+  // warn when prices are non-monotonic instead of silently composing a
+  // wrong matrix.
+  for (let i = 1; i < plans.length; i++) {
+    const prev = plans[i - 1].prices;
+    const curr = plans[i].prices;
+    const prevRank = prev.monthly || prev.annually;
+    const currRank = curr.monthly || curr.annually;
+    if (currRank < prevRank) {
+      logger.warn(`payment.products lists "${plans[i].id}" after the pricier "${plans[i - 1].id}" — the comparison matrix inherits values by catalog order (lowest tier first); reorder the catalog.`);
+    }
+  }
+
+  splitCommonFeatures(plans);
+
+  // Billing toggle only exists when both cadences are actually purchasable
+  const billing = {
+    monthly: plans.some((plan) => plan.prices.monthly > 0),
+    annually: plans.some((plan) => plan.prices.annually > 0),
+  };
+
+  // Honest annual-savings badge: the best real discount across paid plans
+  let savingsPercent = 0;
+  for (const plan of plans) {
+    if (plan.prices.monthly > 0 && plan.prices.annually > 0) {
+      const percent = Math.round((1 - plan.prices.annually / (plan.prices.monthly * 12)) * 100);
+      if (percent > savingsPercent) savingsPercent = percent;
+    }
+  }
+
+  // The catalog's trial, as ONE number the page can speak (#273). The copy it
+  // feeds is UNIVERSAL ("every paid plan starts with a N-day free trial"), so
+  // the number only exists when every paid plan agrees on it: a catalog whose
+  // paid plans carry different trials (or one without a trial at all) speaks
+  // no universal number → 0, and trial copy renders nowhere, exactly like a
+  // catalog with no trial. Free plans carry nothing to disagree with, and the
+  // per-plan `plan.trialDays` still states each plan's own truth.
+  const paidPlans = plans.filter((plan) => !plan.free);
+  const trialDays = paidPlans.length > 0 && paidPlans.every((plan) => plan.trialDays === paidPlans[0].trialDays)
+    ? paidPlans[0].trialDays
+    : 0;
+
+  return {
+    plans: plans,
+    oneTime: oneTime,
+    enterprise: enterprise,
+    billing: billing,
+    savingsPercent: savingsPercent,
+    trialDays: trialDays,
+    comparison: composeComparison(plans),
+  };
+}
+
+module.exports = { composePricing, visibleProducts };

package/dist/purge.js

@@ -0,0 +1,95 @@
+/**
+ * Cloudflare cache purge — the UJM cloudflare-purge successor, de-ITW'd:
+ * legacy proxied through the hardcoded ITW wrapper API (which held the
+ * token server-side); this talks to the Cloudflare API directly with the
+ * BRAND's own CLOUDFLARE_TOKEN from the .env cascade.
+ *
+ * Zone resolution: config `edge.providers.cloudflare.zone` wins;
+ * otherwise the zone is looked up by the brand URL's apex domain. No token
+ * → a clean skip (machine-readable), never a failure — purging is a
+ * post-deploy nicety, not a gate.
+ */
+const fetch = require('wonderful-fetch');
+
+const API = 'https://api.cloudflare.com/client/v4';
+
+/**
+ * The apex domain of a site URL: playground.omegajs.dev → omegajs.dev.
+ * Multi-label TLDs aren't handled (none of ours) — config `edge.providers.cloudflare.zone`
+ * is the override for exotic zones.
+ * @param {string} url
+ * @returns {string|null}
+ */
+function apexOf(url) {
+  const host = String(url || '').replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+  const labels = host.split('.').filter(Boolean);
+  if (labels.length < 2) {
+    return null;
+  }
+  return labels.slice(-2).join('.');
+}
+
+/**
+ * Purge the site's Cloudflare zone cache (purge_everything).
+ *
+ * @param {object} options
+ * @param {object} options.config - resolved web config (edge.providers.cloudflare.zone, brand.url)
+ * @param {string} [options.token] - Cloudflare API token (default: env CLOUDFLARE_TOKEN)
+ * @param {boolean} [options.dryRun] - resolve + plan, send nothing
+ * @param {function} [options.fetcher] - injection point for tests (default: wonderful-fetch)
+ * @returns {Promise<{ status: 'purged'|'planned'|'skipped', reason?: string, zone?: string, zoneName?: string }>}
+ */
+async function purgeZoneCache(options) {
+  const { config, dryRun = false, fetcher = fetch } = options;
+  const token = options.token !== undefined ? options.token : process.env.CLOUDFLARE_TOKEN;
+
+  if (!token) {
+    return { status: 'skipped', reason: 'no CLOUDFLARE_TOKEN in the env cascade' };
+  }
+
+  const headers = { Authorization: `Bearer ${token}` };
+
+  // Zone id: explicit config wins; otherwise look it up by apex domain
+  let zone = config.edge && config.edge.providers && config.edge.providers.cloudflare && config.edge.providers.cloudflare.zone;
+  let zoneName = null;
+  if (!zone) {
+    const apex = apexOf(config.brand && config.brand.url);
+    if (!apex) {
+      return { status: 'skipped', reason: 'no edge.providers.cloudflare.zone in config and no brand.url to derive the zone from' };
+    }
+    const lookup = await fetcher(`${API}/zones?name=${apex}`, { method: 'get', response: 'json', headers });
+    const match = lookup && lookup.result && lookup.result[0];
+    if (!match) {
+      return { status: 'skipped', reason: `no Cloudflare zone named ${apex} visible to this token` };
+    }
+    zone = match.id;
+    zoneName = match.name;
+  }
+
+  if (dryRun) {
+    return { status: 'planned', zone, zoneName };
+  }
+
+  const result = await fetcher(`${API}/zones/${zone}/purge_cache`, {
+    method: 'post',
+    response: 'json',
+    headers,
+    body: { purge_everything: true },
+  });
+
+  if (!result || result.success !== true) {
+    const errors = (result && result.errors) || [];
+    const detail = errors.length ? JSON.stringify(errors) : 'unknown error';
+    // Code 10000 on purge_cache with a token that could READ the zone =
+    // missing permission (DNS-scoped tokens hit this — the exact live
+    // rehearsal failure): purging needs Zone → Cache Purge → Purge.
+    const hint = errors.some((error) => error.code === 10000)
+      ? ' — the token lacks the Cache Purge permission: edit it at https://dash.cloudflare.com/profile/api-tokens and add Zone → Cache Purge → Purge'
+      : '';
+    throw new Error(`Cloudflare purge failed: ${detail}${hint}`);
+  }
+
+  return { status: 'purged', zone, zoneName };
+}
+
+module.exports = { purgeZoneCache, apexOf };

package/dist/redirect-page.js

@@ -0,0 +1,45 @@
+/**
+ * The ONE shape of a GENERATED redirect page (#429 socials, #561 download and
+ * extension shortlinks). Legacy UJM hand-maintained these as default pages in
+ * `src/defaults/dist/redirects/**`; here they are source strings registered as
+ * virtual templates on the same lane as the framework's default pages
+ * (engine.js), so they ride `modules/utilities/redirect` (noindex +
+ * sitemap-excluded by the layout) and a consumer page at the same permalink
+ * takes that URL over.
+ *
+ * A brand never hand-writes one: the config block IS the declaration.
+ */
+
+// A YAML double-quoted scalar (the dynamic-pages spelling).
+const yaml = (value) => JSON.stringify(String(value));
+
+/**
+ * One generated redirect page.
+ * @param {object} page
+ * @param {string} page.virtual - the virtual template path (its identity in the build)
+ * @param {string} page.label - what generated it, for logs and collision reports
+ * @param {string} page.url - the permalink
+ * @param {string} page.redirect - where it sends the visitor
+ * @param {string} page.note - the source comment written into the page
+ * @returns {{ virtual: string, label: string, url: string, raw: string }}
+ */
+function redirectPage({ virtual, label, url, redirect, note }) {
+  return {
+    virtual,
+    label,
+    url,
+    raw: [
+      '---',
+      'layout: modules/utilities/redirect',
+      `permalink: ${url}`,
+      '',
+      `# ${note}`,
+      'redirect:',
+      `  url: ${yaml(redirect)}`,
+      '---',
+      '',
+    ].join('\n'),
+  };
+}
+
+module.exports = { redirectPage };

package/dist/sample-content.js

@@ -0,0 +1,210 @@
+/**
+ * Sample content (spec §8): the shared filler that keeps a content-less brand
+ * alive in development — posts, teammates, updates. One corpus for every
+ * theme, auto-generated with ROLLING dates: each file's authored date is a
+ * rhythm relative to SAMPLE_EPOCH_UTC, and generation re-anchors that rhythm
+ * to "now" (or an explicit anchor), so a virgin blog always looks alive —
+ * never "6 months stale". `omega dev` also materializes the generated set
+ * under the target's gitignored `.omega/sample-content/` so humans can read and
+ * copy the files; the tree is machine-owned and regenerated every boot.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const reads = require('./vendor/devkit/reads.js');
+
+// The day the sample corpus dates were authored against (spec §8 ruling,
+// Ian 2026-07-18). Anchor === epoch reproduces the authored dates exactly —
+// the determinism pin the test harness uses.
+const SAMPLE_EPOCH_UTC = Date.UTC(2026, 6, 18);
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+// Collection dir (consumer + injection lane) ↔ packaged corpus dir.
+const SAMPLE_SETS = [
+  { collectionDir: '_posts', samplesDir: 'sample-posts' }, // the blog (11 posts — enough to exercise pagination at size 6)
+  { collectionDir: '_team', samplesDir: 'sample-team' }, // the /team portrait grid + member pages
+  { collectionDir: '_updates', samplesDir: 'sample-updates' }, // the /updates release feed
+];
+
+/**
+ * Parse a YYYY-MM-DD string to a UTC-midnight timestamp.
+ * @param {string} value
+ * @returns {number}
+ */
+function parseDay(value) {
+  const [year, month, day] = value.split('-').map(Number);
+  return Date.UTC(year, month - 1, day);
+}
+
+/**
+ * Format a UTC timestamp as YYYY-MM-DD.
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatDay(ms) {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+/**
+ * Resolve the rolling-date anchor (UTC-midnight ms). Precedence: explicit
+ * option > OMEGA_SAMPLE_ANCHOR env (the harness determinism pin) > today.
+ * @param {string} [explicit] - YYYY-MM-DD
+ * @returns {number}
+ */
+function resolveAnchor(explicit) {
+  const value = explicit || process.env.OMEGA_SAMPLE_ANCHOR;
+  if (!value) {
+    const now = new Date();
+    return Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  }
+  if (!DATE_RE.test(value)) {
+    throw new Error(`Invalid sample-content anchor "${value}" — expected YYYY-MM-DD`);
+  }
+  return parseDay(value);
+}
+
+/**
+ * Shift a YYYY-MM-DD string by the anchor's offset from the corpus epoch.
+ * @param {string} value
+ * @param {number} anchorMs
+ * @returns {string}
+ */
+function shiftDay(value, anchorMs) {
+  return formatDay(parseDay(value) + (anchorMs - SAMPLE_EPOCH_UTC));
+}
+
+/**
+ * Roll one corpus file: date-prefixed filenames shift (posts — Eleventy reads
+ * page.date from the prefix), `date: YYYY-MM-DD` lines inside the frontmatter
+ * block shift (updates), a generated-content header comment lands inside
+ * the frontmatter (inert in YAML, never rendered), and the `generated: true`
+ * marker lands with it — the RENDER-visible half (#208), which templates key
+ * the TEST badge off so filler can never be mistaken for the brand's own
+ * writing on screen. It rides the generator, never the corpus files, so every
+ * sample document carries it and no fixture can forget to.
+ * @param {string} name - corpus filename
+ * @param {string} content - corpus file content
+ * @param {number} anchorMs
+ * @param {string} collectionDir - for the header's "real files" hint
+ * @returns {{ name: string, content: string }}
+ */
+function rollFile(name, content, anchorMs, collectionDir) {
+  const dated = name.match(/^(\d{4}-\d{2}-\d{2})-(.*)$/);
+  const outName = dated ? `${shiftDay(dated[1], anchorMs)}-${dated[2]}` : name;
+
+  let outContent = content;
+  const fmEnd = content.startsWith('---\n') ? content.indexOf('\n---', 4) : -1;
+  if (fmEnd !== -1) {
+    const header = '# Generated sample content (@omega.js/web) — dates roll with each dev build.\n'
+      + `# Do not edit: real files in ${collectionDir}/ replace this whole set.\n`
+      + 'generated: true\n';
+    const frontmatter = content
+      .slice(4, fmEnd)
+      .replace(/^(\s*date: )(\d{4}-\d{2}-\d{2})$/gm, (_, prefix, day) => `${prefix}${shiftDay(day, anchorMs)}`);
+    outContent = `---\n${header}${frontmatter}${content.slice(fmEnd)}`;
+  }
+  return { name: outName, content: outContent };
+}
+
+/**
+ * Generate one sample set from the packaged corpus with dates re-anchored.
+ * @param {string} defaultsDir - the package defaults/ root
+ * @param {{ collectionDir: string, samplesDir: string }} set
+ * @param {number} anchorMs
+ * @returns {Array<{ name: string, content: string }>}
+ */
+function generateSampleSet(defaultsDir, set, anchorMs) {
+  const dir = path.join(defaultsDir, set.samplesDir);
+  // Through the captured-read helper (#200): configureOmega generates the sets
+  // at config time, so the corpus dir becomes a dev config-reset target. The
+  // boot-phase caller (reconcileSampleContent) runs outside a capture scope,
+  // where the same reads record nothing.
+  return reads.readdir(dir)
+    .filter((name) => name.endsWith('.md'))
+    .sort()
+    .map((name) => rollFile(name, reads.read(path.join(dir, name)), anchorMs, set.collectionDir));
+}
+
+/**
+ * Does the consumer have any file of their own in a collection dir?
+ * Recursive — Jekyll-style year subfolders (_posts/2024/…) count. Dotfiles
+ * don't.
+ *
+ * Reads through the captured-read helper as a RESCAN capture (#200 Lane B):
+ * the collection dirs are where the brand's real content lands, so they must
+ * never become config-reset targets — the answer is re-scanned and the sample
+ * injection gate consults it at render time. Config-time callers wrap this in
+ * `reads.rescan(...)` (src/decisions.js); the boot-phase caller
+ * (reconcileSampleContent) runs outside a capture scope and records nothing.
+ * @param {string} consumerDir
+ * @param {string} collectionDir - collection folder name ('_posts', '_team')
+ * @returns {boolean}
+ */
+function hasOwnContent(consumerDir, collectionDir) {
+  const root = path.join(consumerDir, collectionDir);
+  if (!reads.dirExists(root)) return false;
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const entry of reads.readdir(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      if (entry.isDirectory()) stack.push(path.join(dir, entry.name));
+      else if (entry.isFile()) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Materialize the generated sets under `<targetRoot>/.omega/sample-content/` —
+ * the gitignored test path (spec §8). Idempotent: each active collection is
+ * rebuilt wholesale, collections the consumer owns are removed, and the tree
+ * carries a self-`.gitignore` so it can never be committed regardless of the
+ * target's own ignore rules. Never mixed with real brand content.
+ * @param {object} options
+ * @param {string} options.targetRoot - the target root (owns .omega/)
+ * @param {string} options.consumerDir - the site src dir (own-content checks)
+ * @param {string} options.defaultsDir - the package defaults/ root
+ * @param {string} [options.anchor] - YYYY-MM-DD anchor override
+ * @returns {{ root: string, written: string[], removed: string[] }}
+ */
+function reconcileSampleContent(options) {
+  const root = path.join(options.targetRoot, '.omega', 'sample-content');
+  const anchorMs = resolveAnchor(options.anchor);
+  const written = [];
+  const removed = [];
+
+  for (const set of SAMPLE_SETS) {
+    const target = path.join(root, set.collectionDir);
+    if (hasOwnContent(options.consumerDir, set.collectionDir)) {
+      if (fs.existsSync(target)) {
+        fs.rmSync(target, { recursive: true, force: true });
+        removed.push(set.collectionDir);
+      }
+      continue;
+    }
+    fs.rmSync(target, { recursive: true, force: true });
+    fs.mkdirSync(target, { recursive: true });
+    for (const { name, content } of generateSampleSet(options.defaultsDir, set, anchorMs)) {
+      fs.writeFileSync(path.join(target, name), content);
+      written.push(path.join(set.collectionDir, name));
+    }
+  }
+
+  if (written.length) {
+    fs.writeFileSync(path.join(root, '.gitignore'), '*\n');
+  } else if (fs.existsSync(root)) {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+  return { root, written, removed };
+}
+
+module.exports = {
+  SAMPLE_EPOCH_UTC,
+  SAMPLE_SETS,
+  resolveAnchor,
+  generateSampleSet,
+  hasOwnContent,
+  reconcileSampleContent,
+};