backend-manager 5.9.7 → 5.9.8

package/test/helpers/environment.js

@@ -0,0 +1,230 @@
+/**
+ * Test: environment detection + URL helpers
+ * Covers the Manager's getEnvironment() SSOT, the derived is*() checks, the URL
+ * builders (getApiUrl / getFunctionsUrl / getWebsiteUrl + parent variants), and the
+ * assistant→Manager forwarding.
+ *
+ * Run: npx mgr test bem:helpers/environment
+ *
+ * Contract (see docs/environment-detection.md):
+ *   - getEnvironment() is the SINGLE SOURCE OF TRUTH — the only reader of the raw env
+ *     vars (BEM_TESTING / ENVIRONMENT / FUNCTIONS_EMULATOR / TERM_PROGRAM). Returns
+ *     exactly ONE of 'development' | 'testing' | 'production' (testing wins).
+ *   - isDevelopment()/isProduction()/isTesting() DERIVE from getEnvironment() — they
+ *     never read raw signals, so they can NEVER disagree with it. Exactly one is true.
+ *   - getApiUrl/getFunctionsUrl/getWebsiteUrl resolve LOCAL in dev OR testing, prod
+ *     otherwise. The parent helpers ALWAYS return the live URL (no localhost).
+ *   - The assistant forwards each method to its Manager (identical results).
+ */
+
+// Run a thunk with the env-detection vars cleared, restoring them afterward. These are
+// the only inputs getEnvironment() reads, so clearing them gives a clean slate per case.
+function withEnv(overrides, fn) {
+  const KEYS = ['BEM_TESTING', 'ENVIRONMENT', 'FUNCTIONS_EMULATOR', 'TERM_PROGRAM'];
+  const saved = {};
+  for (const k of KEYS) saved[k] = process.env[k];
+  try {
+    for (const k of KEYS) delete process.env[k];
+    for (const k of Object.keys(overrides)) process.env[k] = overrides[k];
+    return fn();
+  } finally {
+    for (const k of KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  }
+}
+
+module.exports = {
+  description: 'Environment detection + URL helpers',
+  type: 'group',
+
+  tests: [
+    // ─── getEnvironment() resolution + precedence ───
+
+    {
+      name: 'getEnvironment: testing wins over everything (BEM_TESTING=true)',
+      async run({ Manager, assert }) {
+        withEnv({ BEM_TESTING: 'true', ENVIRONMENT: 'production' }, () => {
+          assert.equal(Manager.getEnvironment(), 'testing');
+        });
+      },
+    },
+    {
+      name: 'getEnvironment: production when ENVIRONMENT=production (not testing)',
+      async run({ Manager, assert }) {
+        withEnv({ ENVIRONMENT: 'production' }, () => {
+          assert.equal(Manager.getEnvironment(), 'production');
+        });
+      },
+    },
+    {
+      name: 'getEnvironment: development when ENVIRONMENT=development',
+      async run({ Manager, assert }) {
+        withEnv({ ENVIRONMENT: 'development' }, () => {
+          assert.equal(Manager.getEnvironment(), 'development');
+        });
+      },
+    },
+    {
+      name: 'getEnvironment: development when FUNCTIONS_EMULATOR is set',
+      async run({ Manager, assert }) {
+        withEnv({ FUNCTIONS_EMULATOR: 'true' }, () => {
+          assert.equal(Manager.getEnvironment(), 'development');
+        });
+      },
+    },
+    {
+      name: 'getEnvironment: defaults to production with no signal (deployed function)',
+      async run({ Manager, assert }) {
+        withEnv({}, () => {
+          assert.equal(Manager.getEnvironment(), 'production');
+        });
+      },
+    },
+
+    // ─── The KEY invariant: is*() derive from getEnvironment() and can NEVER disagree ───
+
+    {
+      name: 'invariant: is*() exactly matches getEnvironment() across every scenario',
+      async run({ Manager, assert }) {
+        const scenarios = [
+          { env: { BEM_TESTING: 'true', ENVIRONMENT: 'production' }, expect: 'testing' },
+          { env: { ENVIRONMENT: 'production' },                     expect: 'production' },
+          { env: { ENVIRONMENT: 'development' },                    expect: 'development' },
+          { env: { FUNCTIONS_EMULATOR: 'true' },                    expect: 'development' },
+          { env: {},                                                expect: 'production' },
+        ];
+        for (const s of scenarios) {
+          withEnv(s.env, () => {
+            const e = Manager.getEnvironment();
+            assert.equal(e, s.expect, `getEnvironment for ${JSON.stringify(s.env)}`);
+            // Each is*() must equal (getEnvironment() === its value) — no independent reads.
+            assert.equal(Manager.isDevelopment(), e === 'development', `isDevelopment for ${e}`);
+            assert.equal(Manager.isTesting(),     e === 'testing',     `isTesting for ${e}`);
+            assert.equal(Manager.isProduction(),  e === 'production',  `isProduction for ${e}`);
+          });
+        }
+      },
+    },
+    {
+      name: 'invariant: exactly one of is*() is true in every scenario (mutually exclusive)',
+      async run({ Manager, assert }) {
+        const envs = [
+          { BEM_TESTING: 'true' },
+          { ENVIRONMENT: 'production' },
+          { ENVIRONMENT: 'development' },
+          { FUNCTIONS_EMULATOR: 'true' },
+          {},
+        ];
+        for (const env of envs) {
+          withEnv(env, () => {
+            const trueCount = [Manager.isDevelopment(), Manager.isTesting(), Manager.isProduction()]
+              .filter(Boolean).length;
+            assert.equal(trueCount, 1, `exactly one true for ${JSON.stringify(env)}`);
+          });
+        }
+      },
+    },
+    {
+      name: 'isProduction is a real positive check (NOT just !isDevelopment) — false in testing',
+      async run({ Manager, assert }) {
+        withEnv({ BEM_TESTING: 'true' }, () => {
+          assert.equal(Manager.isDevelopment(), false, 'isDevelopment false in testing');
+          assert.equal(Manager.isProduction(),  false, 'isProduction false in testing');
+          assert.equal(Manager.isTesting(),     true,  'isTesting true in testing');
+        });
+      },
+    },
+
+    // ─── assistant forwards to the Manager (identical results) ───
+
+    {
+      name: 'assistant forwards getEnvironment()/is*() to the Manager (identical)',
+      async run({ Manager, assistant, assert }) {
+        const cases = [
+          { BEM_TESTING: 'true' },
+          { ENVIRONMENT: 'production' },
+          { ENVIRONMENT: 'development' },
+        ];
+        for (const env of cases) {
+          withEnv(env, () => {
+            assert.equal(assistant.getEnvironment(), Manager.getEnvironment(), 'getEnvironment forward');
+            assert.equal(assistant.isDevelopment(), Manager.isDevelopment(), 'isDevelopment forward');
+            assert.equal(assistant.isTesting(),     Manager.isTesting(),     'isTesting forward');
+            assert.equal(assistant.isProduction(),  Manager.isProduction(),  'isProduction forward');
+          });
+        }
+      },
+    },
+
+    // ─── URL helpers: local in dev/testing, production otherwise ───
+
+    {
+      name: 'getApiUrl: localhost in development AND testing, prod otherwise',
+      async run({ Manager, assert }) {
+        withEnv({ FUNCTIONS_EMULATOR: 'true' }, () => {
+          assert.equal(Manager.getApiUrl(), 'http://localhost:5002', 'dev → localhost');
+        });
+        withEnv({ BEM_TESTING: 'true' }, () => {
+          assert.equal(Manager.getApiUrl(), 'http://localhost:5002', 'testing → localhost');
+        });
+        withEnv({ ENVIRONMENT: 'production' }, () => {
+          assert.match(Manager.getApiUrl(), /^https:\/\/api\./, 'prod → api.<domain>');
+        });
+      },
+    },
+    {
+      name: 'getApiUrl: explicit env arg overrides current environment',
+      async run({ Manager, assert }) {
+        // Under the test harness we're in 'testing', but an explicit arg forces the mapping.
+        assert.equal(Manager.getApiUrl('development'), 'http://localhost:5002', "arg 'development' → localhost");
+        assert.match(Manager.getApiUrl('production'), /^https:\/\/api\./, "arg 'production' → prod");
+      },
+    },
+    {
+      name: 'getFunctionsUrl: localhost in development AND testing, cloudfunctions otherwise',
+      async run({ Manager, assert }) {
+        withEnv({ FUNCTIONS_EMULATOR: 'true' }, () => {
+          assert.match(Manager.getFunctionsUrl(), /^http:\/\/localhost:5001\//, 'dev → localhost:5001');
+        });
+        withEnv({ BEM_TESTING: 'true' }, () => {
+          assert.match(Manager.getFunctionsUrl(), /^http:\/\/localhost:5001\//, 'testing → localhost:5001');
+        });
+        withEnv({ ENVIRONMENT: 'production' }, () => {
+          assert.match(Manager.getFunctionsUrl(), /cloudfunctions\.net$/, 'prod → cloudfunctions.net');
+        });
+      },
+    },
+    {
+      name: 'getWebsiteUrl: localhost:4000 in development AND testing, brand.url otherwise',
+      async run({ Manager, assert }) {
+        withEnv({ FUNCTIONS_EMULATOR: 'true' }, () => {
+          assert.equal(Manager.getWebsiteUrl(), 'https://localhost:4000', 'dev → localhost:4000');
+        });
+        withEnv({ BEM_TESTING: 'true' }, () => {
+          assert.equal(Manager.getWebsiteUrl(), 'https://localhost:4000', 'testing → localhost:4000');
+        });
+        withEnv({ ENVIRONMENT: 'production' }, () => {
+          const url = Manager.getWebsiteUrl();
+          assert.equal(url.startsWith('https://localhost'), false, 'prod → NOT localhost');
+        });
+      },
+    },
+
+    // ─── Parent helpers ALWAYS resolve live (never localhost), even in dev/testing ───
+
+    {
+      name: 'getParentApiUrl / getParentUrl never redirect to localhost (always live)',
+      async run({ Manager, assert }) {
+        // Even under the test harness ('testing'), the parent is a real remote server.
+        const parentUrl = Manager.getParentUrl();
+        const parentApi = Manager.getParentApiUrl();
+        assert.equal((parentUrl || '').includes('localhost'), false, 'getParentUrl not localhost');
+        assert.equal((parentApi || '').includes('localhost'), false, 'getParentApiUrl not localhost');
+        // When set, the parent API URL carries the api. subdomain.
+        if (parentApi) assert.match(parentApi, /^https:\/\/api\./, 'parent api uses api. subdomain');
+      },
+    },
+  ],
+};

package/test/helpers/infer-contact.js

@@ -0,0 +1,113 @@
+/**
+ * Test: libraries/infer-contact.js
+ * Unit tests for contact inference from email addresses
+ *
+ * AI tests only run when TEST_EXTENDED_MODE is set.
+ */
+const { inferContact, capitalize } = require('../../src/manager/libraries/infer-contact.js');
+
+module.exports = {
+  description: 'Infer contact from email',
+  type: 'group',
+
+  tests: [
+    // ─── capitalize ───
+
+    {
+      name: 'capitalize-single-word',
+      async run({ assert }) {
+        assert.equal(capitalize('john'), 'John', 'Should capitalize first letter');
+      },
+    },
+
+    {
+      name: 'capitalize-multiple-words',
+      async run({ assert }) {
+        assert.equal(capitalize('john doe'), 'John Doe', 'Should capitalize each word');
+      },
+    },
+
+    {
+      name: 'capitalize-all-uppercase',
+      async run({ assert }) {
+        assert.equal(capitalize('JOHN'), 'John', 'Should lowercase after first letter');
+      },
+    },
+
+    {
+      name: 'capitalize-mixed-case',
+      async run({ assert }) {
+        assert.equal(capitalize('jOHN dOE'), 'John Doe', 'Should normalize mixed case');
+      },
+    },
+
+    {
+      name: 'capitalize-empty-string',
+      async run({ assert }) {
+        assert.equal(capitalize(''), '', 'Empty string should return empty');
+      },
+    },
+
+    {
+      name: 'capitalize-null',
+      async run({ assert }) {
+        assert.equal(capitalize(null), '', 'Null should return empty');
+      },
+    },
+
+    {
+      name: 'capitalize-undefined',
+      async run({ assert }) {
+        assert.equal(capitalize(undefined), '', 'Undefined should return empty');
+      },
+    },
+
+    // ─── inferContact: returns empty without AI key ───
+
+    {
+      name: 'infer-contact-no-ai-returns-none',
+      async run({ assert }) {
+        // Without BACKEND_MANAGER_OPENAI_API_KEY, should return empty result
+        const originalKey = process.env.BACKEND_MANAGER_OPENAI_API_KEY;
+        delete process.env.BACKEND_MANAGER_OPENAI_API_KEY;
+
+        try {
+          const result = await inferContact('alice.wonderland@example.com');
+
+          assert.equal(result.firstName, '', 'No first name without AI');
+          assert.equal(result.lastName, '', 'No last name without AI');
+          assert.equal(result.company, '', 'No company without AI');
+          assert.equal(result.method, 'none', 'Method should be none');
+          assert.equal(result.confidence, 0, 'Confidence should be 0');
+        } finally {
+          if (originalKey) {
+            process.env.BACKEND_MANAGER_OPENAI_API_KEY = originalKey;
+          }
+        }
+      },
+    },
+
+    // ─── inferContact: AI path (requires TEST_EXTENDED_MODE) ───
+
+    {
+      name: 'infer-contact-ai',
+      skip: !process.env.TEST_EXTENDED_MODE ? 'TEST_EXTENDED_MODE not set (skipping AI inference test)' : false,
+      timeout: 30000,
+
+      async run({ assert, Manager, skip }) {
+        if (!process.env.BACKEND_MANAGER_OPENAI_API_KEY && !process.env.OPENAI_API_KEY) {
+          return skip('BACKEND_MANAGER_OPENAI_API_KEY not set');
+        }
+
+        const assistant = Manager.Assistant();
+        const result = await inferContact('john.smith@microsoft.com', assistant);
+
+        assert.ok(result, 'Should return a result');
+        assert.equal(result.method, 'ai', 'Should use AI method');
+        assert.hasProperty(result, 'firstName', 'Should have firstName');
+        assert.hasProperty(result, 'lastName', 'Should have lastName');
+        assert.ok(typeof result.confidence === 'number', 'Confidence should be a number');
+      },
+    },
+  ],
+};

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');
+      },
+    },
+  ],
+};