@omega.js/extension 0.1.0

package/dist/test/suites/build/deploy-dispatch.test.js

@@ -0,0 +1,76 @@
+// Build-layer test for commands/deploy.js's dispatch address (#799): the repo a
+// CI dispatch targets comes from the brand's config, never the git remote of
+// whatever repo the target sits in. Inside a brand nested in another repo (a
+// brand inside the framework monorepo) the remote is the ENCLOSING repo, so the
+// dispatch went to a workflow that was never there.
+
+const path = require('path');
+const fs   = require('fs');
+const os   = require('os');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const deployPath = path.join(__dirname, '..', '..', '..', 'commands', 'deploy.js');
+
+// A brand monorepo with one extension target: config/omega.json5 at the root,
+// the target under targets/, which is what the config walk looks for.
+function stageBrand(config) {
+  const brandRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-brand-'));
+  const targetDir = path.join(brandRoot, 'targets', 'extension');
+  fs.mkdirSync(path.join(brandRoot, 'config'), { recursive: true });
+  fs.mkdirSync(targetDir, { recursive: true });
+  fs.writeFileSync(path.join(brandRoot, 'config', 'omega.json5'), JSON.stringify(config));
+  return { brandRoot, targetDir };
+}
+
+function inTarget(targetDir, run) {
+  const previous = process.cwd();
+  process.chdir(targetDir);
+  try {
+    return run();
+  } finally {
+    process.chdir(previous);
+  }
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'deploy — the CI dispatch address comes from config',
+  tests: [
+    {
+      name: 'dispatch address: the CONFIG names the repo, never the enclosing checkout (#799)',
+      run: (ctx) => {
+        const { dispatchAddress } = require(deployPath);
+        const { brandRoot, targetDir } = stageBrand({
+          brand: { id: 'acme', name: 'Acme', url: 'https://acme.test' },
+          repo: { providers: { github: { org: 'Acme-Org' } } },
+          targets: { extension: {} },
+        });
+
+        try {
+          // The name is the derived `<brand.id>-omega` default (#809): the config
+          // declares an org and no repo of its own.
+          ctx.expect(inTarget(targetDir, dispatchAddress)).toEqual({ owner: 'Acme-Org', repo: 'acme-omega' });
+        } finally {
+          fs.rmSync(brandRoot, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'dispatch address: a config that names no repo REFUSES instead of dispatching somewhere (#799)',
+      run: (ctx) => {
+        const { dispatchAddress } = require(deployPath);
+        const { brandRoot, targetDir } = stageBrand({
+          brand: { id: 'acme', name: 'Acme', url: 'https://acme.test' },
+          targets: { extension: {} },
+        });
+
+        try {
+          ctx.expect(() => inTarget(targetDir, dispatchAddress)).toThrow(/brand repo to dispatch on/);
+        } finally {
+          fs.rmSync(brandRoot, { recursive: true, force: true });
+        }
+      },
+    },
+  ],
+});

package/dist/test/suites/build/distribute-task.test.js

@@ -0,0 +1,111 @@
+// Build-layer tests for gulp/tasks/distribute.js — the static-image lane (#259).
+//
+// distribute used to exclude `src/**/*.{jpg,jpeg,png,gif,svg,webp}` "because
+// imagemin handles them", but no imagemin task exists in this framework: a
+// consumer's images never reached dist/ and every project needed a build:pre
+// hook to copy them by hand. Images now copy as-is; the exclusions that DO have
+// an owning task (bundle, sass, the html task) stay.
+//
+// The task module reads its project from cwd at REQUIRE time, so each test
+// stages a temp project, chdirs into it, and requires the task fresh — the same
+// model as package-task.test.js.
+
+const path = require('path');
+const fs   = require('fs');
+const os   = require('os');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const SRC       = path.join(__dirname, '..', '..', '..');
+const TASK_PATH = path.join(SRC, 'gulp', 'tasks', 'distribute.js');
+
+// Stage a temp extension project. `files` is a relative-path → contents map.
+function stageProject(files) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-distribute-task-'));
+
+  fs.writeFileSync(path.join(tmp, 'package.json'), `{ "name": "staged-ext", "version": "3.1.4" }`);
+
+  for (const [relative, contents] of Object.entries(files || {})) {
+    const full = path.join(tmp, relative);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, contents);
+  }
+
+  return tmp;
+}
+
+// Run `fn(task)` with cwd pinned to `dir` and the task module loaded fresh.
+async function inProject(dir, fn) {
+  const oldCwd = process.cwd();
+  const flush = () => {
+    for (const key of Object.keys(require.cache)) {
+      if (key.startsWith(SRC + path.sep)) delete require.cache[key];
+    }
+  };
+
+  flush();
+  try {
+    process.chdir(dir);
+    return await fn(require(TASK_PATH));
+  } finally {
+    process.chdir(oldCwd);
+    flush();
+  }
+}
+
+module.exports = defineCases({
+  type: 'group',
+  layer: 'build',
+  description: 'distribute task — the static-image lane',
+  tests: [
+    {
+      name: 'consumer images reach dist/ byte-for-byte (no build:pre copy hook needed)',
+      run: async (ctx) => {
+        // A real PNG header — proves the bytes survive the stream untouched
+        const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x01]);
+        const tmp = stageProject({
+          'src/manifest.json': `{ manifest_version: 3, name: 'Staged' }`,
+          'src/assets/images/mascot.png': png,
+          'src/assets/images/logo.svg': '<svg xmlns="http://www.w3.org/2000/svg"></svg>',
+        });
+
+        try {
+          await inProject(tmp, async (task) => {
+            await task.distribute();
+
+            const mascot = path.join(tmp, 'dist', 'assets', 'images', 'mascot.png');
+            ctx.expect(fs.existsSync(mascot)).toBe(true);
+            ctx.expect(fs.readFileSync(mascot).equals(png)).toBe(true);
+            ctx.expect(fs.existsSync(path.join(tmp, 'dist', 'assets', 'images', 'logo.svg'))).toBe(true);
+          });
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'the exclusions with an owning task stay excluded (js, scss, views html)',
+      run: async (ctx) => {
+        const tmp = stageProject({
+          'src/manifest.json': `{ manifest_version: 3, name: 'Staged' }`,
+          'src/assets/js/components/popup/index.js': `// the bundle task owns this\n`,
+          'src/assets/css/main.scss': `// the sass task owns this\n`,
+          'src/views/popup/index.html': `<!-- the html task owns this -->\n`,
+        });
+
+        try {
+          await inProject(tmp, async (task) => {
+            await task.distribute();
+
+            ctx.expect(fs.existsSync(path.join(tmp, 'dist', 'assets', 'js', 'components', 'popup', 'index.js'))).toBe(false);
+            ctx.expect(fs.existsSync(path.join(tmp, 'dist', 'assets', 'css', 'main.scss'))).toBe(false);
+            ctx.expect(fs.existsSync(path.join(tmp, 'dist', 'views', 'popup', 'index.html'))).toBe(false);
+            // …and the manifest, which no other task copies, still lands
+            ctx.expect(fs.existsSync(path.join(tmp, 'dist', 'manifest.json'))).toBe(true);
+          });
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+  ],
+});

package/dist/test/suites/build/ensure-target.test.js

@@ -0,0 +1,141 @@
+// ensure-target + deploy-precheck — the two halves `omega setup` used to be
+// ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)): the local half
+// runs on every verb and is idempotent, the network half is a deploy precheck
+// with one opt-out flag.
+//
+// The fixture is a real consumer manifest that already satisfies the peer
+// dependencies, so nothing installs — a satisfied target installing nothing is
+// exactly what makes ensureTarget safe on every verb.
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const jetpack = require('fs-jetpack');
+
+const SRC = path.join(__dirname, '..', '..', '..');
+const Manager = require(path.join(SRC, 'build.js'));
+const { ensureTarget } = require(path.join(SRC, 'commands', 'lib', 'ensure-target.js'));
+const { deployPrecheck } = require(path.join(SRC, 'commands', 'lib', 'deploy-precheck.js'));
+const cli = require(path.join(SRC, 'cli.js'));
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const package = Manager.getPackage('main');
+
+// A consumer whose peer deps are already satisfied — the steady state.
+function stageConsumer() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-ensure-'));
+  const devDependencies = { [package.name]: `^${package.version}` };
+  for (const [name, ver] of Object.entries(package.peerDependencies || {})) {
+    devDependencies[name] = ver;
+  }
+  jetpack.write(path.join(tmp, 'package.json'), `${JSON.stringify({ name: 'staged-app', version: '1.0.0', devDependencies }, null, 2)}\n`);
+  return tmp;
+}
+
+module.exports = defineCases({
+  type: 'group',
+  layer: 'build',
+  description: 'ensure-target — the local half every verb runs (#675)',
+  tests: [
+    {
+      name: 'writes on a fresh target, no-op on the rerun',
+      run: async (ctx) => {
+        const tmp = stageConsumer();
+
+        try {
+          const first = await ensureTarget({ projectDir: tmp });
+
+          ctx.expect(first.written.length > 0).toBe(true);
+          ctx.expect(first.changed.some((line) => line.startsWith('package.json'))).toBe(true);
+          // No `.env` scaffolds ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)):
+          // a target .env is a human-only override; keys live in the brand root .env.
+          ctx.expect(jetpack.exists(path.join(tmp, '.env'))).toBe(false);
+
+          const manifest = jetpack.read(path.join(tmp, 'package.json'), 'json');
+          ctx.expect(manifest.private).toBe(true);
+          // The synced scripts never mention the retired command
+          ctx.expect(JSON.stringify(manifest.scripts).includes('omega setup')).toBe(false);
+
+          // The rerun adds nothing and syncs nothing. (One caveat, pre-existing
+          // and named in `merged`: config/omega.json5 is copied verbatim on the
+          // fresh pass and re-emitted in the defaults-merge's normalized form on
+          // the next one, so it converges on pass three.)
+          const second = await ensureTarget({ projectDir: tmp });
+          ctx.expect(second.written).toEqual([]);
+          ctx.expect(second.changed).toEqual([]);
+
+          const third = await ensureTarget({ projectDir: tmp });
+          ctx.expect(third).toEqual({ written: [], merged: [], changed: [] });
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'refuses a workspace root, loudly, without writing a single file (#699)',
+      run: async (ctx) => {
+        // The accident: `omega deploy` at a workspace root scaffolded a whole
+        // extension target into it — src/, hooks/, workflows, rewritten root
+        // scripts — before failing anyway. Parity with the same case in
+        // @omega.js/desktop's suite (#706).
+        const tmp = stageConsumer();
+        const manifestPath = path.join(tmp, 'package.json');
+        const manifest = jetpack.read(manifestPath, 'json');
+        manifest.workspaces = ['packages/*'];
+        jetpack.write(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+        const before = jetpack.read(manifestPath);
+
+        try {
+          let refusal = null;
+          try {
+            await ensureTarget({ projectDir: tmp });
+          } catch (e) {
+            refusal = e;
+          }
+
+          ctx.expect(refusal).toBeTruthy();
+          ctx.expect(refusal.message).toMatch(/refusing to scaffold into/);
+          ctx.expect(refusal.message).toMatch(/declares "workspaces"/);
+          ctx.expect(refusal.message.includes(tmp)).toBe(true);
+
+          // Nothing scaffolded, and the manifest is byte-identical.
+          ctx.expect(jetpack.list(tmp)).toEqual(['package.json']);
+          ctx.expect(jetpack.read(manifestPath)).toBe(before);
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'deploy precheck: --no-secrets skips every step, bare deploy runs it',
+      run: async (ctx) => {
+        const quiet = { log() {}, warn() {}, error() {} };
+        const ran = [];
+        const steps = [{ name: 'framework-freshness', run: () => { ran.push('framework-freshness'); } }];
+
+        const skipped = await deployPrecheck({ projectDir: '/tmp/x', options: { secrets: false }, logger: quiet, steps });
+        ctx.expect(skipped).toEqual({ skipped: 'opt-out' });
+        ctx.expect(ran).toEqual([]);
+
+        const result = await deployPrecheck({ projectDir: '/tmp/x', options: {}, logger: quiet, steps });
+        ctx.expect(ran).toEqual(['framework-freshness']);
+        ctx.expect(result.ran).toEqual(ran);
+      },
+    },
+    {
+      name: 'cli: no `setup` command, a bare invocation resolves to help, migrate stays its own command',
+      run: (ctx) => {
+        const { commandsDir, aliases, defaultCommand } = cli.config;
+
+        ctx.expect(defaultCommand).toBe('help');
+        ctx.expect('setup' in aliases).toBe(false);
+        ctx.expect(jetpack.exists(path.join(commandsDir, 'setup.js'))).toBe(false);
+
+        // The one-time hook-layout migration is a deliberate verb, not a step
+        // every build repeats.
+        ctx.expect(Boolean(aliases.migrate)).toBe(true);
+        ctx.expect(jetpack.exists(path.join(commandsDir, 'migrate.js'))).toBeTruthy();
+      },
+    },
+  ],
+});

package/dist/test/suites/build/env-delivery.test.js

@@ -0,0 +1,239 @@
+// The env schema is the ONE declaration of how a key reaches the extension
+// ([#627](https://github.com/Omega-JS-Stack/omega/issues/627)): the publish
+// workflow's secrets block, the build's bake list, and `omega deploy`'s
+// push-secrets step all read `delivery: { extension: … }` and nothing else.
+// Before this, each of the three carried its own hand-kept list and they drifted
+// (the #582 fix had to be made in the workflow by hand, one key at a time).
+//
+// Offline by construction: the scaffold writes into a temp dir and the `gh`/
+// `git` boundaries are injected — no network, no real repo.
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const { publishSecretKeys, bakeKeys, renderSecretsBlock, WORKFLOW_OWNED_KEYS } = require('../../../vendor/config/env-delivery.js');
+
+const SRC = path.join(__dirname, '..', '..', '..');
+const { scaffoldDefaults } = require(path.join(SRC, 'gulp', 'tasks', 'defaults.js'));
+// The bake seam is the BUNDLE's since #743 — the snapshot is baked into every
+// emitted bundle, so the schema's bake list and its guard live with it.
+const bundleTask = require(path.join(SRC, 'gulp', 'tasks', 'bundle.js'));
+const { publishEnvSecrets } = require(path.join(SRC, 'commands', 'lib', 'push-secrets.js'));
+const { STEPS } = require(path.join(SRC, 'commands', 'lib', 'deploy-precheck.js'));
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const quiet = { log() {}, warn() {}, error() {} };
+
+/** A temp target dir, optionally with a local-level .env. */
+function tmpTarget(env) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-env-delivery-'));
+  if (env !== undefined) fs.writeFileSync(path.join(tmp, '.env'), env);
+  return tmp;
+}
+
+/** Declare the brand's own GitHub repo — the publish precondition. */
+function declareRepo(dir, slug) {
+  fs.mkdirSync(path.join(dir, 'config'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'config', 'omega.json5'), [
+    '{',
+    "  brand: { id: 'my-brand', name: 'My Brand', url: 'https://my.brand' },",
+    `  repo: { providers: { github: { repo: '${slug}' } } },`,
+    '  targets: { extension: {} },',
+    '}',
+  ].join('\n'));
+}
+
+module.exports = defineCases({
+  type: 'group',
+  layer: 'build',
+  description: 'env delivery (#627) — the workflow block, the bake list, and push-secrets from ONE schema',
+  tests: [
+    {
+      name: 'the publish workflow renders the schema block — every CI key, no token left (#627, #582)',
+      run: (ctx) => {
+        const tmp = tmpTarget();
+
+        try {
+          scaffoldDefaults({ outputDir: tmp });
+          const workflow = fs.readFileSync(path.join(tmp, '.github', 'workflows', 'publish.yml'), 'utf8');
+
+          ctx.expect(workflow.includes('[ githubSecrets ]')).toBe(false);
+          for (const key of publishSecretKeys('extension').filter((k) => !WORKFLOW_OWNED_KEYS.includes(k))) {
+            ctx.expect(workflow).toContain(`\n  ${key}: \${{ secrets.${key} }}`);
+          }
+
+          // #582's pin, now schema-derived: a dispatched CI run has no `.env`,
+          // so the Measurement Protocol secret only reaches the build through
+          // this block — without it every published extension baked an empty
+          // secret and sent no events, silently.
+          ctx.expect(workflow).toContain('GOOGLE_ANALYTICS_SECRET: ${{ secrets.GOOGLE_ANALYTICS_SECRET }}');
+
+          // GITHUB_TOKEN is the runner's own, not a schema key — still literal.
+          ctx.expect(workflow).toContain('GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}');
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'the rendered block is the config renderer\'s, byte for byte',
+      run: (ctx) => {
+        const tmp = tmpTarget();
+
+        try {
+          scaffoldDefaults({ outputDir: tmp });
+          const workflow = fs.readFileSync(path.join(tmp, '.github', 'workflows', 'publish.yml'), 'utf8');
+
+          ctx.expect(workflow).toContain(`  ${renderSecretsBlock('extension', { indent: '  ' })}\n`);
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'the build bakes exactly the schema\'s bake list, valued from the build env',
+      run: (ctx) => {
+        // The hardcoded `process.env.GOOGLE_ANALYTICS_SECRET` read is gone: the
+        // key set is the schema's, so a new baked key is one schema entry.
+        ctx.expect(bundleTask.BAKED_KEYS).toEqual(bakeKeys('extension'));
+        ctx.expect(bundleTask.BAKED_KEYS).toEqual(['GOOGLE_ANALYTICS_SECRET']);
+
+        const saved = process.env.GOOGLE_ANALYTICS_SECRET;
+        try {
+          process.env.GOOGLE_ANALYTICS_SECRET = 'fixture-mp-secret';
+          ctx.expect(bundleTask.readBakedEnv().GOOGLE_ANALYTICS_SECRET).toBe('fixture-mp-secret');
+
+          delete process.env.GOOGLE_ANALYTICS_SECRET;
+          // Absent is the empty string, never undefined — the baked snapshot is
+          // JSON and a missing key would read as "no analytics config at all".
+          ctx.expect(bundleTask.readBakedEnv().GOOGLE_ANALYTICS_SECRET).toBe('');
+        } finally {
+          if (saved === undefined) delete process.env.GOOGLE_ANALYTICS_SECRET;
+          else process.env.GOOGLE_ANALYTICS_SECRET = saved;
+        }
+      },
+    },
+    {
+      name: 'the bake REFUSES a configured stream with no secret in build mode, warns in development (#626)',
+      run: (ctx) => {
+        // #582's failure mode, guarded at the seam it happens: a CI publish
+        // runs with no `.env`, so a brand with a GA4 stream id and no
+        // Measurement Protocol secret baked an empty string and shipped an
+        // extension that sent no events — silently, forever.
+        const configured = { analytics: { providers: { google: { id: 'G-FIXTURE' } } } };
+        let thrown = null;
+        try {
+          bundleTask.readBakedEnv({}, { config: configured, build: true, logger: quiet });
+        } catch (e) {
+          thrown = e;
+        }
+
+        ctx.expect(thrown === null).toBe(false);
+        // The BRAND-level key a human sets, and the config path that owes it.
+        ctx.expect(thrown.message).toContain('GOOGLE_ANALYTICS_SECRET_EXTENSION');
+        ctx.expect(thrown.message).toContain('analytics.providers.google.id');
+
+        // Development warns and keeps going — a half-configured brand is a
+        // normal step on the way to a configured one.
+        const said = [];
+        const loud = { log() {}, warn: (m) => said.push(m), error() {} };
+        const baked = bundleTask.readBakedEnv({}, { config: configured, build: false, logger: loud });
+        ctx.expect(baked.GOOGLE_ANALYTICS_SECRET).toBe('');
+        ctx.expect(said.join('\n')).toContain('GOOGLE_ANALYTICS_SECRET_EXTENSION');
+
+        // The secret under its DELIVERED name is the value the build holds.
+        ctx.expect(bundleTask.readBakedEnv({ GOOGLE_ANALYTICS_SECRET: 'shh' }, { config: configured, build: true, logger: quiet }).GOOGLE_ANALYTICS_SECRET)
+          .toBe('shh');
+
+        // No stream configured, nothing owed.
+        ctx.expect(bundleTask.readBakedEnv({}, { config: {}, build: true, logger: quiet }).GOOGLE_ANALYTICS_SECRET).toBe('');
+      },
+    },
+    {
+      name: 'push-secrets publishes the schema set, valued from the composed env, on stdin',
+      run: (ctx) => {
+        const tmp = tmpTarget('CHROME_CLIENT_ID=chrome-id\nGOOGLE_ANALYTICS_SECRET_EXTENSION=mp-secret\nMY_CUSTOM_THING=custom\n');
+        declareRepo(tmp, 'acme/ext');
+        const gh = [];
+
+        try {
+          const result = publishEnvSecrets({
+            targetDir: tmp,
+            logger: quiet,
+            env: {},
+            gitExecFn: () => 'git@github.com:acme/ext.git\n',
+            execFn: (file, args, options) => { gh.push({ file, args, input: options.input }); return ''; },
+          });
+
+          // The brand-level GOOGLE_ANALYTICS_SECRET_EXTENSION lands under its
+          // DELIVERED name; the undeclared key is nobody's secret.
+          ctx.expect(result.published).toEqual(['CHROME_CLIENT_ID', 'GOOGLE_ANALYTICS_SECRET']);
+          ctx.expect(gh.map((c) => c.args.join(' '))).toEqual([
+            'auth status',
+            'secret set CHROME_CLIENT_ID --repo acme/ext',
+            'secret set GOOGLE_ANALYTICS_SECRET --repo acme/ext',
+          ]);
+          ctx.expect(gh.slice(1).map((c) => c.input)).toEqual(['chrome-id', 'mp-secret']);
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'push-secrets skips LOUDLY on CI, an empty cascade, no remote, and a stranger\'s repo',
+      run: (ctx) => {
+        const noGh = () => { throw new Error('gh must not run'); };
+        const messages = [];
+        const loud = { log: (m) => messages.push(m), warn: (m) => messages.push(m), error: (m) => messages.push(m) };
+
+        const empty = tmpTarget('MY_CUSTOM_THING=custom\n');
+        declareRepo(empty, 'acme/ext');
+
+        try {
+          ctx.expect(publishEnvSecrets({ targetDir: empty, logger: loud, env: { CI: 'true' }, execFn: noGh, gitExecFn: noGh }))
+            .toEqual({ skipped: 'ci' });
+
+          ctx.expect(publishEnvSecrets({ targetDir: empty, logger: loud, env: {}, execFn: noGh, gitExecFn: noGh }))
+            .toEqual({ skipped: 'no-secrets' });
+
+          const keyed = tmpTarget('CHROME_CLIENT_ID=chrome-id\n');
+          declareRepo(keyed, 'acme/ext');
+          ctx.expect(publishEnvSecrets({
+            targetDir: keyed,
+            logger: loud,
+            env: {},
+            execFn: noGh,
+            gitExecFn: () => { throw new Error('fatal: no such remote'); },
+          })).toEqual({ skipped: 'no-remote' });
+
+          // The enclosing checkout is not the brand's repo — never arm a
+          // stranger's Actions with this brand's store credentials.
+          ctx.expect(publishEnvSecrets({
+            targetDir: keyed,
+            logger: loud,
+            env: {},
+            execFn: noGh,
+            gitExecFn: () => 'git@github.com:Omega-JS-Stack/omega.git\n',
+          })).toEqual({ skipped: 'repo-mismatch' });
+
+          fs.rmSync(keyed, { recursive: true, force: true });
+
+          const said = messages.join('\n');
+          ctx.expect(said).toContain('CI already has the repo secrets');
+          ctx.expect(said).toContain('no keys composed for this target');
+          ctx.expect(said).toContain('no GitHub remote');
+          ctx.expect(said).toContain("this brand's repo is acme/ext");
+        } finally {
+          fs.rmSync(empty, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'the deploy precheck runs push-secrets after the freshness check (#680)',
+      run: (ctx) => {
+        ctx.expect(STEPS.map((step) => step.name)).toEqual(['framework-freshness', 'push-secrets']);
+      },
+    },
+  ],
+});

package/dist/test/suites/build/env-watch.test.js

@@ -0,0 +1,86 @@
+// The dev lane treats the whole `.env` chain as a watch input
+// ([#681](https://github.com/Omega-JS-Stack/omega/issues/681)).
+//
+// The backend's stage watch already did — an edit to the brand root's .env
+// re-stages and the running emulator sees it — while the extension's gulp read
+// the cascade once at boot and never noticed an edit. This pins the PATH
+// RESOLUTION the `serve` task wires up (the same level the backend's
+// stage-watch test pins): every layer of the chain, and each layer's
+// `.env.<environment>` overlay (#586).
+//
+// Offline by construction: temp dirs and path resolution only, and the watcher
+// is closed before the case returns.
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const jetpack = require('fs-jetpack');
+
+const SRC = path.join(__dirname, '..', '..', '..');
+const serveTask = require(path.join(SRC, 'gulp', 'tasks', 'serve.js'));
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+// An extension target inside a brand monorepo, with a company root above it:
+// <root>/company/.env, <root>/brand/.env, <root>/brand/targets/extension/.
+function seedBrand() {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'extension-env-watch-')));
+  const companyRoot = path.join(root, 'company');
+  const brandRoot = path.join(root, 'brand');
+  const targetDir = path.join(brandRoot, 'targets', 'extension');
+
+  jetpack.write(path.join(companyRoot, '.env'), '');
+  jetpack.write(path.join(brandRoot, '.omega', 'company.json'), JSON.stringify({ root: companyRoot }));
+  jetpack.write(path.join(brandRoot, 'config', 'omega.json5'), '{ brand: { id: "fixture" }, targets: { extension: {} } }');
+  jetpack.dir(targetDir);
+
+  return { root, companyRoot, brandRoot, targetDir };
+}
+
+module.exports = defineCases({
+  type: 'group',
+  layer: 'build',
+  description: 'env-watch (#681) — the dev lane watches every layer of the .env chain',
+  tests: [
+    {
+      name: 'the serve watcher lists company, brand and target — overlays included',
+      run: (ctx) => {
+        const { root, companyRoot, brandRoot, targetDir } = seedBrand();
+        const watcher = serveTask.watchEnvSources(targetDir, { environment: 'development' });
+
+        try {
+          ctx.expect(watcher.inputs.map((input) => input.path)).toEqual([
+            path.join(companyRoot, '.env'),
+            path.join(companyRoot, '.env.development'),
+            path.join(brandRoot, '.env'),
+            path.join(brandRoot, '.env.development'),
+            path.join(targetDir, '.env'),
+            path.join(targetDir, '.env.development'),
+          ]);
+          ctx.expect(watcher.inputs.map((input) => input.layer)).toEqual([
+            'company', 'company', 'brand', 'brand', 'target', 'target',
+          ]);
+        } finally {
+          watcher.close();
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'a standalone target watches only its own .env layer',
+      run: (ctx) => {
+        const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'extension-env-watch-solo-')));
+        const watcher = serveTask.watchEnvSources(root, { environment: 'development' });
+
+        try {
+          ctx.expect(watcher.inputs.map((input) => input.path)).toEqual([
+            path.join(root, '.env'),
+            path.join(root, '.env.development'),
+          ]);
+        } finally {
+          watcher.close();
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+  ],
+});