@omega.js/desktop 0.50.0 → 0.51.0

package/dist/vendor/config/env-delivery.js

@@ -21,14 +21,31 @@
  *     ([#454](https://github.com/Omega-JS-Stack/omega/issues/454)), so they
  *     drop out of every rendered and published set.
  *
- * Pattern families (`match`, no `name`) carry a delivery like anything else,
- * but have no fixed name to render, so nothing here can list them.
+ * The schema NAMES most of what travels, and two kinds of key it cannot name
+ * ride the same pipeline through the target's COMPOSED production values
+ * (`values`, from composeTargetEnv), which every list here takes as an option:
  *
- * Every function takes an optional `schema` so a caller — the tests — can
+ *   - a PATTERN family member (`match`, no `name`): the schema knows
+ *     `CONNECTIONS_<PROVIDER>_CLIENT_ID` as a shape, so only a composed set can
+ *     say which providers this brand actually configured
+ *     ([#876](https://github.com/Omega-JS-Stack/omega/issues/876)).
+ *   - a CUSTOM key the schema does not know at all: a consumer's own line in
+ *     the brand `.env`, which used to reach no runner and fail the consumer's
+ *     own workflow step silently
+ *     ([#835](https://github.com/Omega-JS-Stack/omega/issues/835)). It travels
+ *     in the target's FILE mode: written into the `.env` the runner builds on
+ *     the backend, the runner env alone everywhere else.
+ *
+ * Both halves come out of ONE primitive (`deliveredKeys`), so what a workflow
+ * injects, what push-secrets publishes, and what the backend's `.env` writer
+ * names can never disagree inside a run. No `values` = the schema half alone,
+ * which is what a lane with no brand to compose from gets.
+ *
+ * Every function takes an optional `schema` so a caller (the tests) can
  * exercise the rules against a fixture; the default is the real one.
  */
 
-const { ENV_SCHEMA } = require('./env-schema.js');
+const { ENV_SCHEMA, envSchemaEntry } = require('./env-schema.js');
 
 // Keys a generated workflow's own `env:` block already declares. The generated
 // block never restates one (a repeated YAML mapping key is invalid) — they are
@@ -39,6 +56,39 @@ const WORKFLOW_OWNED_KEYS = ['GH_TOKEN', 'CLOUDFLARE_TOKEN', 'NODE_VERSION', 'NO
 // generated region is always a valid, self-explaining line of YAML.
 const EMPTY_BLOCK = '# (no CI-delivered keys for this target — the next omega verb regenerates this block)';
 
+// What a target's generated workflow carries in the runner env, per target.
+//
+// The default is the CI half: `ci` plus `bake` (a bake is injected before it is
+// baked), because those artifacts carry their values inside themselves and
+// never read an env file.
+//
+// The BACKEND is the one target whose deployed artifact ships a composed `.env`
+// and whose deploy now runs on a runner
+// ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)): the runner has
+// no brand checkout to compose that file from, so its workflow WRITES the .env
+// from the runner env, which puts every `env` delivery on the runner too.
+const WORKFLOW_MODES = {
+  backend: ['env', 'ci', 'bake'],
+};
+
+const DEFAULT_WORKFLOW_MODES = ['ci', 'bake'];
+
+/**
+ * The mode a key the schema does not declare travels in, per target: the
+ * target's own FILE mode where it has one (backend, whose workflow writes the
+ * `.env` its upload ships with), the runner env everywhere else (#835).
+ *
+ * A custom key declares no delivery, so it takes the channel its target
+ * already uses for the keys it composes. A packaged app carries no `.env`, so
+ * there is nothing on web, desktop or the extension for a file mode to mean.
+ *
+ * @param {string} target - Target name.
+ * @returns {string} `'env'` or `'ci'`.
+ */
+function customDeliveryMode(target) {
+  return (WORKFLOW_MODES[target] || DEFAULT_WORKFLOW_MODES).includes('env') ? 'env' : 'ci';
+}
+
 /**
  * The delivered names a target receives in the given modes, sorted and
  * deduplicated.
@@ -74,6 +124,79 @@ function deliveredNames(target, modes, schema) {
   return [...names].sort();
 }
 
+// GitHub's own rule for a secret name: letters, digits and underscores, never
+// leading with a digit. A composed key that breaks it is refused by name.
+const SECRET_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * The ONE delivered key set (#835, #876): the schema's named deliveries for
+ * this target in these modes, plus what only the target's COMPOSED production
+ * values can name.
+ *
+ * Every list in this file derives from here, so the workflow block, the
+ * published secrets and the backend's `.env` key list are three renderings of
+ * one set rather than three sets that have to agree.
+ *
+ * A composed key is added when it is a `match` family member this target
+ * delivers in these modes, or when the schema does not know it at all and the
+ * target's custom mode is one of them. It is NOT added when the schema names
+ * it: the walk above already ruled on every fixed name, so a `machineLocal`
+ * path and a key whose only delivery here is the local `.env` stay home
+ * exactly as they did before a composed set existed. A WORKFLOW_OWNED name is
+ * never taken from a composed set either: those belong to the template, and
+ * neither is a `GITHUB_`-prefixed name, which GitHub refuses as a secret. A
+ * composed name GitHub could not hold as a secret at all throws, naming the key
+ * and the rule.
+ *
+ * @param {string} target - Target name ('web', 'backend', …).
+ * @param {string[]} modes - The delivery modes to collect.
+ * @param {object} [options]
+ * @param {object[]} [options.schema] - Env schema entries (default: the real schema).
+ * @param {Object<string, string>} [options.values] - The target's composed
+ *   production values (names are read, values never are).
+ * @returns {string[]} Delivered env var names, sorted.
+ */
+function deliveredKeys(target, modes, { schema = ENV_SCHEMA, values = null } = {}) {
+  const names = new Set(deliveredNames(target, modes, schema));
+  if (!values) return [...names].sort();
+
+  const customMode = customDeliveryMode(target);
+
+  for (const key of Object.keys(values)) {
+    if (names.has(key)) continue;
+
+    const entry = envSchemaEntry(key, schema);
+
+    if (entry) {
+      // A fixed name is the walk above's business, whatever it decided.
+      if (entry.name) continue;
+      if (entry.machineLocal) continue;
+      if (!modes.includes(entry.delivery && entry.delivery[target])) continue;
+      names.add(key);
+      continue;
+    }
+
+    if (!modes.includes(customMode)) continue;
+    if (WORKFLOW_OWNED_KEYS.includes(key)) continue;
+    // GitHub REFUSES an Actions secret whose name starts with GITHUB_ (the
+    // prefix is the runner's own), so publishing one would fail the deploy
+    // precheck outright. A brand .env carrying GITHUB_TOKEN is a plausible
+    // typo for GH_TOKEN, and the workflow reads its own `secrets.GITHUB_TOKEN`
+    // either way.
+    if (key.startsWith('GITHUB_')) continue;
+    // dotenv reads `[\w.-]+` as a key, so a brand `.env` can carry a name
+    // GitHub's secret API refuses outright (`ACME.WEBHOOK`). Delivering it
+    // would render a workflow line nothing can resolve and fail the publish
+    // three layers from the typo, so it fails HERE, by name.
+    if (!SECRET_NAME.test(key)) {
+      throw new Error(`${key}: a delivered env key must be a GitHub secret name (${SECRET_NAME.source.replace(/^\^|\$$/g, '')}), so rename it in the target's .env`);
+    }
+    names.add(key);
+  }
+
+  return [...names].sort();
+}
+
 /**
  * The keys a target's generated workflow needs in the runner env: every `ci`
  * delivery, plus every `bake` (a bake is injected before it is baked).
@@ -83,8 +206,60 @@ function deliveredNames(target, modes, schema) {
  * @param {object[]} [options.schema] - Env schema entries (default: the real schema).
  * @returns {string[]} Delivered env var names, sorted.
  */
-function workflowSecretKeys(target, { schema = ENV_SCHEMA } = {}) {
-  return deliveredNames(target, ['ci', 'bake'], schema);
+function workflowSecretKeys(target, { schema = ENV_SCHEMA, values = null } = {}) {
+  return deliveredKeys(target, WORKFLOW_MODES[target] || DEFAULT_WORKFLOW_MODES, { schema, values });
+}
+
+/**
+ * The keys a target's RUNTIME reads from the `.env` its artifact ships with:
+ * every `env` delivery, and ONLY those. Backend is the only target with one
+ * today, and the one caller is its generated workflow, which writes that file
+ * on the runner from the secrets the block above injects (#872).
+ *
+ * A `ci` key is deliberately not here: it reaches the deploy PROCESS through
+ * the runner env (the deploy credential, the license key the verdict is checked
+ * with) and the shipped artifact must never carry it. The mode list below is
+ * the whole of that exclusion, and `artifactEnvValues` applies the same rule to
+ * the other writer of a backend `.env`, the stage's composer.
+ *
+ * @param {string} target - Target name.
+ * @param {object} [options]
+ * @param {object[]} [options.schema] - Env schema entries.
+ * @returns {string[]} Delivered env var names, sorted.
+ */
+function envFileKeys(target, { schema = ENV_SCHEMA, values = null } = {}) {
+  return deliveredKeys(target, ['env'], { schema, values });
+}
+
+/**
+ * Composed env values, narrowed to what a target's shipped artifact may carry:
+ * everything the composer resolved, minus every key the schema delivers to this
+ * target as `ci` ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)).
+ *
+ * The two sets differ on purpose. `composeTargetEnv` (env.js) resolves a value
+ * for EVERY key a target claims, because the secrets publisher needs the `ci`
+ * values too: a repo secret the workflow injects has to be valued from the same
+ * cascade as everything else. The `.env` written INTO an artifact is the
+ * narrower half, and this is the filter that says so, from the same declaration
+ * `envFileKeys` reads. A pattern family and a target-layer key have no `ci`
+ * delivery to match, so they pass through untouched.
+ *
+ * @param {string} target - Target name.
+ * @param {Object<string, string>} values - The composed values.
+ * @param {object} [options]
+ * @param {object[]} [options.schema] - Env schema entries.
+ * @returns {Object<string, string>} A new map, runner-only keys removed.
+ */
+function artifactEnvValues(target, values, { schema = ENV_SCHEMA } = {}) {
+  const runnerOnly = new Set(deliveredKeys(target, ['ci'], { schema }));
+  const shipped = {};
+
+  for (const [key, value] of Object.entries(values)) {
+    if (runnerOnly.has(key)) continue;
+    shipped[key] = value;
+  }
+
+  return shipped;
 }
 
 /**
@@ -97,7 +272,27 @@ function workflowSecretKeys(target, { schema = ENV_SCHEMA } = {}) {
  * @returns {string[]} Delivered env var names, sorted.
  */
 function bakeKeys(target, { schema = ENV_SCHEMA } = {}) {
-  return deliveredNames(target, ['bake'], schema);
+  return deliveredKeys(target, ['bake'], { schema });
+}
+
+/**
+ * The SOURCE names of a target's baked keys: the brand-level name a human sets
+ * (`GOOGLE_ANALYTICS_SECRET_DESKTOP`), not the `deliverAs` name the build reads
+ * it under. The bake GUARD names keys at the level a human can fix them, and it
+ * must not judge a target on keys it never bakes
+ * ([#891](https://github.com/Omega-JS-Stack/omega/issues/891): the desktop's
+ * other rules are CI-delivered signing credentials, which the deploy lane owns).
+ *
+ * @param {string} target - Target name.
+ * @param {object} [options]
+ * @param {object[]} [options.schema] - Env schema entries.
+ * @returns {string[]} Brand-level env var names, sorted.
+ */
+function bakeSourceKeys(target, { schema = ENV_SCHEMA } = {}) {
+  return schema
+    .filter((entry) => entry.name && !entry.machineLocal && entry.delivery && entry.delivery[target] === 'bake')
+    .map((entry) => entry.name)
+    .sort();
 }
 
 /**
@@ -128,18 +323,45 @@ function publishSecretKeys(target, options) {
  * @param {string} [options.indent] - The token's indent (default two spaces).
  * @returns {string} The block body (no leading indent).
  */
-function renderSecretsBlock(target, { schema = ENV_SCHEMA, indent = '  ' } = {}) {
-  const lines = workflowSecretKeys(target, { schema })
+function renderSecretsBlock(target, { schema = ENV_SCHEMA, indent = '  ', values = null } = {}) {
+  const lines = workflowSecretKeys(target, { schema, values })
     .filter((key) => !WORKFLOW_OWNED_KEYS.includes(key))
     .map((key) => `${key}: \${{ secrets.${key} }}`);
 
   return lines.length ? lines.join(`\n${indent}`) : EMPTY_BLOCK;
 }
 
+/**
+ * The KEY NAMES a workflow writes its target's `.env` from, as a JSON array
+ * ready to drop into the template's writer step (#872).
+ *
+ * NAMES only, never `KEY="$KEY"` lines: the writer is a node one-liner that
+ * reads each name out of the runner env and serializes the file through
+ * `serializeEnv` (env.js), the documented SSOT for every `.env` writeback. The
+ * step this replaced pasted values into a shell heredoc, where a value carrying
+ * a NEWLINE split its own line and everything after it parsed as a key of its
+ * own (verified: a `K="$K"` heredoc with a multi-line value yields the injected
+ * key), and a quote or a backslash left the file malformed. No shell ever sees
+ * a value now.
+ *
+ * @param {string} target - Target name.
+ * @param {object} [options]
+ * @param {object[]} [options.schema] - Env schema entries.
+ * @returns {string} A JSON array of names, sorted (`[]` when the target ships no .env).
+ */
+function renderEnvFileKeys(target, { schema = ENV_SCHEMA, values = null } = {}) {
+  return JSON.stringify(envFileKeys(target, { schema, values }));
+}
+
 module.exports = {
   WORKFLOW_OWNED_KEYS,
+  deliveredKeys,
   workflowSecretKeys,
+  envFileKeys,
+  artifactEnvValues,
   bakeKeys,
+  bakeSourceKeys,
   publishSecretKeys,
   renderSecretsBlock,
+  renderEnvFileKeys,
 };

package/dist/vendor/config/env-retired.js

@@ -0,0 +1,137 @@
+/**
+ * Retired ENV keys ([#893](https://github.com/Omega-JS-Stack/omega/issues/893))
+ * - the `.env` half of retired-keys.js.
+ *
+ * Six values were declared in both homes at once: the env schema carried them
+ * as non-secret keys while the config schema already declared (or now
+ * declares) the same fact. Two homes for one value drift, and the rule that
+ * settles which one wins is in docs/shared/config.md ("Config or env?"):
+ * config holds what is PUBLIC by design (an id a store URL carries, a key a
+ * browser bundle ships, a value printed in a binary), `.env` holds secrets,
+ * the login coordinates that only travel with a secret, and machine paths.
+ *
+ * There is no dual-read anywhere in OMEGA, so a `.env` line left behind is a
+ * value nothing reads: the id a brand carefully pasted would be ignored and
+ * the publish would address the wrong listing, or none. Every layer read
+ * therefore FAILS on one, naming the config path the value moved to
+ * (env.js's parseEnvFile, the one place a `.env` layer is parsed).
+ *
+ * The config-side register gets nothing from this move: these were never
+ * config keys, so nothing there was renamed.
+ *
+ * The register also carries the env-side RENAMES
+ * ([#845](https://github.com/Omega-JS-Stack/omega/issues/845)): a key that is
+ * still a secret and still lives in `.env`, under a new name. Same silence,
+ * same refusal; the fix it names is renaming the line, not deleting it.
+ *
+ * And it carries the keys that are retired OUTRIGHT
+ * ([#819](https://github.com/Omega-JS-Stack/omega/issues/819)): no config path,
+ * no new env name, because what replaced the key is a MECHANISM rather than a
+ * value. Such a row declares `replacement: null` and its refusal reads as a
+ * deletion with nowhere to move the value to.
+ */
+
+// env var name -> { replacement, why, home } (docs/shared/config.md carries the
+// rows). `home` is where the replacement LIVES: 'config' by default (the #893
+// move), or 'env' for a key that stayed a secret and only changed NAME, which
+// is a rename of the line rather than a deletion. `replacement: null` is a key
+// with no successor of any kind (#819): the line is simply deleted, and the
+// row's `why` names the mechanism that made it unnecessary.
+const RETIRED_ENV_KEYS = {
+  CHROME_EXTENSION_ID: {
+    replacement: 'targets.<name>.listings.chrome.id',
+    why: 'a store item id is public by design (it is in the listing URL), so it lives beside that listing in config',
+  },
+  FIREFOX_EXTENSION_ID: {
+    replacement: 'targets.<name>.listings.firefox.id',
+    why: "the AMO add-on id IS the manifest's gecko id, and config is its ONE home: the local scaffold pins the derived id there and the package task writes it into the manifest",
+  },
+  EDGE_PRODUCT_ID: {
+    replacement: 'targets.<name>.listings.edge.id',
+    why: 'a store product id is public by design (it is in the listing URL), so it lives beside that listing in config',
+  },
+  RECAPTCHA_SITE_KEY: {
+    replacement: 'captcha.providers.recaptcha.siteKey',
+    why: 'the site key is rendered into every page that carries a form, so it is public by definition; RECAPTCHA_SECRET_KEY stays in .env',
+  },
+  PAYPAL_CLIENT_ID: {
+    replacement: 'payment.providers.paypal.clientId',
+    why: 'the public half of the PayPal pair, already declared in config; the backend read it through a boot bridge that copied config into env',
+  },
+  CHARGEBEE_SITE: {
+    replacement: 'payment.providers.chargebee.site',
+    why: 'the site name is in every Chargebee URL, already declared in config; the backend read it through a boot bridge that copied config into env',
+  },
+  // The connections pair ([#845](https://github.com/Omega-JS-Stack/omega/issues/845)):
+  // these are SECRETS and stayed in `.env`, so the row is a rename, not a move.
+  // Exact names only, one per provider: the register is a name lookup, so the
+  // `OAUTH2_*` family is spelled out a row at a time as a brand needs it, and
+  // Google is the pair every brand carries today.
+  OAUTH2_GOOGLE_CLIENT_ID: {
+    home: 'env',
+    replacement: 'CONNECTIONS_GOOGLE_CLIENT_ID',
+    why: '#788 renamed the oauth2 feature to connections, the env family included; the backend reads only CONNECTIONS_<PROVIDER>_CLIENT_ID now',
+  },
+  OAUTH2_GOOGLE_CLIENT_SECRET: {
+    home: 'env',
+    replacement: 'CONNECTIONS_GOOGLE_CLIENT_SECRET',
+    why: '#788 renamed the oauth2 feature to connections, the env family included; the backend reads only CONNECTIONS_<PROVIDER>_CLIENT_SECRET now',
+  },
+  // The test-lane pair ([#819](https://github.com/Omega-JS-Stack/omega/issues/819),
+  // Ian 2026-09-13): retired outright, so neither row names a replacement. A
+  // suite no longer holds a credential of its own, which is why there is
+  // nothing to move the value to.
+  OMEGA_TEST_FIREBASE_ADMIN_KEY: {
+    replacement: null,
+    why: 'retired: desktop, extension and web test their own sign-in through a seeded persona from the backend emulator (#904), so no suite mints a custom token from a service account any more',
+  },
+  OMEGA_TEST_USER_UID: {
+    replacement: null,
+    why: 'retired: desktop, extension and web test their own sign-in through a seeded persona from the backend emulator (#904), and the roster names the persona, so no uid is configured anywhere',
+  },
+};
+
+/**
+ * The retired keys a parsed `.env` layer carries, in the layer's own order.
+ *
+ * Presence is the whole test: an empty value (`KEY=`) documents a key nothing
+ * reads, so it is owed the same deletion as a valued one.
+ *
+ * @param {Object<string, string>} values - Parsed `.env` values.
+ * @returns {Array<{ key: string, replacement: string|null, why: string }>}
+ */
+function findRetiredEnvKeys(values) {
+  return Object.keys(values || {})
+    .filter((key) => RETIRED_ENV_KEYS[key])
+    .map((key) => ({ key, ...RETIRED_ENV_KEYS[key] }));
+}
+
+/**
+ * Refuse a `.env` layer that still carries a retired key, spelling the move
+ * out. A row with no replacement says so plainly: the line is deleted and
+ * nothing takes the value anywhere (#819).
+ *
+ * @param {Object<string, string>} values - Parsed `.env` values.
+ * @param {string} envPath - The file the values came from (named in the error).
+ * @throws {Error} Naming every retired key in the layer, its new home, and why.
+ */
+function assertNoRetiredEnvKeys(values, envPath) {
+  const found = findRetiredEnvKeys(values);
+  if (found.length === 0) return;
+
+  const moves = found.map(({ key, replacement, why, home }) => {
+    if (!replacement) return `  ${key} is retired outright: delete the .env line, nothing replaces the value (${why})`;
+
+    return home === 'env'
+      ? `  ${key} renamed to ${replacement}; rename the .env line (${why})`
+      : `  ${key} moved to ${replacement} in config/omega.json5; delete the .env line (${why})`;
+  });
+
+  throw new Error(
+    `${envPath} carries ${found.length} retired env key(s). Nothing reads them, so the value is silently lost:\n`
+    + `${moves.join('\n')}\n`
+    + 'The rule, and the whole register: docs/shared/config.md ("Config or env?").',
+  );
+}
+
+module.exports = { RETIRED_ENV_KEYS, findRetiredEnvKeys, assertNoRetiredEnvKeys };

package/dist/vendor/config/env-rules.js

@@ -26,7 +26,11 @@
  * PRESENCE ONLY, never a value shape (Ian 2026-08-26): a rule fires when the
  * key is empty, never because a value "looks wrong". `requiredWhen` is
  * one-directional — a truthy config path makes the key mandatory; an empty key
- * never says anything about the config.
+ * never says anything about the config. A rule may PIN the path to one value
+ * (`platforms.windows.signing.strategy=self-hosted`,
+ * [#891](https://github.com/Omega-JS-Stack/omega/issues/891)), because an
+ * enum's value is what decides which credentials exist: the EV token belongs to
+ * the self-hosted strategy, never to the cloud one.
  *
  * The checker NEVER throws and never logs. It returns the violations and the
  * caller decides the severity (build mode and production boot fail loudly,
@@ -53,6 +57,21 @@ function hasValue(env, entry) {
   return Boolean(entry.deliverAs && env[entry.deliverAs]);
 }
 
+/**
+ * Whether a `requiredWhen` expression holds for a config: a truthy path, or an
+ * exact match when the expression pins one (`<path>=<value>`).
+ *
+ * @param {object} config - The resolved omega.json5 config.
+ * @param {string} expression - The schema entry's `requiredWhen`.
+ * @returns {boolean}
+ */
+function requiredWhenHolds(config, expression) {
+  const [path, expected] = String(expression).split('=');
+  const value = getPath(config, path);
+
+  return expected === undefined ? Boolean(value) : String(value) === expected;
+}
+
 /**
  * Check a resolved config + env pair against the schema's presence rules.
  *
@@ -82,7 +101,7 @@ function checkEnvRules(config, env, { target, schema = ENV_SCHEMA } = {}) {
 
     if (entry.required) {
       violations.push({ key: entry.name, rule: 'required', path: null });
-    } else if (getPath(config, entry.requiredWhen)) {
+    } else if (requiredWhenHolds(config, entry.requiredWhen)) {
       violations.push({ key: entry.name, rule: 'requiredWhen', path: entry.requiredWhen });
     }
   }
@@ -90,4 +109,4 @@ function checkEnvRules(config, env, { target, schema = ENV_SCHEMA } = {}) {
   return violations;
 }
 
-module.exports = { checkEnvRules };
+module.exports = { checkEnvRules, requiredWhenHolds };