@omega.js/desktop 0.50.0 → 0.51.0

package/dist/vendor/devkit/target-secrets.js

@@ -9,10 +9,15 @@
  * the ONE copy; each framework binds it with its own target string and nothing
  * else.
  *
- *   1. DERIVE — the KEY SET is the env schema's: every entry whose `delivery`
- *      names the target (`publishSecretKeys(target)`, @omega.js/config). Never
- *      "whatever the composed .env holds", which published a brand's unrelated
- *      keys to a runner.
+ *   1. DERIVE: the KEY SET is @omega.js/config'sONE delivery primitive, read
+ *      off the schema AND the composed values (`publishSecretKeys(target,
+ *      { values })`): every entry whose `delivery` names the target, plus the
+ *      `match` family members this brand actually configured
+ *      ([#876](https://github.com/Omega-JS-Stack/omega/issues/876)) and the
+ *      keys the schema does not know at all, a consumer's own
+ *      ([#835](https://github.com/Omega-JS-Stack/omega/issues/835)). Still not
+ *      "whatever the composed .env holds": a declared key this target does not
+ *      deliver, and every `machineLocal` one, stay home.
  *   2. COLLECT — the VALUES come from the target's COMPOSED env
  *      (`composeTargetEnv`, [#678](https://github.com/Omega-JS-Stack/omega/issues/678)):
  *      company ← brand ← target `.env`, the brand-side layers schema-filtered
@@ -23,7 +28,7 @@
  *      schema drops them from the delivered set itself.
  *   3. GUARD — secrets belong to the repo whose Actions run the workflow, and
  *      the only acceptable proof of which repo that is, is the brand's own
- *      config (`repo.providers.github`). An inferred git remote is not proof: a
+ *      config (`repo.org`, the SOURCE repo). An inferred git remote is not proof: a
  *      target vendored into a framework/test monorepo, a cloned starter still
  *      pointing at the template author, or any fork would publish this brand's
  *      `.env` to a stranger's Actions.
@@ -34,20 +39,80 @@
  * a skip — it throws the boundary's instructions (install, `gh auth login`, or
  * `omega deploy --no-secrets`).
  *
- * Desktop binds it too ([#682](https://github.com/Omega-JS-Stack/omega/issues/682)),
- * over the `resolveValue` seam: its signing secrets are named by PATH in the
- * cascade (`CSC_LINK=config/certs/dev-id.p12`) and what CI needs is the FILE, so
- * it base64-encodes an existing file between COLLECT and PUBLISH. That seam is
- * the only shape difference between the three binds — the transport is one.
+ * A key the SCHEMA says this target's config requires (`required` /
+ * `requiredWhen`, @omega.js/config's env-rules) and the cascade resolves EMPTY
+ * stops the publish outright ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)):
+ * the run that reads those secrets is the one that signs a release, and half a
+ * signing set on a runner is a green build nobody can install. Nothing is
+ * pushed on that path, so the fix and the re-run are one step, not a partial
+ * state to reason about. A key that is merely absent and NOT required gets one
+ * line naming it.
+ *
+ * There is no per-framework BIND any more
+ * ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)): the four files
+ * that passed a target string and a seam were four places to forget a rule, and
+ * the standalone `omega push-secrets` verb they backed is gone with them. The
+ * seams live HERE, in one table keyed by target type, and every caller (each
+ * framework's deploy precheck, the manager's repo walk) makes the same call.
+ *
+ *   desktop  `resolveValue` base64-encodes a secret that names a FILE
+ *            (#682: `CSC_LINK` points at a `.p12` and CI needs the bytes), and
+ *            `deriveValues` fills the signing paths from the signing tree, by
+ *            the ONE derivation the desktop env load runs
+ *            (`@omega.js/devkit/signing-env`), so no operator pastes a path.
+ *   backend  `extraSecrets`: the deploy credential is a service-account FILE
+ *            the cloud manage service mints (#872), so there is nothing in the
+ *            cascade to compose it from and it arrives already valued.
+ *   web, extension  plain strings, no seam.
+ *
+ * `dryRun` ([#895](https://github.com/Omega-JS-Stack/omega/issues/895)) prints
+ * the key NAMES that would publish, the derived lines and any refusal, and
+ * sends nothing. The refusal still THROWS in a dry run: a plan that cannot be
+ * made is loud.
  */
-const { composeTargetEnv } = require('../config/index.js');
+const { composeTargetEnv, loadConfig } = require('../config/index.js');
 const { publishSecretKeys } = require('../config/env-delivery.js');
+const { checkEnvRules } = require('../config/env-rules.js');
 const { publishActionsSecrets } = require('./actions-secrets.js');
-const { resolveRepo } = require('./deploy.js');
+const { resolveRepo, resolveDeployLane } = require('./deploy.js');
+const { targetSeams } = require('./target-seams.js');
 
 /**
- * The publishable secrets for a target: the schema's delivery set for it,
- * valued from the composed env. An empty value never claims a key.
+ * The target's COMPOSED env, with the bind's own derivations applied to it.
+ *
+ * PRODUCTION, named rather than sniffed: these values fuel the runner's release
+ * build, and the composer would otherwise default to whatever environment this
+ * shell happens to be
+ * ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)): the same
+ * determinism the "FILES only, never the shell" rule above buys.
+ *
+ * Everything that reads the cascade reads it through HERE (the required-key
+ * check and the collection both), so a derived value is as real as a typed one
+ * to each of them ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)).
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root.
+ * @param {string} options.target - Target name.
+ * @param {function} [options.deriveValues] - The derive seam (see collectTargetSecrets).
+ * @param {object} [options.logger] - `{ log, warn, error }`; each derivation prints one line.
+ * @returns {{ values: object, fixes: Object<string, string> }}
+ */
+function composeValues({ targetDir, target, deriveValues, logger }) {
+  const { values } = composeTargetEnv({ targetDir, target, environment: 'production' });
+
+  const { derived = [], fixes = {} } = (deriveValues ? deriveValues(values) : null) || {};
+  for (const { key, value } of derived) {
+    if (logger) logger.log(`${key} derived from ${value}`);
+  }
+
+  return { values, fixes };
+}
+
+/**
+ * The publishable secrets for a target: the delivery set the ONE primitive
+ * answers for it (schema names, family members, the consumer's own keys),
+ * valued from the same composed env the set is read off. An empty value never
+ * claims a key.
  *
  * @param {object} options
  * @param {string} options.targetDir - The target root (its .env is the local layer).
@@ -56,20 +121,32 @@ const { resolveRepo } = require('./deploy.js');
  *   applied to each collected value before it travels (desktop base64-encodes
  *   its file-path signing secrets). A falsy return DROPS the key, exactly as an
  *   empty composed value does.
+ * @param {function} [options.deriveValues] - `(values) => { derived, fixes }`, the
+ *   seam applied to the COMPOSED map before anything reads it: a bind may VALUE
+ *   a key the cascade left empty (desktop derives its signing paths from the
+ *   dispersed artifacts) and may name, per key it could NOT value, the fix line
+ *   the refusal should carry. `derived` is `[{ key, value }]` (already written
+ *   into the map); `fixes` is `key → sentence`.
  * @returns {Object<string, string>} key → value, ready to publish.
  */
 function collectTargetSecrets(options) {
-  const { targetDir, target, resolveValue } = options;
-  // PRODUCTION, named rather than sniffed: these values fuel the runner's
-  // release build, and the composer would otherwise default to whatever
-  // environment this shell happens to be
-  // ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)) — the same
-  // determinism the "FILES only, never the shell" rule above buys.
-  const { values } = composeTargetEnv({ targetDir, target, environment: 'production' });
+  const { targetDir, target, logger } = options;
+  const seams = targetSeams({ target, targetDir });
+  const resolveValue = 'resolveValue' in options ? options.resolveValue : seams.resolveValue;
+  const deriveValues = 'deriveValues' in options ? options.deriveValues : seams.deriveValues;
+  const { values } = composeValues({ targetDir, target, deriveValues, logger });
 
   const secrets = {};
-  for (const key of publishSecretKeys(target)) {
-    if (!values[key]) continue;
+  // The key set and the values come from ONE composition (#835, #876): a
+  // family member or a consumer's own key exists only in the composed map, so
+  // the set has to be read off the same map it is valued from.
+  for (const key of publishSecretKeys(target, { values })) {
+    if (!values[key]) {
+      // Never silence: a key with no value in the cascade is a key CI will not
+      // have. Whether that MATTERS is the schema's answer, below.
+      if (logger) logger.log(`No value for ${key} in the .env cascade: not published`);
+      continue;
+    }
     const value = resolveValue ? resolveValue(values[key], key) : values[key];
     if (value) secrets[key] = value;
   }
@@ -78,10 +155,55 @@ function collectTargetSecrets(options) {
 }
 
 /**
- * The brand's OWN repo as `owner/name`, from the target's resolved config — the
- * same derivation `omega deploy --direct` uses (`repo.providers.github`, name
- * falling back to brand.id). Null when the config declares nothing usable or
- * doesn't load.
+ * The keys this target's own config REQUIRES that the cascade cannot value.
+ *
+ * The rules are the schema's, evaluated by the ONE checker (#626) against the
+ * target's resolved config and its COMPOSED env, narrowed to the keys this
+ * publisher would send: a required key CI never reads is not the publish's
+ * business, and a rule nobody delivers cannot be fixed by pushing anything.
+ *
+ * The bind's derivations run FIRST (`deriveValues`), because a key the brand
+ * never typed but the dispersed files answer is not missing, and a key the
+ * derivation could not value carries that seam's own fix line
+ * ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)).
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root.
+ * @param {string} options.target - Target name.
+ * @param {function} [options.deriveValues] - The derive seam (see collectTargetSecrets).
+ * @returns {Array<{ key: string, rule: string, path: string|null, fix: string|null }>}
+ */
+function missingRequiredSecrets(options) {
+  const { targetDir, target } = options;
+  const deriveValues = 'deriveValues' in options
+    ? options.deriveValues
+    : targetSeams({ target, targetDir }).deriveValues;
+
+  let config;
+  try {
+    // PRODUCTION, the same environment `composeValues` composes for: the rules
+    // and the values have to be read off ONE config, or a developer machine's
+    // `config/omega.development.json5` decides whether a release publish
+    // refuses ([#895](https://github.com/Omega-JS-Stack/omega/issues/895)).
+    config = loadConfig(targetDir, target, { environment: 'production' }).config;
+  } catch (e) {
+    // No loadable config: there is no declaration to owe anything to.
+    return [];
+  }
+
+  const { values, fixes } = composeValues({ targetDir, target, deriveValues });
+  const delivered = new Set(publishSecretKeys(target, { values }));
+
+  return checkEnvRules(config, values, { target })
+    .filter((violation) => delivered.has(violation.key))
+    .map((violation) => ({ ...violation, fix: fixes[violation.key] || null }));
+}
+
+/**
+ * The brand's SOURCE repo as `owner/name`, from the target's resolved config:
+ * the one the workflows and their secrets live on, derived as
+ * `<brand.id>-omega` under `repo.org` (#883). Null when the config declares
+ * nothing usable or doesn't load.
  *
  * @param {object} options
  * @param {string} options.targetDir - The target root.
@@ -90,13 +212,14 @@ function collectTargetSecrets(options) {
  */
 function declaredBrandRepo(options) {
   try {
-    const { loadConfig, brandRepoOwner, brandRepoName } = require('../config/index.js');
-    const { config } = loadConfig(options.targetDir, options.target);
+    const { loadConfig, sourceRepo } = require('../config/index.js');
+    // PRODUCTION, like every other read this publish makes (#895): the repo a
+    // release's secrets belong to is the one the production config names.
+    const { config } = loadConfig(options.targetDir, options.target, { environment: 'production' });
     if (!config) return null;
 
-    const owner = brandRepoOwner(config);
-    const name = brandRepoName(config);
-    return owner && name ? `${owner}/${name}` : null;
+    const source = sourceRepo(config);
+    return source ? source.slug : null;
   } catch (e) {
     return null;
   }
@@ -111,16 +234,28 @@ function declaredBrandRepo(options) {
  * @param {string} options.target - Target name ('web', 'extension', …).
  * @param {object} options.logger - `{ log, warn, error }`.
  * @param {object} [options.env] - Env map (default: process.env).
- * @param {function} [options.resolveValue] - Value seam (see collectTargetSecrets).
+ * @param {boolean} [options.dryRun] - Print the plan (key NAMES, the derived
+ *   lines, any refusal) and send nothing (#895).
+ * @param {function} [options.resolveValue] - Value seam override (tests).
+ * @param {function} [options.deriveValues] - Derive seam override (tests).
+ * @param {Object<string, string>} [options.extraSecrets] - Override for the
+ *   target's already-valued keys, merged OVER the composed set (tests).
  * @param {function} [options.execFn] - Injectable `gh` exec (tests).
  * @param {function} [options.gitExecFn] - Injectable `git` exec for remote discovery (tests).
- * @returns {{ skipped: string }|{ published: string[], failed: Array<object> }}
+ * @returns {{ skipped: string }|{ planned: string[] }|{ published: string[], failed: Array<object> }}
  */
 function publishTargetSecrets(options) {
   options = options || {};
-  const { targetDir, target, logger } = options;
+  const { targetDir, target, logger, dryRun } = options;
   const env = options.env || process.env;
 
+  // The target type's own shape differences, in ONE table (#891). A caller
+  // passes a seam only to stub it.
+  const seams = targetSeams({ target, targetDir });
+  const resolveValue = 'resolveValue' in options ? options.resolveValue : seams.resolveValue;
+  const deriveValues = 'deriveValues' in options ? options.deriveValues : seams.deriveValues;
+  const extraSecrets = 'extraSecrets' in options ? options.extraSecrets : seams.extraSecrets;
+
   // CI runs the generated workflow as its build/publish step — the secrets
   // already exist there and the runner token can't write them.
   if (env.GITHUB_ACTIONS === 'true' || env.CI === 'true') {
@@ -128,30 +263,80 @@ function publishTargetSecrets(options) {
     return { skipped: 'ci' };
   }
 
-  const secrets = collectTargetSecrets({ targetDir, target, resolveValue: options.resolveValue });
+  // The schema's set, plus the caller's own already-valued keys. An extra has
+  // no `.env` home to compose from (backend's deploy credential is a FILE the
+  // firebase service mints, #872), so it arrives valued and travels verbatim:
+  // `resolveValue` is the COMPOSED half's seam and would only mangle it. An
+  // empty extra claims no key, exactly as an empty composed value does.
+  // The config's OWN requirements first: a half set is never published (#891)
+  const missing = missingRequiredSecrets({ targetDir, target, deriveValues });
+  if (missing.length > 0) {
+    // ONE line shape per key, whatever answers it: `<KEY> (required by <path>):
+    // <the fix>`. A key a bind can DERIVE names the producer that delivers the
+    // file (`omega manage --service certificates`, then disperse) instead of
+    // asking for a path to paste; everything else names the .env to set.
+    const lines = missing.map(({ key, path, fix }) => {
+      const detail = fix || `set it in the ${target} target's .env or the brand's, then re-run.`;
+
+      return `  ${key}${path ? ` (required by ${path})` : ''}: ${detail}`;
+    });
+    throw new Error(
+      `${missing.length} secret(s) this brand's config requires are empty in the .env cascade (company/brand/target). `
+      + `Nothing was published.\n${lines.join('\n')}`,
+    );
+  }
+
+  const secrets = { ...collectTargetSecrets({ targetDir, target, resolveValue, deriveValues, logger }) };
+  for (const [key, value] of Object.entries(extraSecrets || {})) {
+    if (value) secrets[key] = value;
+  }
+
   const keys = Object.keys(secrets);
   if (!keys.length) {
     logger.warn('Skipping secret publication — no keys composed for this target from the .env cascade (company/brand/target)');
     return { skipped: 'no-secrets' };
   }
 
-  let repo;
-  try {
-    const { owner, repo: name } = resolveRepo({ cwd: targetDir, execFn: options.gitExecFn });
-    repo = `${owner}/${name}`;
-  } catch (e) {
-    logger.warn(`Skipping secret publication — no GitHub remote here (${e.message})`);
-    return { skipped: 'no-remote' };
-  }
-
   const declared = declaredBrandRepo({ targetDir, target });
   if (!declared) {
-    logger.warn('Skipping secret publication — this brand names no GitHub repo in config (repo.providers.github). Set it, then re-run `omega deploy`.');
+    logger.warn('Skipping secret publication: this brand names no GitHub repo in config (repo.org). Set it, then re-run `omega deploy`.');
     return { skipped: 'no-declared-repo' };
   }
-  if (declared.toLowerCase() !== repo.toLowerCase()) {
-    logger.warn(`Skipping secret publication — the git remote here is ${repo}, but this brand's repo is ${declared}. Run \`omega deploy\` from the brand's own checkout.`);
-    return { skipped: 'repo-mismatch' };
+
+  // A NESTED brand (its root is not the toplevel of the git repo it sits in)
+  // has a remote that answers the ENCLOSING repo by construction, and its
+  // deploy pushes a snapshot to the DECLARED repo regardless
+  // ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)), so the
+  // mismatch guard would only ever skip a publish that is correct. Every other
+  // guard stays: what the guard protects against is a checkout that COULD have
+  // been the brand's own and is not.
+  const { nested } = resolveDeployLane({ dir: targetDir, execFn: options.gitExecFn });
+  const repo = declared;
+
+  if (!nested) {
+    let remote;
+    try {
+      const { owner, repo: name } = resolveRepo({ cwd: targetDir, execFn: options.gitExecFn });
+      remote = `${owner}/${name}`;
+    } catch (e) {
+      logger.warn(`Skipping secret publication — no GitHub remote here (${e.message})`);
+      return { skipped: 'no-remote' };
+    }
+
+    if (declared.toLowerCase() !== remote.toLowerCase()) {
+      logger.warn(`Skipping secret publication — the git remote here is ${remote}, but this brand's repo is ${declared}. Run \`omega deploy\` from the brand's own checkout.`);
+      return { skipped: 'repo-mismatch' };
+    }
+  }
+
+  // The PLAN, and nothing else (#895): what the composition answered, by NAME.
+  // It runs after the refusal and the two guards above on purpose, so a dry run
+  // is a real preview of whether the deploy would publish at all: every one of
+  // them is a READ, and a plan naming keys the real run would skip is a promise
+  // the deploy cannot keep.
+  if (dryRun) {
+    logger.log(`DRY RUN, would publish ${keys.length} secret(s) for ${target}: ${keys.join(', ')}`);
+    return { planned: keys };
   }
 
   logger.log(`Publishing ${keys.length} secret(s) to ${repo}: ${keys.join(', ')}`);
@@ -162,4 +347,4 @@ function publishTargetSecrets(options) {
   return result;
 }
 
-module.exports = { collectTargetSecrets, declaredBrandRepo, publishTargetSecrets };
+module.exports = { collectTargetSecrets, declaredBrandRepo, missingRequiredSecrets, publishTargetSecrets };

package/dist/vendor/devkit/test/esm-only-fixture.js

@@ -0,0 +1,48 @@
+/**
+ * The ONE ESM-only dependency every OMEGA target proves its bundle lane against
+ * ([#906](https://github.com/Omega-JS-Stack/omega/issues/906)).
+ *
+ * `fixtures/esm-only-package/` is a real package (`"type": "module"`, no
+ * CommonJS build) with one entry per environment, chosen by export condition:
+ * the NODE entry opens a require of its own with
+ * `createRequire(import.meta.url)`, the shape that threw in a packaged desktop
+ * app, and the BROWSER entry touches no Node built-in. One package, so a target
+ * asks for it by its own name and gets the half its bundle is built for.
+ *
+ * It is INSTALLED rather than pointed at: `installEsmOnlyFixture(projectRoot)`
+ * copies it into the project's `node_modules`, which is where a bundler's normal
+ * resolution looks and the only shape that is the same in this monorepo and in a
+ * consumer running a framework's self-test off its packaged dist (desktop and
+ * extension carry the directory there through `omega.vendorAssets`).
+ */
+const path = require('path');
+const jetpack = require('fs-jetpack');
+
+// The name a consumer entry imports, and what the fixture's two entries say
+// about themselves. Exported because a test asserting the bundled copy ran must
+// compare against the ONE spelling, not a retyped twin.
+const FIXTURE_NAME = 'esm-only-fixture';
+const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'esm-only-package');
+const NODE_MARKER = 'ESM_ONLY_FIXTURE_NODE';
+const BROWSER_MARKER = 'ESM_ONLY_FIXTURE_BROWSER';
+
+/**
+ * Install the fixture into a project, the way npm installs a dependency.
+ * @param {string} projectRoot - the project that will import it
+ * @returns {string} where it landed (`<projectRoot>/node_modules/esm-only-fixture`)
+ * @throws {Error} when the fixture is not where this module ships it: in a
+ *   packaged framework that means the vendor step did not carry it, and a test
+ *   that silently skipped the dependency would prove nothing
+ */
+function installEsmOnlyFixture(projectRoot) {
+  if (!jetpack.exists(FIXTURE_DIR)) {
+    throw new Error(`[devkit test] the ESM-only fixture is missing from ${FIXTURE_DIR}. A framework running this off its packaged dist needs the omega.vendorAssets entry that carries it`);
+  }
+
+  const destination = path.join(projectRoot, 'node_modules', FIXTURE_NAME);
+  jetpack.copy(FIXTURE_DIR, destination, { overwrite: true });
+
+  return destination;
+}
+
+module.exports = { installEsmOnlyFixture, FIXTURE_NAME, FIXTURE_DIR, NODE_MARKER, BROWSER_MARKER };

package/dist/vendor/devkit/test/fixtures/esm-only-package/browser.js

@@ -0,0 +1,19 @@
+// The BROWSER half of the fixture (the `browser` export condition), for the
+// targets whose bundles are browser output: @omega.js/web's esm chunks and
+// service worker, @omega.js/extension's iife bundles. It reaches for no Node
+// built-in and no `import.meta` (esbuild rewrites `import.meta` in iife output
+// too, and warns), because the thing a browser bundle has to prove is the other
+// half of [#906](https://github.com/Omega-JS-Stack/omega/issues/906): an
+// ESM-only package resolves, bundles and RUNS, with a real value on the other
+// side.
+export const flavor = 'browser';
+export const marker = 'ESM_ONLY_FIXTURE_BROWSER';
+
+/**
+ * A value the bundled copy has to compute at RUNTIME, so a test asserting it
+ * proves the module evaluated rather than proving its text survived.
+ * @returns {string} the fixture's own name for itself
+ */
+export function describeFixture() {
+  return `${marker}:${flavor}`;
+}

package/dist/vendor/devkit/test/fixtures/esm-only-package/index.js

@@ -0,0 +1,20 @@
+// The NODE half of the fixture (the `default` export condition): what an
+// ESM-only dependency does the moment it needs a require of its own, which is
+// the shape that broke a packaged desktop app
+// ([#906](https://github.com/Omega-JS-Stack/omega/issues/906)). yargs-parser is
+// the live case: `createRequire(import.meta.url)` with an `import.meta.url` of
+// `undefined` throws ERR_INVALID_ARG_VALUE before a single line of app code
+// runs.
+//
+// `viaRequire` requires a BUILT-IN rather than a file beside this one: a
+// relative require resolves against the caller's own directory, which for a
+// bundled copy is the bundle's, so a relative path would be testing where the
+// output landed instead of whether the require works at all.
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export const flavor = 'node';
+export const fileUrl = import.meta.url;
+export const viaRequire = typeof require('node:path').join === 'function';
+export const marker = 'ESM_ONLY_FIXTURE_NODE';

package/dist/vendor/devkit/test/fixtures/esm-only-package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "esm-only-fixture",
+  "version": "1.0.0",
+  "private": true,
+  "description": "An ESM-only dependency, as every OMEGA target's bundle lane has to be able to carry one (#906)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "browser": "./browser.js",
+      "default": "./index.js"
+    }
+  }
+}

package/dist/vendor/monitoring/env.js

@@ -8,20 +8,30 @@
  *   OMEGA_SENTRY_ENABLED=false  kill switch — nothing reports, ever
  *   OMEGA_TEST_RUNNER           a test run never pollutes a live project
  *   OMEGA_SENTRY_FORCE=true     report from a non-production run (local proving)
- *   OMEGA_BUILD_MODE=true       the DEFAULT production signal, for hosts that
- *                               have no runtime one
+ *   the ONE environment         the DEFAULT production signal, for hosts that
+ *                               pass no runtime one
  *
- * The production signal is the host's to supply. @omega.js/desktop has no
- * runtime answer — "should we ship telemetry" is a property of its BUILD, so it
- * falls through to OMEGA_BUILD_MODE. @omega.js/backend does have one
- * (`Manager.isProduction()`, env-derived and stable for the life of the
- * process) and passes it in.
+ * The production signal is the host's to supply, and the DEFAULT is the one
+ * environment every OMEGA target answers from
+ * ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)):
+ * `@omega.js/config/environment`'s `isProduction()`, read off the host the gates
+ * were asked for (`process.env.OMEGA_ENVIRONMENT` on Node, the host's baked
+ * `config.environment` in a browser-ish context such as a renderer bundle).
+ * OMEGA_BUILD_MODE used to be that default, which made it a FIFTH production
+ * signal with its own opinion: a build-mode run of a development artifact
+ * reported as production, and a packaged production app whose lane did not
+ * carry the flag reported as development. @omega.js/backend still passes its
+ * own answer in (`Manager.isProduction()`), and a boolean a host supplies
+ * always wins.
  */
 
+const { isProduction } = require('../config/environment.js');
+
 /**
  * Read the environment gates for core.resolveConfig().
- * @param {object} [host] - the host's own signals
- * @param {boolean} [host.isProduction] - overrides the OMEGA_BUILD_MODE default
+ * @param {object} [host] - the host's own signals, and the context the one
+ *   environment is read off (a Manager carrying the baked `config`)
+ * @param {boolean} [host.isProduction] - overrides the one environment's answer
  * @param {boolean} [host.allowInDev] - the host's own dev opt-in (e.g. @omega.js/backend's `reportErrorsInDev`)
  * @returns {{ killed: boolean, killedReason: string|null, isProduction: boolean, allowInDev: boolean }}
  */
@@ -41,7 +51,7 @@ function readGates(host) {
     killedReason,
     isProduction: typeof host.isProduction === 'boolean'
       ? host.isProduction
-      : env.OMEGA_BUILD_MODE === 'true',
+      : isProduction.call(host),
     allowInDev:   !!host.allowInDev || env.OMEGA_SENTRY_FORCE === 'true',
   };
 }

package/dist/vendor/monitoring/main.js

@@ -30,7 +30,7 @@ const main = {
   initialize(host) {
     main._initialized = true;
 
-    const { shouldEnable, options, reason } = resolveConfig(host && host.config && host.config.monitoring, readGates());
+    const { shouldEnable, options, reason } = resolveConfig(host && host.config && host.config.monitoring, readGates(host));
     main._options = options;
 
     if (!shouldEnable) {

package/dist/vendor/monitoring/preload.js

@@ -21,7 +21,7 @@ const preload = {
    * @param {object} host - the desktop Manager: { config }
    */
   initialize(host) {
-    const { shouldEnable, reason } = resolveConfig(host && host.config && host.config.monitoring, readGates());
+    const { shouldEnable, reason } = resolveConfig(host && host.config && host.config.monitoring, readGates(host));
     preload._enabled = shouldEnable;
     if (!shouldEnable) logger.log(`disabled — ${reason}`);
   },

package/dist/vendor/monitoring/renderer.js

@@ -26,7 +26,7 @@ const renderer = {
   initialize(host) {
     renderer._initialized = true;
 
-    const { shouldEnable, options, reason } = resolveConfig(host && host.config && host.config.monitoring, readGates());
+    const { shouldEnable, options, reason } = resolveConfig(host && host.config && host.config.monitoring, readGates(host));
     renderer._options = options;
 
     if (!shouldEnable) {

package/docs/analytics.md

@@ -46,7 +46,7 @@ Mint the secret in GA4 Admin → Data Streams → your stream → **Measurement
 
 ### Production builds
 
-The `bundle` task's esbuild `define` bakes `process.env.GOOGLE_ANALYTICS_SECRET` into the bundled main process at build time, so packaged apps don't need `.env` at runtime. The build runs with the secret set (CI does this via the GitHub Actions secret pushed by `mgr push-secrets`).
+The `bundle` task's esbuild `define` bakes `process.env.GOOGLE_ANALYTICS_SECRET` into the bundled main process at build time, so packaged apps don't need `.env` at runtime. The build runs with the secret set (CI does this via the GitHub Actions secret `omega deploy`'s precheck pushes).
 
 ## API
 

package/docs/auto-updater.md

@@ -110,13 +110,13 @@ Long enough that an actively-used app won't surprise-quit mid-task. Short enough
 
 ### Test mode behavior
 
-When `manager.isTesting() === true` (canonical signal: `OMEGA_TEST_MODE=true`), the auto-updater swaps in test-friendly defaults so a real download → idle wait → install can complete in seconds instead of minutes:
+When `manager.isTesting() === true` (the one input: `OMEGA_ENVIRONMENT=testing`), the auto-updater swaps in test-friendly defaults so a real download → idle wait → install can complete in seconds instead of minutes:
 
 - **Idle threshold**: `IDLE_INSTALL_THRESHOLD_MS_TESTING = 3000ms` (3 sec) instead of 15 min.
 - **Both timers**: `IDLE_TICK_MS_TESTING = 500ms` replaces `feedCheckIntervalMs` and `idleEvalIntervalMs`.
 - **`_promptToInstall` short-circuits** before invoking `dialog.showMessageBox`. The native dialog is modal + blocking + would pop a window the test process can't dismiss programmatically. In test mode the prompt logs `[testing] _promptToInstall(...) — skipped native dialog.` and returns. Tests that want to assert prompt behavior override `_promptToInstall` per-test (see `auto-updater.test.js`).
 
-This lets the framework's own integration tests drive the full sequence (`OMEGA_DEV_UPDATE=available` → state machine → 500ms tick → 3s idle threshold elapses → stubbed `installNow` fires) in ~5s. Consumers running their own tests should set `OMEGA_TEST_MODE=true` to inherit the same defaults.
+This lets the framework's own integration tests drive the full sequence (`OMEGA_DEV_UPDATE=available` → state machine → 500ms tick → 3s idle threshold elapses → stubbed `installNow` fires) in ~5s. Consumers running their own tests should name `OMEGA_ENVIRONMENT=testing` to inherit the same defaults.
 
 ## Menu integration
 
@@ -224,8 +224,8 @@ The submenu is dev-only (same gate as `view/developer/toggle-devtools`) and is a
 
 ```
 provider: github
-owner:    <releases.owner ?? the brand repo's owner>
-repo:     <releases.repo  ?? `${brand.id}-releases`>
+owner:    <repo.org>
+repo:     `${brand.id}-releases`
 releaseType: release
 ```
 
@@ -233,7 +233,7 @@ So your private app repo and your public release repo are completely decoupled
 
 ## Failure modes
 
-- **Update repo isn't public** → `electron-updater` gets 404 or 401 against a private repo. Fix: ensure the releases repo (`<owner>/<brand.id>-releases` by default) is public.
+- **Update repo isn't public** → `electron-updater` gets 404 or 401 against a private repo. Fix: ensure the releases repo (`<repo.org>/<brand.id>-releases`) is public; `omega deploy`'s precheck creates it that way.
 - **Token rotates / expires for `releases` repo** — `electron-updater` doesn't authenticate downloads (anonymous public reads). So tokens don't apply on the consumer side.
 - **`app-update.yml` missing in the packaged app** → look at the build log for `electron-builder`'s "creating updates yml" line. If it's skipped, your `publish` block didn't materialize correctly into `dist/electron-builder.yml`.
 - **`error` status with code `ERR_UPDATER_CHANNEL_FILE_NOT_FOUND`** → there's no `latest-mac.yml` (or `latest.yml` / `latest-linux.yml`) at the configured channel. Run a release first.

package/docs/boot-sequence.md

@@ -5,7 +5,7 @@
 ## Order
 
 1. **`startup.applyEarly()`** — first thing, before `whenReady`. Calls `app.dock.hide()` for `mode: 'hidden'` (zero-bounce production via `LSUIElement` baked at build time).
-1b. **userData path isolation** — appends an environment suffix to `app.getPath('userData')` so each environment's session data, logs, and `electron-store` files stay separate on the same machine: production untouched, development gets ` (Development)`, testing (`OMEGA_TEST_MODE=true`) gets ` (Testing)`. The testing dir is **wiped at boot** so every test run starts from a clean slate (post-run state stays on disk for inspection until the next run; set `OMEGA_TEST_KEEP_USERDATA=1` to skip the wipe). **Must run before `storage.initialize()`** (which constructs `electron-store` against the path).
+1b. **userData path isolation** — appends an environment suffix to `app.getPath('userData')` so each environment's session data, logs, and `electron-store` files stay separate on the same machine: production untouched, development gets ` (Development)`, testing (`OMEGA_ENVIRONMENT=testing`) gets ` (Testing)`. The testing dir is **wiped at boot** so every test run starts from a clean slate (post-run state stays on disk for inspection until the next run; set `OMEGA_TEST_KEEP_USERDATA=1` to skip the wipe). **Must run before `storage.initialize()`** (which constructs `electron-store` against the path).
 1c. **Global user-agent fallback** — sets `app.userAgentFallback` to a branded template via `node-powertools.template`. Default per-platform templates: `Mozilla/5.0 (... <platform-specific> ...) AppleWebKit/537.36 (KHTML, like Gecko) {brand.name}/{app.version} Chrome/{chrome} Safari/537.36`. Merge tags resolve from `{ brand: { name, id }, app: { version }, chrome, electron, node, platform, arch }`. Every BrowserWindow load + electron-updater fetch + node-fetch via the renderer carries the branded UA. Consumers can override post-init by re-setting `app.userAgentFallback` from their main.js.
 2. **`app.on('before-quit')`** wired — sets `manager._isQuitting = true` so any quit path (Cmd+Q, role:'quit' menu, programmatic `app.quit()`, OS shutdown) bypasses the window-manager's hide-on-close trap.
 3. **`ipc`** — typed channel bus online before any feature can register handlers.