@omega.js/backend 0.1.0

package/dist/vendor/config/order.js

@@ -0,0 +1,139 @@
+/**
+ * Canonical top-level key order for brand omega.json5 files — "omega
+ * reorders the keys so the order is consistent" (Ian), with comments
+ * traveling alongside their keys. Applied on every config writeback and
+ * exposed standalone.
+ *
+ * The order is the legacy omega-manager brand-config order extended with
+ * the new-world sections. Unknown keys keep their relative order after the
+ * known ones. Only the TOP level is ordered — nested layout stays exactly
+ * as authored.
+ *
+ * Loss-proof by construction: the root object's inner region is cut into
+ * contiguous TILES, one per top-level entry — each tile runs from the end
+ * of the previous entry's last line to the end of its own last line, so
+ * leading comment blocks, blank lines, and same-line trailing comments all
+ * belong to exactly one tile. Reordering permutes whole tiles and never
+ * synthesizes text (beyond trailing commas, which JSON5 allows everywhere).
+ * The result must JSON5-parse to data deep-equal to the input or this
+ * throws and the caller writes nothing.
+ */
+const { isDeepStrictEqual } = require('node:util');
+const JSON5 = require('json5');
+
+const { parseRoot } = require('./edit.js');
+
+// `targets` goes LAST (Ian 2026-07-14) — it's the per-target override layer,
+// so it reads best after every shared section it can override.
+// The de-branding rekey (#23) collapsed several vendor-named top-level keys
+// into role-shaped homes — `repo`, `edge`, `captcha`, `search`, `forms`,
+// `inbound` — and folded `firebase`/`gcp` into `cloud`. Only the TOP level is
+// ordered, so each fold is one entry here; the nesting under it is authored.
+// Every SHARED_SCHEMA top-level key belongs here — the drift guard in
+// test/order.test.js fails the moment the schema grows one this list misses
+// (#503: socials, github, directory, ports, client had drifted out), and its
+// REVERSE guard fails on a key that is neither schema-known nor a named
+// manager-owned block (#484 retired `testing`: no schema rule, and the testing
+// service reads no config at all, so converters were carrying a dead key).
+const CANONICAL_TOP_LEVEL_ORDER = [
+  'enabled', 'parent', 'brand', 'url', 'company', 'socials', 'account', 'local', 'ports',
+  'repo', 'github', 'domain',
+  'edge', 'cloud', 'captcha', 'analytics',
+  'monitoring', 'advertising', 'features', 'payment', 'connections', 'sponsorships',
+  'marketing', 'blog', 'devlog', 'reviews', 'seo', 'search',
+  'dataRequest', 'forms', 'inbound',
+  'server', 'assets', 'directory',
+  'certificates', 'theme', 'ai', 'translation', 'client', 'migrations', 'targets',
+];
+
+/**
+ * Reorder a brand omega.json5 source's top-level keys into canonical order,
+ * comments riding with their keys. Returns the source unchanged when there
+ * is nothing to reorder (or when the file's shape rules out safe tiling —
+ * multiple entries on one line).
+ *
+ * @param {string} source - omega.json5 text (must parse).
+ * @returns {string} Reordered source with identical data.
+ */
+function applyCanonicalOrder(source) {
+  const original = JSON5.parse(source);
+
+  // Every entry needs a trailing comma before tiles can be permuted — the
+  // original last entry may lack one and would break mid-file. Insert from
+  // the end so offsets stay valid, then re-parse.
+  let text = source;
+  const scan = parseRoot(text);
+  if (scan.entries.length < 2) {
+    return source;
+  }
+  const missingCommas = scan.entries
+    .filter((entry) => !entry.hasComma)
+    .sort((a, b) => b.valueNode.end - a.valueNode.end);
+  for (const entry of missingCommas) {
+    text = `${text.slice(0, entry.valueNode.end)},${text.slice(entry.valueNode.end)}`;
+  }
+
+  const root = parseRoot(text);
+
+  // Prefix: everything through the end of the line the '{' sits on
+  const firstNewline = text.indexOf('\n', root.start);
+  if (firstNewline === -1) {
+    return source; // single-line root — nothing to tile
+  }
+  const prefixEnd = firstNewline + 1;
+
+  const lineEndAfter = (pos) => {
+    const nl = text.indexOf('\n', pos);
+    return nl === -1 ? pos : nl + 1;
+  };
+
+  const tiles = [];
+  let cursor = prefixEnd;
+  for (const entry of root.entries) {
+    const end = lineEndAfter(entry.commaEnd);
+    if (end <= cursor) {
+      return source; // two entries share a line — tiling would tear it
+    }
+    tiles.push({ key: entry.key, text: text.slice(cursor, end) });
+    cursor = end;
+  }
+
+  // Tail: anything between the last entry's line and the closing brace's
+  // line (detached trailing comments) stays where it is
+  const braceLineStart = text.lastIndexOf('\n', root.closeStart - 1) + 1;
+  const tail = text.slice(cursor, Math.max(cursor, braceLineStart));
+
+  const rank = (key) => {
+    // `targets` is last by POLICY — even unknown keys (which rank after the
+    // known ones, relative order kept) never sort past it.
+    if (key === 'targets') {
+      return Number.MAX_SAFE_INTEGER;
+    }
+    const index = CANONICAL_TOP_LEVEL_ORDER.indexOf(key);
+    return index === -1 ? CANONICAL_TOP_LEVEL_ORDER.length : index;
+  };
+  const ordered = [...tiles].sort((a, b) => rank(a.key) - rank(b.key));
+
+  if (ordered.every((tile, index) => tile === tiles[index]) && text === source) {
+    return source; // already canonical, nothing inserted
+  }
+
+  const result = text.slice(0, prefixEnd)
+    + ordered.map((tile) => tile.text).join('')
+    + tail
+    + text.slice(Math.max(cursor, braceLineStart));
+
+  let parsed;
+  try {
+    parsed = JSON5.parse(result);
+  } catch (e) {
+    throw new Error(`Canonical reorder produced unparseable output — nothing written: ${e.message}`);
+  }
+  if (!isDeepStrictEqual(parsed, original)) {
+    throw new Error('Canonical reorder changed the config data — nothing written');
+  }
+
+  return result;
+}
+
+module.exports = { applyCanonicalOrder, CANONICAL_TOP_LEVEL_ORDER };

package/dist/vendor/config/ports.js

@@ -0,0 +1,374 @@
+/**
+ * Port auto-allocation (N7) — classic defaults, probe at boot, bump-if-taken.
+ *
+ * The allocator is boot-time only: when the classic defaults are free (the
+ * single-brand case) resolution returns them untouched and dev behaves
+ * exactly as it always has. When a port is taken (a second brand's stack is
+ * up), that port bumps +1 until free — per port, with a shared claimed-set so
+ * two names never land on the same number.
+ *
+ * The RESOLVED map publishes two ways (the CLI that booted the stack owns
+ * both): a ports file (`<projectDir>/.temp/ports.json`, pid-stamped, deleted
+ * on clean shutdown) for sibling processes of the same brand, and
+ * `OMEGA_<NAME>_PORT` env vars injected into spawned children for URL
+ * getters. Browser code receives `dev.ports` via the injected dev config —
+ * it can read neither env nor files.
+ *
+ * A port is not always the whole fact: the website's dev ORIGIN carries a
+ * protocol too (mkcert HTTPS by default), and a sibling reading `website:
+ * 4000` cannot guess it. The publisher writes the resolved origin string
+ * beside the map in the same file, and `readSiblingOrigin` reads it back
+ * ([#262](https://github.com/Omega-JS-Stack/omega/issues/262)).
+ *
+ * Under local HTTPS the map carries two hosting entries: `https` is the
+ * public origin (the mkcert proxy) and `hosting` is the proxy's INTERNAL
+ * plain-http port. A consumer process targets `https`, never `hosting`
+ * ([#795](https://github.com/Omega-JS-Stack/omega/issues/795)).
+ *
+ * Explicit pins (config `ports` section) never bump: a pinned port that is
+ * busy is a hard error naming the pin, because the user asked for exactly
+ * that port.
+ */
+
+const fs = require('fs');
+const net = require('net');
+const path = require('path');
+const { findBrandRoot } = require('./load.js');
+
+// The classic defaults every framework has always used — allocation starts
+// here, and single-brand dev never leaves them.
+const CLASSIC_PORTS = {
+  auth: 9099,
+  functions: 5001,
+  firestore: 8080,
+  database: 9000,
+  hosting: 5002,
+  storage: 9199,
+  pubsub: 8085,
+  ui: 4050,
+  website: 4000,
+  livereload: 35729,
+  cdp: 9222,
+};
+
+const PORTS_FILE = 'ports.json';
+
+// The dev website origin every surface assumes when no live website published
+// one — the classic port, over the protocol `omega dev` speaks by default (the
+// mkcert proxy). An assumption, and every fallback says so out loud (#262).
+const CLASSIC_DEV_ORIGIN = `https://localhost:${CLASSIC_PORTS.website}`;
+
+/**
+ * Attempt one bind (the probe primitive). On macOS/BSD, wildcard and
+ * specific-address listeners COEXIST on the same port — so no single bind
+ * can see every listener; isPortFree composes four.
+ * @param {object} listenOptions - net listen options ({ port } = wildcard).
+ * @param {boolean} [ignoreMissingFamily] - Treat address-family-unavailable
+ *   errors (no IPv6 on this host) as free rather than busy.
+ * @returns {Promise<boolean>} True when the bind succeeded.
+ */
+function bindProbe(listenOptions, ignoreMissingFamily = false) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', (error) => {
+      if (ignoreMissingFamily && ['EADDRNOTAVAIL', 'EAFNOSUPPORT', 'EINVAL'].includes(error.code)) {
+        return resolve(true);
+      }
+      resolve(false);
+    });
+    server.listen(listenOptions, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+/**
+ * Is this port free for a dev server to take? Bind-probe, not connect-probe
+ * — and FOUR binds, because on macOS/BSD specific-address and wildcard
+ * listeners coexist per port, and so do the two wildcard families: a
+ * 127.0.0.1 probe misses an IPv6-wildcard listener (`*:port`), a wildcard
+ * probe misses a 127.0.0.1-specific one, a `localhost` server can sit on ::1
+ * alone, and the bare-`{ port }` bind lands on the IPv6 wildcard `::`, which
+ * coexists with a foreign `0.0.0.0` holder (Docker, `nc -l`, any
+ * non-loopback dev server). Free means all of 127.0.0.1, ::1 (when the host
+ * has IPv6), 0.0.0.0, and the `::` wildcard bind succeed — matching what
+ * firebase-tools' own connect-probe will conclude at boot.
+ * @param {number} port - Port to probe.
+ * @returns {Promise<boolean>} True when the port is free.
+ */
+async function isPortFree(port) {
+  return (await bindProbe({ port, host: '127.0.0.1' }))
+    && (await bindProbe({ port, host: '::1' }, true))
+    && (await bindProbe({ port, host: '0.0.0.0' }))
+    && (await bindProbe({ port }));
+}
+
+/**
+ * Resolve a port map: each wanted port keeps its value when free, bumps +1
+ * until free when taken. Pinned ports (explicit config) never bump — busy
+ * pin throws.
+ *
+ * @param {object} options
+ * @param {object} options.wanted - Name → desired port (usually the classic
+ *   defaults or a brand's firebase.json values).
+ * @param {object} [options.pins] - Name → explicitly-configured port (config
+ *   `ports` section). Pinned names use the pin verbatim; busy → throw.
+ * @param {Set<number>} [options.claimed] - Ports already claimed in this
+ *   process run (shared across resolvePorts calls for multi-family boots).
+ * @returns {Promise<{ ports: object, bumped: string[] }>} Resolved map + the
+ *   names that moved off their wanted value.
+ */
+async function resolvePorts({ wanted, pins = {}, claimed = new Set() }) {
+  const ports = {};
+  const bumped = [];
+
+  for (const [name, wantedPort] of Object.entries(wanted)) {
+    const pin = pins[name];
+
+    if (typeof pin === 'number') {
+      if (claimed.has(pin) || !(await isPortFree(pin))) {
+        throw new Error(`Port ${pin} (pinned via config ports.${name}) is already in use — free it or change the pin`);
+      }
+      ports[name] = pin;
+      claimed.add(pin);
+      continue;
+    }
+
+    let candidate = wantedPort;
+    while (claimed.has(candidate) || !(await isPortFree(candidate))) {
+      candidate += 1;
+    }
+
+    if (candidate !== wantedPort) {
+      bumped.push(name);
+    }
+    ports[name] = candidate;
+    claimed.add(candidate);
+  }
+
+  return { ports, bumped };
+}
+
+/**
+ * Publish the resolved map for sibling processes of the same brand.
+ * @param {string} projectDir - The project directory (owns `.temp/`).
+ * @param {object} ports - Resolved name → port map.
+ * @param {object} [facts] - Resolved non-port facts published beside the map
+ *   ({ origin }, the website's resolved dev origin — protocol included).
+ * @returns {string} The file path written.
+ */
+function writePortsFile(projectDir, ports, facts = {}) {
+  const dir = path.join(projectDir, '.temp');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, PORTS_FILE);
+  fs.writeFileSync(file, JSON.stringify({ ports, ...facts, pid: process.pid, startedAt: new Date().toISOString() }, null, 2));
+  return file;
+}
+
+/**
+ * Read a live ports file's WHOLE payload (the map plus the facts published
+ * beside it). Returns null when absent, unparseable, or stale (the writing
+ * process is no longer running).
+ * @param {string} projectDir - The project directory.
+ * @returns {object|null} The parsed payload, or null.
+ */
+function readPortsData(projectDir) {
+  const file = path.join(projectDir, '.temp', PORTS_FILE);
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== 'object' || !parsed.ports) {
+    return null;
+  }
+
+  // Stale check: the allocator deletes the file on clean shutdown, so a
+  // surviving file with a dead pid is a crash leftover — ignore it.
+  if (parsed.pid) {
+    try {
+      process.kill(parsed.pid, 0);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  return parsed;
+}
+
+/**
+ * Read a live ports file. Returns null when absent, unparseable, or stale
+ * (the writing process is no longer running).
+ * @param {string} projectDir - The project directory.
+ * @returns {object|null} The resolved name → port map, or null.
+ */
+function readPortsFile(projectDir) {
+  const data = readPortsData(projectDir);
+  return data ? data.ports : null;
+}
+
+/**
+ * Remove the ports file (clean shutdown).
+ * @param {string} projectDir - The project directory.
+ */
+function clearPortsFile(projectDir) {
+  try {
+    fs.unlinkSync(path.join(projectDir, '.temp', PORTS_FILE));
+  } catch (error) {
+    // Absent is fine.
+  }
+}
+
+/**
+ * Merge the live ports files of the sibling targets in the same brand — a
+ * running backend's resolved emulator map, as the website/desktop/extension
+ * target beside it sees it. Dead-pid leftovers are ignored by readPortsFile; the
+ * caller's OWN target dir is skipped (a previous run of the same process).
+ *
+ * Read at USE time, never once at boot: the ports file is pid-stamped and
+ * deleted on shutdown, so a boot-time read races the sibling that has not
+ * booted yet and goes stale the moment an emulator restarts on new numbers
+ * ([#300](https://github.com/Omega-JS-Stack/omega/issues/300)).
+ *
+ * No brand root (standalone consumer) → empty map, and the caller falls back
+ * to the classic ports.
+ * @param {string} targetDir - The reading target's root (its own file is skipped).
+ * @returns {object} Merged name → port map.
+ */
+function readSiblingPorts(targetDir) {
+  const merged = {};
+
+  for (const dir of siblingTargetDirs(targetDir)) {
+    Object.assign(merged, readPortsFile(dir) || {});
+  }
+
+  return merged;
+}
+
+/**
+ * The resolved dev WEBSITE ORIGIN a sibling target of the same brand published —
+ * protocol and port together, because a port alone cannot say whether the dev
+ * server speaks TLS (mkcert is the default) and every client that links to the
+ * website in dev needs the whole origin
+ * ([#262](https://github.com/Omega-JS-Stack/omega/issues/262)).
+ *
+ * Read at USE time like readSiblingPorts, and null when no sibling is live —
+ * the caller falls back to the classic assumption and says so.
+ * @param {string} targetDir - The reading target's root (its own file is skipped).
+ * @returns {string|null} The published origin, or null.
+ */
+function readSiblingOrigin(targetDir) {
+  for (const dir of siblingTargetDirs(targetDir)) {
+    const origin = readPortsData(dir)?.origin;
+    if (origin) {
+      return origin;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * The sibling target dirs of the target that asks: every `targets/<name>` of
+ * the same brand except its own. No brand root (standalone consumer) → none.
+ * @param {string} targetDir - The reading target's root.
+ * @returns {string[]} Absolute sibling target dirs.
+ */
+function siblingTargetDirs(targetDir) {
+  const brandRoot = findBrandRoot(targetDir);
+  if (!brandRoot) {
+    return [];
+  }
+
+  const targetsDir = path.join(brandRoot, 'targets');
+  const dirs = [];
+
+  for (const entry of fs.existsSync(targetsDir) ? fs.readdirSync(targetsDir, { withFileTypes: true }) : []) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) {
+      continue;
+    }
+    const dir = path.join(targetsDir, entry.name);
+    if (path.resolve(dir) === path.resolve(targetDir)) {
+      continue;
+    }
+    dirs.push(dir);
+  }
+
+  return dirs;
+}
+
+/**
+ * Env-var name for a port ('auth' → 'OMEGA_AUTH_PORT').
+ * @param {string} name - Port name.
+ * @returns {string} Env var name.
+ */
+function envName(name) {
+  return `OMEGA_${name.toUpperCase()}_PORT`;
+}
+
+/**
+ * Resolved map → the OMEGA_*_PORT env block to inject into spawned children.
+ * @param {object} ports - Resolved name → port map.
+ * @returns {object} Env var name → string port.
+ */
+function portsToEnv(ports) {
+  const env = {};
+  for (const [name, port] of Object.entries(ports)) {
+    env[envName(name)] = String(port);
+  }
+  return env;
+}
+
+/**
+ * Read a port from the environment (`OMEGA_<NAME>_PORT`).
+ * @param {string} name - Port name ('auth', 'hosting', ...).
+ * @param {object} [env] - Env object (defaults to process.env).
+ * @returns {number|null} The port, or null when unset/invalid.
+ */
+function envPort(name, env = process.env) {
+  const raw = env[envName(name)];
+  const port = Number.parseInt(raw, 10);
+  return Number.isInteger(port) && port > 0 ? port : null;
+}
+
+/**
+ * Every `OMEGA_<NAME>_PORT` in an environment as a resolved map — the inverse
+ * of portsToEnv, for a spawned child reading the whole map its parent
+ * injected rather than one name at a time.
+ * @param {object} [env] - Env object (defaults to process.env).
+ * @returns {object} Name → port map (lowercased names, invalid values dropped).
+ */
+function envPorts(env = process.env) {
+  const ports = {};
+  for (const key of Object.keys(env)) {
+    const match = /^OMEGA_([A-Z0-9]+)_PORT$/.exec(key);
+    if (!match) {
+      continue;
+    }
+    const name = match[1].toLowerCase();
+    const port = envPort(name, env);
+    if (port) {
+      ports[name] = port;
+    }
+  }
+  return ports;
+}
+
+module.exports = {
+  CLASSIC_PORTS,
+  CLASSIC_DEV_ORIGIN,
+  isPortFree,
+  resolvePorts,
+  writePortsFile,
+  readPortsFile,
+  clearPortsFile,
+  readSiblingPorts,
+  readSiblingOrigin,
+  envName,
+  portsToEnv,
+  envPort,
+  envPorts,
+};

package/dist/vendor/config/providers.js

@@ -0,0 +1,32 @@
+/**
+ * The `role.providers.<provider>` shape (#425) — every role names its vendors
+ * the same way, so "which provider did the brand pick?" is ONE question with
+ * one answer here instead of a hand-rolled read per service.
+ *
+ * The tri-state is unchanged, it just moved into key presence:
+ *   - no `providers` block, or an empty one → nothing chosen (the role's
+ *     service skips, exactly what a null `provider` used to mean)
+ *   - `{ namecheap: {…} }`                  → chosen, with its settings
+ *   - `{ namecheap: false }`                → deliberately disabled
+ *
+ * Roles that can only ever have one live provider (domain's registrar,
+ * translation's engine, devlog's writer) read the chosen one through this;
+ * roles that run several at once (payment, analytics) iterate the block
+ * themselves — presence per vendor is the whole gate there.
+ */
+
+/**
+ * The chosen provider key in a `providers` block.
+ *
+ * @param {object} [providers] - A role's `providers` map
+ * @returns {string|null} - The provider name, or null when none is chosen
+ */
+function chosenProvider(providers) {
+  if (!providers || typeof providers !== 'object' || Array.isArray(providers)) {
+    return null;
+  }
+
+  return Object.keys(providers).find((name) => providers[name] !== false) || null;
+}
+
+module.exports = { chosenProvider };

package/dist/vendor/config/repo.js

@@ -0,0 +1,142 @@
+/**
+ * @omega.js/config repo — the SINGLE derivation of the brand's GitHub repo
+ * (owner + name), shared by every surface that targets the brand repo (web
+ * `omega deploy --direct`, the manager's github service setup/repo/pages,
+ * the backend CMS routes that commit posts).
+ *
+ * One optional key: `repo.providers.github.repo` (or, on a backend load, the
+ * target-overlaid `targets.backend.github.repo`, which wins) — either a bare name
+ * ("omega-brand") or an "owner/name" slug ("itw-creative-works/omega-brand").
+ * Defaults: name falls to `<brand.id>-omega`, owner falls to `repo.providers.github.org`.
+ * That name is the `<brand.id>-<role>` repo rule (Ian 2026-09-07,
+ * [#809](https://github.com/Omega-JS-Stack/omega/issues/809)): every repo a brand
+ * owns is its id plus the role it plays, `omega` for the source monorepo beside
+ * the `releases` one below, so nobody types a repo name to get the right one.
+ * The slug's owner slot carries the legacy omega-manager orgMain/orgWebsite
+ * split (Ian 2026-07-19): most ITW brands house the brand repo under the paid
+ * company org (itw-creative-works) while `repo.providers.github.org` keeps
+ * naming the brand's own org for org-profile reconciliation. The retired `repoWebsite` URL key
+ * (2026-07-19, Ian: "we no longer need it — that was for when the website
+ * lived NOT in the monorepo") is superseded by this slug: one repo per
+ * brand, named by the brand.
+ *
+ * Born from the 2026-07-18 launch-night collision: the bare brand-id
+ * fallback resolved brand "omega" to Omega-JS-Stack/omega — the framework
+ * MONOREPO — instead of the brand repo.
+ */
+
+/**
+ * Parse a `repo.providers.github.repo` value: "owner/name" slug or bare "name".
+ *
+ * @param {string} value - e.g. "itw-creative-works/omega-brand" or "omega-brand"
+ * @returns {{ owner: string, name: string }} owner is '' for bare names.
+ */
+function parseRepoSlug(value) {
+  const trimmed = (value || '').trim();
+  if (!trimmed) return { owner: '', name: '' };
+  const slash = trimmed.indexOf('/');
+  if (slash === -1) return { owner: '', name: trimmed };
+  return { owner: trimmed.slice(0, slash), name: trimmed.slice(slash + 1) };
+}
+
+/**
+ * The github keys the derivation reads: the shared `repo.providers.github`
+ * block, overlaid by the target's own `github` entry (a backend load composes
+ * `targets.backend.github` — the CMS's content identity — onto the top level,
+ * and per the merge chain the target wins).
+ *
+ * @param {object} config - Composed omega config (brand + local layers).
+ * @returns {object} Merged `{ org, repo, … }` keys.
+ */
+function githubKeys(config) {
+  return { ...(config?.repo?.providers?.github || {}), ...(config?.github || {}) };
+}
+
+/**
+ * The brand repo's bare name (no owner): a typed slug or bare name, else the
+ * `<brand.id>-omega` default of the `<brand.id>-<role>` rule.
+ *
+ * @param {object} config - Composed omega config (brand + local layers).
+ * @returns {string} Repo name ('' when nothing in the chain resolves).
+ */
+function brandRepoName(config) {
+  const github = githubKeys(config);
+  // The id half is trimmed like a typed slug: the role suffix is appended to
+  // it, so untrimmed whitespace would sit INSIDE the composed name.
+  const id = (config?.brand?.id || '').trim();
+
+  return parseRepoSlug(github.repo).name
+    || (id ? `${id}-omega` : '');
+}
+
+/**
+ * The brand repo's owner (GitHub org or user).
+ *
+ * @param {object} config - Composed omega config (brand + local layers).
+ * @returns {string} Owner ('' when nothing in the chain resolves).
+ */
+function brandRepoOwner(config) {
+  const github = githubKeys(config);
+  return parseRepoSlug(github.repo).owner || github.org || '';
+}
+
+/**
+ * The brand repo as ONE finished value: owner, name, and the "owner/name" slug
+ * the GitHub API takes. This is the form a FRAMEWORK hands to consumer code —
+ * @omega.js/backend exposes it as `config.resolved.github` ([#290](https://github.com/Omega-JS-Stack/omega/issues/290)),
+ * because a brand target cannot require this private package and must never
+ * re-derive the merge rules for itself.
+ *
+ * @param {object} config - Composed omega config (brand + local layers).
+ * @returns {{ owner: string, name: string, repo: string }} `repo` is the slug, '' unless BOTH halves resolve (half an address addresses nothing).
+ */
+function brandRepo(config) {
+  const owner = brandRepoOwner(config);
+  const name = brandRepoName(config);
+
+  return { owner, name, repo: owner && name ? `${owner}/${name}` : '' };
+}
+
+/**
+ * The releases keys the derivation reads: the desktop target's own `releases`
+ * block, overlaid by the top-level one a desktop-resolved config carries (the
+ * merge chain overlays `targets.desktop` onto the top level, so the overlay is
+ * the resolved value). Both shapes are live: the site global reads a raw config,
+ * where the block sits under the target, while every desktop verb reads the
+ * resolved one.
+ *
+ * @param {object} config - Composed omega config (raw or desktop-resolved).
+ * @returns {object} Merged `{ enabled, owner, repo }` keys.
+ */
+function releasesKeys(config) {
+  const target = config?.targets?.desktop;
+  const entry = target && typeof target === 'object' && !Array.isArray(target) ? target.releases : undefined;
+
+  return { ...(entry || {}), ...(config?.releases || {}) };
+}
+
+/**
+ * The brand's ONE public releases repo: where the versioned `v<x.y.z>` releases
+ * that feed electron-updater live, and where the website's versionless
+ * `/releases/latest/download/<asset>` links point ([#620](https://github.com/Omega-JS-Stack/omega/issues/620),
+ * [#799](https://github.com/Omega-JS-Stack/omega/issues/799)). One repo per
+ * brand, named after it: `<brand.id>-releases` by default, under the brand
+ * repo's own owner, so a brand that declares nothing still has an address.
+ *
+ * This is the ONE home of that rule. Every reader takes it from here (the site
+ * global's download links, @omega.js/desktop's electron-builder publish block,
+ * its release-repo provisioning, its finalize-release upload), so the feed a
+ * shipped app polls and the URL a download button carries can never disagree.
+ *
+ * @param {object} config - Composed omega config (raw or desktop-resolved).
+ * @returns {{ owner: string, name: string, repo: string }} `repo` is the slug, '' unless BOTH halves resolve (half an address addresses nothing).
+ */
+function releasesRepo(config) {
+  const releases = releasesKeys(config);
+  const owner = releases.owner || brandRepoOwner(config);
+  const name = releases.repo || (config?.brand?.id ? `${config.brand.id}-releases` : '');
+
+  return { owner, name, repo: owner && name ? `${owner}/${name}` : '' };
+}
+
+module.exports = { parseRepoSlug, brandRepoName, brandRepoOwner, brandRepo, releasesRepo };