@omega.js/extension 0.1.0

package/dist/test/suites/build/boot-timeout.test.js

@@ -0,0 +1,92 @@
+// Build-layer tests for the boot layer's per-test timeout default (#262).
+//
+// A boot test drives the consumer's REAL extension, and the first run after a
+// fresh build pays the cold Firebase service-worker init — observed at 20-30s,
+// right on top of the old 20000ms default, so a consumer's boot test only
+// passed once they declared a timeout of their own. The default is the fix; a
+// consumer-side override is not.
+//
+// The cost is a Chromium cold start, so this asserts the CONTRACT (the number
+// and the wiring that carries it) rather than re-running the boot layer.
+
+const path = require('path');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const RUNNER = path.join(__dirname, '..', '..', 'runner.js');
+const BOOT_SUITES = path.join(__dirname, '..', 'boot');
+
+// The observed worst case the default has to clear (#262).
+const OBSERVED_FIRST_RUN_SW_INIT_MS = 30000;
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'boot-layer timeout default',
+  tests: [
+    {
+      name: 'the default clears a cold first-run Firebase SW init with room to spare',
+      run: (ctx) => {
+        const { BOOT_DEFAULT_TIMEOUT } = require(RUNNER);
+        ctx.expect(BOOT_DEFAULT_TIMEOUT).toBe(45000);
+        ctx.expect(BOOT_DEFAULT_TIMEOUT > OBSERVED_FIRST_RUN_SW_INIT_MS).toBe(true);
+      },
+    },
+    {
+      name: 'a boot test that declares no timeout is handed the default, through the real runner core',
+      run: async (ctx) => {
+        const fs = require('fs');
+        const os = require('os');
+        const { createRunner } = require('../../../vendor/devkit/test/runner-core.js');
+        const { BOOT_DEFAULT_TIMEOUT } = require(RUNNER);
+
+        // A real suites dir with one real boot test, run through the real core:
+        // the boot glue is where a test's timeout is resolved, and this is the
+        // number a fresh-build run actually races against.
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-boot-timeout-'));
+        fs.mkdirSync(path.join(tmp, 'suites', 'boot'), { recursive: true });
+        fs.writeFileSync(path.join(tmp, 'suites', 'boot', 'no-timeout.test.js'),
+          `module.exports = { layer: 'boot', description: 'no timeout declared', inspect: async () => {} };\n`);
+
+        let handed = null;
+        const runner = createRunner({
+          title: 'boot timeout probe',
+          packageName: '@omega.js/extension',
+          targetAlias: 'extension',
+          suitesDir: path.join(tmp, 'suites'),
+          frameworkTestDir: path.join(tmp, 'framework-tests'),
+          bootDefaultTimeout: BOOT_DEFAULT_TIMEOUT,
+          boot: { run: async ({ tests }) => { handed = tests; } },
+        });
+
+        // The probe runner reports like any run — its report is not THIS run's,
+        // so it stays out of the output.
+        const realLog = console.log;
+        console.log = () => {};
+
+        try {
+          await runner.run({ layer: 'boot' });
+          ctx.expect(handed.length).toBe(1);
+          ctx.expect(handed[0].timeout).toBe(BOOT_DEFAULT_TIMEOUT);
+        } finally {
+          console.log = realLog;
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'no framework boot test declares a timeout — a fresh build runs on the default',
+      run: (ctx) => {
+        const fs = require('fs');
+
+        // The point of raising the default: a boot suite needs no timeout of
+        // its own to survive a cold first run.
+        for (const file of fs.readdirSync(BOOT_SUITES).filter((name) => name.endsWith('.test.js'))) {
+          const mod = require(path.join(BOOT_SUITES, file));
+          const tests = Array.isArray(mod) ? mod : (mod.tests || [mod]);
+          ctx.expect(mod.timeout).toBe(undefined);
+          tests.forEach((t) => ctx.expect(t.timeout).toBe(undefined));
+        }
+      },
+    },
+  ],
+});

package/dist/test/suites/build/build-error-notification.test.js

@@ -0,0 +1,122 @@
+// Build-layer tests for Manager.getBuildErrorNotificationArgs() — the notifly
+// argv the build-error reporter spawns (#104).
+//
+// Build messages routinely carry apostrophes and parentheses ("the app's
+// package.json has no version (Chrome refuses …)"). The reporter used to
+// interpolate the message into a single shell string, which the shell then
+// mangled — the report survived, the notification died with a syntax error.
+// The contract now is an ARGV ARRAY handed to a shell-free spawn, so every
+// character of the message reaches notifly verbatim.
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const Manager = require(path.join(__dirname, '..', '..', '..', 'build.js'));
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+// The live message from the versionless-manifest package test — apostrophe,
+// parentheses, quotes and a colon in one string.
+const NASTY = `Cannot build the manifest: the extension app's package.json has no "version" (Chrome refuses to load a manifest without one)`;
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'Manager — build-error notification argv is shell-free',
+  tests: [
+    {
+      name: 'returns an argv array, never a shell string',
+      run: (ctx) => {
+        const args = Manager.getBuildErrorNotificationArgs('Package', NASTY);
+        ctx.expect(Array.isArray(args)).toBe(true);
+        ctx.expect(args.every((a) => typeof a === 'string')).toBe(true);
+      },
+    },
+    {
+      name: 'an apostrophe-bearing message is ONE verbatim arg (no quoting, no escapes)',
+      run: (ctx) => {
+        const args = Manager.getBuildErrorNotificationArgs('Package', NASTY);
+        const message = args[args.indexOf('--message') + 1];
+        ctx.expect(message).toBe(NASTY);
+        ctx.expect(message.includes('\\')).toBe(false);
+      },
+    },
+    {
+      name: 'title carries the plugin name and the flags notifly expects',
+      run: (ctx) => {
+        const args = Manager.getBuildErrorNotificationArgs('Bundle', 'boom');
+        ctx.expect(args[args.indexOf('--title') + 1]).toBe('Build Error: Bundle');
+        // No --appIcon: the old value was a machine-specific absolute path (#126)
+        ctx.expect(args.includes('--appIcon')).toBe(false);
+        ctx.expect(args.includes('--timeout')).toBe(true);
+        ctx.expect(args.includes('--sound')).toBe(true);
+      },
+    },
+    {
+      // The end-to-end proof, run against a REAL child process (no shell, no mock):
+      // every arg arrives at the child byte-identical, apostrophes and all. The
+      // old shell string never got this far — /bin/sh died parsing it.
+      name: 'the argv survives a real shell-free spawn byte-identical',
+      run: (ctx) => {
+        const args = Manager.getBuildErrorNotificationArgs('Package', NASTY);
+        const printer = 'process.stdout.write(JSON.stringify(process.argv.slice(1)))';
+        const result = spawnSync(process.execPath, ['-e', printer, '--', ...args], { encoding: 'utf8' });
+
+        ctx.expect(result.status).toBe(0);
+        ctx.expect(result.stderr).toBe('');
+        ctx.expect(JSON.parse(result.stdout)).toEqual(args);
+      },
+    },
+    {
+      // notifly is an optional local nicety: on a machine without it the spawn
+      // used to dump a raw `spawn notifly ENOENT` error after the suite (#123).
+      // The ENOENT here comes from a REAL spawn of a binary that cannot exist.
+      name: 'a real missing-binary ENOENT prints ONE friendly note, no error dump',
+      run: (ctx) => {
+        const result = spawnSync('omega-notifly-does-not-exist-xyz', ['--title', 'x'], { shell: false });
+        ctx.expect(result.error.code).toBe('ENOENT');
+
+        const warns = [];
+        const errors = [];
+        const origWarn = console.warn;
+        const origError = console.error;
+        console.warn = (...args) => warns.push(args.join(' '));
+        console.error = (...args) => errors.push(args.join(' '));
+        try {
+          Manager.reportNotificationFailure(result.error);
+        } finally {
+          console.warn = origWarn;
+          console.error = origError;
+        }
+
+        ctx.expect(warns.length).toBe(1);
+        ctx.expect(warns[0]).toContain('notifly not installed — skipping desktop notification');
+        ctx.expect(warns[0].includes('ENOENT')).toBe(false);
+        ctx.expect(warns[0].includes('spawnSync')).toBe(false);
+        ctx.expect(errors.length).toBe(0);
+      },
+    },
+    {
+      name: 'every other spawn failure keeps the logged-not-thrown error',
+      run: (ctx) => {
+        const failure = Object.assign(new Error('permission denied'), { code: 'EACCES' });
+
+        const warns = [];
+        const errors = [];
+        const origWarn = console.warn;
+        const origError = console.error;
+        console.warn = (...args) => warns.push(args.join(' '));
+        console.error = (...args) => errors.push(args.join(' '));
+        try {
+          Manager.reportNotificationFailure(failure);
+        } finally {
+          console.warn = origWarn;
+          console.error = origError;
+        }
+
+        ctx.expect(errors.length).toBe(1);
+        ctx.expect(errors[0]).toContain('Failed to send notification');
+        ctx.expect(warns.length).toBe(0);
+      },
+    },
+  ],
+});

package/dist/test/suites/build/build-json-bake.test.js

@@ -0,0 +1,302 @@
+// The OMEGA_BUILD_JSON bake, bundle lane
+// ([#743](https://github.com/Omega-JS-Stack/omega/issues/743)).
+//
+// The snapshot an extension context reads is composed here and BAKED into every
+// emitted bundle two ways — `define` replaces the bare identifier at compile
+// time, `banner` prepends the globalThis/self/window assignment — which is the
+// shape @omega.js/desktop has always used. It used to be a
+// `packaged/<target>/raw/build.js` JSONP file the service worker
+// importScripts()'d and every page loaded with its own <script> tag, plus a
+// `build.json` sidecar nothing read; both files are gone, so what this suite
+// pins is that the artifact still carries the same facts.
+//
+// The composition cases moved here from package-task.test.js with the code:
+// `cloud` reaching the snapshot is what the SW's Firebase auth lives or dies by
+// (#46), the license stamp rides outside `config` (#320), and the dev port map
+// is the ONLY channel a browser context has to a bumped emulator (#300, #262).
+//
+// The task module reads its project (package.json / config / dist) 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's inProject().
+
+const path = require('path');
+const fs   = require('fs');
+const os   = require('os');
+const vm   = require('vm');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const SRC       = path.join(__dirname, '..', '..', '..');
+const TASK_PATH = path.join(SRC, 'gulp', 'tasks', 'bundle.js');
+const { readBakedBuildJson } = require(path.join(SRC, 'gulp', 'tasks', 'utils', 'build-json.js'));
+
+// The boot lane loads the in-tree fixture consumer, which stands in for a real
+// built extension — so it carries a checked-in copy of the banner.
+const FIXTURE = path.join(SRC, 'test', 'fixtures', 'consumer-extension', 'dist');
+
+// Stage a temp extension project. `files` is a relative-path → contents map
+// written verbatim (the entry points the bundle task discovers, …).
+function stageProject(opts = {}) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-build-json-'));
+
+  fs.writeFileSync(path.join(tmp, 'package.json'), opts.pkg ?? `{ "name": "staged-ext", "version": "3.1.4" }`);
+
+  if (opts.config !== undefined) {
+    fs.mkdirSync(path.join(tmp, 'config'), { recursive: true });
+    fs.writeFileSync(path.join(tmp, 'config', 'omega.json5'), opts.config);
+  }
+
+  for (const [relative, contents] of Object.entries(opts.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();
+  }
+}
+
+// An entry that reads the snapshot BOTH ways the bake delivers it: the bare
+// identifier the `define` replaces at compile time, and the globals the `banner`
+// assigns at load time (`self` is what background.js reads, `window`/`globalThis`
+// what every page context reads). The global reads are guarded so the body can
+// also be run on its OWN, with no banner in scope — that run is what tells the
+// two mechanisms apart.
+const PROBE_ENTRY = [
+  'globalThis.__fromDefine = OMEGA_BUILD_JSON.config.brand.id;',
+  'try { globalThis.__fromGlobal = globalThis.OMEGA_BUILD_JSON.config.brand.id; } catch (e) { globalThis.__fromGlobal = null; }',
+  'try { globalThis.__fromSelf = self.OMEGA_BUILD_JSON.config.brand.id; } catch (e) { globalThis.__fromSelf = null; }',
+  '',
+].join('\n');
+
+// Run an emitted bundle the way a browser would — it is a self-contained iife
+// with no imports and no chrome APIs — and hand back what it set.
+//
+// `banner: false` runs everything BUT the first line, in a scope where nothing
+// has assigned OMEGA_BUILD_JSON. Only the compile-time `define` can answer there,
+// so this is what proves the define is doing work rather than the banner's global
+// quietly covering for it.
+function runBundleFile(file, options = {}) {
+  const source = fs.readFileSync(file, 'utf8');
+  const scope = {};
+  scope.self = scope;
+  vm.runInNewContext(options.banner === false ? source.slice(source.indexOf('\n') + 1) : source, scope);
+  return scope;
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'OMEGA_BUILD_JSON bake — composed once, carried by every emitted bundle (#743)',
+  timeout: 120000,
+  tests: [
+    {
+      name: 'every emitted bundle carries the snapshot as a define AND as the global (#743)',
+      run: async (ctx) => {
+        const tmp = stageProject({
+          config: `{
+            brand: { id: 'staged', name: 'Staged' },
+            targets: { extension: {} },
+          }`,
+          files: {
+            // The service worker's entry and a page entry — the two contexts the
+            // JSONP file used to reach by two different mechanisms.
+            'src/assets/js/components/background/index.js': PROBE_ENTRY,
+            'src/assets/js/components/popup/index.js': PROBE_ENTRY,
+          },
+        });
+        try {
+          await inProject(tmp, async (task) => {
+            const failure = await new Promise((resolve) => task.bundleTask(resolve));
+            ctx.expect(failure).toBe(undefined);
+
+            for (const name of ['background', 'popup']) {
+              const emitted = path.join(tmp, 'dist', 'assets', 'js', 'components', `${name}.bundle.js`);
+              ctx.expect(fs.existsSync(emitted)).toBe(true);
+
+              // The banner IS the first line — it has to land ahead of the
+              // bundle's own code, which is the load order the SW's
+              // importScripts('/build.js') used to buy.
+              ctx.expect(readBakedBuildJson(emitted).config.brand.id).toBe('staged');
+
+              // banner: globalThis and self both answer, the two names the
+              // page contexts and the service worker read (#743)
+              const ran = runBundleFile(emitted);
+              ctx.expect(ran.__fromGlobal).toBe('staged');
+              ctx.expect(ran.__fromSelf).toBe('staged');
+
+              // define: the bare identifier became the literal at compile time —
+              // it still answers with the banner line withheld, where nothing
+              // has assigned the global at all.
+              const bare = runBundleFile(emitted, { banner: false });
+              ctx.expect(bare.__fromDefine).toBe('staged');
+              ctx.expect(bare.__fromGlobal).toBe(null);
+              ctx.expect(bare.__fromSelf).toBe(null);
+            }
+          });
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      // The boot lane is what proves a BROWSER resolves the bake, and it runs
+      // against the checked-in fixture rather than a build. That only means
+      // anything while the fixture carries the banner this generator emits — so
+      // the shape (the IIFE, the three scopes it assigns) is pinned here against
+      // the live function. Change buildJsonBanner and this fails until the
+      // fixture is regenerated.
+      name: 'the boot fixture carries the banner buildJsonBanner emits, per bundle (#743)',
+      run: async (ctx) => {
+        const task = require(TASK_PATH);
+
+        for (const file of ['background.js', 'popup.bundle.js']) {
+          const full = path.join(FIXTURE, file);
+          const firstLine = fs.readFileSync(full, 'utf8').split('\n', 1)[0];
+
+          ctx.expect(firstLine).toBe(task.buildJsonBanner(readBakedBuildJson(full)).js);
+          // Every bundle carries its OWN copy — that is what replaced the single file.
+          ctx.expect(readBakedBuildJson(full).config.brand.id).toBe('bxm-fixture');
+        }
+      },
+    },
+    {
+      name: 'the snapshot carries cloud from config/omega.json5 (#46)',
+      run: async (ctx) => {
+        const tmp = stageProject({
+          config: `{
+            brand: { id: 'staged', name: 'Staged' },
+            cloud: { config: { apiKey: 'AIza-staged', projectId: 'demo-staged', appId: '1:2:web:3' } },
+            targets: { extension: {} },
+          }`,
+        });
+        try {
+          await inProject(tmp, async (task) => {
+            const buildJson = await task.composeBuildJson();
+
+            ctx.expect(buildJson.config.cloud.config.apiKey).toBe('AIza-staged');
+            ctx.expect(buildJson.config.cloud.config.projectId).toBe('demo-staged');
+            // Without it the service worker's Firebase auth never initializes
+            ctx.expect(buildJson.config.firebase.app.enabled).toBe(true);
+          });
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'the snapshot records the build\'s license verdict, outside the client config (#320)',
+      run: async (ctx) => {
+        const tmp = stageProject({
+          config: `{ brand: { id: 'staged', name: 'Staged' }, targets: { extension: {} } }`,
+        });
+        try {
+          await inProject(tmp, async (task) => {
+            const buildJson = await task.composeBuildJson();
+
+            // A test run is not a production build, so it never phones home:
+            // keyless is what an unlicensed artifact records (spec call 5).
+            ctx.expect(buildJson.license).toEqual({ status: 'keyless', payments: 'gated', attribution: 'shown' });
+            // A fact about the BUILD — the client contract is untouched.
+            ctx.expect(buildJson.config.license).toBeUndefined();
+          });
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'cloud is an empty object when config/omega.json5 declares none',
+      run: async (ctx) => {
+        const tmp = stageProject({});
+        try {
+          await inProject(tmp, async (task) => {
+            const buildJson = await task.composeBuildJson();
+            ctx.expect(buildJson.config.cloud).toEqual({});
+            ctx.expect(buildJson.config.firebase.app.enabled).toBe(false);
+          });
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'the bake carries the sibling backend\'s resolved emulator ports, and never in production (#300)',
+      run: async (ctx) => {
+        // An extension context has no env and no filesystem — the bake is its
+        // ONLY channel to a bumped emulator. Stage the target inside a real brand
+        // with a live backend ports file beside it.
+        const brand = fs.mkdtempSync(path.join(os.tmpdir(), 'extension-dev-ports-brand-'));
+        fs.mkdirSync(path.join(brand, 'config'), { recursive: true });
+        fs.writeFileSync(path.join(brand, 'config', 'omega.json5'), `{ brand: { id: 'staged', name: 'Staged' } }`);
+        fs.mkdirSync(path.join(brand, 'targets', 'backend', '.temp'), { recursive: true });
+        fs.writeFileSync(path.join(brand, 'targets', 'backend', '.temp', 'ports.json'), JSON.stringify({
+          ports: { auth: 9100, firestore: 8081, hosting: 5003 }, pid: process.pid, startedAt: 'x',
+        }));
+
+        // …and a live WEBSITE publishing its resolved origin beside its port —
+        // bumped AND https, the pair a port number alone can never express (#262)
+        fs.mkdirSync(path.join(brand, 'targets', 'website', '.temp'), { recursive: true });
+        fs.writeFileSync(path.join(brand, 'targets', 'website', '.temp', 'ports.json'), JSON.stringify({
+          ports: { website: 4001 }, origin: 'https://localhost:4001', pid: process.pid, startedAt: 'x',
+        }));
+
+        const app = path.join(brand, 'targets', 'extension');
+        fs.mkdirSync(app, { recursive: true });
+        fs.writeFileSync(path.join(app, 'package.json'), `{ "name": "staged-ext", "version": "3.1.4" }`);
+
+        // The runner itself exports OMEGA_TEST_MODE, and getEnvironment() reads
+        // it BEFORE OMEGA_BUILD_MODE — a "production" bake under omega test is
+        // otherwise a testing bake (the auth-emulator-gate bakeConfig idiom).
+        // OMEGA_LICENSE_KEY rides the list because a production bake runs the
+        // license check (#320): the suite stays offline on a machine that has
+        // a real key exported.
+        const ENV_KEYS = ['OMEGA_BUILD_MODE', 'OMEGA_TEST_MODE', 'NODE_ENV', 'OMEGA_LICENSE_KEY'];
+        const bake = async (mode) => {
+          const previous = Object.fromEntries(ENV_KEYS.map((key) => [key, process.env[key]]));
+          ENV_KEYS.forEach((key) => delete process.env[key]);
+          if (mode === 'production') process.env.OMEGA_BUILD_MODE = 'true';
+          try {
+            return await inProject(app, async (task) => (await task.composeBuildJson()).config);
+          } finally {
+            ENV_KEYS.forEach((key) => {
+              if (previous[key] === undefined) delete process.env[key]; else process.env[key] = previous[key];
+            });
+          }
+        };
+
+        try {
+          const dev = await bake('development');
+          ctx.expect(dev.dev.ports.auth).toBe(9100);
+          ctx.expect(dev.dev.ports.firestore).toBe(8081);
+          ctx.expect(dev.dev.ports.hosting).toBe(5003);
+          // The website's origin is a resolved fact in the same map (#262)
+          ctx.expect(dev.dev.origin).toBe('https://localhost:4001');
+
+          // A packaged build has no local stack to reach — no map ships
+          const production = await bake('production');
+          ctx.expect(production.dev).toBe(undefined);
+        } finally {
+          fs.rmSync(brand, { recursive: true, force: true });
+        }
+      },
+    },
+  ],
+});

package/dist/test/suites/build/build-verb.test.js

@@ -0,0 +1,138 @@
+// Build-layer tests for the canonical `build` verb ([#81](https://github.com/Omega-JS-Stack/omega/issues/81)
+// parity sweep — desktop had the verb, extension only had the npm script).
+// The synced projectScripts `build` is the thin `omega build` alias, so the
+// verb must run the pipeline ITSELF — clean, then the gulp build task under
+// OMEGA_BUILD_MODE — and never shell back to `npm run build` (that would
+// recurse forever). Mirrors desktop's build-verbs.test.js.
+
+const path = require('path');
+const fs   = require('fs');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const SRC          = path.join(__dirname, '..', '..', '..');
+const CLI_PATH     = path.join(SRC, 'cli.js');
+const COMMANDS_DIR = path.join(SRC, 'commands');
+
+const build = require(path.join(COMMANDS_DIR, 'build.js'));
+
+// Record the steps a plan runs, in order, without executing anything real.
+// The step implementations are the seam runPlan already takes as an argument —
+// nothing is faked, we just hand it a recorder instead of the real runners (a
+// real gulp package build has no place in a unit test).
+function recorder(log) {
+  const record = (type) => (options, step) => { log.push(step.task ? `${type}:${step.task}` : type); };
+  return { clean: record('clean'), gulp: record('gulp') };
+}
+
+function stubCommand(name, fn) {
+  const file = path.join(COMMANDS_DIR, `${name}.js`);
+  require.cache[file] = { id: file, filename: file, loaded: true, children: [], paths: [], exports: fn };
+}
+
+function unstub(name) {
+  delete require.cache[path.join(COMMANDS_DIR, `${name}.js`)];
+}
+
+function freshCli() {
+  delete require.cache[CLI_PATH];
+  return require(CLI_PATH);
+}
+
+async function withEnv(run) {
+  const previous = process.env.OMEGA_BUILD_MODE;
+  delete process.env.OMEGA_BUILD_MODE;
+  try {
+    return await run();
+  } finally {
+    if (previous === undefined) delete process.env.OMEGA_BUILD_MODE;
+    else                       process.env.OMEGA_BUILD_MODE = previous;
+  }
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'build verb — the CLI owns the pipeline and its build-mode flag',
+  tests: [
+    {
+      name: 'positional "build" routes to commands/build.js',
+      run: async (ctx) => {
+        let invoked = false;
+        stubCommand('build', async () => { invoked = true; });
+        try {
+          const Main = freshCli();
+          await new Main().process({ _: ['build'] });
+          ctx.expect(invoked).toBe(true);
+        } finally {
+          unstub('build');
+        }
+      },
+    },
+    {
+      name: 'alias "-b" routes to the build command, like every sibling CLI',
+      run: async (ctx) => {
+        let invoked = false;
+        stubCommand('build', async () => { invoked = true; });
+        try {
+          const Main = freshCli();
+          await new Main().process({ _: [], b: true });
+          ctx.expect(invoked).toBe(true);
+        } finally {
+          unstub('build');
+        }
+
+        const { aliases } = freshCli().config;
+        ctx.expect(aliases.build.includes('-b')).toBe(true);
+        ctx.expect(aliases.build.includes('--build')).toBe(true);
+      },
+    },
+    {
+      name: 'build: OMEGA_BUILD_MODE + clean → gulp build',
+      run: (ctx) => {
+        const plan = build.plan({});
+        ctx.expect(plan.env.OMEGA_BUILD_MODE).toBe('true');
+        ctx.expect(plan.steps.map((s) => (s.task ? `${s.type}:${s.task}` : s.type)))
+          .toEqual(['clean', 'gulp:build']);
+      },
+    },
+    {
+      name: 'runPlan sets the env flag and runs the steps in order',
+      run: async (ctx) => {
+        const log = [];
+        await withEnv(async () => {
+          await build.runPlan(build.plan({}), {}, recorder(log));
+          ctx.expect(process.env.OMEGA_BUILD_MODE).toBe('true');
+        });
+        ctx.expect(log).toEqual(['clean', 'gulp:build']);
+      },
+    },
+    {
+      name: 'every plan step type has a runner in the RUNNERS table',
+      run: (ctx) => {
+        const known = Object.keys(build.RUNNERS);
+        for (const step of build.plan({}).steps) {
+          ctx.expect(known.includes(step.type)).toBe(true);
+        }
+      },
+    },
+    {
+      name: 'the verb never shells back to `npm run build` (the recursion the alias would cause)',
+      run: (ctx) => {
+        // Comments may NAME the forbidden command (the header documents the
+        // recursion rule) — the guard polices code only.
+        const source = fs.readFileSync(path.join(COMMANDS_DIR, 'build.js'), 'utf8')
+          .replace(/\/\/[^\n]*/g, '')
+          .replace(/\/\*[\s\S]*?\*\//g, '');
+        ctx.expect(/npm run build/.test(source)).toBe(false);
+        ctx.expect(source.includes('npm run gulp -- ')).toBe(true);
+      },
+    },
+    {
+      name: 'the synced projectScripts build script is the thin `omega build` alias (#748)',
+      run: (ctx) => {
+        const pkg = JSON.parse(fs.readFileSync(path.join(SRC, '..', 'package.json'), 'utf8'));
+        ctx.expect(pkg.projectScripts.build).toBe('omega build');
+      },
+    },
+  ],
+});