@omega.js/backend 0.1.0

package/dist/cli/commands/test.js

@@ -0,0 +1,976 @@
+const BaseCommand = require('./base-command');
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+const util = require('util');
+const { spawnShell } = require('../utils/spawn-shell');
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+const powertools = require('node-powertools');
+const { loadEmulatorPorts } = require('./setup-tests/emulator-config');
+const { javaInstallHint } = require('./setup-tests/helpers');
+const { readPortsFile, portsToEnv } = require('../../vendor/config/index.js');
+const { writeTestMode, captureSyncedEnv, SYNCED_ENV_KEYS } = require('../../test/utils/test-mode-file');
+const EmulatorCommand = require('./emulator');
+const { refuseWhenCustom } = require('../utils/project-type');
+const { runTargetChecks } = require('../utils/target-checks');
+const { STOP_SIGNALS } = require('../../vendor/devkit/stop-signals.js');
+
+// The Firebase emulator hub — fixed, not part of the N7-allocated map.
+const HUB_PORT = 4400;
+
+// Where a running hub publishes WHO it is: firebase-tools writes
+// `${os.tmpdir()}/hub-<projectId>.json` ({version, origins, pid}) for the life
+// of the stack. The file name IS the identity — the hub's own
+// `GET /emulators` answers a map of emulator → listen info and has never
+// carried a project id, so the read that asked it for one always came back
+// empty ([#258](https://github.com/Omega-JS-Stack/omega/issues/258)).
+const HUB_LOCATOR_PREFIX = 'hub-';
+const HUB_LOCATOR_SUFFIX = '.json';
+
+/**
+ * Does a process with this pid exist right now?
+ *
+ * Signal 0 checks for existence without delivering anything. EPERM means it
+ * exists and belongs to another user — still alive, which is the question.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 1) {
+    return false;
+  }
+
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+/**
+ * The project id of the emulator whose HUB is listening on `hubPort`, read
+ * from the locator files firebase-tools publishes.
+ *
+ * A locator only counts when it claims THIS port and its pid is still alive —
+ * firebase-tools does not always remove the file, so a crashed run's leftover
+ * would otherwise name a hub that is long gone. Two live claims on one port
+ * mean one of them is a stale file whose pid got recycled, and nothing says
+ * which: ambiguous reads as unproven, the same safe fall-through as no file at
+ * all ([#258](https://github.com/Omega-JS-Stack/omega/issues/258)).
+ * @param {number} hubPort - The hub port to identify.
+ * @param {string} [tmpDir] - Where locators live (defaults to os.tmpdir()).
+ * @returns {string|null} The project id, or null when unproven.
+ */
+function readHubLocatorProjectId(hubPort, tmpDir) {
+  const dir = tmpDir || os.tmpdir();
+  const claimants = new Set();
+
+  for (const name of jetpack.list(dir) || []) {
+    if (!name.startsWith(HUB_LOCATOR_PREFIX) || !name.endsWith(HUB_LOCATOR_SUFFIX)) {
+      continue;
+    }
+
+    const projectId = name.slice(HUB_LOCATOR_PREFIX.length, -HUB_LOCATOR_SUFFIX.length);
+    if (!projectId) {
+      continue;
+    }
+
+    let locator;
+    try {
+      locator = jetpack.read(path.join(dir, name), 'json');
+    } catch (error) {
+      continue; // Not a locator, or half-written
+    }
+
+    const onThisPort = (locator?.origins || []).some((origin) => {
+      try {
+        return Number(new URL(origin).port) === Number(hubPort);
+      } catch (error) {
+        return false;
+      }
+    });
+
+    if (onThisPort && isProcessAlive(Number(locator.pid))) {
+      claimants.add(projectId);
+    }
+  }
+
+  return claimants.size === 1 ? [...claimants][0] : null;
+}
+
+/**
+ * Adopt the emulator already listening on our functions port, or allocate
+ * fresh ports and boot our own?
+ *
+ * A bare port probe answered "something is listening", which the run read as
+ * "our emulator is up" — so another brand's stack on the classic ports got
+ * adopted and the run died on a health fetch against the wrong project
+ * ([#258](https://github.com/Omega-JS-Stack/omega/issues/258)). Adoption now
+ * needs PROOF of identity: unproven falls through to the N7 bump path, which
+ * relocates around the incumbent exactly as a second brand's boot does.
+ * @param {object} evidence
+ * @param {boolean} evidence.portInUse - Something is listening on the functions port.
+ * @param {boolean} [evidence.ownsPortsFile] - This project's own live ports file publishes that port.
+ * @param {string|null} evidence.runningProjectId - Project id the listener reports (null when unreadable).
+ * @param {string|null} evidence.expectedProjectId - Project id this run belongs to.
+ * @returns {{adopt: boolean, reason: string, runningProjectId: string|null}}
+ */
+function decideEmulatorAdoption({ portInUse, ownsPortsFile, runningProjectId, expectedProjectId }) {
+  const decision = { adopt: false, reason: 'no-emulator', runningProjectId: runningProjectId || null };
+
+  if (!portInUse) {
+    return decision;
+  }
+
+  // This project's .temp/ports.json, written by OUR emulator and read only
+  // while its writer is alive. The hub is NOT allocated by N7, so a bumped run
+  // shares it with whoever booted first — this is the proof that still holds.
+  if (ownsPortsFile) {
+    return { ...decision, adopt: true, reason: 'ports-file' };
+  }
+
+  if (!runningProjectId || !expectedProjectId) {
+    return { ...decision, reason: 'unidentified' };
+  }
+
+  if (runningProjectId !== expectedProjectId) {
+    return { ...decision, reason: 'project-mismatch' };
+  }
+
+  return { ...decision, adopt: true, reason: 'project-match' };
+}
+
+class TestCommand extends BaseCommand {
+  async execute() {
+    const self = this.main;
+    const argv = self.argv;
+
+    // The emulator test lane needs Cloud Functions; custom mode has none (#584)
+    if (refuseWhenCustom(self.firebaseProjectPath, 'test')) return;
+
+    // Tee THIS process to <targetRoot>/logs/test.log (#197) — the setup lines, the
+    // port summary and the emulator boot that the runner-child's dist/test.log
+    // never sees.
+    this.attachVerbLog('test');
+
+    // `--extended` CLI shorthand for the shared, unprefixed TEST_EXTENDED_MODE
+    // env var (cross-framework parity with BXM/UJM/EM). Either the flag OR the
+    // env var opts into REAL external services (default skipped). Set this
+    // BEFORE the captureSyncedEnv/writeTestMode pre-flight below so the flag
+    // flows into the emulator's test-mode.json too — making
+    // `npx omega test --extended` equivalent to `TEST_EXTENDED_MODE=true npx omega test`.
+    if (argv.extended) {
+      process.env.TEST_EXTENDED_MODE = 'true';
+    }
+
+    // Framework self-test: when `npx omega test` is run from the @omega.js/backend repo
+    // (no firebase.json in cwd), boot the bundled fixture project under
+    // src/test/fixtures/firebase-project. Mirrors BXM/UJM *_TEST_BOOT_PROJECT.
+    const isSelfTest = this.setupSelfTest();
+
+    // The AUDIT half of the retired `omega setup` (#675): the target checks
+    // run before anything boots, healing what they can and halting on what
+    // they cannot. Skipped on the framework self-test — the bundled fixture is
+    // not a consumer target to heal, and the checks would rewrite it.
+    if (!isSelfTest) {
+      this.ui.section('Target checks');
+      await runTargetChecks(self);
+    }
+
+    // functions/ is staged output (src/dist pillar): stage fresh so the run
+    // reads current src + composed config. The auto-start emulator path stages
+    // again inside startEmulators — idempotent and cheap; THIS call covers the
+    // existing-emulator path, where nothing else would refresh the tree.
+    // A test lane composes its .env for TESTING (#586): the run's own
+    // OMEGA_TEST_MODE is set on the emulator child, not on this process, so the
+    // environment is named here rather than sniffed.
+    this.ensureStaged({ environment: 'testing' });
+
+    // Get test paths from CLI args (e.g., "bem test admin/" or "bem test general/generate-uuid")
+    const testPaths = (argv._ || []).slice(1); // Remove 'test' from args
+
+    // On self-test with no explicit target, run only the boot smoke suite —
+    // the fast inner loop. The FULL suite also passes against the fixture
+    // (`npm test -- backend:`): it carries corpus-parity payment config and
+    // boot-syncs the canonical rules for exactly that.
+    if (isSelfTest && testPaths.length === 0) {
+      testPaths.push('backend:boot');
+    }
+
+    // Determine the project directory
+    const projectDir = self.firebaseProjectPath;
+    const functionsDir = path.join(projectDir, 'dist');
+
+    // Pre-flight: write the allowlisted env subset to a shared state file
+    // (`<projectDir>/.temp/test-mode.json`). The running emulator watches this
+    // file and mutates its own `process.env` to match, eliminating the need
+    // to coordinate env vars across both terminals. The test command is the
+    // authoritative writer — whatever you pass here becomes the live mode
+    // within ~50ms.
+    //
+    // Allowlist lives in src/test/utils/test-mode-file.js (SYNCED_ENV_KEYS).
+    // Today: just TEST_EXTENDED_MODE. Add more keys there to make them
+    // live-syncable.
+    {
+      const envSubset = captureSyncedEnv(process.env);
+      writeTestMode(projectDir, envSubset);
+      const extended = !!process.env.TEST_EXTENDED_MODE;
+      this.log(chalk.gray(`  Test mode: ${extended ? 'extended (real external APIs)' : 'normal (external APIs skipped)'}`));
+    }
+
+    // N7: a RUNNING emulator's published port map wins — it may have bumped
+    // off the firebase.json values (second-brand boot). No live map →
+    // firebase.json/classic (and the auto-start path re-resolves after boot).
+    let emulatorPorts = loadEmulatorPorts(projectDir);
+    const publishedPorts = readPortsFile(projectDir);
+    if (publishedPorts) {
+      emulatorPorts = { ...emulatorPorts, ...publishedPorts };
+    }
+
+    // Load project configuration
+    const projectConfig = this.loadProjectConfig(functionsDir, argv);
+    if (!projectConfig) {
+      // Config-validation abort must fail the process — a bare return exits 0
+      // and reads as a green run to any script chaining on the exit code.
+      process.exitCode = 1;
+      return;
+    }
+
+    // Opt-in lanes. OFF by default and gated on conditions the default suite
+    // must never depend on (credentials, the network, a CLI). A gate that
+    // refuses prints ONE line and the run exits clean — a skipped lane is a
+    // normal outcome, not a failure
+    // ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+    if (argv.lane) {
+      const gate = this.openLane(argv.lane);
+
+      if (!gate) {
+        return;
+      }
+
+      this.lane = gate;
+      testPaths.push(`backend:${gate.laneModule.LANE}`);
+    }
+
+    // Build unified test config object
+    // Use hosting URL for all API requests (rewrites to omega_api function)
+    const testConfig = {
+      ...projectConfig,
+      apiUrl: `http://127.0.0.1:${emulatorPorts.hosting}`,
+      projectDir,
+      testPaths,
+      emulatorPorts,
+      isFrameworkSelfTest: isSelfTest, // gates the boot/ smoke layer (excluded for consumers)
+    };
+
+    // Adopt the running emulator only when it PROVES it is ours — a listener on
+    // the functions port is not evidence of ownership
+    // ([#258](https://github.com/Omega-JS-Stack/omega/issues/258)).
+    const portInUse = await this.isEmulatorRunning(emulatorPorts);
+    const adoption = decideEmulatorAdoption({
+      portInUse: portInUse,
+      ownsPortsFile: !!publishedPorts && publishedPorts.functions === emulatorPorts.functions,
+      runningProjectId: portInUse ? this.readRunningProjectId(emulatorPorts) : null,
+      expectedProjectId: projectConfig.cloud?.config?.projectId || null,
+    });
+
+    if (adoption.adopt) {
+      this.log(chalk.cyan('Running tests against EXISTING emulator'));
+
+      // The forwarder needs the RESOLVED port, so it starts here rather than at
+      // the gate — and stops in the finally, so a failed run never leaves a
+      // `stripe listen` behind holding the terminal.
+      const laneSession = await this.startLane(testConfig, emulatorPorts);
+
+      try {
+        await this.runTestsDirectly(this.buildTestCommand({ ...testConfig, laneEnv: laneSession.env }), functionsDir, emulatorPorts);
+      } finally {
+        laneSession.stop();
+      }
+    } else {
+      if (adoption.reason === 'project-mismatch') {
+        this.log(chalk.yellow(`  Port ${emulatorPorts.functions} belongs to project "${adoption.runningProjectId}", not "${projectConfig.cloud?.config?.projectId}" — booting this project's own emulator on free ports.`));
+      } else if (adoption.reason === 'unidentified') {
+        this.log(chalk.yellow(`  Port ${emulatorPorts.functions} is in use by a listener that does not identify itself — booting this project's own emulator on free ports.`));
+      }
+
+      this.log(chalk.cyan('Starting emulator and running tests...'));
+      // The command is built INSIDE runEmulatorTests, after boot — allocation
+      // may bump ports, and a pre-built command would bake the stale ones.
+      await this.runEmulatorTests(testConfig, functionsDir);
+    }
+  }
+
+  /**
+   * Open an opt-in lane, or say why it stays shut
+   *
+   * The ONE decision point for every lane: the gate answers from facts already
+   * on this machine (a credential, a CLI, the environment), so a refusal costs
+   * nothing and reads as a skip. Nothing is started here — the forwarding needs
+   * a port the emulator has not chosen yet.
+   *
+   * @param {string} name - The `--lane=` value
+   * @returns {object|null} The opened lane, or null when it stays shut
+   */
+  openLane(name) {
+    let laneModule;
+
+    try {
+      laneModule = require(path.join(__dirname, 'test-lanes', `${name}.js`));
+    } catch (error) {
+      this.logError(`Unknown test lane: ${name}`);
+      process.exitCode = 1;
+      return null;
+    }
+
+    const decision = laneModule.resolveGate({ env: laneModule.env, hasStripeCli: !!laneModule.findStripeCli() });
+
+    if (!decision.ok) {
+      this.log(laneModule.skipLine(decision.reason));
+      return null;
+    }
+
+    this.log(chalk.cyan(`  Lane --lane=${name}: ENABLED (real external services)`));
+
+    return { laneModule, decision };
+  }
+
+  /**
+   * Bring an opened lane up against the RESOLVED emulator ports
+   *
+   * Creates the Stripe fixtures the brand's catalogue needs (idempotently — a
+   * rerun reuses them) and starts the forwarder, handing back the env the runner
+   * child needs and the stop the caller owes it. No lane opened = an inert
+   * session, so both run paths call this unconditionally.
+   *
+   * @param {object} testConfig - The resolved test config
+   * @param {object} emulatorPorts - The port map the emulator actually took
+   * @returns {Promise<{ env: object, stop: function }>}
+   */
+  async startLane(testConfig, emulatorPorts) {
+    const inert = { env: {}, stop: () => {} };
+
+    if (!this.lane) {
+      return inert;
+    }
+
+    const { laneModule, decision } = this.lane;
+    const stripePath = laneModule.findStripeCli();
+
+    const { fixtures, unsupported } = laneModule.planFixtures(
+      testConfig.payment?.products,
+      testConfig.payment?.currency,
+    );
+
+    for (const item of unsupported) {
+      this.logWarning(`  Lane ${laneModule.LANE}: ${item.productId} has no Stripe fixture — ${item.reason}`);
+    }
+
+    const stripe = require('stripe')(decision.key);
+
+    await laneModule.ensureFixtures({
+      stripe: stripe,
+      fixtures: fixtures,
+      log: (line) => this.log(chalk.gray(`  [${laneModule.LANE}] ${line}`)),
+    });
+
+    const { stop } = await laneModule.startForwarding({
+      apiKey: decision.key,
+      forwardUrl: laneModule.forwardUrl({ hostingPort: emulatorPorts.hosting, webhookKey: testConfig.webhookKey }),
+      log: (line) => this.log(chalk.gray(`  [Stripe] ${line}`)),
+    });
+
+    this.log(chalk.gray(`  [${laneModule.LANE}] forwarding real test-mode webhooks to localhost:${emulatorPorts.hosting}\n`));
+
+    return {
+      env: {
+        [laneModule.LANE_ENV]: laneModule.LANE,
+        STRIPE_CLI_PATH: stripePath,
+      },
+      stop: stop,
+    };
+  }
+
+  /**
+   * Load project configuration from config/omega.json5 and .env
+   */
+  loadProjectConfig(functionsDir, argv) {
+    const { hasOmegaConfig, loadConfig, loadEnv, resolvedBrandHost } = require('../../vendor/config/index.js');
+
+    // Load the .env cascade first so env vars are available
+    loadEnv(functionsDir);
+
+    // Load config/omega.json5 (resolved — the loader walks up to the brand
+    // layer from the functions dir in a brand monorepo)
+    if (!hasOmegaConfig(functionsDir)) {
+      this.logError('Error: Missing config/omega.json5');
+      return null;
+    }
+
+    let config;
+    try {
+      config = loadConfig(functionsDir, 'backend').config;
+    } catch (error) {
+      this.logError(`Error: Could not load config/omega.json5: ${error.message}`);
+      return null;
+    }
+
+    // Derive computed values (not in config file)
+    const adminKey = argv.key || process.env.OMEGA_ADMIN_KEY;
+    const webhookKey = argv.webhookKey || process.env.OMEGA_WEBHOOK_KEY;
+    // The persona domain is the brand's HOST — one derivation, shared with the
+    // seeder and the dev palette
+    // ([#708](https://github.com/Omega-JS-Stack/omega/issues/708)).
+    const domain = resolvedBrandHost(config);
+
+    // Validate required configuration
+    if (!config.cloud?.config?.projectId) {
+      this.logError('Error: Missing cloud.config.projectId in config/omega.json5');
+      return null;
+    }
+
+    if (!adminKey) {
+      this.logError('Error: Missing admin key');
+      this.log(chalk.gray('  Set OMEGA_ADMIN_KEY in your .env file or pass --key flag'));
+      return null;
+    }
+
+    if (!webhookKey) {
+      this.logError('Error: Missing webhook key');
+      this.log(chalk.gray('  Set OMEGA_WEBHOOK_KEY in your .env file or pass --webhook-key flag'));
+      return null;
+    }
+
+    if (!config.brand?.id) {
+      this.logError('Error: Missing brand.id in config/omega.json5');
+      return null;
+    }
+
+    if (!domain) {
+      this.logError('Error: Missing brand.url in config/omega.json5 (personas are seeded on the brand host)');
+      return null;
+    }
+
+    // Pass entire config + computed values not in config file
+    return {
+      ...config,
+      adminKey,
+      webhookKey,
+      domain,
+    };
+  }
+
+  /**
+   * Build the test command with environment variables
+   */
+  /**
+   * Framework self-test detection + fixture wiring.
+   *
+   * When `npx omega test` runs from a directory that is NOT a Firebase project
+   * (no firebase.json) AND is the @omega.js/backend repo (or OMEGA_TEST_BOOT_PROJECT
+   * is set), point the run at the bundled fixture project and link the local
+   * framework + firebase deps into it so the emulator's function workers resolve
+   * them. This is @omega.js/backend's equivalent of BXM's OMEGA_TEST_BOOT_PROJECT / UJM's
+   * UJ_TEST_BOOT_PROJECT. Returns true if self-test wiring was applied.
+   */
+  setupSelfTest() {
+    const self = this.main;
+
+    // Normal consumer run — cwd is already a Firebase project. Nothing to do.
+    if (jetpack.exists(path.join(self.firebaseProjectPath, 'firebase.json'))) {
+      return false;
+    }
+
+    // Self-test if OMEGA_TEST_BOOT_PROJECT is set, or cwd is the @omega.js/backend repo.
+    let isSelfTest = !!process.env.OMEGA_TEST_BOOT_PROJECT;
+    if (!isSelfTest) {
+      try {
+        isSelfTest = require(path.join(process.cwd(), 'package.json')).name === '@omega.js/backend';
+      } catch (_) { /* no package.json — not a self-test */ }
+    }
+    if (!isSelfTest) {
+      return false;
+    }
+
+    const fixture = process.env.OMEGA_TEST_BOOT_PROJECT
+      ? path.resolve(process.env.OMEGA_TEST_BOOT_PROJECT)
+      : path.resolve(__dirname, '..', '..', 'test', 'fixtures', 'firebase-project');
+
+    process.env.OMEGA_TEST_BOOT_PROJECT = fixture;
+    self.firebaseProjectPath = fixture;
+
+    // The test HTTP client authenticates with the fixture's admin keys (the
+    // server reads the same keys from config/omega.json5). Inject them from
+    // the fixture config so loadProjectConfig finds them — no committed .env
+    // needed (single source = the fixture config). The namespace rides the
+    // same mechanism: the uuid route's v5 default reads OMEGA_NAMESPACE in
+    // the emulated functions, which inherit this process env.
+    try {
+      const cfg = require('../../vendor/config/index.js').loadConfig(fixture, 'backend').config;
+      process.env.OMEGA_ADMIN_KEY = process.env.OMEGA_ADMIN_KEY || cfg.omega?.key;
+      process.env.OMEGA_WEBHOOK_KEY = process.env.OMEGA_WEBHOOK_KEY || cfg.omega?.webhookKey;
+      process.env.OMEGA_NAMESPACE = process.env.OMEGA_NAMESPACE || cfg.omega?.namespace;
+    } catch (_) { /* fixture config unreadable — let the normal key check report it */ }
+
+    // Anonymous HMAC unsubscribe tests sign links with this shared secret; the
+    // emulated functions inherit it from this process env (same mechanism as the
+    // webhook key above). Test-only value — production sets its own env var.
+    process.env.UNSUBSCRIBE_HMAC_KEY = process.env.UNSUBSCRIBE_HMAC_KEY || '_test-unsubscribe-hmac-key';
+
+    this.ensureFixtureServiceAccount(fixture);
+    this.ensureFixtureEnv(fixture);
+    this.ensureFixtureRules(fixture);
+    this.linkFixtureDeps(fixture);
+    this.log(chalk.cyan(`  Self-test: booting bundled fixture project (${fixture})`));
+    return true;
+  }
+
+  /**
+   * Write a throwaway service-account.json into the fixture so firebase-admin's
+   * `cert()` can parse it. @omega.js/backend's manager uses the cert path when
+   * GOOGLE_APPLICATION_CREDENTIALS is unset (as in the functions emulator). The
+   * key is a freshly-generated RSA key — emulator-only, never authenticates
+   * against Google (the project is a `demo-` project), so it is generated at
+   * runtime and gitignored, never committed. Written to the TARGET ROOT (the
+   * authored home under the src/dist pillar) — the stage step carries it into
+   * functions/.
+   */
+  ensureFixtureServiceAccount(fixture) {
+    const crypto = require('crypto');
+    const saPath = path.join(fixture, 'service-account.json');
+    const projectId = 'demo-omega-backend';
+    const { privateKey } = crypto.generateKeyPairSync('rsa', {
+      modulusLength: 2048,
+      privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+      publicKeyEncoding: { type: 'spki', format: 'pem' },
+    });
+    const serviceAccount = {
+      type: 'service_account',
+      project_id: projectId,
+      private_key_id: '0'.repeat(40),
+      private_key: privateKey,
+      client_email: `fixture@${projectId}.iam.gserviceaccount.com`,
+      client_id: '0'.repeat(21),
+      auth_uri: 'https://accounts.google.com/o/oauth2/auth',
+      token_uri: 'https://oauth2.googleapis.com/token',
+      auth_provider_x509_cert_url: 'https://www.googleapis.com/oauth2/v1/certs',
+      client_x509_cert_url: `https://www.googleapis.com/robot/v1/metadata/x509/fixture%40${projectId}.iam.gserviceaccount.com`,
+    };
+    try {
+      fs.writeFileSync(saPath, `${JSON.stringify(serviceAccount, null, 2)}\n`);
+    } catch (e) {
+      this.logWarning(`Could not write fixture service-account.json: ${e.message}`);
+    }
+  }
+
+  /**
+   * Seed the fixture's `.env` with every key the env schema marks REQUIRED
+   * ([#581](https://github.com/Omega-JS-Stack/omega/issues/581)). The fixture
+   * carries a consumer `config/omega.json5`, so it IS a brand's backend to the
+   * boot guard — and firebase-tools analyzes function definitions in its own
+   * child process, which never saw the values injected into this one above, so
+   * `Manager.init()` threw before a single function loaded.
+   *
+   * Values come from the SAME resolution the injection above does (the fixture
+   * config's `omega.*` keys, the shared unsubscribe secret), so the server and
+   * the test client authenticate with one value; a key the schema marks
+   * required LATER gets an obvious dummy, so the fixture can never fall behind
+   * the schema again. Existing lines are never touched — a fixture edit
+   * survives the run that reads it. Written to the TARGET ROOT (the authored
+   * home under the src/dist pillar); the stage step carries it into functions/.
+   * Emulator-only values, gitignored like the service account, never committed.
+   */
+  ensureFixtureEnv(fixture) {
+    const { requiredEnvKeys } = require('../../vendor/config/index.js');
+    const envPath = path.join(fixture, '.env');
+    const existing = jetpack.exists(envPath) ? jetpack.read(envPath) : '';
+    const present = util.parseEnv(existing);
+
+    const lines = requiredEnvKeys('backend')
+      .filter((name) => !present[name])
+      .map((name) => `${name}="${process.env[name] || `fixture-${name.toLowerCase().replace(/_/g, '-')}`}"`);
+
+    if (lines.length === 0) {
+      return;
+    }
+
+    const header = existing ? '' : '# @omega.js/backend self-test fixture — emulator-only values, seeded per run.\n';
+
+    try {
+      jetpack.write(envPath, `${header}${existing}${existing && !existing.endsWith('\n') ? '\n' : ''}${lines.join('\n')}\n`);
+    } catch (e) {
+      this.logWarning(`Could not write fixture .env: ${e.message}`);
+    }
+  }
+
+  /**
+   * Seed the fixture's BRAND rules source — the same seed the scaffold ships
+   * to a consumer. The framework half is no longer
+   * copied anywhere: the stage below compiles it in
+   * ([#255](https://github.com/Omega-JS-Stack/omega/issues/255)), so the rules
+   * suite exercises the real compiled artifact, exactly what a consumer
+   * deploys. Runtime-derived and gitignored like the service account, and
+   * never clobbered — a fixture edit survives the run that reads it.
+   */
+  ensureFixtureRules(fixture) {
+    const { ensureBrandRulesSource } = require('../utils/compile-rules');
+    ensureBrandRulesSource({ projectDir: fixture });
+  }
+
+  /**
+   * Symlink the local framework + firebase deps into the fixture's TARGET-ROOT
+   * node_modules so the emulator's function workers can resolve them — Node
+   * resolution walks up from the staged functions/ tree (which carries no
+   * node_modules of its own under the src/dist pillar). Mirrors what
+   * `npx omega install dev` does in a real consumer, but for the fixture and
+   * without an npm install (firebase-admin/firebase-functions come from
+   * @omega.js/backend's own node_modules; @omega.js/backend points at the repo root).
+   */
+  linkFixtureDeps(fixture) {
+    const fnNodeModules = path.join(fixture, 'node_modules');
+    jetpack.dir(fnNodeModules);
+
+    const frameworkRoot = path.resolve(__dirname, '..', '..', '..'); // src/cli/commands -> repo root
+    const links = {
+      '@omega.js/backend': frameworkRoot,
+      'firebase-admin': path.join(frameworkRoot, 'node_modules', 'firebase-admin'),
+      'firebase-functions': path.join(frameworkRoot, 'node_modules', 'firebase-functions'),
+    };
+
+    for (const [name, target] of Object.entries(links)) {
+      const linkPath = path.join(fnNodeModules, name);
+      try { fs.rmSync(linkPath, { recursive: true, force: true }); } catch (_) { /* nothing to remove */ }
+      try {
+        // The link's PARENT, not just node_modules — a scoped name like
+        // @omega.js/backend needs its node_modules/@omega.js dir to exist first
+        fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+        fs.symlinkSync(target, linkPath, process.platform === 'win32' ? 'junction' : 'dir');
+      } catch (e) {
+        this.logWarning(`Could not link ${name} into fixture: ${e.message}`);
+      }
+    }
+  }
+
+  buildTestCommand(testConfig) {
+    const testScriptPath = path.join(__dirname, '..', '..', 'test', 'run-tests.js');
+
+    // The RESOLVED port map, minus the TLS front. The runner loads route
+    // handlers IN-PROCESS, so its Manager's URL getters answer from
+    // OMEGA_*_PORT the same way a function worker's do — unset, they fell back
+    // to the classic 5002, which under `omega emulator`'s HTTPS default is the
+    // mkcert proxy, not hosting: the test provider's auto-webhook followed the
+    // proxy's 307 to https and died on a cert this process has no CA for
+    // ([#291](https://github.com/Omega-JS-Stack/omega/issues/291)). `https` is
+    // deliberately dropped — the runner is a plain-http client of the stack
+    // (its own apiUrl already is), so it gets hosting's internal port.
+    const { https: _tlsFront, ...plainHttpPorts } = testConfig.emulatorPorts;
+
+    // Pass entire config as base64-encoded JSON to avoid shell escaping issues
+    const testEnv = {
+      ...portsToEnv(plainHttpPorts),
+      OMEGA_TEST_CONFIG: Buffer.from(JSON.stringify(testConfig)).toString('base64'),
+      FIRESTORE_EMULATOR_HOST: `127.0.0.1:${testConfig.emulatorPorts.firestore}`,
+      FIREBASE_AUTH_EMULATOR_HOST: `127.0.0.1:${testConfig.emulatorPorts.auth}`,
+      // The project the emulator booted with — resolved from the same config
+      // the emulator command boots on (loadProjectConfig hard-fails without it).
+      // The runner's admin app and the wipe's auth bulk-clear both read it, and
+      // the wipe's URL names a project the emulator answers 200 for whether it
+      // knows it or not: without this the wipe cleared a project nothing in the
+      // run ever touched and reported success
+      // ([#292](https://github.com/Omega-JS-Stack/omega/issues/292)).
+      GCLOUD_PROJECT: testConfig.cloud.config.projectId,
+      // GCLOUD_PROJECT alone makes the child's init-time environment read as
+      // production (nothing else marks it yet: runner.js stamps its own
+      // OMEGA_TEST_MODE only later, inside run()), which wakes the
+      // firebase-functions logger compat shim and turns every test line into
+      // JSON. Say what this process IS before Manager.init() looks.
+      OMEGA_TEST_MODE: 'true',
+      // An opt-in lane's own environment: the lane name the runner's discovery
+      // gates on, plus whatever the lane brought up (the forwarder's signing
+      // secret). Empty on every default run.
+      ...(testConfig.laneEnv || {}),
+    };
+
+    const envString = Object.entries(testEnv)
+      .map(([key, value]) => `${key}='${value}'`)
+      .join(' ');
+
+    return `${envString} node "${testScriptPath}"`;
+  }
+
+  /**
+   * Check if emulator is already running
+   * @param {object} emulatorPorts - The port map this run expects.
+   * @returns {Promise<boolean>}
+   */
+  isEmulatorRunning(emulatorPorts) {
+    // Check if functions emulator port is in use
+    // If it is, assume emulator is running
+    return this.isPortInUse(emulatorPorts.functions);
+  }
+
+  /**
+   * The project id the emulator listening on our ports belongs to, read from
+   * the hub locator firebase-tools publishes for a running stack. Anything
+   * unproven (no locator, a dead pid, two live claims) comes back null, which
+   * the decision above treats as "unidentified", never as "ours".
+   * @param {object} emulatorPorts - The resolved port map.
+   * @returns {string|null} The running emulator's project id.
+   */
+  readRunningProjectId(emulatorPorts) {
+    return readHubLocatorProjectId(emulatorPorts?.hub || HUB_PORT);
+  }
+
+  /**
+   * Signal the running emulator process to roll emulator.log.
+   *
+   * Mechanism: write a sentinel file at emulator.log.reset. The emulator command
+   * (src/cli/commands/emulator.js) polls for it and, on detection, closes its
+   * current write stream and reopens with flags: 'w' (truncating cleanly from its
+   * own perspective — avoids the sparse-file problem caused by external truncation).
+   *
+   * Waits up to 2s for the sentinel to be consumed. If it's still there after 2s
+   * the emulator isn't watching (probably running an older @omega.js/backend or started outside
+   * `npx omega emulator`); we delete the sentinel and proceed — tests still run, the
+   * log just won't be reset for this run.
+   */
+  async requestEmulatorLogReset(projectDir) {
+    const sentinelPath = this.getTempPath('emulator.log.reset');
+
+    try {
+      fs.writeFileSync(sentinelPath, '');
+    } catch (e) {
+      return; // Can't write — skip, not fatal
+    }
+
+    // Poll for the emulator to consume the sentinel (it deletes the file when done)
+    const maxWaitMs = 2000;
+    const pollIntervalMs = 100;
+    const start = Date.now();
+
+    while (Date.now() - start < maxWaitMs) {
+      if (!fs.existsSync(sentinelPath)) {
+        return; // Emulator picked it up and rolled the log
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+
+    // Timed out — emulator didn't see the sentinel. Clean up so we don't leave it behind.
+    try { fs.unlinkSync(sentinelPath); } catch (e) { /* ok */ }
+  }
+
+  /**
+   * Run tests directly (emulator already running)
+   */
+  async runTestsDirectly(testCommand, functionsDir, emulatorPorts) {
+    const projectDir = this.main.firebaseProjectPath;
+
+    // Ask the running emulator process to roll emulator.log so this test run gets a
+    // clean slate. We touch a sentinel file the emulator polls for (every ~500ms) and
+    // wait briefly for it to be consumed. If the emulator isn't watching (older @omega.js/backend
+    // version, or not started via `npx omega emulator`), we time out silently — the log
+    // just won't be fresh, tests still run normally.
+    await this.requestEmulatorLogReset(projectDir);
+
+    this.log(chalk.gray(`  Hosting: http://127.0.0.1:${emulatorPorts.hosting}`));
+    this.log(chalk.gray(`  Firestore: 127.0.0.1:${emulatorPorts.firestore}`));
+    this.log(chalk.gray(`  Auth: 127.0.0.1:${emulatorPorts.auth}`));
+    this.log(chalk.gray(`  UI: http://127.0.0.1:${emulatorPorts.ui}`));
+
+    // Set up log file in the project's functions/ directory (alongside firebase-tools logs)
+    const logPath = this.getLogsPath('test.log');
+    const logStream = fs.createWriteStream(logPath, { flags: 'w' });
+    const stripAnsi = (str) => str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
+
+    this.log(chalk.gray(`  Logs saving to: ${logPath}\n`));
+
+    // The runner's OWN exit code, kept: a no-match answers with a code of its
+    // own inside a brand-root fan-out (#814), and collapsing every non-zero to
+    // 1 here would hide it. powertools registers its close listener before it
+    // hands the child over, so this one has run by the time the catch does.
+    let childExit = 0;
+
+    try {
+      await powertools.execute(testCommand, {
+        log: false,
+        cwd: functionsDir,
+        config: {
+          stdio: ['inherit', 'pipe', 'pipe'],
+          env: { ...process.env, FORCE_COLOR: '1' },
+        },
+      }, (child) => {
+        // Tee stdout to both console and log file (strip ANSI codes for clean log)
+        child.stdout.on('data', (data) => {
+          process.stdout.write(data);
+          logStream.write(stripAnsi(data.toString()));
+        });
+
+        // Tee stderr to both console and log file (strip ANSI codes for clean log)
+        child.stderr.on('data', (data) => {
+          process.stderr.write(data);
+          logStream.write(stripAnsi(data.toString()));
+        });
+
+        // Clean up log stream when child exits
+        child.on('close', (code) => {
+          childExit = code ?? 1;
+          logStream.end();
+        });
+      });
+    } catch (error) {
+      process.exit(childExit || 1);
+    }
+  }
+
+  /**
+   * Run tests with Firebase emulator (starts emulator, runs tests, shuts down).
+   *
+   * Two real child processes are used so emulator output and test-runner output
+   * land in separate log files:
+   *   - `emulator.log` — `firebase emulators:start` stdout/stderr (managed by EmulatorCommand)
+   *   - `test.log`     — the test-runner subprocess stdout/stderr (managed here)
+   */
+  async runEmulatorTests(testConfig, functionsDir) {
+    try {
+      await powertools.execute('java -version', { log: false });
+    } catch (e) {
+      this.logError(`Java is required to run tests (Firebase emulators depend on it).`);
+      this.logError(`Install with: ${javaInstallHint()}`);
+      process.exit(1);
+    }
+
+    this.log(chalk.gray('  Starting Firebase emulator...\n'));
+
+    const emulatorCmd = new EmulatorCommand(this.main);
+    let started;
+
+    try {
+      started = await emulatorCmd.startEmulators({ environment: 'testing' });
+    } catch (error) {
+      this.logError(`Emulator error: ${error.message || error}`);
+      process.exit(1);
+    }
+
+    const { shutdown, exitPromise, emulatorPorts } = started;
+
+    // The forwarder needs the RESOLVED port too, so it starts after the boot
+    const laneSession = await this.startLane(testConfig, emulatorPorts);
+
+    // Build the test command from the RESOLVED ports — allocation may have
+    // bumped them off the firebase.json values testConfig was seeded with.
+    const testCommand = this.buildTestCommand({
+      ...testConfig,
+      apiUrl: `http://127.0.0.1:${emulatorPorts.hosting}`,
+      emulatorPorts,
+      laneEnv: laneSession.env,
+    });
+
+    // ONE handler, three signals: this run OWNS the stack it just booted, so
+    // every way it is asked to stop takes the same teardown. Wired to SIGINT
+    // alone, a supervisor's SIGTERM or a closed terminal's SIGHUP took Node's
+    // default action and orphaned the whole firebase tree onto PID 1 — the
+    // [#629](https://github.com/Omega-JS-Stack/omega/issues/629) defect on this
+    // sibling path ([#722](https://github.com/Omega-JS-Stack/omega/issues/722)).
+    //
+    // The signal is DIRECTED at this pid, so it reaches the CLI and nothing
+    // else: the test runner spawned below is this run's child, not its
+    // co-signee, and a teardown that only stops the emulator leaves the suites
+    // running orphaned to PID 1. It is therefore signalled by hand, and the
+    // handler is reentrancy-guarded — a second signal arriving mid-teardown
+    // (SIGINT then SIGTERM is exactly how a supervisor escalates) would
+    // otherwise start the whole thing again underneath the first.
+    let testChild = null;
+    let stopping = false;
+
+    const onStopSignal = async () => {
+      if (stopping) {
+        return;
+      }
+
+      stopping = true;
+
+      this.log(chalk.gray('\n  Shutting down emulator...'));
+
+      if (testChild && testChild.exitCode === null && testChild.signalCode === null) {
+        try { testChild.kill('SIGTERM'); } catch (e) { /* already gone */ }
+      }
+
+      await shutdown();
+      process.exit(130);
+    };
+    STOP_SIGNALS.forEach((signal) => process.on(signal, onStopSignal));
+
+    // Print the same connection summary the existing-emulator path shows
+    this.log('');
+    this.log(chalk.gray(`  Hosting: http://127.0.0.1:${emulatorPorts.hosting}`));
+    this.log(chalk.gray(`  Firestore: 127.0.0.1:${emulatorPorts.firestore}`));
+    this.log(chalk.gray(`  Auth: 127.0.0.1:${emulatorPorts.auth}`));
+    this.log(chalk.gray(`  UI: http://127.0.0.1:${emulatorPorts.ui}`));
+
+    // Spawn the test runner as its own child so its stdout/stderr can be teed to test.log
+    const logPath = this.getLogsPath('test.log');
+    const logStream = fs.createWriteStream(logPath, { flags: 'w' });
+    const stripAnsi = (str) => str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
+
+    this.log(chalk.gray(`  Logs saving to: ${logPath}\n`));
+
+    let testExitCode = 0;
+
+    try {
+      testChild = spawnShell(testCommand, {
+        cwd: functionsDir,
+        env: { ...process.env, FORCE_COLOR: '1' },
+        stdio: ['inherit', 'pipe', 'pipe'],
+      });
+
+      testChild.stdout.on('data', (data) => {
+        process.stdout.write(data);
+        if (!logStream.destroyed) logStream.write(stripAnsi(data.toString()));
+      });
+
+      testChild.stderr.on('data', (data) => {
+        process.stderr.write(data);
+        if (!logStream.destroyed) logStream.write(stripAnsi(data.toString()));
+      });
+
+      testExitCode = await new Promise((resolve) => {
+        testChild.on('close', (code) => {
+          if (!logStream.destroyed) logStream.end();
+          resolve(code ?? 1);
+        });
+      });
+    } catch (error) {
+      this.logError(`Test runner error: ${error.message || error}`);
+      testExitCode = 1;
+    } finally {
+      laneSession.stop();
+
+      // A stop signal owns the teardown AND the exit from the moment it
+      // arrives: this path is only reached at all because the handler killed
+      // the child this run was waiting on. Tearing down again here would
+      // signal the stack out from under it — and dropping the handlers would
+      // hand the next signal back to Node's default action mid-teardown. So
+      // the process is left to the handler's own exit.
+      if (stopping) {
+        await new Promise(() => {});
+      }
+
+      STOP_SIGNALS.forEach((signal) => process.removeListener(signal, onStopSignal));
+      await shutdown();
+      await exitPromise;
+    }
+
+    process.exit(testExitCode);
+  }
+}
+
+// Static, alongside Middleware's precedent — the adopt-or-bump decision is
+// pure, so tests exercise it directly instead of through a booted emulator, and
+// the identity read takes a tmp dir so real locator files can stand in for a
+// running hub.
+TestCommand.decideEmulatorAdoption = decideEmulatorAdoption;
+TestCommand.readHubLocatorProjectId = readHubLocatorProjectId;
+
+module.exports = TestCommand;