@omega.js/extension 0.1.0

package/dist/vendor/account/schema.js

@@ -0,0 +1,272 @@
+/**
+ * USER_SCHEMA — the canonical OMEGA user/account schema (pure data, no logic).
+ *
+ * Extracted verbatim from @omega.js/backend's src/manager/helpers/user.js, which is
+ * the authoritative shape (@omega.js/client's DEFAULT_ACCOUNT had drifted from it).
+ *
+ * Each leaf field is { type, default, nullable }
+ * Special keys:
+ *   $passthrough  — preserve all existing keys from input, don't strip unknowns
+ *   $template     — shape applied to every dynamic key in a $passthrough object
+ *   '$template'   — (string value) reference to parent's $template
+ *   '$timestamp'  — shorthand for { timestamp, timestampUNIX } defaulting to epoch
+ *   '$timestamp:now' — same but defaults to current time
+ *   '$uuid', '$randomId', '$apiKey', '$oldDate' — resolved at runtime (generators
+ *   are injected by the host — see engine.js; absent generators resolve to null)
+ */
+
+/**
+ * One attribution TOUCH — a single visit's campaign context, shared by
+ * `attribution.first` and `attribution.last`
+ * ([#384](https://github.com/Omega-JS-Stack/omega/issues/384)). `tags` holds the
+ * utm set and `clickIds` the ad-platform click ids (fbclid/gclid/…), both
+ * passthrough because the platforms keep adding params. The schema is read-only
+ * to the engine, so one object serves both slots.
+ */
+const ATTRIBUTION_TOUCH = {
+  tags: { $passthrough: true },
+  clickIds: { $passthrough: true },
+  referrer: { type: 'string', default: null, nullable: true },
+  url: { type: 'string', default: null, nullable: true },
+  page: { type: 'string', default: null, nullable: true },
+  timestamp: { type: 'string', default: null, nullable: true },
+};
+
+const USER_SCHEMA = {
+  auth: {
+    uid: { type: 'string', default: null, nullable: true },
+    email: { type: 'string', default: null, nullable: true },
+    temporary: { type: 'boolean', default: false },
+  },
+  subscription: {
+    product: {
+      id: { type: 'string', default: 'basic' },
+      name: { type: 'string', default: 'Basic' },
+    },
+    status: { type: 'string', default: 'active' },
+    expires: '$timestamp',
+    trial: {
+      claimed: { type: 'boolean', default: false },
+      expires: '$timestamp',
+      // How the trial ENDED: 'converted' | 'lapsed' | null (still running, or never
+      // answered). `claimed` says only that a trial happened — a converted trial and a
+      // lapsed one carry identical dates — so this is the one stored conversion signal.
+      // Stamped by the trial-lapse sweep once the provider confirms which it was.
+      outcome: { type: 'string', default: null, nullable: true },
+    },
+    cancellation: {
+      pending: { type: 'boolean', default: false },
+      date: '$timestamp',
+    },
+    payment: {
+      provider: { type: 'string', default: null, nullable: true },
+      orderId: { type: 'string', default: null, nullable: true },
+      resourceId: { type: 'string', default: null, nullable: true },
+      frequency: { type: 'string', default: null, nullable: true },
+      price: { type: 'number', default: 0 },
+      startDate: '$timestamp',
+      updatedBy: {
+        event: {
+          name: { type: 'string', default: null, nullable: true },
+          id: { type: 'string', default: null, nullable: true },
+        },
+        date: '$timestamp',
+      },
+    },
+    // The discount riding the subscription right now
+    // ([#325](https://github.com/Omega-JS-Stack/omega/issues/325)). Shaped as a
+    // discount-codes validate() RESULT — the one shape the whole payment stack
+    // already speaks — so the billing card reads exactly what the apply route
+    // wrote, and neither side learns a second spelling. `valid: false` (the
+    // default) IS "no discount": absent and denied read the same everywhere.
+    //
+    // Both shapes are always present and default to 0, unlike a fresh validate()
+    // result which omits the one it is not: this node is MERGED onto a document
+    // that may already carry a discount, and a percent claim landing on a stored
+    // amount would otherwise be read as the older, wrong number.
+    //
+    // `source` is what makes it safe to read as a CLAIM. Today only the winback
+    // claim writes this node; a code typed at checkout will set the same node
+    // when checkout starts writing it, and a winback pitch suppressed by someone
+    // else's promo is an offer silently withheld — so the node says which system
+    // applied it ('winback' | 'checkout'), and only 'winback' is the claimed
+    // signal the cancel flow gates on.
+    //
+    // `resourceId` is the subscription the discount was applied TO, stamped at
+    // claim time ([#333](https://github.com/Omega-JS-Stack/omega/issues/333)).
+    // It is what makes the node clearable: the unified webhook write carries no
+    // discount key, so a merge preserves this node forever, and a customer who
+    // churned and resubscribed carried a spent claim into the NEW subscription,
+    // where `source: 'winback'` reads as "already claimed" and silently retires
+    // an offer the backend would grant again. The webhook pipeline compares the
+    // stamp against the subscription each event is about and CLEARS the node
+    // (back to these defaults) on a mismatch: a new subscription is a clean
+    // slate. An unstamped node (written before the stamp existed) is read as
+    // belonging to the subscription it is found on, because nothing can prove
+    // otherwise and no live discount is ever taken away on a guess, and the
+    // pipeline stamps it there, so it clears on the next resubscribe like any
+    // other.
+    discount: {
+      valid: { type: 'boolean', default: false },
+      code: { type: 'string', default: null, nullable: true },
+      percent: { type: 'number', default: 0 },
+      amount: { type: 'number', default: 0 },
+      duration: { type: 'string', default: null, nullable: true },
+      source: { type: 'string', default: null, nullable: true },
+      resourceId: { type: 'string', default: null, nullable: true },
+    },
+  },
+  roles: {
+    $passthrough: true,
+    admin: { type: 'boolean', default: false },
+    betaTester: { type: 'boolean', default: false },
+    developer: { type: 'boolean', default: false },
+  },
+  flags: {
+    $passthrough: true,
+    signupProcessed: { type: 'boolean', default: false },
+  },
+  affiliate: {
+    code: { type: 'string', default: '$randomId' },
+    referrals: { type: 'array', default: [] },
+  },
+  metadata: {
+    created: '$timestamp:now',
+    updated: '$timestamp:now',
+  },
+  activity: {
+    geolocation: {
+      ip: { type: 'string', default: null, nullable: true },
+      continent: { type: 'string', default: null, nullable: true },
+      country: { type: 'string', default: null, nullable: true },
+      region: { type: 'string', default: null, nullable: true },
+      city: { type: 'string', default: null, nullable: true },
+      latitude: { type: 'number', default: 0 },
+      longitude: { type: 'number', default: 0 },
+    },
+    client: {
+      language: { type: 'string', default: null, nullable: true },
+      mobile: { type: 'boolean', default: false },
+      device: { type: 'string', default: null, nullable: true },
+      platform: { type: 'string', default: null, nullable: true },
+      browser: { type: 'string', default: null, nullable: true },
+      vendor: { type: 'string', default: null, nullable: true },
+      runtime: { type: 'string', default: null, nullable: true },
+      userAgent: { type: 'string', default: null, nullable: true },
+      url: { type: 'string', default: null, nullable: true },
+    },
+  },
+  api: {
+    clientId: { type: 'string', default: '$uuid' },
+    privateKey: { type: 'string', default: '$apiKey' },
+  },
+  // The documents this account owns, by KIND: `{ teams: ['team-abc'] }`
+  // ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)). A counted
+  // feature's catalog entry names the kinds its counters mirror onto
+  // (`usage: { mirror: ['teams'] }`), and this is what resolves a kind to real
+  // document paths — so a mirror is declared once in config instead of
+  // re-derived at every call site. Server-written like `usage`: a client that
+  // could write it could point another account's counters at its own doc.
+  owns: {
+    $passthrough: true,
+  },
+  usage: {
+    $passthrough: true,
+    // Admin-granted extra credits, feature id → number
+    // ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)). Declared
+    // HERE so the sibling `$template` never resolves it as a counter block:
+    // it is a map of limits, not a map of counts. `usage` is a framework field
+    // the security rules deny every client, so an override can only ever be
+    // server-written — which is what makes it trustworthy as a limit.
+    overrides: { $passthrough: true },
+    $template: {
+      monthly: { type: 'number', default: 0 },
+      daily: { type: 'number', default: 0 },
+      total: { type: 'number', default: 0 },
+      // When the counter last moved. The old `id` field went with the retired
+      // `increment(name, value, { id })` option (#647): nothing writes it now,
+      // and a schema field nothing fills reads as a fact that is always null.
+      last: {
+        timestamp: { type: 'string', default: '$oldDate' },
+        timestampUNIX: { type: 'number', default: 0 },
+      },
+    },
+  },
+  personal: {
+    birthday: '$timestamp',
+    gender: { type: 'string', default: null, nullable: true },
+    location: {
+      country: { type: 'string', default: null, nullable: true },
+      region: { type: 'string', default: null, nullable: true },
+      city: { type: 'string', default: null, nullable: true },
+      postalCode: { type: 'string', default: null, nullable: true },
+      street: { type: 'string', default: null, nullable: true },
+    },
+    name: {
+      first: { type: 'string', default: null, nullable: true },
+      last: { type: 'string', default: null, nullable: true },
+    },
+    company: {
+      name: { type: 'string', default: null, nullable: true },
+      position: { type: 'string', default: null, nullable: true },
+    },
+    telephone: {
+      countryCode: { type: 'number', default: 0 },
+      national: { type: 'number', default: 0 },
+    },
+  },
+  connections: {
+    $passthrough: true,
+  },
+  attribution: {
+    affiliate: {
+      code: { type: 'string', default: null, nullable: true },
+      timestamp: { type: 'string', default: null, nullable: true },
+      url: { type: 'string', default: null, nullable: true },
+      page: { type: 'string', default: null, nullable: true },
+    },
+    // The touch model: `first` is the visit that first brought the user here,
+    // written once and never overwritten; `last` is the newest TAGGED visit. No
+    // expiry — the timestamps carry any read-time lookback window. Replaces the
+    // single `utm` blob outright (no dual-read).
+    first: ATTRIBUTION_TOUCH,
+    last: ATTRIBUTION_TOUCH,
+  },
+  // The tracking-consent snapshot the client captured, stored verbatim: passthrough
+  // because this layer never interprets it — the consent module owns its shape. NOT
+  // the same thing as `consent` below, which is the legal/marketing decision.
+  trackingConsent: {
+    $passthrough: true,
+  },
+  consent: {
+    legal: {
+      status: { type: 'string', default: 'revoked' },
+      grantedAt: {
+        timestamp: { type: 'string', default: null, nullable: true },
+        timestampUNIX: { type: 'number', default: null, nullable: true },
+        source: { type: 'string', default: null, nullable: true },
+        ip: { type: 'string', default: null, nullable: true },
+        text: { type: 'string', default: null, nullable: true },
+      },
+    },
+    marketing: {
+      status: { type: 'string', default: 'revoked' },
+      grantedAt: {
+        timestamp: { type: 'string', default: null, nullable: true },
+        timestampUNIX: { type: 'number', default: null, nullable: true },
+        source: { type: 'string', default: null, nullable: true },
+        ip: { type: 'string', default: null, nullable: true },
+        text: { type: 'string', default: null, nullable: true },
+      },
+      revokedAt: {
+        timestamp: { type: 'string', default: null, nullable: true },
+        timestampUNIX: { type: 'number', default: null, nullable: true },
+        source: { type: 'string', default: null, nullable: true },
+        ip: { type: 'string', default: null, nullable: true },
+        text: { type: 'string', default: null, nullable: true },
+      },
+    },
+  },
+};
+
+module.exports = USER_SCHEMA;

package/dist/vendor/account/subscription.js

@@ -0,0 +1,38 @@
+/**
+ * resolveSubscription — extracted verbatim from @omega.js/backend's User.resolveSubscription
+ * (the superset: @omega.js/client's drifted copy lacked `everPaid`).
+ *
+ * Resolves calculated subscription fields that require derivation logic.
+ * Raw data (product.id, status, trial, cancellation) is on the account directly.
+ * Returns: { plan, active, trialing, cancelling, everPaid }
+ * - plan: the plan ID the user effectively has access to RIGHT NOW ('basic' if cancelled/suspended)
+ * - active: user has active access (active, trialing, or cancelling)
+ * - trialing: user is in an active trial (status is 'active' but trial hasn't expired)
+ * - cancelling: cancellation is pending (status is 'active' but cancellation.pending is true)
+ * - everPaid: user has had a paid subscription at some point (payment.startDate exists)
+ */
+function resolveSubscription(account) {
+  const subscription = (account?.subscription || account?.properties?.subscription) || {};
+  const productId = subscription.product?.id || 'basic';
+
+  let trialing = false;
+  let cancelling = false;
+
+  if (productId !== 'basic' && subscription.status === 'active') {
+    trialing = !!(subscription.trial?.claimed
+      && subscription.trial?.expires?.timestampUNIX > Math.floor(Date.now() / 1000));
+    cancelling = !trialing && !!subscription.cancellation?.pending;
+  }
+
+  const active = (productId !== 'basic' && subscription.status === 'active');
+
+  return {
+    plan: active ? productId : 'basic',
+    active,
+    trialing,
+    cancelling,
+    everPaid: (subscription.payment?.startDate?.timestampUNIX || 0) > 0,
+  };
+}
+
+module.exports = resolveSubscription;

package/dist/vendor/config/company.js

@@ -0,0 +1,31 @@
+/**
+ * The company layer's ONE discovery rule.
+ *
+ * A brand managed by a company workspace carries `.omega/company.json` at its
+ * root (stamped idempotently by company manage runs) pointing at the company
+ * root. Everything that cascades — the config chain (load.js), the .env chain
+ * (env.js), owner hooks (hooks.js) — resolves the company root through here,
+ * so the stamp is read exactly one way.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// A brand's pointer at its company root.
+const COMPANY_MARKER = path.join('.omega', 'company.json');
+
+/**
+ * The company root a brand points at via its .omega/company.json marker.
+ * @param {string} brandRoot
+ * @returns {string|null} Absolute company root, or null when unstamped/unreadable.
+ */
+function readCompanyRoot(brandRoot) {
+  try {
+    const marker = JSON.parse(fs.readFileSync(path.join(brandRoot, COMPANY_MARKER), 'utf8'));
+    return typeof marker.root === 'string' && marker.root ? marker.root : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { readCompanyRoot, COMPANY_MARKER };

package/dist/vendor/config/defaults.js

@@ -0,0 +1,173 @@
+/**
+ * Schema-derived defaults — the ONE home of every config default
+ * ([#478](https://github.com/Omega-JS-Stack/omega/issues/478)).
+ *
+ * Defaults used to be scattered: a per-framework `options.defaults` blob, the
+ * manager's DEFAULTS layer, read-site fallbacks, and prose in the schema
+ * descriptions. Now a schema entry declares its own `default:` and everything
+ * derives from that:
+ *
+ *   - `schemaDefaults(target)` builds the merge chain's LOWEST layer
+ *     (load.js). A framework still passes `options.defaults` on top, but only
+ *     where that framework genuinely differs from the schema answer.
+ *   - `missingDefaults(config)` names the blocks a brand's omega.json5 has yet
+ *     to materialize — the manage walk writes exactly those, with each block's
+ *     schema description as its guiding comment, and never touches a key the
+ *     brand already authored (a new subsystem simply appears on the next run).
+ *
+ * A key with no sane framework answer carries no `default:` and is never
+ * materialized: owner decisions, tri-states that mean "ask", ids the services
+ * provision, anything secret-shaped (secrets live in .env regardless).
+ *
+ * A rule may also carry `materialize: false`
+ * ([#793](https://github.com/Omega-JS-Stack/omega/issues/793)): its `default:`
+ * still RESOLVES (schemaDefaults, so every reader sees the value) but is never
+ * WRITTEN into a brand's file. That is for framework facts a brand may override
+ * and rarely does — presentation the framework owns — where a copy in every
+ * brand config is a copy that drifts from the thing it came from.
+ */
+
+const { SHARED_SCHEMA, TARGET_SCHEMAS } = require('./schema.js');
+const { isPlainObject } = require('./merge.js');
+
+function hasDefault(rule) {
+  return Object.prototype.hasOwnProperty.call(rule, 'default');
+}
+
+/**
+ * Whether a rule's default is WRITTEN into a brand's file, not merely resolved
+ * ([#793](https://github.com/Omega-JS-Stack/omega/issues/793)). `materialize:
+ * false` means resolution-only: the fact stays at the layer that owns it.
+ * @param {object} rule
+ * @returns {boolean}
+ */
+function isMaterialized(rule) {
+  return rule.materialize !== false;
+}
+
+/**
+ * The rules that carry a default: SHARED_SCHEMA always, plus that target's
+ * refinements (they overlay the same top-level namespace loadConfig resolves).
+ * @param {string} [target] - Canonical target name ('web', 'backend', ...).
+ * @returns {object[]}
+ */
+function defaultRules(target) {
+  const rules = target && TARGET_SCHEMAS[target]
+    ? [...SHARED_SCHEMA, ...TARGET_SCHEMAS[target]]
+    : SHARED_SCHEMA;
+
+  return rules.filter(hasDefault);
+}
+
+function setAtPath(target, dotted, value) {
+  const names = dotted.split('.');
+  const leaf = names.pop();
+  let node = target;
+
+  for (const name of names) {
+    if (!isPlainObject(node[name])) node[name] = {};
+    node = node[name];
+  }
+
+  node[leaf] = value;
+}
+
+/**
+ * The default config a brand that authors nothing gets — every schema
+ * `default:` at its own dot-path. A fresh deep copy per call: a caller that
+ * mutates the result can never reach back into the schema.
+ * @param {string} [target] - Canonical target name; adds that target's refinements.
+ * @returns {object}
+ */
+function schemaDefaults(target) {
+  return defaultsFrom(defaultRules(target));
+}
+
+/**
+ * The default config a given rule set describes — every `default:` at its own
+ * dot-path, deep-copied per call.
+ * @param {object[]} rules - Rules that carry a default.
+ * @returns {object}
+ */
+function defaultsFrom(rules) {
+  const defaults = {};
+
+  for (const rule of rules) {
+    setAtPath(defaults, rule.path, structuredClone(rule.default));
+  }
+
+  return defaults;
+}
+
+/**
+ * The guiding comments a materialized block travels with: dot-path →
+ * description, for every defaulted key and for the container entries above
+ * them (a `marketing` block insert is documented, and so is each key it
+ * carries). The editor writes a comment only where it INSERTS that path, so
+ * the map covers the whole default set and the file gets what it lacks.
+ *
+ * @param {string} [target] - Canonical target name; adds that target's refinements.
+ * @returns {Object<string, string>}
+ */
+function defaultComments(target) {
+  const rules = target && TARGET_SCHEMAS[target]
+    ? [...SHARED_SCHEMA, ...TARGET_SCHEMAS[target]]
+    : SHARED_SCHEMA;
+
+  const defaulted = rules.filter(hasDefault).filter(isMaterialized).map((rule) => rule.path);
+  const comments = {};
+
+  for (const rule of rules) {
+    const documents = defaulted.some((dotted) => dotted === rule.path || dotted.startsWith(`${rule.path}.`));
+    if (documents && rule.description) {
+      comments[rule.path] = rule.description;
+    }
+  }
+
+  return comments;
+}
+
+function collectMissing(defaults, present, prefix, target, found) {
+  for (const [key, value] of Object.entries(defaults)) {
+    const dotted = prefix ? `${prefix}.${key}` : key;
+    const authored = isPlainObject(present) && Object.prototype.hasOwnProperty.call(present, key);
+
+    if (!authored) {
+      found.push({ path: dotted, value });
+      continue;
+    }
+
+    // Present and still a container on both sides → look for holes inside it.
+    // A brand that authored anything else at this path (a scalar, false, null)
+    // made a decision: never dive in, never overwrite.
+    if (isPlainObject(value) && isPlainObject(present[key])) {
+      collectMissing(value, present[key], dotted, target, found);
+    }
+  }
+
+  return found;
+}
+
+/**
+ * The schema-defaulted blocks a config does not carry yet, each at the HIGHEST
+ * path that is missing (a brand with no `marketing` at all gets one
+ * `marketing` block, not one edit per key inside it).
+ *
+ * Run against the RAW file contents the heal is about to edit, never a
+ * resolved config — resolution already merged the defaults in, so every block
+ * would read as present.
+ *
+ * @param {object} config - Parsed omega.json5 contents.
+ * @param {string} [target] - Canonical target name; adds that target's refinements.
+ * @returns {Array<{ path: string, value: * }>}
+ */
+function missingDefaults(config, target) {
+  // Resolution-only defaults are skipped whole: a `materialize: false` rule's
+  // value belongs to the framework, and writing it here would hand a brand a
+  // copy to drift ([#793](https://github.com/Omega-JS-Stack/omega/issues/793))
+  const writable = defaultsFrom(defaultRules(target).filter(isMaterialized));
+
+  return collectMissing(writable, config || {}, '', target, []);
+}
+
+module.exports = { schemaDefaults, missingDefaults, defaultComments, defaultRules };

package/dist/vendor/config/demo.js

@@ -0,0 +1,18 @@
+/**
+ * @omega.js/config demo — the shared demo-project test. Firebase's own
+ * convention: `demo-*` project ids are emulator-only (no real GCP project
+ * exists or ever will). Cloud-touching services and commands short-circuit
+ * on it instead of aiming real Google APIs at a project that 403s.
+ */
+
+/**
+ * Whether a Firebase project id is a demo-* (emulator-only) project.
+ *
+ * @param {string} projectId - e.g. 'demo-omega'
+ * @returns {boolean}
+ */
+function isDemoProject(projectId) {
+  return String(projectId || '').startsWith('demo-');
+}
+
+module.exports = { isDemoProject };

package/dist/vendor/config/desktop-artifacts.js

@@ -0,0 +1,110 @@
+/**
+ * @omega.js/config desktop-artifacts — the SINGLE naming rule for a desktop
+ * target's release assets ([#620](https://github.com/Omega-JS-Stack/omega/issues/620)).
+ *
+ * Two readers, one rule: @omega.js/desktop's `gulp/build-config` writes these
+ * names into `dist/electron-builder.yml`'s artifactName templates, and
+ * [site-global.js](site-global.js) derives the website's direct-download URLs
+ * from them (`<releasesUrl>/download/<name>`). A second spelling anywhere is a
+ * dead download button on a live site, so the derivation lives here and both
+ * sides call it.
+ *
+ * Names carry NO version. That is the whole point: GitHub's
+ * `/releases/latest/download/<asset>` only resolves when the asset name is the
+ * same in every release, so releasing a desktop version never touches the
+ * website and the published URLs never change. electron-updater is unaffected —
+ * it reads the feed files (`latest-mac.yml`, `latest.yml`), which name whatever
+ * artifact the build produced.
+ *
+ * Nothing puts an arch back into a name that omits one: electron-builder's
+ * macro expander only REPLACES a `${arch}` token where it appears. So these
+ * names support exactly the default build — a UNIVERSAL mac, a SINGLE linux
+ * arch, and windows' multi-arch NSIS installer (which merges every arch into
+ * one file anyway). @omega.js/desktop's build-config refuses any other arch set
+ * rather than let two builds collide on one name; per-arch names are a future
+ * additive change.
+ */
+
+// Every artifact a release publishes as a user-facing download, per platform,
+// in the order the platform offers them — the FIRST is the platform's default
+// (`/download/<platform>` leads with it, legacy UJM parity). The artifact keys
+// ARE the website's URL vocabulary (`/download/<platform>/<artifact>`).
+//
+// Deliberately absent: the mac auto-update ZIP (electron-updater fetches it
+// from the feed; nobody links it) and the snap (the Snap Store publishes it,
+// so it is never a release asset).
+const DESKTOP_ARTIFACTS = {
+  mac:     { universal: { ext: 'dmg' } },
+  windows: { universal: { ext: 'exe' } },
+  linux:   { debian: { ext: 'deb' }, appimage: { ext: 'AppImage' } },
+};
+
+/**
+ * The product name a desktop target packages under — the same derivation
+ * @omega.js/desktop's `Manager.getConfig()` applies (`app.productName` ←
+ * `brand.name`), so the website reads the name the packager actually used.
+ *
+ * @param {object} config - Desktop-shaped config (`{ app, brand }`).
+ * @returns {string} Product name ('' when neither key resolves).
+ */
+function desktopProductName(config) {
+  return config?.app?.productName || config?.brand?.name || '';
+}
+
+/**
+ * A product name reduced to filename-safe characters. electron-builder's
+ * `${productName}` keeps spaces, which become dots in NSIS output and behave
+ * inconsistently across targets; hyphens are consistent everywhere.
+ *
+ * @param {string} productName - Raw product name ("Deployment Playground").
+ * @returns {string} Sanitized name ("Deployment-Playground"), '' when empty.
+ */
+function sanitizeProductName(productName) {
+  return String(productName || '')
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * One artifact's versionless filename: `<Product>-<platform>-<artifact>.<ext>`.
+ *
+ * @param {string} productName - Raw product name (sanitized here).
+ * @param {string} platform - Platform key (mac, windows, linux).
+ * @param {string} artifact - Artifact key (universal, debian, appimage, …).
+ * @param {string} [ext] - Extension override — pass electron-builder's literal
+ *   `${ext}` to get a TEMPLATE that covers every target sharing the platform's
+ *   fallback (mac's dmg + auto-update zip).
+ * @returns {string} The filename ('' with no product name to build it from).
+ */
+function desktopArtifactName(productName, platform, artifact, ext) {
+  const product = sanitizeProductName(productName);
+  const extension = ext || DESKTOP_ARTIFACTS[platform]?.[artifact]?.ext;
+  if (!product || !extension) return '';
+
+  return `${product}-${platform}-${artifact}.${extension}`;
+}
+
+/**
+ * Every published artifact's filename, keyed platform → artifact, in offer
+ * order.
+ *
+ * @param {string} productName - Raw product name.
+ * @returns {object} `{ mac: { universal: 'App-mac-universal.dmg' }, … }`, or
+ *   `{}` when there is no product name to derive from.
+ */
+function desktopArtifactNames(productName) {
+  if (!sanitizeProductName(productName)) return {};
+
+  const names = {};
+  for (const [platform, artifacts] of Object.entries(DESKTOP_ARTIFACTS)) {
+    names[platform] = {};
+    for (const artifact of Object.keys(artifacts)) {
+      names[platform][artifact] = desktopArtifactName(productName, platform, artifact);
+    }
+  }
+
+  return names;
+}
+
+module.exports = { DESKTOP_ARTIFACTS, desktopProductName, sanitizeProductName, desktopArtifactName, desktopArtifactNames };