@omega.js/desktop 0.50.0 → 0.51.0

package/dist/vendor/config/env.js

@@ -5,8 +5,8 @@
  *
  * Same walk as the config cascade (load.js owns it): a target inside a brand
  * monorepo ({brand}/targets/{target}) layers the brand root's .env under its own,
- * and a brand stamped with .omega/company.json layers its company root's
- * .env underneath that. Loading uses dotenv's no-override semantics — keys
+ * and a brand naming a company (`company: { id }`) layers that company's own
+ * `company/.env` underneath that (#677). Loading uses dotenv's no-override semantics: keys
  * already in process.env (the shell) always win, and files apply
  * innermost-first, so local beats brand beats company.
  *
@@ -30,32 +30,40 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { findBrandRoot } = require('./load.js');
-const { readCompanyRoot } = require('./company.js');
-const { ENV_SCHEMA, envFileGroups } = require('./env-schema.js');
-
-// The ONE environment vocabulary, strongest signal first: every `.env.<name>`
-// overlay is suffixed with one of these, every framework's environment() answers
-// one of these, and nothing anywhere spells a fourth
-// ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)).
-const ENV_ENVIRONMENTS = ['development', 'testing', 'production'];
+const { resolveCompany } = require('./company.js');
+const { ENV_SCHEMA, envFileGroups, envSchemaEntry } = require('./env-schema.js');
+const { assertNoRetiredEnvKeys } = require('./env-retired.js');
+// The one vocabulary lives with the one environment module (#817); this file
+// re-exports it so the .env overlay names and the runtime answer stay one list.
+const { ENV_ENVIRONMENTS } = require('./environment.js');
 
 /**
- * The runtime environment — the SINGLE SOURCE OF TRUTH for the one vocabulary,
- * shared by the env overlay above and by every framework's own environment
- * answer (@omega.js/backend's `env.environment()` / `Manager.getEnvironment()`
- * delegate here). Exactly ONE of three mutually-exclusive values: testing wins,
- * then production, else development.
+ * The AMBIENT environment answer: what a lane resolves when nothing named one
+ * for it. It is the PRODUCER of the one input, never a second reader of it:
+ * `environment.js` owns the runtime answer (one input, `OMEGA_ENVIRONMENT`, no
+ * guessing), and this is the sniff a lane runs ONCE to decide what to set
+ * ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)). It is also the
+ * default for the two overlay selections below (`.env.<environment>` and
+ * `config/omega.<environment>.json5`), so a compose that was told nothing
+ * follows the same answer the runtime will give.
+ *
+ * An already-set `OMEGA_ENVIRONMENT` wins outright, so the producer and the
+ * reader can never disagree inside one process. Otherwise: testing wins, then
+ * production, else development.
  *
  * The final `else` is PRODUCTION on purpose: a deployed Cloud Function has no
  * FUNCTIONS_EMULATOR and often no ENVIRONMENT var, so "no signal" IS the normal
  * production state. Defaulting to development would make every deployed
- * function skip real side effects (emails/analytics/webhooks). (Contrast
- * UJM/BXM, whose deployed artifacts always carry their signal.)
+ * function skip real side effects (emails/analytics/webhooks).
  *
  * @returns {'testing'|'production'|'development'} The environment.
  */
 function envEnvironment() {
-  // Testing takes precedence — set by the test runner / emulator (OMEGA_TEST_MODE=true).
+  // The one input, when a lane already named it (#817).
+  if (ENV_ENVIRONMENTS.includes(process.env.OMEGA_ENVIRONMENT)) {
+    return process.env.OMEGA_ENVIRONMENT;
+  }
+  // Testing takes precedence, set by the test runner / emulator (OMEGA_TEST_MODE=true).
   if (process.env.OMEGA_TEST_MODE === 'true') {
     return 'testing';
   }
@@ -104,14 +112,17 @@ function envLayerFiles(envPath, environment) {
 function resolveEnvChain(startDir) {
   const targetDir = path.resolve(startDir);
   const brandRoot = findBrandRoot(targetDir);
-  // The marker sits at the brand root; when startDir IS a brand root (no
-  // targets/ walk above it), its own marker supplies the company layer.
-  const companyRoot = readCompanyRoot(brandRoot || targetDir);
+  // The company is named by the BRAND's config; when startDir IS a brand root
+  // (no targets/ walk above it), its own config names it. The layer is the
+  // company TREE's `.env`, named whether or not it exists: this resolves paths,
+  // and an `.env.<environment>` overlay (#586) derives from the base name, so a
+  // company that ships only an overlay still layers.
+  const company = resolveCompany(brandRoot || targetDir);
 
   return {
     local: path.join(targetDir, '.env'),
     brand: brandRoot ? path.join(brandRoot, '.env') : null,
-    company: companyRoot ? path.join(companyRoot, '.env') : null,
+    company: company.dir ? path.join(company.dir, '.env') : null,
   };
 }
 
@@ -163,7 +174,7 @@ function loadEnvChain(envPaths) {
   for (const envPath of envPaths) {
     if (!envPath || !fs.existsSync(envPath)) continue;
 
-    const parsed = require('dotenv').parse(fs.readFileSync(envPath, 'utf8'));
+    const parsed = parseEnvFile(envPath);
     for (const [key, value] of Object.entries(parsed)) {
       if (value === '' || key in process.env) continue;
       process.env[key] = value;
@@ -311,13 +322,22 @@ function reloadEnv(startDir, { target, environment = envEnvironment() } = {}) {
 /**
  * Parse one .env file into a plain map. Missing files read as empty.
  *
+ * The ONE place a `.env` layer is read, so it is also where a RETIRED key is
+ * refused ([#893](https://github.com/Omega-JS-Stack/omega/issues/893)): there
+ * is no dual-read, so a line for a key that moved into config is a value
+ * nothing consults, and both readers below (the process cascade and the
+ * artifact composer) fail on it naming the move.
+ *
  * @param {string|null} envPath
  * @returns {Object<string, string>} Parsed key → value.
  */
 function parseEnvFile(envPath) {
   if (!envPath || !fs.existsSync(envPath)) return {};
 
-  return require('dotenv').parse(fs.readFileSync(envPath, 'utf8'));
+  const parsed = require('dotenv').parse(fs.readFileSync(envPath, 'utf8'));
+  assertNoRetiredEnvKeys(parsed, envPath);
+
+  return parsed;
 }
 
 /**
@@ -358,7 +378,11 @@ function deliveringEntry(key, target) {
  * there is): a key rides down when some entry claims it — by name or by
  * pattern — names this target, and sits in a file group. The TARGET layer
  * passes through unfiltered: placing a key in the target's own .env IS the
- * targeting. `deliverAs` renames on arrival in EVERY layer (the per-target GA4
+ * targeting. A key NO entry claims at all is the consumer's own
+ * ([#835](https://github.com/Omega-JS-Stack/omega/issues/835)) and rides down
+ * to every target: the schema never heard of it, so it names no target to be
+ * filtered by, and a consumer who wants one on a single target has that
+ * target's own .env. `deliverAs` renames on arrival in EVERY layer (the per-target GA4
  * secrets), so a human writing the brand-level name in the target's own .env
  * gets the one delivered key, overriding the brand's.
  *
@@ -398,7 +422,12 @@ function composeTargetEnv({ targetDir, target, environment = envEnvironment() })
   for (const { file, layer, filtered } of files) {
     const claimed = {};
     for (const [key, value] of Object.entries(parseEnvFile(file))) {
-      if (filtered && !deliveringEntry(key, target)) continue;
+      // The filter is on DECLARED keys: an entry that does not name this
+      // target keeps its key home. A key the schema knows nothing about is the
+      // CONSUMER's own (#835), has no target of its own to be judged by, and
+      // rides down to every target; a consumer who wants one on a single
+      // target puts it in that target's .env, which passes unfiltered anyway.
+      if (filtered && envSchemaEntry(key) && !deliveringEntry(key, target)) continue;
       claimed[key] = value;
     }
 

package/dist/vendor/config/environment.js

@@ -0,0 +1,189 @@
+/**
+ * environment.js, the ONE environment module every OMEGA target answers from
+ * ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)).
+ *
+ * Four calls, one implementation, one call form everywhere: `getEnvironment()`
+ * plus `isDevelopment()` / `isProduction()` / `isTesting()`, mixed into a
+ * framework's Manager with `attachTo()`. @omega.js/backend, @omega.js/desktop,
+ * @omega.js/extension and @omega.js/web each carried their own copy of this
+ * logic, each with its own signal list and its own DEFAULT, and the copies
+ * disagreed: desktop answered `production` with no signal while the extension
+ * answered `development`, so a desktop dev boot baked itself as a production
+ * artifact.
+ *
+ * The fix is by construction, and it is the whole contract:
+ *
+ *   ONE INPUT. On Node it is `process.env.OMEGA_ENVIRONMENT`. In a browser
+ *   context (a desktop renderer, an extension view, a web page), which can read
+ *   neither env nor files, it is `config.environment`, the build fact every
+ *   surface already bakes into `OMEGA_BUILD_JSON.config`
+ *   ([#896](https://github.com/Omega-JS-Stack/omega/issues/896)), reached as
+ *   `this.config.environment` off the Manager the call is made on. Nothing else
+ *   is consulted: no `app.isPackaged`, no `manifest.update_url`, no `NODE_ENV`,
+ *   no terminal sniffing.
+ *
+ *   NO DEFAULT. A context with no input does not guess a safe answer, it throws
+ *   and names the variable. A guessed environment is how a dev build ships as
+ *   production and how a production build talks to an emulator, and both of
+ *   those failures are silent until a user finds them.
+ *
+ * Who SETS the one input is each target's own business, at the one place it
+ * already resolves its config, through `setEnvironment()` below (the only
+ * writer, so a fourth word can never reach the variable): the backend's boot
+ * takes the .env cascade's ambient answer, the desktop and extension build
+ * Managers take `production` under their build-mode flag and the ambient answer
+ * otherwise, and web's verbs name their own (`omega build` is production,
+ * `omega dev` is development).
+ *
+ * This module requires NOTHING. It is bundled into browser artifacts (the
+ * desktop renderer, every extension bundle) and vendored into
+ * @omega.js/client, so a single `node:fs` at the top would break all three.
+ */
+
+// The ONE environment vocabulary, and the home of it. Every `.env.<name>`
+// overlay is suffixed with one of these, every `config/omega.<name>.json5`
+// overlay is named with one of these, every framework's environment answer is
+// one of these, and nothing anywhere spells a fourth
+// ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)).
+const ENV_ENVIRONMENTS = ['development', 'testing', 'production'];
+
+// The ONE input's name, spelled once so every error message and every writer
+// reads it from here.
+const ENVIRONMENT_VAR = 'OMEGA_ENVIRONMENT';
+
+/**
+ * The Node input: the environment variable, when this context has a `process`
+ * at all (a browser bundle does not).
+ * @returns {string|undefined} the raw value.
+ */
+function fromProcess() {
+  return typeof process !== 'undefined' && process.env
+    ? process.env[ENVIRONMENT_VAR]
+    : undefined;
+}
+
+/**
+ * The browser input: the build fact baked into `OMEGA_BUILD_JSON.config`,
+ * reached through the Manager the call was made on.
+ * @param {object} [context] - the `this` of the call.
+ * @returns {string|undefined} the raw value.
+ */
+function fromBakedConfig(context) {
+  return context && context.config ? context.config.environment : undefined;
+}
+
+/**
+ * The running environment, from the one input.
+ *
+ * @this {object} [context] - a Manager carrying the baked `config`.
+ * @returns {'development'|'testing'|'production'} exactly one of the three.
+ * @throws {Error} when neither input names one of the three.
+ */
+function getEnvironment() {
+  const value = fromProcess() || fromBakedConfig(this);
+
+  if (!ENV_ENVIRONMENTS.includes(value)) {
+    // Loud by design: every lane sets the input, so reaching here is a broken
+    // lane, and any answer invented here would be wrong somewhere it matters.
+    throw new Error(`${ENVIRONMENT_VAR} is not set to one of ${ENV_ENVIRONMENTS.join(' | ')} (got ${value === undefined ? 'nothing' : JSON.stringify(value)}). On Node the lane that boots or builds this target sets it; in a browser context it is the baked OMEGA_BUILD_JSON.config.environment, which every OMEGA build writes.`);
+  }
+
+  return value;
+}
+
+/**
+ * @this {object} [context] - a Manager carrying the baked `config`.
+ * @returns {boolean} true only in development (never in testing).
+ */
+function isDevelopment() {
+  return getEnvironment.call(this) === 'development';
+}
+
+/**
+ * @this {object} [context] - a Manager carrying the baked `config`.
+ * @returns {boolean} true only in production, a real positive check.
+ */
+function isProduction() {
+  return getEnvironment.call(this) === 'production';
+}
+
+/**
+ * @this {object} [context] - a Manager carrying the baked `config`.
+ * @returns {boolean} true only while a test lane runs this process.
+ */
+function isTesting() {
+  return getEnvironment.call(this) === 'testing';
+}
+
+/**
+ * The ONE writer of the one input, so every lane that names an environment
+ * spells it the same way and a fourth word is refused at the moment it is
+ * written rather than at the moment it is read.
+ *
+ * @param {string} value - one of the three names.
+ * @returns {string} the same value, so a caller can name it and pass it on.
+ * @throws {Error} when it is not one of the three.
+ */
+function setEnvironment(value) {
+  if (!ENV_ENVIRONMENTS.includes(value)) {
+    throw new Error(`${ENVIRONMENT_VAR} cannot be set to ${value === undefined ? 'nothing' : JSON.stringify(value)}: it is one of ${ENV_ENVIRONMENTS.join(' | ')}.`);
+  }
+
+  process.env[ENVIRONMENT_VAR] = value;
+
+  return value;
+}
+
+/**
+ * The environment a NODE BUILD LANE is for, decided once for the two frameworks
+ * whose build Manager names it at load (@omega.js/desktop and
+ * @omega.js/extension, which carried byte-identical copies of this expression).
+ * Two rules, no sniffing:
+ *
+ *   1. The build-mode flag is the lane SAYING it produces a production artifact
+ *      (`omega build` sets `OMEGA_BUILD_MODE`), and it wins over anything
+ *      inherited, so a production build spawned from a test run still bakes
+ *      production.
+ *   2. Otherwise a lane that already named one keeps it (the test runners spawn
+ *      their children with `testing`), and a bare dev boot is `development`.
+ *
+ * It DECIDES; the caller writes it with `setEnvironment()`, which stays the one
+ * writer. This is the only default anywhere near this module, and it belongs to
+ * a build lane alone: a READER still gets no default at all.
+ *
+ * @param {boolean} buildMode - The lane's build-mode flag (`Manager.isBuildMode()`).
+ * @returns {'development'|'testing'|'production'} the word that lane is for.
+ */
+function buildLaneEnvironment(buildMode) {
+  return buildMode ? 'production' : (fromProcess() || 'development');
+}
+
+/**
+ * Mix the surface into a Manager constructor's prototype AND the constructor
+ * itself, so `Manager.isTesting()` works statically too. The idiom every
+ * framework already attaches with.
+ *
+ * @param {Function} Manager - the constructor to extend.
+ */
+function attachTo(Manager) {
+  Manager.prototype.getEnvironment = getEnvironment;
+  Manager.prototype.isDevelopment  = isDevelopment;
+  Manager.prototype.isProduction   = isProduction;
+  Manager.prototype.isTesting      = isTesting;
+  Manager.getEnvironment = getEnvironment;
+  Manager.isDevelopment  = isDevelopment;
+  Manager.isProduction   = isProduction;
+  Manager.isTesting      = isTesting;
+}
+
+module.exports = {
+  ENV_ENVIRONMENTS,
+  ENVIRONMENT_VAR,
+  getEnvironment,
+  isDevelopment,
+  isProduction,
+  isTesting,
+  setEnvironment,
+  buildLaneEnvironment,
+  attachTo,
+};

package/dist/vendor/config/hooks.js

@@ -19,9 +19,11 @@
  * add their own `config/hooks/` ignore line.
  *
  * Resolution walks the same hierarchy as the .env cascade: the brand root's
- * own `config/hooks/` first, then the company root's (via the
- * .omega/company.json stamp) — so a company-wide hook covers every brand and
- * a single brand can still override it. Hooks are plain CJS modules whose
+ * own `config/hooks/` first, then the company tree's (the parent brand's
+ * `company/config/hooks/`, resolved through company.js), so a company-wide hook
+ * covers every brand and a single brand can still override it. It is the ONE
+ * inheritance rule (#677) applied to one more relative path, and costs no code
+ * of its own. Hooks are plain CJS modules whose
  * `module.exports` IS the hook function; call-site docs define each hook's
  * signature and return contract.
  */
@@ -29,7 +31,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { readCompanyRoot } = require('./company.js');
+const { resolveCompany } = require('./company.js');
 
 // Hook points are code-owned kebab-case path constants ('account/password') —
 // enforce the shape so a typo'd or traversal-shaped path fails loudly.
@@ -44,7 +46,7 @@ function hookFile(root, hookPath) {
 
 /**
  * Resolve a hook point to the file that defines it: the brand root's own
- * `config/hooks/<hookPath>.js`, else the company root's (company.json stamp).
+ * `config/hooks/<hookPath>.js`, else the company tree's.
  *
  * @param {string} startRoot - Brand (or standalone-project) root
  * @param {string} hookPath - Call-site-mirroring hook point, e.g. 'account/password'
@@ -55,13 +57,13 @@ function resolveHook(startRoot, hookPath) {
     throw new Error(`Invalid hook path ${JSON.stringify(hookPath)} — kebab-case segments joined by '/', e.g. 'account/password'`);
   }
 
-  const roots = [path.resolve(startRoot)];
-  const companyRoot = readCompanyRoot(roots[0]);
-  if (companyRoot && companyRoot !== roots[0]) {
-    roots.push(companyRoot);
-  }
+  const brandRoot = path.resolve(startRoot);
+  const own = hookFile(brandRoot, hookPath);
+  if (fs.existsSync(own)) return own;
 
-  return roots.map((root) => hookFile(root, hookPath)).find((file) => fs.existsSync(file)) || null;
+  // One relative path, one rule: whatever the child lacks resolves from the
+  // company tree at the same place.
+  return resolveCompany(brandRoot).file(path.relative(brandRoot, own));
 }
 
 /**