backend-manager 5.2.18 → 5.3.0

package/test/helpers/merge-line-files.js

@@ -0,0 +1,271 @@
+/**
+ * Test: mergeLineBasedFiles()
+ * Unit tests for the line-based .env / .gitignore / CLAUDE.md merge.
+ *
+ * Tests the pure function directly — no emulator, no Firestore, no HTTP.
+ *
+ * Regression coverage for the bug that scrambled consumers' `.env` files: an
+ * older positional implementation zipped comment lines and value lines by index,
+ * so any drift in key order shifted every value under the wrong header. The
+ * canonical impl merges BY KEY, so headers always re-anchor to the template and
+ * values follow their key across sections.
+ */
+const {
+  mergeLineBasedFiles,
+  DEFAULT_MARKER,
+  CUSTOM_MARKER,
+} = require('../../src/utils/merge-line-files.js');
+
+// Setup-test helper shim — must re-export the SAME canonical impl (SSOT).
+const helperShim = require('../../src/cli/commands/setup-tests/helpers/merge-line-files.js');
+
+// A representative framework .env template (keys grouped under headers).
+const TEMPLATE = [
+  DEFAULT_MARKER,
+  '# GitHub',
+  'GH_TOKEN=""',
+  '',
+  '# AI',
+  'OPENAI_API_KEY=""',
+  'ANTHROPIC_API_KEY=""',
+  '',
+  '# Payment Processors',
+  'PAYPAL_CLIENT_SECRET=""',
+  'STRIPE_SECRET_KEY=""',
+  '',
+  CUSTOM_MARKER,
+  '# Add your custom environment variables below this line',
+].join('\n');
+
+// Pull the value assigned to a key in a given section of a merged result.
+function keyValueInSection(merged, key, section /* 'default' | 'custom' */) {
+  const lines = merged.split('\n');
+  let mode = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === DEFAULT_MARKER) { mode = 'default'; continue; }
+    if (trimmed === CUSTOM_MARKER) { mode = 'custom'; continue; }
+    if (mode !== section || !trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq < 0) continue;
+    if (trimmed.slice(0, eq).trim() === key) return trimmed.slice(eq + 1);
+  }
+  return undefined;
+}
+
+// Count how many times a key appears anywhere (catches duplication bugs).
+function keyOccurrences(merged, key) {
+  return merged.split('\n').filter((l) => l.trim().startsWith(`${key}=`)).length;
+}
+
+// Assert a key sits directly under the expected comment header in the merged output.
+function headerAboveKey(merged, key) {
+  const lines = merged.split('\n');
+  const idx = lines.findIndex((l) => l.trim().startsWith(`${key}=`));
+  if (idx < 0) return null;
+  for (let i = idx - 1; i >= 0; i--) {
+    const t = lines[i].trim();
+    if (t.startsWith('#') && t !== DEFAULT_MARKER && t !== CUSTOM_MARKER) return t;
+    if (t && !t.startsWith('#')) continue; // another key — keep scanning up
+  }
+  return null;
+}
+
+module.exports = {
+  description: 'mergeLineBasedFiles() line-based .env / .gitignore merge',
+  type: 'group',
+
+  tests: [
+    {
+      name: 'ssot-helper-shim-is-same-function',
+      async run({ assert }) {
+        assert.equal(
+          helperShim.mergeLineBasedFiles,
+          mergeLineBasedFiles,
+          'setup-tests helper must re-export the canonical mergeLineBasedFiles (SSOT)'
+        );
+        assert.equal(helperShim.DEFAULT_SECTION_MARKER, DEFAULT_MARKER, 'marker alias matches');
+        assert.equal(helperShim.CUSTOM_SECTION_MARKER, CUSTOM_MARKER, 'marker alias matches');
+        assert.ok(helperShim.hasSectionMarkers(TEMPLATE), 'hasSectionMarkers detects markers');
+      },
+    },
+
+    {
+      name: 'preserves-existing-values-by-key',
+      async run({ assert }) {
+        const existing = [
+          DEFAULT_MARKER,
+          '# GitHub',
+          'GH_TOKEN="ghp_real"',
+          '# AI',
+          'OPENAI_API_KEY="sk-real"',
+          'ANTHROPIC_API_KEY=""',
+          '# Payment Processors',
+          'PAYPAL_CLIENT_SECRET="pp_real"',
+          'STRIPE_SECRET_KEY=""',
+          CUSTOM_MARKER,
+        ].join('\n');
+
+        const merged = mergeLineBasedFiles(existing, TEMPLATE, '.env');
+        assert.equal(keyValueInSection(merged, 'GH_TOKEN', 'default'), '"ghp_real"', 'GH_TOKEN value kept');
+        assert.equal(keyValueInSection(merged, 'OPENAI_API_KEY', 'default'), '"sk-real"', 'OPENAI value kept');
+        assert.equal(keyValueInSection(merged, 'PAYPAL_CLIENT_SECRET', 'default'), '"pp_real"', 'PAYPAL value kept');
+      },
+    },
+
+    {
+      name: 'keys-stay-under-correct-header-when-order-drifts',
+      async run({ assert }) {
+        // Existing file has keys in a DIFFERENT order than the template. The old
+        // positional merge would shift values under the wrong header here.
+        const existing = [
+          DEFAULT_MARKER,
+          '# Misc (old grouping)',
+          'STRIPE_SECRET_KEY="stripe_real"',
+          'OPENAI_API_KEY="openai_real"',
+          'GH_TOKEN="gh_real"',
+          'PAYPAL_CLIENT_SECRET="pp_real"',
+          'ANTHROPIC_API_KEY="anthropic_real"',
+          CUSTOM_MARKER,
+        ].join('\n');
+
+        const merged = mergeLineBasedFiles(existing, TEMPLATE, '.env');
+
+        assert.equal(headerAboveKey(merged, 'OPENAI_API_KEY'), '# AI', 'OPENAI under # AI');
+        assert.equal(headerAboveKey(merged, 'ANTHROPIC_API_KEY'), '# AI', 'ANTHROPIC under # AI');
+        assert.equal(headerAboveKey(merged, 'PAYPAL_CLIENT_SECRET'), '# Payment Processors', 'PAYPAL under # Payment Processors');
+        assert.equal(headerAboveKey(merged, 'STRIPE_SECRET_KEY'), '# Payment Processors', 'STRIPE under # Payment Processors');
+        assert.equal(headerAboveKey(merged, 'GH_TOKEN'), '# GitHub', 'GH_TOKEN under # GitHub');
+
+        // Values still attached to the right keys.
+        assert.equal(keyValueInSection(merged, 'STRIPE_SECRET_KEY', 'default'), '"stripe_real"', 'STRIPE value intact');
+        assert.equal(keyValueInSection(merged, 'OPENAI_API_KEY', 'default'), '"openai_real"', 'OPENAI value intact');
+      },
+    },
+
+    {
+      name: 'promotes-custom-key-to-default-when-template-adopts-it',
+      async run({ assert }) {
+        // User had APOLLO_API_KEY in Custom; framework adds it to the template.
+        const tplWithApollo = TEMPLATE.replace('STRIPE_SECRET_KEY=""', 'STRIPE_SECRET_KEY=""\nAPOLLO_API_KEY=""');
+        const existing = [
+          DEFAULT_MARKER,
+          '# GitHub',
+          'GH_TOKEN="gh_real"',
+          '# AI',
+          'OPENAI_API_KEY=""',
+          'ANTHROPIC_API_KEY=""',
+          '# Payment Processors',
+          'PAYPAL_CLIENT_SECRET=""',
+          'STRIPE_SECRET_KEY=""',
+          CUSTOM_MARKER,
+          'APOLLO_API_KEY="apollo_real"',
+          'GITHUB_TOKEN="legacy"',
+        ].join('\n');
+
+        const merged = mergeLineBasedFiles(existing, tplWithApollo, '.env');
+
+        assert.equal(keyValueInSection(merged, 'APOLLO_API_KEY', 'default'), '"apollo_real"', 'APOLLO promoted to Default with value');
+        assert.equal(keyValueInSection(merged, 'APOLLO_API_KEY', 'custom'), undefined, 'APOLLO removed from Custom');
+        assert.equal(keyOccurrences(merged, 'APOLLO_API_KEY'), 1, 'APOLLO not duplicated');
+      },
+    },
+
+    {
+      name: 'migrates-unknown-default-key-to-custom',
+      async run({ assert }) {
+        // User has a legacy key in Default that the template no longer defines.
+        const existing = [
+          DEFAULT_MARKER,
+          '# GitHub',
+          'GITHUB_TOKEN="legacy_real"', // template now uses GH_TOKEN
+          'GH_TOKEN="gh_real"',
+          '# AI',
+          'OPENAI_API_KEY=""',
+          'ANTHROPIC_API_KEY=""',
+          '# Payment Processors',
+          'PAYPAL_CLIENT_SECRET=""',
+          'STRIPE_SECRET_KEY=""',
+          CUSTOM_MARKER,
+        ].join('\n');
+
+        const merged = mergeLineBasedFiles(existing, TEMPLATE, '.env');
+
+        assert.equal(keyValueInSection(merged, 'GITHUB_TOKEN', 'custom'), '"legacy_real"', 'legacy key migrated to Custom with value');
+        assert.equal(keyValueInSection(merged, 'GITHUB_TOKEN', 'default'), undefined, 'legacy key gone from Default');
+        assert.equal(keyValueInSection(merged, 'GH_TOKEN', 'default'), '"gh_real"', 'GH_TOKEN kept in Default');
+      },
+    },
+
+    {
+      name: 'preserves-custom-section-verbatim',
+      async run({ assert }) {
+        const existing = [
+          DEFAULT_MARKER,
+          '# GitHub',
+          'GH_TOKEN=""',
+          '# AI',
+          'OPENAI_API_KEY=""',
+          'ANTHROPIC_API_KEY=""',
+          '# Payment Processors',
+          'PAYPAL_CLIENT_SECRET=""',
+          'STRIPE_SECRET_KEY=""',
+          CUSTOM_MARKER,
+          'MY_CUSTOM_KEY="custom_real"',
+          '# OAuth2',
+          'OAUTH_ID="abc"',
+        ].join('\n');
+
+        const merged = mergeLineBasedFiles(existing, TEMPLATE, '.env');
+        assert.equal(keyValueInSection(merged, 'MY_CUSTOM_KEY', 'custom'), '"custom_real"', 'custom key preserved');
+        assert.equal(keyValueInSection(merged, 'OAUTH_ID', 'custom'), '"abc"', 'custom OAuth key preserved');
+        assert.ok(merged.includes('# OAuth2'), 'custom comment preserved');
+      },
+    },
+
+    {
+      name: 'normalizes-raw-values-to-double-quoted',
+      async run({ assert }) {
+        const existing = [
+          DEFAULT_MARKER,
+          '# GitHub',
+          'GH_TOKEN=raw-no-quotes',
+          '# AI',
+          "OPENAI_API_KEY='single'",
+          'ANTHROPIC_API_KEY=""',
+          '# Payment Processors',
+          'PAYPAL_CLIENT_SECRET=""',
+          'STRIPE_SECRET_KEY=""',
+          CUSTOM_MARKER,
+        ].join('\n');
+
+        const merged = mergeLineBasedFiles(existing, TEMPLATE, '.env');
+        assert.equal(keyValueInSection(merged, 'GH_TOKEN', 'default'), '"raw-no-quotes"', 'raw value double-quoted');
+        assert.equal(keyValueInSection(merged, 'OPENAI_API_KEY', 'default'), '"single"', 'single-quoted canonicalized to double');
+      },
+    },
+
+    {
+      name: 'is-idempotent',
+      async run({ assert }) {
+        const existing = [
+          DEFAULT_MARKER,
+          '# GitHub',
+          'GH_TOKEN="gh_real"',
+          '# AI',
+          'OPENAI_API_KEY="sk"',
+          'ANTHROPIC_API_KEY=""',
+          '# Payment Processors',
+          'PAYPAL_CLIENT_SECRET=""',
+          'STRIPE_SECRET_KEY=""',
+          CUSTOM_MARKER,
+          'CUSTOM="x"',
+        ].join('\n');
+
+        const once = mergeLineBasedFiles(existing, TEMPLATE, '.env');
+        const twice = mergeLineBasedFiles(once, TEMPLATE, '.env');
+        assert.equal(once, twice, 're-running the merge produces identical output');
+      },
+    },
+  ],
+};

package/test/routes/marketing/webhook-forward.js

@@ -21,12 +21,13 @@ module.exports = {
     {
       name: 'forwarder-returns-404-on-non-parent-brand',
       auth: 'none',
-      async run({ http, assert, config }) {
-        // Sanity check: this brand should NOT be configured as the parent
-        assert.ok(
-          config.parent && config.parent !== 'self',
-          `Test brand should have config.parent set to a URL (got: ${config.parent})`
-        );
+      async run({ http, assert, config, skip }) {
+        // This gate only applies to CHILD brands. If this brand IS the parent
+        // (config.parent === 'self'), the forwarder route is visible by design,
+        // so there's nothing to assert here — skip rather than fail.
+        if (!config.parent || config.parent === 'self') {
+          skip('Brand is its own parent (config.parent === "self") — forwarder gate does not apply');
+        }
 
         const response = await http.as('none').post(
           `marketing/webhook/forward?provider=sendgrid&key=${process.env.BACKEND_MANAGER_WEBHOOK_KEY}`,
@@ -40,7 +41,13 @@ module.exports = {
     {
       name: 'forwarder-returns-404-even-with-valid-key',
       auth: 'none',
-      async run({ http, assert }) {
+      async run({ http, assert, config, skip }) {
+        // Only meaningful on a CHILD brand. On the parent itself the forwarder is
+        // visible by design, so skip rather than fail.
+        if (!config.parent || config.parent === 'self') {
+          skip('Brand is its own parent (config.parent === "self") — forwarder gate does not apply');
+        }
+
         // A valid key shouldn't unlock the forwarder — gate is on config.parent, not key.
         const response = await http.as('none').post(
           `marketing/webhook/forward?provider=beehiiv&key=${process.env.BACKEND_MANAGER_WEBHOOK_KEY}`,

package/test/routes/payments/cancel.js

@@ -92,9 +92,12 @@ module.exports = {
 
     {
       name: 'succeeds-with-test-processor',
-      async run({ http, assert, config, accounts, firestore, waitFor }) {
+      async run({ http, assert, config, accounts, firestore, waitFor, skip }) {
         const uid = accounts['route-cancel-success'].uid;
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices?.monthly);
+        if (!paidProduct) {
+          skip('No paid product with monthly price configured in this brand');
+        }
 
         // Step 1: Create a test subscription intent to set up a proper paid subscription
         const intentResponse = await http.as('route-cancel-success').post('payments/intent', {

package/test/routes/payments/dispute-alert.js

@@ -239,15 +239,18 @@ module.exports = {
       async run({ http, assert, firestore }) {
         const alertId = '_test-dispute-duplicate';
 
-        // Send first alert
-        await http.as('none').post(`payments/dispute-alert?key=${process.env.BACKEND_MANAGER_WEBHOOK_KEY}`, {
+        // Pre-seed an in-flight dispute directly. We seed (rather than POST a first alert)
+        // because the route fires an async on-write trigger that, for synthetic test data
+        // with no matching charge, can transition the doc to 'failed' — at which point the
+        // dedup contract intentionally treats it as RETRYABLE, not a duplicate. Racing a
+        // live POST against that trigger made this test flaky. Seeding 'processing' (a
+        // non-failed, in-flight state) deterministically exercises the dedup path.
+        await firestore.set(`payments-disputes/${alertId}`, {
           id: alertId,
-          card: '4242',
-          amount: 29.99,
-          transactionDate: '2026-03-07',
+          status: 'processing',
         });
 
-        // Send duplicate
+        // A subsequent identical alert must be reported as a duplicate (not reprocessed).
         const response = await http.as('none').post(`payments/dispute-alert?key=${process.env.BACKEND_MANAGER_WEBHOOK_KEY}`, {
           id: alertId,
           card: '4242',

package/test/routes/payments/intent.js

@@ -5,7 +5,9 @@
  * Validation tests use processor=stripe (fail at SDK step, proving validation logic)
  * Success tests use processor=test (full intent→webhook→trigger pipeline)
  *
- * Product-agnostic: resolves the first paid product from config.payment.products
+ * Product-agnostic: resolves the first paid product from config.payment.products.
+ * If the brand has no paid product configured, each test skips — this is a
+ * config-gap, not a code failure.
  */
 module.exports = {
   description: 'Payment intent creation',
@@ -16,8 +18,11 @@ module.exports = {
     {
       name: 'rejects-unauthenticated',
       auth: 'none',
-      async run({ http, assert, config }) {
+      async run({ http, assert, config, skip }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
 
         const response = await http.as('none').post('payments/intent', {
           processor: 'stripe',
@@ -31,8 +36,11 @@ module.exports = {
 
     {
       name: 'rejects-missing-processor',
-      async run({ http, assert, config }) {
+      async run({ http, assert, config, skip }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
 
         const response = await http.as('basic').post('payments/intent', {
           productId: paidProduct.id,
@@ -57,8 +65,11 @@ module.exports = {
 
     {
       name: 'rejects-missing-frequency-for-subscription',
-      async run({ http, assert, config }) {
+      async run({ http, assert, config, skip }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.type === 'subscription' && p.prices);
+        if (!paidProduct) {
+          skip('No paid subscription product configured in this brand');
+        }
 
         const response = await http.as('basic').post('payments/intent', {
           processor: 'stripe',
@@ -72,8 +83,11 @@ module.exports = {
     {
       name: 'rejects-active-paid-user',
       auth: 'premium-active',
-      async run({ http, assert, config }) {
+      async run({ http, assert, config, skip }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
 
         const response = await http.as('premium-active').post('payments/intent', {
           processor: 'stripe',
@@ -88,8 +102,11 @@ module.exports = {
     {
       name: 'rejects-suspended-user',
       auth: 'premium-suspended',
-      async run({ http, assert, config }) {
+      async run({ http, assert, config, skip }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
 
         const response = await http.as('premium-suspended').post('payments/intent', {
           processor: 'stripe',
@@ -104,8 +121,11 @@ module.exports = {
     {
       name: 'rejects-cancelling-user',
       auth: 'premium-cancelling',
-      async run({ http, assert, config }) {
+      async run({ http, assert, config, skip }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
 
         const response = await http.as('premium-cancelling').post('payments/intent', {
           processor: 'stripe',
@@ -120,8 +140,11 @@ module.exports = {
     {
       name: 'allows-cancelled-user',
       auth: 'premium-expired',
-      async run({ http, assert, config }) {
+      async run({ http, assert, config, skip }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
 
         const response = await http.as('premium-expired').post('payments/intent', {
           processor: 'test',
@@ -148,8 +171,11 @@ module.exports = {
 
     {
       name: 'rejects-unknown-processor',
-      async run({ http, assert, config }) {
+      async run({ http, assert, config, skip }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
 
         const response = await http.as('basic').post('payments/intent', {
           processor: 'unknown-processor',
@@ -163,8 +189,11 @@ module.exports = {
 
     {
       name: 'rejects-invalid-discount-code',
-      async run({ http, assert, config }) {
+      async run({ http, assert, config, skip }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
 
         const response = await http.as('basic').post('payments/intent', {
           processor: 'stripe',
@@ -179,8 +208,11 @@ module.exports = {
 
     {
       name: 'saves-discount-to-intent-doc',
-      async run({ http, assert, config, firestore }) {
+      async run({ http, assert, config, firestore, skip }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
 
         const response = await http.as('journey-payments-intent-discount').post('payments/intent', {
           processor: 'test',
@@ -202,8 +234,11 @@ module.exports = {
 
     {
       name: 'saves-attribution-and-supplemental-to-intent-doc',
-      async run({ http, assert, config, firestore }) {
+      async run({ http, assert, config, firestore, skip }) {
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
 
         const response = await http.as('journey-payments-intent-attribution').post('payments/intent', {
           processor: 'test',
@@ -223,9 +258,12 @@ module.exports = {
 
     {
       name: 'succeeds-with-test-processor',
-      async run({ http, assert, config, firestore, accounts, waitFor }) {
+      async run({ http, assert, config, firestore, accounts, waitFor, skip }) {
         const uid = accounts['journey-payments-intent'].uid;
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
 
         const response = await http.as('journey-payments-intent').post('payments/intent', {
           processor: 'test',
@@ -256,9 +294,12 @@ module.exports = {
 
     {
       name: 'downgrades-trial-for-user-with-history',
-      async run({ http, assert, config, accounts, firestore, waitFor }) {
+      async run({ http, assert, config, accounts, firestore, waitFor, skip }) {
         const uid = accounts['journey-payments-intent-trial'].uid;
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices);
+        if (!paidProduct) {
+          skip('No paid product configured in this brand');
+        }
         const orderDocPath = `payments-orders/_test-order-history-${uid}`;
 
         // Create fake subscription history so user is ineligible for trial

package/test/routes/payments/portal.js

@@ -56,9 +56,12 @@ module.exports = {
 
     {
       name: 'succeeds-with-test-processor',
-      async run({ http, assert, config, accounts, firestore, waitFor }) {
+      async run({ http, assert, config, accounts, firestore, waitFor, skip }) {
         const uid = accounts['journey-payments-portal-route'].uid;
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices?.monthly);
+        if (!paidProduct) {
+          skip('No paid product with monthly price configured in this brand');
+        }
 
         // Set up a paid subscription with the test processor
         const intentResponse = await http.as('journey-payments-portal-route').post('payments/intent', {

package/test/routes/payments/refund.js

@@ -112,9 +112,12 @@ module.exports = {
 
     {
       name: 'succeeds-with-test-processor',
-      async run({ http, assert, config, accounts, firestore, waitFor }) {
+      async run({ http, assert, config, accounts, firestore, waitFor, skip }) {
         const uid = accounts['route-refund-success'].uid;
         const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices?.monthly);
+        if (!paidProduct) {
+          skip('No paid product with monthly price configured in this brand');
+        }
 
         // Step 1: Create a test subscription intent to set up a proper paid subscription
         const intentResponse = await http.as('route-refund-success').post('payments/intent', {