@omega.js/backend 0.1.0

package/test/boot/deploy-staging.test.js

@@ -0,0 +1,446 @@
+/**
+ * Deploy staging — the two layers that make a functions upload self-contained.
+ *
+ * stage-functions (src/dist pillar): functions/ is GENERATED from the authored
+ * target tree — src copy, derived manifest, composed brand⊕local config (#31), and
+ * the target-root files that ride the artifact. Exercised on real temp trees.
+ *
+ * stage-local-packages: Cloud Build can't follow file: paths outside the
+ * functions folder, and its buildpack runs `npm ci` (lockfile required) — such
+ * deps pack into functions/omega_modules/, package.json respells, the lockfile
+ * regenerates, and everything restores afterward. Exercised against REAL npm
+ * on a throwaway package — no mocks.
+ */
+
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const jetpack = require('fs-jetpack');
+
+const stageLocalPackages = require('../../dist/cli/utils/stage-local-packages.js');
+const { stageFunctions } = require('../../dist/cli/utils/stage-functions.js');
+const { loadConfig } = require('../helpers/_shared-config.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const BACKEND_BIN = path.resolve(__dirname, '../../bin/omega-backend');
+
+function makeTmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'backend-stage-'));
+}
+
+module.exports = defineCases({
+  description: 'Deploy staging — local file: deps pack into the functions upload',
+  type: 'group',
+  timeout: 120000,
+
+  tests: [
+    {
+      name: 'stages-outside-file-deps-and-restores',
+      async run({ assert }) {
+        const tmp = makeTmp();
+
+        // A tiny real package OUTSIDE the functions dir...
+        const pkgDir = path.join(tmp, 'fakepkg');
+        jetpack.write(path.join(pkgDir, 'package.json'), JSON.stringify({
+          name: '@omega.js/fakepkg',
+          version: '1.0.0',
+          private: true,
+          main: 'index.js',
+        }, null, 2));
+        jetpack.write(path.join(pkgDir, 'index.js'), 'module.exports = 1;\n');
+
+        // ...referenced the way the monorepo's functions dirs do it
+        const functionsPath = path.join(tmp, 'functions');
+        jetpack.write(path.join(functionsPath, 'package.json'), `${JSON.stringify({
+          name: 'test-functions',
+          version: '0.0.1',
+          private: true,
+          dependencies: { '@omega.js/fakepkg': 'file:../fakepkg' },
+        }, null, 2)}\n`);
+
+        const staging = await stageLocalPackages({ functionsPath });
+
+        // Staged: tarball vendored inside, dep respelled, lockfile matches
+        assert.deepEqual(staging.staged, ['@omega.js/fakepkg']);
+        const stagedPkg = jetpack.read(path.join(functionsPath, 'package.json'), 'json');
+        assert.equal(stagedPkg.dependencies['@omega.js/fakepkg'], 'file:omega_modules/omega.js-fakepkg-1.0.0.tgz');
+        assert.equal(jetpack.exists(path.join(functionsPath, 'omega_modules', 'omega.js-fakepkg-1.0.0.tgz')), 'file');
+
+        const lock = jetpack.read(path.join(functionsPath, 'package-lock.json'), 'json');
+        assert.ok(lock, 'lockfile generated for the staged shape');
+        assert.ok(lock.packages['node_modules/@omega.js/fakepkg'], 'lockfile resolves the staged tarball');
+
+        // Restore: original shape back verbatim, staging artifacts gone
+        await staging.restore();
+        const restored = jetpack.read(path.join(functionsPath, 'package.json'), 'json');
+        assert.equal(restored.dependencies['@omega.js/fakepkg'], 'file:../fakepkg');
+        assert.equal(jetpack.exists(path.join(functionsPath, 'package-lock.json')), false, 'lockfile absent again (none existed before)');
+        assert.equal(jetpack.exists(path.join(functionsPath, 'omega_modules')), false, 'staging dir removed');
+
+        jetpack.remove(tmp);
+      },
+    },
+
+    {
+      name: 'no-op-when-no-outside-file-deps',
+      async run({ assert }) {
+        const tmp = makeTmp();
+
+        const functionsPath = path.join(tmp, 'functions');
+        jetpack.write(path.join(functionsPath, 'package.json'), JSON.stringify({
+          name: 'fns',
+          version: '1.0.0',
+          private: true,
+          dependencies: { 'firebase-admin': '^13.0.0' },
+        }, null, 2));
+
+        const staging = await stageLocalPackages({ functionsPath });
+
+        assert.deepEqual(staging.staged, []);
+        assert.equal(jetpack.exists(path.join(functionsPath, 'omega_modules')), false, 'nothing staged');
+        await staging.restore(); // harmless no-op
+
+        jetpack.remove(tmp);
+      },
+    },
+
+    {
+      // #331: the lane packed only the framework package itself. @omega.js/client
+      // is a REAL runtime dependency of @omega.js/backend (never vendored) and is
+      // unpublished under the publish latch — so regenerating the lock against the
+      // staged shape asked the REGISTRY for it and 404'd, and no deploy ran.
+      name: 'packs-linked-omega-deps-transitively-so-the-lock-never-asks-the-registry',
+      async run({ assert }) {
+        const tmp = makeTmp();
+
+        // A local @omega.js package that exists NOWHERE but this disk — the
+        // registry-404 shape (client under the publish latch)
+        const depDir = path.join(tmp, 'workspace', 'faketransitive');
+        jetpack.write(path.join(depDir, 'package.json'), JSON.stringify({
+          name: '@omega.js/faketransitive',
+          version: '0.1.0',
+          private: true,
+          main: 'index.js',
+        }, null, 2));
+        jetpack.write(path.join(depDir, 'index.js'), 'module.exports = 1;\n');
+
+        // The framework package: declares it by REGISTRY spec (that is how
+        // @omega.js/backend spells @omega.js/client) and resolves it through a
+        // node_modules SYMLINK — the local-era shape npm workspaces / `mgr i local` make
+        const pkgDir = path.join(tmp, 'fakeframework');
+        jetpack.write(path.join(pkgDir, 'package.json'), JSON.stringify({
+          name: '@omega.js/fakeframework',
+          version: '1.0.0',
+          private: true,
+          main: 'index.js',
+          dependencies: { '@omega.js/faketransitive': '^0.1.0' },
+        }, null, 2));
+        jetpack.write(path.join(pkgDir, 'index.js'), 'module.exports = 2;\n');
+        jetpack.dir(path.join(pkgDir, 'node_modules', '@omega.js'));
+        fs.symlinkSync(depDir, path.join(pkgDir, 'node_modules', '@omega.js', 'faketransitive'), 'dir');
+
+        const functionsPath = path.join(tmp, 'functions');
+        jetpack.write(path.join(functionsPath, 'package.json'), `${JSON.stringify({
+          name: 'test-functions',
+          version: '0.0.1',
+          private: true,
+          dependencies: { '@omega.js/fakeframework': 'file:../fakeframework' },
+        }, null, 2)}\n`);
+
+        const staging = await stageLocalPackages({ functionsPath });
+
+        // BOTH packages ride the upload — the linked one too
+        assert.deepEqual(staging.staged, ['@omega.js/fakeframework', '@omega.js/faketransitive']);
+        assert.equal(jetpack.exists(path.join(functionsPath, 'omega_modules', 'omega.js-fakeframework-1.0.0.tgz')), 'file');
+        assert.equal(jetpack.exists(path.join(functionsPath, 'omega_modules', 'omega.js-faketransitive-0.1.0.tgz')), 'file');
+
+        // The framework tarball still declares `^0.1.0` internally — only an
+        // override redirects that NESTED resolution to the packed artifact
+        const stagedPkg = jetpack.read(path.join(functionsPath, 'package.json'), 'json');
+        assert.equal(stagedPkg.dependencies['@omega.js/fakeframework'], 'file:omega_modules/omega.js-fakeframework-1.0.0.tgz');
+        assert.equal(stagedPkg.overrides['@omega.js/faketransitive'], 'file:omega_modules/omega.js-faketransitive-0.1.0.tgz');
+
+        // The lock npm ci will read: resolved from the tarball, never the registry
+        const lock = jetpack.read(path.join(functionsPath, 'package-lock.json'), 'json');
+        const locked = lock.packages['node_modules/@omega.js/faketransitive'];
+        assert.ok(locked, 'the linked dependency is in the lockfile');
+        assert.equal(locked.resolved, 'file:omega_modules/omega.js-faketransitive-0.1.0.tgz');
+
+        // Restore: the override is staging-only, gone with everything else
+        await staging.restore();
+        const restored = jetpack.read(path.join(functionsPath, 'package.json'), 'json');
+        assert.equal(restored.dependencies['@omega.js/fakeframework'], 'file:../fakeframework');
+        assert.equal(restored.overrides, undefined, 'staging overrides never survive the restore');
+        assert.equal(jetpack.exists(path.join(functionsPath, 'omega_modules')), false, 'staging dir removed');
+
+        jetpack.remove(tmp);
+      },
+    },
+
+    {
+      // #331's second half: a failed staging must stop the deploy loudly — throw
+      // (never a swallowed ✗), and leave the functions folder exactly as found.
+      name: 'staging-failure-throws-and-restores-the-functions-folder',
+      async run({ assert }) {
+        const tmp = makeTmp();
+
+        const pkgDir = path.join(tmp, 'fakepkg');
+        jetpack.write(path.join(pkgDir, 'package.json'), JSON.stringify({
+          name: '@omega.js/fakepkg',
+          version: '1.0.0',
+          private: true,
+          main: 'index.js',
+        }, null, 2));
+        jetpack.write(path.join(pkgDir, 'index.js'), 'module.exports = 1;\n');
+
+        // The pack succeeds, then the LOCK REGEN fails (a file: spec pointing at
+        // a tarball that does not exist) — the failure lands AFTER the manifest
+        // was respelled on disk, which is exactly where the 404 landed
+        const functionsPath = path.join(tmp, 'functions');
+        const original = `${JSON.stringify({
+          name: 'test-functions',
+          version: '0.0.1',
+          private: true,
+          dependencies: {
+            '@omega.js/fakepkg': 'file:../fakepkg',
+            'never-here': 'file:missing-tarball.tgz',
+          },
+        }, null, 2)}\n`;
+        jetpack.write(path.join(functionsPath, 'package.json'), original);
+
+        let message = '';
+        try {
+          await stageLocalPackages({ functionsPath });
+        } catch (e) {
+          message = e.message;
+        }
+
+        assert.ok(message, 'a failing staging step throws — the deploy stops');
+        assert.ok(/staging failed/i.test(message), `the error names the staging lane: ${message}`);
+        assert.equal(jetpack.read(path.join(functionsPath, 'package.json')), original, 'manifest restored verbatim');
+        assert.equal(jetpack.exists(path.join(functionsPath, 'omega_modules')), false, 'no half-staged tarballs left behind');
+        assert.equal(jetpack.exists(path.join(functionsPath, 'package-lock.json')), false, 'no half-written lockfile left behind');
+
+        jetpack.remove(tmp);
+      },
+    },
+
+    {
+      // The exit code IS the contract: the observed #331 run printed the ✗ and
+      // read as a success. Spawn the real bin — nothing else pins an exit code.
+      name: 'deploy-exits-nonzero-when-staging-fails',
+      async run({ assert }) {
+        const tmp = makeTmp();
+
+        const targetRoot = path.join(tmp, 'app');
+        jetpack.write(path.join(targetRoot, 'package.json'), JSON.stringify({
+          name: 'exit-code-backend',
+          version: '0.0.1',
+          private: true,
+          engines: { node: '22' },
+          // A local dep whose directory carries no package.json — staging fails
+          // before npm is ever reached, so the exit code is all this measures
+          dependencies: { '@omega.js/brokenpkg': 'file:../brokenpkg' },
+        }, null, 2));
+        jetpack.write(path.join(targetRoot, 'src', 'index.js'), 'module.exports = 1;\n');
+        jetpack.write(path.join(targetRoot, 'config', 'omega.json5'), '{ brand: { id: \'exit-code\', name: \'Exit Code\' }, targets: { backend: {} } }');
+        jetpack.write(path.join(targetRoot, 'firebase.json'), JSON.stringify({ functions: { source: 'dist' } }, null, 2));
+        jetpack.dir(path.join(tmp, 'brokenpkg'));
+
+        const run = spawnSync(process.execPath, [BACKEND_BIN, 'deploy'], {
+          cwd: targetRoot,
+          encoding: 'utf8',
+          env: { ...process.env, OMEGA_SKIP_FRESHNESS: '1' },
+        });
+
+        assert.notEqual(run.status, 0, `a failed staging exits nonzero (got ${run.status})`);
+        assert.ok(/brokenpkg/.test(run.stdout + run.stderr), 'the failure names the package it could not stage');
+
+        jetpack.remove(tmp);
+      },
+    },
+
+    {
+      name: 'stage-functions-carries-the-composed-config-across-the-upload-boundary',
+      async run({ assert }) {
+        const tmp = makeTmp();
+
+        // Brand monorepo shape under the src/dist pillar: authored target tree
+        // (src/ + target-root manifest), NO local omega.json5 — the brand file's
+        // targets section is the per-target home (cp121c), and the STAGE step
+        // must carry the composed config across the upload boundary (#31).
+        const brandRoot = path.join(tmp, 'acme');
+        const targetRoot = path.join(brandRoot, 'targets', 'backend');
+        jetpack.write(path.join(brandRoot, 'config', 'omega.json5'), `{
+          // brand layer — must cross the upload boundary
+          brand: { id: 'acme', name: 'Acme Corp', url: 'https://acme.test' },
+          targets: { backend: { flavor: 'api' }, web: {} },
+        }`);
+        jetpack.write(path.join(targetRoot, 'package.json'), JSON.stringify({
+          name: 'acme-backend',
+          private: true,
+          engines: { node: '22' },
+          // The relative file: dep is spelled from the TARGET ROOT — the staged
+          // manifest must respell it one level deeper (dist/)
+          dependencies: { 'firebase-admin': '^13.0.0', '@acme/lib': 'file:../../libs/lib' },
+        }, null, 2));
+        jetpack.write(path.join(targetRoot, 'src', 'index.js'), 'module.exports = 1;\n');
+        jetpack.write(path.join(targetRoot, 'src', 'routes', 'ping', 'get.js'), 'module.exports = 2;\n');
+        jetpack.write(path.join(targetRoot, 'src', '.dotrc'), 'dotfiles ride the copy\n');
+        jetpack.write(path.join(targetRoot, 'src', 'public', '404.html'), 'CONSUMER 404\n');
+        jetpack.write(path.join(targetRoot, '.env'), 'FAKE_KEY="value"\n');
+        // Runtime artifacts that must SURVIVE a re-stage
+        jetpack.write(path.join(targetRoot, 'dist', 'node_modules', 'marker.txt'), 'kept');
+        jetpack.write(path.join(targetRoot, 'dist', 'emulator.log'), 'kept');
+        jetpack.write(path.join(targetRoot, 'dist', 'stale-old-file.js'), 'wiped');
+
+        const { distDir } = stageFunctions({ projectDir: targetRoot });
+
+        // src copied, derived manifest, stale content wiped, artifacts preserved
+        assert.equal(jetpack.read(path.join(distDir, 'index.js')), 'module.exports = 1;\n');
+        assert.equal(jetpack.read(path.join(distDir, 'routes', 'ping', 'get.js')), 'module.exports = 2;\n');
+        assert.equal(jetpack.read(path.join(distDir, '.dotrc')), 'dotfiles ride the copy\n', 'dotfiles in src/ are copied');
+        assert.equal(jetpack.exists(path.join(distDir, 'stale-old-file.js')), false, 'previous stage wiped');
+
+        // public/: consumer override wins, template default fills the gap
+        assert.equal(jetpack.read(path.join(distDir, 'public', '404.html')), 'CONSUMER 404\n', 'src/public override wins');
+        assert.ok(jetpack.exists(path.join(distDir, 'public', 'index.html')), 'template default fills the gap');
+        assert.equal(jetpack.exists(path.join(distDir, 'public', 'public')), false, 'src/public never double-nests');
+        assert.equal(jetpack.read(path.join(distDir, 'node_modules', 'marker.txt')), 'kept', 'node_modules preserved');
+        assert.equal(jetpack.read(path.join(distDir, 'emulator.log')), 'kept', 'logs preserved');
+        assert.equal(jetpack.read(path.join(distDir, '.env')), 'FAKE_KEY="value"\n', '.env rides the artifact');
+        const manifest = jetpack.read(path.join(distDir, 'package.json'), 'json');
+        assert.equal(manifest.name, 'acme-backend-functions');
+        assert.equal(manifest.main, 'index.js');
+        assert.equal(manifest.engines.node, '22');
+        assert.deepEqual(manifest.dependencies, {
+          'firebase-admin': '^13.0.0',
+          '@acme/lib': 'file:../../../libs/lib', // target-root-relative → dist-relative
+        });
+        assert.equal(manifest.scripts, undefined, 'scripts never ship in the artifact');
+
+        // Simulate the upload: the staged folder ALONE, no brand parent —
+        // the real loader must resolve brand values, not defaults
+        assert.ok(jetpack.read(path.join(distDir, 'config', 'omega.json5')).startsWith('// Staged by `omega build`'), 'staged config carries the banner');
+        const uploadDir = path.join(tmp, 'upload');
+        jetpack.copy(distDir, uploadDir);
+        const uploaded = loadConfig(uploadDir, 'backend', {
+          defaults: { brand: { id: 'my-app', name: 'My Brand' } },
+        });
+        assert.equal(uploaded.config.brand.name, 'Acme Corp', 'brand layer crossed the boundary');
+        assert.equal(uploaded.config.flavor, 'api', 'brand target section survived the flatten');
+        assert.equal(uploaded.enabled, true);
+
+        // Re-stage after a brand edit: the staged config NEVER feeds back in
+        // as a local layer (the wipe runs before the compose) — no staleness
+        jetpack.write(path.join(brandRoot, 'config', 'omega.json5'), `{
+          brand: { id: 'acme', name: 'Acme Corp RENAMED', url: 'https://acme.test' },
+          targets: { backend: { flavor: 'api' }, web: {} },
+        }`);
+        stageFunctions({ projectDir: targetRoot });
+        const restaged = loadConfig(distDir, 'backend');
+        assert.equal(restaged.config.brand.name, 'Acme Corp RENAMED', 'brand edit reflected on re-stage');
+
+        jetpack.remove(tmp);
+      },
+    },
+
+    {
+      name: 'stage-functions-composes-the-artifact-for-ONE-environment',
+      async run({ assert }) {
+        const tmp = makeTmp();
+        const targetRoot = path.join(tmp, 'targets', 'backend');
+
+        jetpack.write(path.join(tmp, 'config', 'omega.json5'), `{
+          brand: { id: 'acme', name: 'Acme Corp', url: 'https://acme.test' },
+          targets: { backend: {} },
+        }`);
+        jetpack.write(path.join(targetRoot, 'package.json'), JSON.stringify({ name: 'acme-backend', private: true }));
+        jetpack.write(path.join(targetRoot, 'src', 'index.js'), 'module.exports = 1;\n');
+
+        // The base .env is the live account; `.env.development` overlays the
+        // test credential a local run uses (#586). dist/.env is COMPOSED from
+        // the cascade by schema (#678): keys only, no marker comments — a
+        // verbatim copy is the OLD contract.
+        jetpack.write(path.join(targetRoot, '.env'), [
+          'STRIPE_SECRET_KEY="sk_live_fixture"',
+          'OMEGA_ADMIN_KEY="fixture-admin-key"',
+          '',
+        ].join('\n'));
+        jetpack.write(path.join(targetRoot, '.env.development'), 'STRIPE_SECRET_KEY="sk_test_fixture"\n');
+
+        // A LOCAL stage composes base + development — the emulator gets the
+        // test credential and never touches the live account
+        const local = stageFunctions({ projectDir: targetRoot, environment: 'development' });
+        const localStaged = jetpack.read(path.join(local.distDir, '.env'));
+        assert.equal(/^STRIPE_SECRET_KEY="sk_test_fixture"$/m.test(localStaged), true, 'the development overlay wins locally');
+        assert.equal(/^OMEGA_ADMIN_KEY="fixture-admin-key"$/m.test(localStaged), true, 'keys no overlay touches come from the base');
+
+        // The DEPLOY stage composes base + production. No `.env.production`
+        // exists, so the base ships — and the development overlay's value never
+        // rides the upload, neither as a row nor as a value
+        const deploy = stageFunctions({ projectDir: targetRoot, environment: 'production' });
+        const staged = jetpack.read(path.join(deploy.distDir, '.env'));
+
+        assert.equal(/^STRIPE_SECRET_KEY="sk_live_fixture"$/m.test(staged), true, 'the deployed artifact carries the live key');
+        assert.equal(staged.includes('sk_test_fixture'), false, "another environment's value never rides the upload");
+        assert.equal(/_DEV=/.test(staged), false, 'the _DEV twins are gone from the mechanism entirely (#586)');
+        assert.equal(/^OMEGA_ADMIN_KEY="fixture-admin-key"$/m.test(staged), true, 'unrelated keys are untouched');
+
+        jetpack.remove(tmp);
+      },
+    },
+
+    {
+      name: 'stage-functions-requires-the-authored-tree',
+      async run({ assert }) {
+        const tmp = makeTmp();
+
+        // (The runner's assert has no .throws — capture manually.)
+        const messageOf = (fn) => {
+          try { fn(); return ''; } catch (e) { return e.message; }
+        };
+
+        // No package.json at the target root → the manifest moved (clear error)
+        jetpack.write(path.join(tmp, 'src', 'index.js'), '// code');
+        assert.ok(/manifest lives at the TARGET ROOT/.test(messageOf(() => stageFunctions({ projectDir: tmp }))), 'missing manifest names the target-root home');
+
+        // Manifest but no src/ → instruct the src-first move
+        jetpack.write(path.join(tmp, 'package.json'), JSON.stringify({ name: 'x', private: true }));
+        jetpack.remove(path.join(tmp, 'src'));
+        assert.ok(/backend targets are src-first/.test(messageOf(() => stageFunctions({ projectDir: tmp }))), 'missing src/ instructs the src-first move');
+
+        jetpack.remove(tmp);
+      },
+    },
+
+    {
+      name: 'stage-functions-refuses-the-framework-package-itself',
+      async run({ assert }) {
+        const tmp = makeTmp();
+
+        // The framework package's own shape: a package.json named
+        // @omega.js/backend beside a src/ dir — which is exactly what a target
+        // root looks like to the stage. `npx omega emulator` from inside the
+        // framework (no target context to dispatch to) walked straight in, wiped
+        // the framework's OWN dist/ and then died on the missing omega.json5,
+        // leaving the CLI unbootable until `npm run prepare` (#308).
+        jetpack.write(path.join(tmp, 'package.json'), JSON.stringify({ name: '@omega.js/backend', private: true }));
+        jetpack.write(path.join(tmp, 'src', 'index.js'), '// framework source');
+        jetpack.write(path.join(tmp, 'dist', 'index.js'), '// prepared output');
+
+        const messageOf = (fn) => {
+          try { fn(); return ''; } catch (e) { return e.message; }
+        };
+        const message = messageOf(() => stageFunctions({ projectDir: tmp }));
+
+        assert.ok(/@omega\.js\/backend framework package/.test(message), `refusal names the framework package: ${message}`);
+        assert.ok(/npm run prepare/.test(message), 'refusal names how the framework dist/ is built');
+        assert.equal(jetpack.read(path.join(tmp, 'dist', 'index.js')), '// prepared output', 'refusal lands BEFORE the wipe — the prepared dist/ survives');
+
+        jetpack.remove(tmp);
+      },
+    },
+  ],
+});

package/test/boot/disposable-domains.test.js

@@ -0,0 +1,154 @@
+/**
+ * Test: the disposable-domain seed/cache contract (libraries/email/disposable-domains.js)
+ *
+ * Issue #68 — a refresh must never dirty the git tree. Real seams throughout:
+ * the only thing stubbed is the network fetch; the cache and seed are the real
+ * files on disk, and git itself is asked whether anything moved.
+ *
+ * Lives in the boot/ layer (framework self-test only) because it asks git about
+ * the framework checkout — a consumer's installed copy has no repo to ask.
+ */
+const { execFileSync } = require('child_process');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+
+const dataset = require('../../dist/manager/libraries/email/disposable-domains.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+const PACKAGE_DIR = path.resolve(__dirname, '../..');
+
+// Upstream's format: one lowercase domain per line.
+const STUBBED_LIST = 'zzz-stub-refresh.example\nAAA-Stub-Refresh.example\n\nzzz-stub-refresh.example\n';
+
+// `git status` scoped to this package — other packages may be dirty for reasons
+// that are not ours.
+function gitStatus() {
+  return execFileSync('git', ['status', '--porcelain', '--', PACKAGE_DIR], { cwd: PACKAGE_DIR, encoding: 'utf8' });
+}
+
+// Swap the cache aside for the duration of fn, restoring exactly what was there.
+async function withCacheStashed(fn) {
+  const existing = jetpack.read(dataset.CACHE_PATH);
+  jetpack.remove(dataset.CACHE_PATH);
+  try {
+    return await fn();
+  } finally {
+    if (existing === undefined) {
+      jetpack.remove(dataset.CACHE_PATH);
+    } else {
+      jetpack.write(dataset.CACHE_PATH, existing);
+    }
+  }
+}
+
+module.exports = defineCases({
+  description: 'Disposable-domain dataset (seed + gitignored refresh cache)',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'refresh-writes-the-cache-and-dirties-nothing-under-git',
+      timeout: 15000,
+
+      async run({ assert }) {
+        const seedBefore = jetpack.read(dataset.SEED_PATH);
+        const seedMtimeBefore = jetpack.inspect(dataset.SEED_PATH, { times: true }).modifyTime.getTime();
+        const statusBefore = gitStatus();
+
+        const originalFetch = global.fetch;
+        let fetchedUrl = null;
+        let seedAfter = null;
+        let seedMtimeAfter = null;
+        let statusAfter = null;
+
+        try {
+          await withCacheStashed(async () => {
+            global.fetch = async (url) => {
+              fetchedUrl = url;
+              return { ok: true, text: async () => STUBBED_LIST };
+            };
+
+            const result = await dataset.refresh();
+
+            seedAfter = jetpack.read(dataset.SEED_PATH);
+            seedMtimeAfter = jetpack.inspect(dataset.SEED_PATH, { times: true }).modifyTime.getTime();
+            statusAfter = gitStatus();
+
+            assert.equal(fetchedUrl, dataset.SOURCE_URL, 'refresh fetches the upstream list');
+            assert.equal(result.path, dataset.CACHE_PATH, 'refresh reports the cache path');
+            assert.deepEqual(
+              jetpack.read(dataset.CACHE_PATH, 'json'),
+              ['aaa-stub-refresh.example', 'zzz-stub-refresh.example'],
+              'the cache holds the deduped, lowercased, sorted list',
+            );
+          });
+        } finally {
+          global.fetch = originalFetch;
+          // If the thing under test DID write the seed, put the committed bytes
+          // back before failing — a regression here must not leave the tracked
+          // file holding the stub list.
+          if (jetpack.read(dataset.SEED_PATH) !== seedBefore) {
+            jetpack.write(dataset.SEED_PATH, seedBefore);
+          }
+        }
+
+        assert.equal(seedAfter, seedBefore, 'the committed seed is byte-identical after a refresh');
+        assert.equal(seedMtimeAfter, seedMtimeBefore, 'the committed seed was not even opened for writing');
+        assert.equal(statusAfter, statusBefore, 'a refresh leaves git status unchanged');
+      },
+    },
+
+    {
+      name: 'cache-path-is-gitignored',
+      timeout: 10000,
+
+      async run({ assert }) {
+        // check-ignore exits 1 when the path is NOT ignored — the whole contract
+        // rests on this, so ask git rather than trusting the .gitignore text.
+        const ignored = execFileSync('git', ['check-ignore', '--', dataset.CACHE_PATH], { cwd: PACKAGE_DIR, encoding: 'utf8' });
+
+        assert.ok(ignored.trim().length > 0, 'git reports the refresh cache path as ignored');
+      },
+    },
+
+    {
+      name: 'lookups-serve-the-seed-when-no-cache-exists',
+      timeout: 15000,
+
+      async run({ assert }) {
+        await withCacheStashed(async () => {
+          const seed = jetpack.read(dataset.SEED_PATH, 'json');
+
+          assert.deepEqual(dataset.load(), seed, 'load() falls back to the committed seed');
+
+          // The real lookup path, re-required with no cache on disk.
+          delete require.cache[require.resolve('../../dist/manager/libraries/email/validation.js')];
+          const { isDisposable } = require('../../dist/manager/libraries/email/validation.js');
+
+          assert.equal(isDisposable(`user@${seed[0]}`), true, 'a seed domain is still blocked with no cache present');
+          assert.equal(isDisposable('user@gmail.com'), false, 'a real provider is not blocked');
+        });
+
+        delete require.cache[require.resolve('../../dist/manager/libraries/email/validation.js')];
+      },
+    },
+
+    {
+      name: 'a-present-cache-wins-over-the-seed',
+      timeout: 15000,
+
+      async run({ assert }) {
+        await withCacheStashed(async () => {
+          jetpack.write(dataset.CACHE_PATH, `${JSON.stringify(['zzz-cache-wins.example'], null, 2)}\n`);
+
+          assert.deepEqual(dataset.load(), ['zzz-cache-wins.example'], 'load() prefers a usable cache');
+
+          // An unparseable cache is an expected external condition — never a throw.
+          jetpack.write(dataset.CACHE_PATH, '{ not json');
+
+          assert.deepEqual(dataset.load(), jetpack.read(dataset.SEED_PATH, 'json'), 'a corrupt cache falls back to the seed');
+        });
+      },
+    },
+  ],
+});

package/test/boot/emulator-boots.test.js

@@ -0,0 +1,39 @@
+/**
+ * Boot smoke — @omega.js/backend's framework self-test layer.
+ *
+ * Runs ONLY when `npx omega test` is invoked from the @omega.js/backend repo (the
+ * runner points OMEGA_TEST_BOOT_PROJECT at src/test/fixtures/firebase-project and
+ * sets isFrameworkSelfTest). It proves the whole self-test path works end to end:
+ * the fixture's functions/index.js boots `Manager.init()` inside the emulator, the
+ * `omega_api` function is wired, and the hosting rewrite routes to it.
+ *
+ * This is @omega.js/backend's equivalent of BXM's `boot/extension-loads` and UJM's site-boot
+ * smoke. It is EXCLUDED from real-consumer runs (see runner.js discoverTests).
+ */
+
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+module.exports = defineCases({
+  description: 'Boot smoke — fixture emulator + omega_api reachable',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'omega_api-health-responds-over-hosting-rewrite',
+      async run({ http, assert }) {
+        const response = await http.get('omega/health');
+        assert.isSuccess(response, 'omega_api /health should respond through the emulator hosting rewrite');
+      },
+    },
+    {
+      name: 'manager-booted-in-functions-runtime',
+      async run({ http, assert }) {
+        // /health is served by the omega_api function, which only exists if
+        // Manager.init() ran in the fixture's functions runtime. A success here
+        // means the local @omega.js/backend (symlinked into the fixture) booted.
+        const response = await http.get('omega/health');
+        assert.isSuccess(response, 'Manager.init() should have wired omega_api in the fixture functions runtime');
+      },
+    },
+  ],
+});