@omega.js/backend 0.1.0

package/test/cli/stage-env-compose.test.js

@@ -0,0 +1,316 @@
+/**
+ * Test: `dist/.env` is COMPOSED from the env cascade on every stage
+ * ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)).
+ *
+ * The brand root's .env is the one file humans and the manager edit; the
+ * target's own .env is an optional per-key override. Before this, the stage
+ * copied the target .env verbatim and only a `manage` run pushed brand keys
+ * into it — so two Google keys added to the playground root .env never
+ * reached the deployed artifact.
+ *
+ * Also pinned here: the watcher's env inputs (the brand-root and company .env
+ * paths). The watch itself is fs.watch on real directories — this asserts the
+ * PATH RESOLUTION it wires up, which is the part that can silently be wrong.
+ *
+ * Run: npx omega test backend:cli/stage-env-compose
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+
+const { stageFunctions, envWatchInputs, watchAndStage } = require('../../dist/cli/utils/stage-functions.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+/**
+ * A backend target inside a brand monorepo, with a company root above it:
+ * <root>/company/.env, <root>/brand/.env, <root>/brand/targets/backend/.
+ */
+function seedBrand({ companyEnv, brandEnv, brandEnvOverlays, targetEnv }) {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'omega-stage-env-')));
+  const companyRoot = path.join(root, 'company');
+  const brandRoot = path.join(root, 'brand');
+  const targetDir = path.join(brandRoot, 'targets', 'backend');
+
+  jetpack.write(path.join(companyRoot, '.env'), companyEnv || '');
+  jetpack.write(path.join(brandRoot, '.omega', 'company.json'), JSON.stringify({ root: companyRoot }));
+  jetpack.write(path.join(brandRoot, 'config', 'omega.json5'), JSON.stringify({
+    brand: { id: 'fixture', name: 'Fixture Brand', url: 'https://fixture.test' },
+    targets: { backend: {} },
+  }));
+
+  jetpack.write(path.join(targetDir, 'package.json'), JSON.stringify({ name: 'fixture-backend', version: '0.0.0' }));
+  jetpack.write(path.join(targetDir, 'src', 'index.js'), '// fixture backend entry\n');
+  if (brandEnv !== undefined) jetpack.write(path.join(brandRoot, '.env'), brandEnv);
+  for (const [environment, contents] of Object.entries(brandEnvOverlays || {})) {
+    jetpack.write(path.join(brandRoot, `.env.${environment}`), contents);
+  }
+  if (targetEnv !== undefined) jetpack.write(path.join(targetDir, '.env'), targetEnv);
+
+  return { root, brandRoot, companyRoot, targetDir };
+}
+
+/** The staged dist/.env, parsed. */
+function stagedEnv(targetDir, options) {
+  stageFunctions({ projectDir: targetDir, ...options });
+  return require('dotenv').parse(jetpack.read(path.join(targetDir, 'dist', '.env')) || '');
+}
+
+/** One key out of the dist/.env sitting on disk right now (no re-stage). */
+function stagedValue(targetDir, key) {
+  return require('dotenv').parse(jetpack.read(path.join(targetDir, 'dist', '.env')) || '')[key];
+}
+
+/** Poll the staged dist/.env until `key` reads `value` (the watcher's re-stage), or give up. */
+async function waitForStaged(targetDir, key, value, timeoutMs = 5000) {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    if (stagedValue(targetDir, key) === value) return true;
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+
+  return false;
+}
+
+module.exports = defineCases({
+  description: 'Stage composes dist/.env from the cascade (brand root ← target override)',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'a-brand-root-key-the-schema-names-reaches-dist-env',
+      auth: 'none',
+
+      async run({ assert }) {
+        const { root, targetDir } = seedBrand({
+          companyEnv: 'ANTHROPIC_API_KEY="company-anthropic"\n',
+          brandEnv: 'GH_TOKEN="brand-gh"\nCONNECTIONS_GOOGLE_CLIENT_ID="brand-oauth-id"\nRECAPTCHA_SITE_KEY="brand-site-key"\nGOOGLE_ANALYTICS_SECRET_BACKEND="brand-stream"\n',
+        });
+
+        try {
+          const env = stagedEnv(targetDir);
+
+          assert.equal(env.GH_TOKEN, 'brand-gh', 'a brand-root key the backend schema names must reach the artifact');
+          assert.equal(env.CONNECTIONS_GOOGLE_CLIENT_ID, 'brand-oauth-id', 'the connections pattern family composes too (#678)');
+          assert.equal(env.ANTHROPIC_API_KEY, 'company-anthropic', 'the company layer fills the gaps');
+          assert.equal(env.GOOGLE_ANALYTICS_SECRET, 'brand-stream', "the backend's own GA4 stream secret arrives renamed");
+          assert.equal(env.RECAPTCHA_SITE_KEY, undefined, 'a key the schema names for web only never joins the functions upload');
+        } finally {
+          jetpack.remove(root);
+        }
+      },
+    },
+
+    {
+      name: 'the-target-env-wins-per-key',
+      auth: 'none',
+
+      async run({ assert }) {
+        const { root, targetDir } = seedBrand({
+          brandEnv: 'GH_TOKEN="brand-gh"\nOPENAI_API_KEY="brand-openai"\n',
+          targetEnv: 'GH_TOKEN="target-gh"\nSOME_BESPOKE_KEY="target-only"\n',
+        });
+
+        try {
+          const env = stagedEnv(targetDir);
+
+          assert.equal(env.GH_TOKEN, 'target-gh', "the target's own .env is the per-key override");
+          assert.equal(env.OPENAI_API_KEY, 'brand-openai', 'keys it does not override still come from the brand root');
+          assert.equal(env.SOME_BESPOKE_KEY, 'target-only', 'a key the schema does not know passes through from the target layer');
+        } finally {
+          jetpack.remove(root);
+        }
+      },
+    },
+
+    {
+      name: 'each-lane-stages-its-own-environment-overlay',
+      auth: 'none',
+
+      // #586: one key, one flat artifact — a deploy composes base + production,
+      // the emulator base + development, a test lane base + testing. No other
+      // environment's file ever rides along.
+      async run({ assert }) {
+        const { root, targetDir } = seedBrand({
+          brandEnv: 'STRIPE_SECRET_KEY="sk_live_base"\nGH_TOKEN="brand-gh"\n',
+          brandEnvOverlays: {
+            development: 'STRIPE_SECRET_KEY="sk_test_dev"\n',
+            testing: 'STRIPE_SECRET_KEY="sk_test_lane"\n',
+          },
+        });
+
+        try {
+          const local = stagedEnv(targetDir, { environment: 'development' });
+          assert.equal(local.STRIPE_SECRET_KEY, 'sk_test_dev', 'the emulator reads the development overlay');
+          assert.equal(local.GH_TOKEN, 'brand-gh', 'a key no overlay touches still comes from the base');
+
+          const lane = stagedEnv(targetDir, { environment: 'testing' });
+          assert.equal(lane.STRIPE_SECRET_KEY, 'sk_test_lane', 'a test lane reads the testing overlay');
+
+          const upload = stagedEnv(targetDir, { environment: 'production' });
+          assert.equal(upload.STRIPE_SECRET_KEY, 'sk_live_base', 'the deploy composes base + production — no overlay exists, so the base ships');
+          assert.equal(Object.keys(upload).filter((key) => key.endsWith('_DEV')).length, 0, 'nothing named _DEV survives anywhere (#586)');
+        } finally {
+          jetpack.remove(root);
+        }
+      },
+    },
+
+    {
+      name: 'no-overlay-file-leaves-the-staged-env-exactly-as-it-was',
+      auth: 'none',
+
+      async run({ assert }) {
+        const { root, targetDir } = seedBrand({
+          brandEnv: 'STRIPE_SECRET_KEY="sk_test_base"\nGH_TOKEN="brand-gh"\n',
+        });
+
+        try {
+          const development = stagedEnv(targetDir, { environment: 'development' });
+          const production = stagedEnv(targetDir, { environment: 'production' });
+
+          assert.deepEqual(development, production, 'with no overlay authored, every environment stages the same artifact');
+          assert.equal(production.STRIPE_SECRET_KEY, 'sk_test_base');
+        } finally {
+          jetpack.remove(root);
+        }
+      },
+    },
+
+    {
+      name: 'only-a-deploy-stamps-the-license-verdict-into-the-artifact',
+      auth: 'none',
+
+      // #320: OMEGA_LICENSE_STATUS is the one COMPUTED key in dist/.env — the
+      // deploy's license verdict, which no cascade layer supplies. Every local
+      // lane stages without it, and an artifact with no status behaves exactly
+      // as it did before the gate existed.
+      async run({ assert }) {
+        const { root, targetDir } = seedBrand({
+          brandEnv: 'GH_TOKEN="brand-gh"\nOMEGA_LICENSE_KEY="brand-license-key"\n',
+        });
+
+        try {
+          const local = stagedEnv(targetDir, { environment: 'development' });
+          assert.equal(local.OMEGA_LICENSE_STATUS, undefined, 'a local stage resolves no verdict, so it stamps none');
+          assert.equal(local.OMEGA_LICENSE_KEY, undefined, 'and the KEY itself never rides the functions upload');
+
+          const deploy = stagedEnv(targetDir, { environment: 'production', licenseStatus: 'keyless' });
+          assert.equal(deploy.OMEGA_LICENSE_STATUS, 'keyless', "the deploy's verdict is what the runtime payment gate reads");
+          assert.equal(deploy.OMEGA_LICENSE_KEY, undefined, 'still only the verdict — never the key');
+          assert.equal(deploy.GH_TOKEN, 'brand-gh', 'the composed cascade is otherwise untouched');
+
+          const licensed = stagedEnv(targetDir, { environment: 'production', licenseStatus: 'licensed' });
+          assert.equal(licensed.OMEGA_LICENSE_STATUS, 'licensed');
+        } finally {
+          jetpack.remove(root);
+        }
+      },
+    },
+
+    {
+      name: 'the-stage-reports-delivered-key-names-and-their-layer',
+      auth: 'none',
+
+      async run({ assert }) {
+        const { root, targetDir } = seedBrand({
+          brandEnv: 'GH_TOKEN="brand-gh"\n',
+          targetEnv: 'OPENAI_API_KEY="target-openai"\n',
+        });
+
+        const lines = [];
+
+        try {
+          stageFunctions({ projectDir: targetDir, log: (message) => lines.push(message) });
+          const output = lines.join('\n');
+
+          assert.match(output, /GH_TOKEN \(brand\)/, 'the log names the key and the layer it came from');
+          assert.match(output, /OPENAI_API_KEY \(target\)/, 'a target-layer key is reported as such');
+          assert.equal(output.includes('brand-gh'), false, 'a .env VALUE is never printed');
+          assert.equal(output.includes('target-openai'), false, 'a .env VALUE is never printed');
+        } finally {
+          jetpack.remove(root);
+        }
+      },
+    },
+
+    {
+      name: 'the-watcher-watches-the-brand-root-and-company-env',
+      auth: 'none',
+
+      async run({ assert }) {
+        const { root, brandRoot, companyRoot, targetDir } = seedBrand({
+          companyEnv: '',
+          brandEnv: '',
+        });
+
+        try {
+          const inputs = envWatchInputs(targetDir);
+          const watched = inputs.map((input) => input.path);
+
+          assert.deepEqual(watched, [
+            path.join(brandRoot, '.env'),
+            path.join(companyRoot, '.env'),
+          ], 'the brand-root and company .env are stage inputs, resolved through the chain — never hard-coded');
+          assert.deepEqual(inputs.map((input) => input.layer), ['brand', 'company']);
+        } finally {
+          jetpack.remove(root);
+        }
+      },
+    },
+
+    {
+      name: 'an-overlay-edit-re-stages-like-a-plain-env-edit',
+      auth: 'none',
+
+      // #586: the overlay is a first-class layer, so it is a first-class WATCH
+      // input — a `.env.development` edit at the brand root (or in the target's
+      // own root) has to reach a running dev server exactly like a `.env` edit.
+      async run({ assert }) {
+        const { root, brandRoot, targetDir } = seedBrand({
+          brandEnv: 'GH_TOKEN="brand-gh"\n',
+          brandEnvOverlays: { development: 'GH_TOKEN="dev-first"\n' },
+        });
+
+        stageFunctions({ projectDir: targetDir, environment: 'development' });
+        assert.equal(stagedValue(targetDir, 'GH_TOKEN'), 'dev-first', 'the first stage reads the overlay');
+
+        // The fixture's own writes settle BEFORE the watch opens — macOS
+        // replays recent FSEvents to a fresh recursive watcher, and a re-stage
+        // from those would read the edit below without ever watching for it.
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        const watcher = watchAndStage({ projectDir: targetDir, environment: 'development', debounceMs: 20 });
+
+        try {
+          jetpack.write(path.join(brandRoot, '.env.development'), 'GH_TOKEN="dev-second"\n');
+          assert.equal(await waitForStaged(targetDir, 'GH_TOKEN', 'dev-second'), true,
+            'a brand-root .env.development edit re-stages');
+
+          jetpack.write(path.join(targetDir, '.env.development'), 'GH_TOKEN="target-dev"\n');
+          assert.equal(await waitForStaged(targetDir, 'GH_TOKEN', 'target-dev'), true,
+            "the target root's own .env.development is a stage input too");
+        } finally {
+          watcher.close();
+          jetpack.remove(root);
+        }
+      },
+    },
+
+    {
+      name: 'a-standalone-target-has-no-brand-or-company-env-to-watch',
+      auth: 'none',
+
+      async run({ assert }) {
+        const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'omega-stage-env-solo-')));
+
+        try {
+          assert.deepEqual(envWatchInputs(dir), [], 'nothing above a standalone target — nothing extra to watch');
+        } finally {
+          jetpack.remove(dir);
+        }
+      },
+    },
+  ],
+});

package/test/cli/stripe-live-lane.test.js

@@ -0,0 +1,303 @@
+/**
+ * Test: the opt-in real-Stripe lane's gate and its fixture plan
+ *
+ * The lane runs real Stripe API calls and forwards real webhooks, so the two
+ * things that decide whether it runs at all — and what it creates when it does —
+ * are pure functions, testable with no account, no CLI and no network
+ * ([#212](https://github.com/Omega-JS-Stack/omega/issues/212)).
+ *
+ * The GATE is the safety property. A lane that ran with the wrong credential
+ * would charge a real card, so every refusal is pinned here: no key, a key that
+ * is not test-shaped, the ONE reader's own live-credential refusal (#586), and a
+ * missing CLI. And the refusals are pinned to say the KEY and the fix and never
+ * the value — a lane that printed a secret to explain itself would be a worse
+ * bug than the one it prevents.
+ *
+ * The FIXTURE PLAN is the correctness property. `resolvePriceId()` matches a
+ * config price to a Stripe price by interval and amount and NOTHING else, so a
+ * plan that is a cent off or names the wrong interval produces fixtures that can
+ * never resolve — a failure that would otherwise surface as a broken checkout.
+ *
+ * Run: npx omega test backend:cli/stripe-live-lane
+ */
+const assert = require('node:assert');
+
+const lane = require('../../dist/cli/commands/test-lanes/stripe-live.js');
+const defineCases = require('../../dist/vendor/devkit/test/define-cases.js');
+
+/** An env reader stand-in: the ONE reader's surface, answering what a suite says */
+function reader(answer) {
+  return {
+    get: () => {
+      if (answer instanceof Error) {
+        throw answer;
+      }
+
+      return answer;
+    },
+  };
+}
+
+/** A reader fault the lane must surface as a skip rather than a crash */
+function readerFault() {
+  const error = new Error('STRIPE_SECRET_KEY is not declared in the env schema');
+  error.name = 'UnknownEnvKeyError';
+  return error;
+}
+
+const CATALOGUE = [
+  { id: 'basic', name: 'Basic', type: 'subscription' },
+  { id: 'premium', name: 'Premium', type: 'subscription', prices: { monthly: 4.99, annually: 49.99 } },
+  { id: 'credits', name: 'Credits', type: 'one-time', prices: { once: 9.5 } },
+  { id: 'legacy', name: 'Legacy', type: 'subscription', prices: { monthly: 1 }, archived: true },
+];
+
+module.exports = defineCases({
+  description: 'The stripe-live lane: the gate that keeps it shut, and the fixtures it plans',
+  type: 'group',
+  timeout: 30000,
+
+  tests: [
+    // ─── The gate ───
+
+    {
+      name: 'a-test-key-and-a-cli-open-the-lane',
+
+      async run() {
+        const decision = lane.resolveGate({ env: reader('sk_test_abc123'), hasStripeCli: true });
+
+        assert.equal(decision.ok, true, 'a test secret key with the CLI installed is the whole requirement');
+        assert.equal(decision.key, 'sk_test_abc123', 'and the resolved key rides along, so nothing reads it twice');
+      },
+    },
+
+    {
+      name: 'no-key-keeps-the-lane-shut',
+
+      async run() {
+        for (const answer of [undefined, null, '']) {
+          const decision = lane.resolveGate({ env: reader(answer), hasStripeCli: true });
+
+          assert.equal(decision.ok, false, `a ${JSON.stringify(answer)} secret must not open the lane`);
+          assert.ok(decision.reason.includes('.env.testing'), `the skip line names the overlay to put the key in, got: ${decision.reason}`);
+        }
+      },
+    },
+
+    {
+      name: 'a-live-key-keeps-the-lane-shut',
+
+      async run() {
+        // #586 retired the reader's live-shape refusal: the `.env.testing`
+        // overlay is where a test credential goes, and every value is trusted.
+        // The `sk_test_` gate below is what keeps a live key out of a lane that
+        // creates subscriptions — it is the ONLY latch now, so it is pinned
+        // against every live shape a Stripe key can carry.
+        for (const live of ['sk_live_abc123', 'rk_live_abc123']) {
+          const decision = lane.resolveGate({ env: reader(live), hasStripeCli: true });
+
+          assert.equal(decision.ok, false, `${live} must never open a lane that creates subscriptions`);
+          assert.ok(decision.reason.includes('sk_test_'), `the skip line names what it wanted, got: ${decision.reason}`);
+        }
+
+        // A reader FAULT is surfaced as a skip too, not a crash
+        const faulted = lane.resolveGate({ env: reader(readerFault()), hasStripeCli: true });
+
+        assert.equal(faulted.ok, false, 'a lane that cannot resolve its key must not run');
+        assert.ok(faulted.reason.includes('STRIPE_SECRET_KEY'), `the skip line carries the reader's own words, got: ${faulted.reason}`);
+      },
+    },
+
+    {
+      name: 'anything-that-is-not-a-test-secret-key-keeps-the-lane-shut',
+
+      async run() {
+        // The shapes a key slot picks up in practice: a restricted key (cannot
+        // create products), a publishable key (pasted from the wrong line), a
+        // live key the reader was never asked about.
+        for (const key of ['rk_test_abc', 'pk_test_abc', 'sk_live_abc', 'whsec_abc', 'nonsense']) {
+          const decision = lane.resolveGate({ env: reader(key), hasStripeCli: true });
+
+          assert.equal(decision.ok, false, `${key.split('_')[0]}_… must not open the lane`);
+          assert.ok(decision.reason.includes(lane.TEST_KEY_PREFIX), `the skip line says what shape is required, got: ${decision.reason}`);
+        }
+      },
+    },
+
+    {
+      name: 'no-stripe-cli-keeps-the-lane-shut',
+
+      async run() {
+        const decision = lane.resolveGate({ env: reader('sk_test_abc123'), hasStripeCli: false });
+
+        assert.equal(decision.ok, false, 'the lane forwards with the CLI — without it there is nothing to forward');
+        assert.ok(decision.reason.includes('stripe.com/docs/stripe-cli'), `the skip line says how to install it, got: ${decision.reason}`);
+      },
+    },
+
+    {
+      name: 'no-refusal-ever-prints-the-secret',
+
+      async run() {
+        // The one rule that outranks helpfulness here. Every reason is a line a
+        // human reads out of a terminal, and terminals get pasted into issues.
+        const secret = 'sk_live_SUPERSECRETVALUE';
+
+        for (const key of [secret, 'rk_test_ANOTHERSECRET', 'pk_test_THIRDSECRET']) {
+          const decision = lane.resolveGate({ env: reader(key), hasStripeCli: true });
+
+          assert.equal(decision.ok, false, `${key} should be refused`);
+          assert.ok(!decision.reason.includes(key), `the skip line must never quote the credential, got: ${decision.reason}`);
+        }
+
+        assert.ok(!lane.skipLine('a reason').includes('sk_'), 'and the printed line carries only the reason');
+      },
+    },
+
+    // ─── The fixture plan ───
+
+    {
+      name: 'the-plan-covers-every-price-a-brand-configures',
+
+      async run() {
+        const { fixtures } = lane.planFixtures(CATALOGUE, 'USD');
+        const ids = fixtures.map((f) => `${f.productId}/${f.frequency}`).sort();
+
+        assert.deepEqual(
+          ids,
+          ['credits/once', 'premium/annually', 'premium/monthly'],
+          'every priced, unarchived, non-basic product needs a fixture — and basic and archived need none',
+        );
+      },
+    },
+
+    {
+      name: 'the-plan-matches-what-resolvePriceId-looks-for',
+
+      async run() {
+        // The whole point: resolvePriceId() compares `unit_amount` against
+        // Math.round(price * 100) and `recurring.interval` against the mapped
+        // frequency. A fixture that does not carry exactly those two can never
+        // be found, however correct it looks in the dashboard.
+        const { fixtures } = lane.planFixtures(CATALOGUE, 'USD');
+
+        const monthly = fixtures.find((f) => f.productId === 'premium' && f.frequency === 'monthly');
+        assert.equal(monthly.unitAmount, 499, '$4.99 is 499 minor units');
+        assert.equal(monthly.interval, 'month', 'monthly maps to Stripe\'s `month`');
+
+        const annually = fixtures.find((f) => f.frequency === 'annually');
+        assert.equal(annually.unitAmount, 4999, '$49.99 is 4999 minor units');
+        assert.equal(annually.interval, 'year', 'annually maps to Stripe\'s `year` — not `annual`');
+
+        const once = fixtures.find((f) => f.frequency === 'once');
+        assert.equal(once.unitAmount, 950, '$9.50 is 950 minor units, not 95');
+        assert.equal(once.interval, null, 'a one-time price has no recurring interval at all');
+
+        assert.ok(fixtures.every((f) => f.currency === 'usd'), 'Stripe wants the currency lower-cased');
+      },
+    },
+
+    {
+      name: 'a-product-the-plan-cannot-represent-is-named-not-dropped',
+
+      async run() {
+        const { fixtures, unsupported } = lane.planFixtures([
+          { id: 'odd', name: 'Odd', type: 'subscription', prices: { fortnightly: 3 } },
+          { id: 'empty', name: 'Empty', type: 'one-time', prices: {} },
+        ], 'USD');
+
+        assert.equal(fixtures.length, 0, 'neither can be represented');
+        assert.equal(unsupported.length, 2, 'and both are reported rather than silently skipped');
+        assert.ok(unsupported[0].reason.includes('fortnightly'), `the reason names the frequency, got: ${unsupported[0].reason}`);
+        assert.ok(unsupported[1].reason.includes('once'), `the reason names the missing price, got: ${unsupported[1].reason}`);
+      },
+    },
+
+    // ─── Idempotency ───
+
+    {
+      name: 'an-existing-price-satisfies-a-fixture-so-a-rerun-creates-nothing',
+
+      async run() {
+        const [monthly] = lane.planFixtures([CATALOGUE[1]], 'USD').fixtures;
+
+        const existing = [
+          { id: 'price_wrong_amount', unit_amount: 500, recurring: { interval: 'month' } },
+          { id: 'price_wrong_interval', unit_amount: 499, recurring: { interval: 'year' } },
+          { id: 'price_right', unit_amount: 499, recurring: { interval: 'month' } },
+        ];
+
+        assert.equal(lane.findSatisfyingPrice(monthly, existing).id, 'price_right', 'a rerun reuses the price the first run made');
+        assert.equal(lane.findSatisfyingPrice(monthly, []), null, 'and a first run finds nothing to reuse');
+        assert.equal(
+          lane.findSatisfyingPrice(monthly, [{ id: 'price_once', unit_amount: 499 }]),
+          null,
+          'a one-time price never satisfies a recurring fixture, however right the amount',
+        );
+      },
+    },
+
+    {
+      name: 'a-one-time-fixture-is-satisfied-only-by-a-non-recurring-price',
+
+      async run() {
+        const [once] = lane.planFixtures([CATALOGUE[2]], 'USD').fixtures;
+
+        assert.equal(lane.findSatisfyingPrice(once, [{ id: 'price_sub', unit_amount: 950, recurring: { interval: 'month' } }]), null, 'a subscription price is not a one-time price');
+        assert.equal(lane.findSatisfyingPrice(once, [{ id: 'price_once', unit_amount: 950 }]).id, 'price_once', 'a bare price at the right amount is');
+      },
+    },
+
+    // ─── The forwarder's readiness ───
+
+    {
+      name: 'the-forwarder-is-ready-only-on-the-cli-line-that-says-so',
+
+      async run() {
+        // The tunnel exists only once `stripe listen` says it does — resolving
+        // earlier would let a trigger fire into nothing. That same line also
+        // carries the CLI's signing secret, which is why it is never logged.
+        assert.equal(
+          lane.isReadyLine('> Ready! You are using Stripe API Version [2024-06-20]. Your webhook signing secret is whsec_abc123XYZ (^C to quit)'),
+          true,
+          'the ready line opens the gate',
+        );
+        assert.equal(lane.isReadyLine('2026-08-25 22:00:00  --> customer.subscription.created [evt_1]'), false, 'a delivery line does not');
+        assert.equal(lane.isReadyLine(''), false, 'and neither does an empty one');
+      },
+    },
+
+    // ─── The lane stays shut to the default run ───
+
+    {
+      name: 'the-lanes-suites-are-unreachable-without-the-gate',
+
+      async run() {
+        // The exclusion is a STRING MATCH between the directory the suites live
+        // in and the lane's own name, in two files. Drift either one and the
+        // lane's suites either vanish from every run or, worse, join the default
+        // one — which is a suite hitting a real payment API because a folder was
+        // renamed.
+        const TestRunner = require('../../dist/test/runner.js');
+
+        assert.ok(
+          TestRunner.LANE_DIRECTORIES.has(lane.LANE),
+          `the runner must skip test/${lane.LANE}/ by default — its lane list holds ${[...TestRunner.LANE_DIRECTORIES].join(', ')}`,
+        );
+        assert.equal(lane.LANE_ENV, 'OMEGA_TEST_LANE', 'and the runner reads the open lane off exactly this env var');
+      },
+    },
+
+    {
+      name: 'the-forward-url-is-the-real-webhook-door',
+
+      async run() {
+        const url = lane.forwardUrl({ hostingPort: 5099, webhookKey: '_test-key' });
+
+        assert.ok(url.startsWith('http://localhost:5099/omega/payments/webhook'), `the lane forwards to the route itself, got ${url}`);
+        assert.ok(url.includes('provider=stripe'), 'as the STRIPE provider — the whole point is that nothing is simulated');
+        assert.ok(url.includes('key=_test-key'), 'carrying the shared key the route also checks');
+      },
+    },
+  ],
+});