@omega.js/extension 0.1.0

package/dist/vendor/devkit/deploy-record.js

@@ -0,0 +1,180 @@
+/**
+ * The per-brand deploy record — `<target>` under the `deploy` section of
+ * `.omega/state.json` (gitignored, per-machine). Multi-instance targets key
+ * per target: the primary stays `<target>`, other instances record under
+ * `<target>:<id>` (see deployKey).
+ *
+ * Written by every framework's deploy verb on success; read by the
+ * manager's testing service to tell "never deployed" (live-URL checks skip
+ * with a nudge) from "deployed but down" (an honest error). A record-less
+ * brand whose live URL answers gets ADOPTED — recorded on the spot — so
+ * fresh clones of long-deployed brands self-heal on their first manage run
+ * (Ian 2026-07-17).
+ *
+ * state.json is the ONE per-machine record file, sectioned per fact kind
+ * (#479): future record-shaped facts join it as sibling top-level sections, so
+ * this module reads and writes ONLY `deploy` and passes every other section
+ * through verbatim — including the config-shaped keys an unmigrated brand
+ * still carries from the retired state CONTENT (#434), which belong to the
+ * state-retirement migration and to nothing here.
+ *
+ * The record spent 0.45.0 in a `.omega/deploys.json` of its own (#449); a
+ * brand still carrying that file has it adopted here, once and loudly.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const jetpack = require('fs-jetpack');
+
+const Logger = require('./logger.js');
+const { findBrandRoot } = require('./local.js');
+
+const logger = new Logger('deploy-record');
+
+function stateFile(dir) {
+  return path.join(findBrandRoot(dir), '.omega', 'state.json');
+}
+
+/**
+ * Read the machine state with its `deploy` section resolved, folding in the
+ * interim `.omega/deploys.json` (#449) on the way — one-time and LOUD, so a
+ * brand that deployed on 0.45.0 keeps its stamps and the operator sees where
+ * they went. Records already in state.json WIN: newest write, newest home.
+ *
+ * A brand whose state.json already carries a `deploy` key is home — the
+ * records are read in place, silently, whatever else the file still holds.
+ *
+ * Rewrites the files it touches, so callers hold the lock.
+ *
+ * @param {string} file - The state.json path.
+ * @returns {Object} The machine state, `deploy` section included.
+ */
+function loadState(file) {
+  const state = jetpack.read(file, 'json') || {};
+  const records = state.deploy || {};
+
+  const deploysFile = path.join(path.dirname(file), 'deploys.json');
+  const deploys = jetpack.read(deploysFile, 'json');
+
+  state.deploy = deploys ? { ...deploys, ...records } : records;
+  if (!deploys) return state;
+
+  // The new home lands before the old file goes: a crash between the two
+  // writes must never leave the records with no file at all.
+  jetpack.write(file, state, { jsonIndent: 2 });
+  jetpack.remove(deploysFile);
+
+  if (Object.keys(deploys).length > 0) {
+    logger.log(`Adopted ${describe(deploys)} from .omega/deploys.json into .omega/state.json — the old file was removed.`);
+  }
+
+  return state;
+}
+
+/**
+ * "1 deploy record" / "3 deploy records" — the adoption line's subject.
+ * @param {Object} records - key → record.
+ * @returns {string}
+ */
+function describe(records) {
+  const count = Object.keys(records).length;
+  return `${count} deploy record${count === 1 ? '' : 's'}`;
+}
+
+/**
+ * Record key for a target's instance (multi-instance targets): the primary
+ * keeps today's bare target key (zero breaking change — existing records
+ * stay valid); any other instance keys `<target>:<id>`, matching the
+ * per-target deploy model (each target deploys its own instance).
+ * @param {string} target - Target key (web/backend/desktop/extension)
+ * @param {string} [instance] - Instance id ('main' or absent = the primary)
+ * @returns {string} The deploy-record key
+ */
+function deployKey(target, instance) {
+  return instance && instance !== 'main' ? `${target}:${instance}` : target;
+}
+
+/**
+ * Run fn under a best-effort cross-process lock on the records file, so two
+ * targets deploying in parallel can't drop each other's record in the
+ * read-modify-write. Lock contention waits briefly; a stale lock (owner
+ * crashed) is stolen after 5s; on timeout we proceed unlocked — a deploy
+ * must never fail over its bookkeeping.
+ * @param {string} file - Records file path.
+ * @param {function} fn - Critical section.
+ * @returns {*} fn's result.
+ */
+function withStateLock(file, fn) {
+  const lockDir = `${file}.lock`;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  const deadline = Date.now() + 2000;
+  let locked = false;
+  while (Date.now() < deadline) {
+    try {
+      fs.mkdirSync(lockDir);
+      locked = true;
+      break;
+    } catch (e) {
+      try {
+        if (Date.now() - fs.statSync(lockDir).mtimeMs > 5000) {
+          fs.rmSync(lockDir, { recursive: true, force: true });
+          continue;
+        }
+      } catch (statError) {
+        continue; // Lock vanished between mkdir and stat — retry immediately
+      }
+      // Synchronous 25ms wait (no async surface here by design)
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    if (locked) {
+      fs.rmSync(lockDir, { recursive: true, force: true });
+    }
+  }
+}
+
+/**
+ * Record a successful deploy for a target.
+ *
+ * @param {Object} options
+ * @param {string} options.dir - Any directory inside the brand (target or root)
+ * @param {string} options.target - Target key (web/backend/desktop/extension)
+ * @param {string} [options.instance] - Instance id; non-main instances record
+ *   under their own `<target>:<id>` key (per-target deploy records)
+ * @param {Object} [options.detail] - Extra fields (method, adopted, …)
+ * @returns {Object} The written record
+ */
+function recordDeploy(options) {
+  const file = stateFile(options.dir);
+  const key = deployKey(options.target, options.instance);
+
+  return withStateLock(file, () => {
+    const state = loadState(file);
+
+    state.deploy[key] = { at: new Date().toISOString(), ...(options.detail || {}) };
+    jetpack.write(file, state, { jsonIndent: 2 });
+
+    return state.deploy[key];
+  });
+}
+
+/**
+ * The recorded deploy for a target's instance — null when the brand has
+ * never deployed it from this machine (and no manage run has adopted a live
+ * site yet).
+ *
+ * @param {Object} options - { dir, target, instance? }
+ * @returns {Object|null}
+ */
+function readDeployRecord(options) {
+  const file = stateFile(options.dir);
+  // Under the lock because the read is also where a legacy record is adopted
+  const state = withStateLock(file, () => loadState(file));
+  return state.deploy[deployKey(options.target, options.instance)] || null;
+}
+
+module.exports = { recordDeploy, readDeployRecord, deployKey };

package/dist/vendor/devkit/deploy.js

@@ -0,0 +1,286 @@
+/**
+ * Deploy executor — the ONE dispatch path for deliberate deploys (D13/D9).
+ *
+ * Commits never auto-publish: scaffolded workflows carry no push triggers, so
+ * publishing is an explicit dispatch of the SAME CI build — from the local
+ * CLI (`omega deploy`), a server-side action (the admin post route's
+ * content-publish), or any plain HTTP caller. All three converge here: a
+ * GitHub REST `workflow_dispatch` call (native fetch, no gh-CLI dependency —
+ * Cloud Functions and laptops share the code path; locally the token can
+ * still come from `gh auth token`).
+ */
+const path = require('node:path');
+const { execSync, execFileSync } = require('node:child_process');
+
+const { findBrandRoot, discoverTargets, frameworkPackagesOf } = require('./local.js');
+
+const API_BASE = 'https://api.github.com';
+
+/**
+ * Parse a git remote URL into { owner, repo }.
+ * Handles ssh (git@github.com:o/r.git), https (https://github.com/o/r.git),
+ * and .git-less forms.
+ * @param {string} url - remote URL
+ * @returns {{ owner: string, repo: string }|null}
+ */
+function parseRemoteUrl(url) {
+  const match = (url || '').trim().match(/github\.com[/:]([^/]+)\/([^/\s]+?)(?:\.git)?$/);
+  if (!match) return null;
+  return { owner: match[1], repo: match[2] };
+}
+
+/**
+ * The repo a CI dispatch addresses: the BRAND's own repo, from its config
+ * ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)). Every framework's
+ * deploy verb asks this instead of `resolveRepo` above, because a git remote
+ * answers the repo the working tree sits in: inside a brand monorepo nested in
+ * another repo (a brand inside the framework monorepo, a target checked out
+ * under someone else's tree) that is the ENCLOSING repo, so the dispatch went to
+ * a workflow that was never there.
+ *
+ * Half an address addresses nothing, so it throws rather than POST to
+ * `undefined/<name>`.
+ *
+ * @param {object} config - Composed omega config for the target being deployed.
+ * @returns {{ owner: string, repo: string }} the brand repo's owner and bare name
+ * @throws {Error} when the config names no repo
+ */
+function dispatchRepo(config) {
+  const { brandRepo } = require('../config/index.js');
+  const { owner, name } = brandRepo(config);
+
+  if (!owner || !name) {
+    throw new Error('Could not determine the brand repo to dispatch on. Set repo.providers.github.org (and repo.providers.github.repo when the repo name is not <brand.id>-omega) in config/omega.json5.');
+  }
+
+  return { owner, repo: name };
+}
+
+/**
+ * Resolve the GitHub repo for a working directory from its origin remote.
+ * @param {object} [options]
+ * @param {string} [options.cwd] - repo directory (default: process.cwd())
+ * @param {string} [options.remote] - remote name (default: origin)
+ * @param {function} [options.execFn] - injectable exec (tests)
+ * @returns {{ owner: string, repo: string }}
+ */
+function resolveRepo(options = {}) {
+  const execFn = options.execFn || ((cmd, opts) => execSync(cmd, opts).toString());
+  const url = execFn(`git config --get remote.${options.remote || 'origin'}.url`, {
+    cwd: options.cwd || process.cwd(),
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  const parsed = parseRemoteUrl(url);
+  if (!parsed) {
+    throw new Error(`Cannot parse a GitHub repo from remote url: ${String(url).trim() || '(none)'}`);
+  }
+  return parsed;
+}
+
+/**
+ * Resolve a GitHub token: GH_TOKEN → GITHUB_TOKEN → `gh auth token`.
+ * @param {object} [options]
+ * @param {object} [options.env] - env map (default: process.env)
+ * @param {function} [options.execFn] - injectable exec (tests)
+ * @returns {string|null}
+ */
+function resolveToken(options = {}) {
+  const env = options.env || process.env;
+  if (env.GH_TOKEN) return env.GH_TOKEN;
+  if (env.GITHUB_TOKEN) return env.GITHUB_TOKEN;
+
+  const execFn = options.execFn || ((cmd, opts) => execSync(cmd, opts).toString());
+  try {
+    const token = execFn('gh auth token', { stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    return token || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Build a workflow_dispatch plan — the exact REST call a deploy will make.
+ * This IS the dry-run output: everything except the send.
+ * @param {object} options
+ * @param {string} options.owner - repo owner
+ * @param {string} options.repo - repo name
+ * @param {string} options.workflow - workflow file name (e.g. build.yml)
+ * @param {string} [options.ref] - branch/tag to run on (default: main)
+ * @param {object} [options.inputs] - workflow_dispatch inputs
+ * @returns {{ method: string, url: string, body: object, runsUrl: string }}
+ */
+function buildDispatch(options) {
+  for (const key of ['owner', 'repo', 'workflow']) {
+    if (!options[key]) throw new Error(`buildDispatch: missing ${key}`);
+  }
+  const body = { ref: options.ref || 'main' };
+  if (options.inputs && Object.keys(options.inputs).length > 0) body.inputs = options.inputs;
+
+  return {
+    method: 'POST',
+    url: `${API_BASE}/repos/${options.owner}/${options.repo}/actions/workflows/${options.workflow}/dispatches`,
+    body: body,
+    runsUrl: `https://github.com/${options.owner}/${options.repo}/actions/workflows/${options.workflow}`,
+  };
+}
+
+/**
+ * Send a dispatch plan to GitHub (204 = accepted).
+ * @param {object} plan - buildDispatch() result
+ * @param {object} options
+ * @param {string} options.token - GitHub token
+ * @param {function} [options.fetchFn] - injectable fetch (tests)
+ * @returns {Promise<object>} the plan, on success
+ */
+async function dispatchWorkflow(plan, options = {}) {
+  if (!options.token) {
+    throw new Error('No GitHub token — set GH_TOKEN in .env or sign in with `gh auth login`');
+  }
+  const fetchFn = options.fetchFn || fetch;
+  const response = await fetchFn(plan.url, {
+    method: plan.method,
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${options.token}`,
+      'X-GitHub-Api-Version': '2022-11-28',
+      'User-Agent': 'omega-deploy',
+    },
+    body: JSON.stringify(plan.body),
+  });
+
+  if (response.status !== 204) {
+    const text = await response.text().catch(() => '');
+    throw new Error(`workflow_dispatch failed (${response.status}): ${text || response.statusText || 'unknown error'}`);
+  }
+  return plan;
+}
+
+/**
+ * The one deploy path: resolve repo + token, build the plan, dispatch — or
+ * return the plan untouched when dryRun is set.
+ * @param {object} options
+ * @param {string} options.workflow - workflow file name
+ * @param {string} [options.cwd] - repo dir for remote resolution
+ * @param {string} [options.owner] - explicit owner (skips git resolution)
+ * @param {string} [options.repo] - explicit repo (skips git resolution)
+ * @param {string} [options.ref] - branch (default main)
+ * @param {object} [options.inputs] - workflow inputs
+ * @param {boolean} [options.dryRun] - build the plan but never send
+ * @param {object} [options.env] - env map for token resolution
+ * @param {function} [options.fetchFn] - injectable fetch
+ * @param {function} [options.execFn] - injectable exec
+ * @returns {Promise<{ plan: object, dispatched: boolean }>}
+ */
+async function deployViaDispatch(options) {
+  const target = options.owner && options.repo
+    ? { owner: options.owner, repo: options.repo }
+    : resolveRepo({ cwd: options.cwd, execFn: options.execFn });
+
+  const plan = buildDispatch({
+    owner: target.owner,
+    repo: target.repo,
+    workflow: options.workflow,
+    ref: options.ref,
+    inputs: options.inputs,
+  });
+
+  if (options.dryRun) {
+    return { plan, dispatched: false };
+  }
+
+  const token = options.token || resolveToken({ env: options.env, execFn: options.execFn });
+  await dispatchWorkflow(plan, { token, fetchFn: options.fetchFn });
+  return { plan, dispatched: true };
+}
+
+/**
+ * Find every `file:` @omega.js spec in the brand tree. npm resolves the
+ * WHOLE workspace tree on any install, so one linked sibling target breaks a
+ * CI install even when the deploying target is clean (the cp194 lesson —
+ * linking is tree-wide, so detection is too). Deploy verbs use this to
+ * AUTO-SELECT their local-artifact lane (mirrored rule, Ian 2026-07-20:
+ * a linked brand ships the LOCAL framework — build here, ship the artifact;
+ * CI dispatch is only for registry-clean trees).
+ * @param {object} [options]
+ * @param {string} [options.dir] - Any directory inside the brand (default cwd).
+ * @returns {string[]} One line per offender: `<manifest> → <name>: <spec>`.
+ */
+function findLocalSpecs(options = {}) {
+  const brandRoot = findBrandRoot(options.dir || process.cwd());
+  const offenders = [];
+
+  for (const targetDir of discoverTargets(brandRoot)) {
+    for (const entry of frameworkPackagesOf(targetDir)) {
+      if (entry.spec.startsWith('file:')) {
+        const manifest = path.relative(brandRoot, path.join(targetDir, 'package.json')) || 'package.json';
+        offenders.push(`${manifest} → ${entry.name}: ${entry.spec}`);
+      }
+    }
+  }
+
+  return offenders;
+}
+
+/**
+ * Throw when the brand tree carries `file:` @omega.js specs — for lanes with
+ * no local-artifact fallback where dispatching would only burn a CI run.
+ * @param {object} [options]
+ * @param {string} [options.dir] - Any directory inside the brand (default cwd).
+ * @throws {Error} Listing every file:-spec'd @omega.js dependency, per target.
+ */
+function assertNoLocalSpecs(options = {}) {
+  const offenders = findLocalSpecs(options);
+  if (offenders.length > 0) {
+    throw new Error(
+      'Local file: packages are linked somewhere in this brand — CI cannot install them.\n'
+      + `  ${offenders.join('\n  ')}\n`
+      + 'Deploy from the local-artifact lane, or restore registry specs first (omega i live).'
+    );
+  }
+}
+
+/**
+ * Commit + push the working tree before a dispatch deploy (D13: the push
+ * itself triggers NOTHING — scaffolded workflows carry no push triggers).
+ * Plain git via argument arrays: universal on consumer machines and
+ * injection-safe for the message.
+ * @param {object} [options]
+ * @param {string} [options.cwd] - Repo directory (default process.cwd()).
+ * @param {string} [options.message] - Commit message (default 'Deploy').
+ * @param {object} [options.logger] - Logger with log (silent when omitted).
+ */
+function syncWorkingTree(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const message = options.message || 'Deploy';
+
+  execFileSync('git', ['add', '-A'], { cwd, stdio: 'inherit' });
+
+  // `git diff --cached --quiet` exits 1 exactly when something is staged
+  let hasStaged = false;
+  try {
+    execFileSync('git', ['diff', '--cached', '--quiet'], { cwd, stdio: 'ignore' });
+  } catch (e) {
+    hasStaged = true;
+  }
+
+  if (hasStaged) {
+    execFileSync('git', ['commit', '-m', message], { cwd, stdio: 'inherit' });
+  } else if (options.logger) {
+    options.logger.log('Working tree clean — nothing to commit');
+  }
+
+  execFileSync('git', ['push'], { cwd, stdio: 'inherit' });
+}
+
+module.exports = {
+  parseRemoteUrl,
+  dispatchRepo,
+  resolveRepo,
+  resolveToken,
+  buildDispatch,
+  dispatchWorkflow,
+  deployViaDispatch,
+  findLocalSpecs,
+  assertNoLocalSpecs,
+  syncWorkingTree,
+};

package/dist/vendor/devkit/empty-modules-plugin.js

@@ -0,0 +1,64 @@
+/**
+ * emptyModulesPlugin — every specifier in the list answers ONE empty CommonJS
+ * module ([#737](https://github.com/Omega-JS-Stack/omega/issues/737), part of
+ * [#128](https://github.com/Omega-JS-Stack/omega/issues/128)).
+ *
+ * A BROWSER bundle still receives imports of things a browser has no version
+ * of: libraries reach for `fs`, `path` or `crypto` on code paths their browser
+ * builds never take, and esbuild has no answer for them, so the build fails on
+ * an import nothing will ever execute. webpack spelled the answer
+ * `resolve.fallback: { fs: false, … }`; this is the same answer as an esbuild
+ * resolve hook, and it is shared because every browser-targeting framework
+ * needs it (@omega.js/desktop's renderer and @omega.js/extension's browser
+ * bundles both pass their own list).
+ *
+ * The substitution is UNCONDITIONAL: a listed name is answered, never resolved
+ * first. That is the whole point for a name that WOULD resolve — `electron`
+ * resolves fine from a desktop project, and resolving it would inline the real
+ * package into a renderer that must never reach it. A name on this list is a
+ * name the caller has decided the bundle may not contain, whatever is installed.
+ *
+ * Anything NOT on the list is untouched and fails with esbuild's normal
+ * resolution error, which is what a genuine missing dependency should do.
+ */
+
+const NAMESPACE = 'omega-empty-module';
+
+/**
+ * Regex-escape a module name so a specifier is matched literally.
+ * @param {string} name - the module name
+ * @returns {string}
+ */
+function escape(name) {
+  return name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * @param {string[]} names - the specifiers to answer with an empty module
+ * @returns {object} the esbuild plugin
+ */
+function emptyModulesPlugin(names) {
+  if (!Array.isArray(names) || names.length === 0) {
+    // Registering the hook with nothing to answer means the caller believes it
+    // shimmed something and did not — the exact bug this plugin exists to stop.
+    throw new Error('[devkit empty-modules] names must be a non-empty array of specifiers to answer with an empty module');
+  }
+
+  // `node:` prefixed specifiers name the same built-ins and must shim the same.
+  const filter = new RegExp(`^(node:)?(${names.map(escape).join('|')})$`);
+
+  return {
+    name: 'omega-empty-modules',
+    setup(build) {
+      build.onResolve({ filter }, (args) => ({ path: args.path, namespace: NAMESPACE }));
+      // CommonJS, so a named import of anything reads as undefined at runtime
+      // rather than failing the build — webpack's `false` fallback did the same.
+      build.onLoad({ filter: /.*/, namespace: NAMESPACE }, () => ({
+        contents: 'module.exports = {};',
+        loader: 'js',
+      }));
+    },
+  };
+}
+
+module.exports = { emptyModulesPlugin, NAMESPACE };

package/dist/vendor/devkit/env-watch.js

@@ -0,0 +1,132 @@
+/**
+ * env-watch — the `.env` chain as a WATCH INPUT for the dev lanes
+ * ([#681](https://github.com/Omega-JS-Stack/omega/issues/681)).
+ *
+ * The backend's stage watch has treated the cascade as an input since #678: an
+ * edit to the brand root's `.env` re-stages `dist/.env` and the running
+ * emulator picks it up (`envWatchInputs`,
+ * packages/backend/src/cli/utils/stage-functions.js). Web, desktop and
+ * extension read the cascade once at CLI/gulp boot and never noticed an edit —
+ * one target live-reloaded env, three did not. This is that same resolution for
+ * the three process.env lanes.
+ *
+ * Every layer of the chain is watched — company ← brand ← target — and each
+ * layer is TWO files, its `.env` and the `.env.<environment>` overlay that wins
+ * over it (#586), exactly the set `loadEnv` reads. DIRECTORIES are watched, not
+ * the files: an editor's save replaces the inode (a file watch does not survive
+ * it), and a layer's `.env` may not exist yet.
+ *
+ * Values NEVER reach a log line — a `.env` is all secrets, so the one line a
+ * reload prints names the FILE that changed.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveEnvChain, envLayerFiles, envEnvironment, reloadEnv } = require('../config/index.js');
+
+// Long enough to collapse an editor's save burst into one reload — the same
+// settle the other dev watchers use.
+const DEBOUNCE_MS = 250;
+
+/**
+ * The `.env` files a dev watcher treats as inputs, weakest layer first: each
+ * layer of the chain and the `.env.<environment>` overlay that wins over it.
+ * Existence is not checked here — a layer's file can appear mid-session.
+ *
+ * Named for the CHAIN it resolves, because the backend's stage watch has its
+ * own `envWatchInputs` (stage-functions.js) with a different contract — brand
+ * and company only, no overlays, no target layer
+ * ([#723](https://github.com/Omega-JS-Stack/omega/issues/723)).
+ *
+ * @param {string} projectDir - The target root (its .env is the local layer).
+ * @param {object} [options]
+ * @param {string} [options.environment] - The environment whose overlay counts
+ *   (defaults to the running one, the same answer loadEnv resolves).
+ * @returns {Array<{ layer: 'company'|'brand'|'target', path: string }>} Absolute paths.
+ */
+function envChainWatchInputs(projectDir, { environment = envEnvironment() } = {}) {
+  const chain = resolveEnvChain(projectDir);
+
+  return [
+    ...envLayerFiles(chain.company, environment).map((file) => ({ layer: 'company', path: file })),
+    ...envLayerFiles(chain.brand, environment).map((file) => ({ layer: 'brand', path: file })),
+    ...envLayerFiles(chain.local, environment).map((file) => ({ layer: 'target', path: file })),
+  ];
+}
+
+/**
+ * Watch the whole `.env` chain and reload the cascade into process.env on a
+ * change, so the NEXT rebuild reads the new values.
+ *
+ * SCOPE, exactly: a NEW key AND an EDITED value both land on that next rebuild,
+ * and a key dropped from the file is dropped from the process — what a file
+ * layer owns, the reload re-reads. A SHELL-set value always wins, whatever any
+ * file now says ([#724](https://github.com/Omega-JS-Stack/omega/issues/724)).
+ *
+ * One `fs.watch` per DIRECTORY (a standalone brand's layers can share one),
+ * filtered to the file names that directory contributes — a sibling file's
+ * churn never reloads anything. A directory that does not exist is skipped, the
+ * same rule the backend's stage watch applies.
+ *
+ * The reload is `reloadEnv`, which keeps the cascade's own precedence: the shell
+ * wins over every file, and a strictly stronger layer wins over a weaker one.
+ *
+ * @param {object} options
+ * @param {string} options.projectDir - The target root.
+ * @param {string} [options.target] - Target name ('web', 'desktop', 'extension')
+ *   — delivers the schema's `deliverAs` renames, exactly as the boot load did.
+ * @param {string} [options.environment] - The environment whose overlay is an
+ *   input (defaults to the running one).
+ * @param {function} [options.log] - Line logger (silent by default).
+ * @param {number} [options.debounceMs]
+ * @returns {{ inputs: Array<{ layer: string, path: string }>, close: function }}
+ */
+function watchEnvChain(options) {
+  const projectDir = options.projectDir;
+  const environment = options.environment || envEnvironment();
+  const log = options.log || (() => {});
+  const debounceMs = options.debounceMs || DEBOUNCE_MS;
+  const inputs = envChainWatchInputs(projectDir, { environment });
+
+  // dir → the file names that dir contributes to the chain
+  const byDir = new Map();
+  for (const input of inputs) {
+    const dir = path.dirname(input.path);
+    if (!byDir.has(dir)) byDir.set(dir, new Set());
+    byDir.get(dir).add(path.basename(input.path));
+  }
+
+  const watchers = [];
+  let timer = null;
+
+  for (const [dir, names] of byDir) {
+    if (!fs.existsSync(dir)) continue;
+
+    const watcher = fs.watch(dir, (event, filename) => {
+      if (!names.has(filename)) return;
+
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        reloadEnv(projectDir, { target: options.target, environment });
+        log(`Reloaded the .env cascade — ${path.join(dir, filename)} changed`);
+      }, debounceMs);
+    });
+
+    // UNREF'd: this watch rides ALONG with a dev lane, it never IS one. An
+    // open fs.watch holds the event loop, so a ref'd handle would leave gulp
+    // running forever after the app it served quits (desktop's `serve` ends
+    // its task on electron's exit, and nothing else keeps that process up).
+    watcher.unref();
+    watchers.push(watcher);
+  }
+
+  return {
+    inputs,
+    close: () => {
+      clearTimeout(timer);
+      for (const watcher of watchers) watcher.close();
+    },
+  };
+}
+
+module.exports = { envChainWatchInputs, watchEnvChain, DEBOUNCE_MS };