backend-manager 5.1.2 → 5.1.4

package/src/manager/libraries/email/generators/lib/templates/field-report.js

@@ -16,7 +16,7 @@
  *
  * Content schema (template-owned — different from the classic schema):
  *   { tldr, dateline, dispatches: [{ kicker, headline, byline, location,
- *     lede, dispatch, dataPoints?, cta?, image_prompt }] }
+ *     lede, dispatch, dataPoints?, image_prompt }] }
  */
 const {
   shell,
@@ -337,7 +337,7 @@ const FIELD_REPORT_SCHEMA = {
       items: {
         type: 'object',
         additionalProperties: false,
-        required: ['kicker', 'headline', 'byline', 'location', 'lede', 'dispatch', 'image_prompt', 'cta', 'dataPoints'],
+        required: ['kicker', 'headline', 'byline', 'location', 'lede', 'dispatch', 'image_prompt', 'dataPoints'],
         properties: {
           kicker:   { type: 'string', maxLength: 30 },  // "DISPATCH" / "FIELD NOTES" / "WATCH" / "BRIEF"
           headline: { type: 'string', maxLength: 90 },  // Tight, declarative
@@ -358,15 +358,10 @@ const FIELD_REPORT_SCHEMA = {
               },
             },
           },
-          cta: {
-            type: ['object', 'null'],
-            additionalProperties: false,
-            required: ['label', 'url'],
-            properties: {
-              label: { type: 'string' },
-              url:   { type: 'string' },
-            },
-          },
+          // CTAs intentionally not part of the contract — the AI cannot author URLs
+          // reliably (no source URLs available, no brand-site knowledge). Newsletters
+          // are self-contained; outbound links come from sponsorship blocks rendered
+          // by the template shell, not from generated dispatch bodies.
           image_prompt: { type: 'string' },
         },
       },
@@ -390,7 +385,6 @@ function normalizeFieldReport(structure, { brand } = {}) {
     lede:         d.lede        || '',
     dispatch:     d.dispatch    || '',
     dataPoints:   Array.isArray(d.dataPoints) ? d.dataPoints.slice(0, 4) : [],
-    cta:          d.cta         || null,
     image_prompt: d.image_prompt || '',
   }));
 
@@ -439,6 +433,8 @@ function buildPrompt({ brand, newsletterConfig, sources }) {
     'CONTENT REQUIREMENTS:',
     '- subject: ≤60 chars, declarative, no clickbait. Reads like a wire-service headline.',
     '- preheader: ≤100 chars, complements subject.',
+    '- summary: 2-3 sentences, plain text, no markdown. An editorial recap of the whole issue (distinct from the in-template `tldr` strip — the summary is consumed by external surfaces like the share preview / summary.md file).',
+    '- tags: 3-5 topical tags. Lowercase, kebab-case, no spaces. Examples: "linkedin", "creator-economy", "platform-policy". Empty array OK if nothing fits cleanly.',
     '- tldr: 2 short sentences max, ~200 chars total. Present tense. Reads like a terminal briefing — what changed, why it matters.',
     '- dateline: one city or "REMOTE" — sets where the issue is filed from. UPPERCASE. Example: "LOS ANGELES" / "REMOTE" / "NEW YORK".',
     '- dispatches: 3-5 items, each is a discrete filed story.',
@@ -449,8 +445,8 @@ function buildPrompt({ brand, newsletterConfig, sources }) {
     '  - lede: one paragraph (1-2 sentences), italic-serif quality, sets the scene in present tense. Reads like the opening of a New Yorker article.',
     '  - dispatch: the body. 90-160 words. Markdown allowed. Present tense. Specific. End with the practical implication for the reader.',
     '  - dataPoints: 2-4 short label/value pairs IF there are meaningful numbers in the topic. Example: [{label:"USERS REACHED",value:"12.4K"},{label:"WoW GROWTH",value:"+38%"}]. SKIP this (empty array) if the topic has no quantifiable data.',
-    '  - cta: { label, url } OR null. Label is mono, uppercase, short (≤24 chars). Examples: "READ THE BRIEF", "SEE THE NUMBERS".',
     '  - image_prompt: one-sentence visual brief for an illustrator. Specific. Think editorial illustration, not stock photo.',
+    '  - DO NOT invent CTAs, "read more" links, or any URLs anywhere in the dispatch. The dispatch must stand on its own without sending the reader off-property.',
     `- signoff: render as TWO LINES with a literal \\n between them. Format: a short closing phrase + the desk name. Examples:\n    "— Stay sharp,\\nThe ${brandName} Desk"\n    "— Until next dispatch,\\nThe ${brandName} Editorial Desk"\n  Do NOT write a summary, motto, or thematic sentence. This is a literal sign-off.`,
     '',
     'OUTPUT:',
@@ -488,7 +484,7 @@ module.exports = {
     name: 'field-report',
     description: 'Wire-service correspondent × Bloomberg terminal. Dispatch kickers, datelines, mono data callouts, end-of-dispatch terminators.',
     requires: ['subject', 'preheader', 'tldr', 'dateline', 'dispatches', 'signoff'],
-    optional: ['citations', 'dataPoints', 'cta', 'image_prompt'],
+    optional: ['citations', 'dataPoints', 'image_prompt'],
     supports: { sponsorships: ['top', 'middle', 'end'], citations: true, images: true },
   },
   schema: FIELD_REPORT_SCHEMA,

package/src/manager/libraries/email/generators/newsletter.js

@@ -24,6 +24,7 @@ const { filterSources } = require('./lib/filter.js');
 const { generateStructure } = require('./lib/structure.js');
 const { generateSectionImage } = require('./lib/svg-illustrator.js');
 const { renderNewsletter } = require('./lib/mjml-template.js');
+const { renderMarkdown } = require('./lib/markdown-renderer.js');
 const { uploadAssets, RAW_BASE } = require('./lib/image-host.js');
 
 /**
@@ -208,16 +209,34 @@ async function generate(Manager, assistant, settings, opts = {}) {
     sponsorships,
   });
 
-  // 3b. Upload the rendered HTML to GitHub alongside the images. Lives in the
-  //     same {brandId}/{campaignId}/ folder as newsletter.html. The folder URL
-  //     becomes the canonical archive of the issue, browseable + downloadable.
+  // 3a. Programmatic markdown view — same `structure`, walked by code (no AI).
+  //     The markdown is split into ## blocks per section so it can be pasted
+  //     into Beehiiv's block editor with ad blocks inserted between dispatches.
+  //     `summary` is a separate short editorial recap, written by the AI
+  //     during the structure step.
+  const markdown = renderMarkdown({
+    structure,
+    brand,
+    imagePaths,
+    sponsorships,
+  });
+
+  const summaryText = (structure.summary || '').trim();
+
+  // 3b. Upload the rendered HTML + markdown + summary to GitHub alongside the
+  //     images. All four kinds live in the same {brandId}/{campaignId}/ folder.
+  //     The folder URL becomes the canonical archive of the issue.
   let assetsFolderUrl = null;
   let htmlUrl = null;
+  let markdownUrl = null;
+  let summaryUrl = null;
 
   if (host === 'github') {
     try {
       const upload = await uploadAssets({
         html,
+        markdown,
+        summary: summaryText || undefined,
         brandId: brand?.id,
         campaignId,
         subject: structure.subject,
@@ -225,6 +244,8 @@ async function generate(Manager, assistant, settings, opts = {}) {
       });
       assetsFolderUrl = upload.folderUrl;
       htmlUrl = upload.htmlUrl;
+      markdownUrl = upload.markdownUrl || null;
+      summaryUrl = upload.summaryUrl || null;
     } catch (e) {
       assistant.error(`Newsletter generator: HTML upload failed — ${e.message}`);
     }
@@ -238,6 +259,7 @@ async function generate(Manager, assistant, settings, opts = {}) {
   //     succeeds regardless. beehiivConfig was already resolved at the top
   //     of the function for the initial enabled-check.
   let beehiivPostId = null;
+  let beehiivFailureReason = null;
 
   if (host === 'github' && beehiivConfig?.enabled) {
     try {
@@ -248,6 +270,7 @@ async function generate(Manager, assistant, settings, opts = {}) {
         subject:       structure.subject,
         preheader:     structure.preheader,
         content:       html,
+        contentTags:   Array.isArray(structure.tags) ? structure.tags : [],
         status:        'draft',
       });
 
@@ -256,13 +279,36 @@ async function generate(Manager, assistant, settings, opts = {}) {
         assistant.log(`Newsletter generator: Beehiiv draft created — ${beehiivPostId}`);
       } else {
         // Expected today until Enterprise plan — log, do not throw.
-        assistant.log(`Newsletter generator: Beehiiv draft upload skipped/failed — ${result?.error || 'unknown'}`);
+        beehiivFailureReason = result?.error || 'unknown error';
+        assistant.log(`Newsletter generator: Beehiiv draft upload skipped/failed — ${beehiivFailureReason}`);
       }
     } catch (e) {
+      beehiivFailureReason = e.message;
       assistant.error(`Newsletter generator: Beehiiv draft upload threw — ${e.message}`);
     }
   }
 
+  // 3d. Fallback alert email — sent to the brand's internal alerts inbox when
+  //     Beehiiv draft creation fails. The newsletter is fully generated and
+  //     archived to GitHub at this point, so the email contains everything
+  //     needed for a human to manually upload to Beehiiv: HTML URL (one-shot
+  //     paste), markdown URL (per-section blocks for ad insertion), summary
+  //     URL, and the tags to set. Failure of THIS email is logged but never
+  //     blocks the cron — the campaign doc is still written either way.
+  if (beehiivFailureReason && htmlUrl) {
+    await sendBeehiivFallbackEmail(Manager, assistant, {
+      brand,
+      subject: structure.subject,
+      preheader: structure.preheader,
+      tags: Array.isArray(structure.tags) ? structure.tags : [],
+      htmlUrl,
+      markdownUrl,
+      summaryUrl,
+      folderUrl: assetsFolderUrl,
+      reason: beehiivFailureReason,
+    });
+  }
+
   // 4. Mark sources as used on parent server (unless caller opted out)
   if (!opts.skipClaim) {
     const parentUrl = Manager.config?.parent;
@@ -308,8 +354,11 @@ async function generate(Manager, assistant, settings, opts = {}) {
     campaignId,
     folderUrl: assetsFolderUrl,
     htmlUrl,
+    markdownUrl,
+    summaryUrl,
     imageUrls: imagePaths,
     beehiivPostId,
+    tags: Array.isArray(structure.tags) ? structure.tags : [],
   } : null;
 
   return {
@@ -318,14 +367,112 @@ async function generate(Manager, assistant, settings, opts = {}) {
     preheader: structure.preheader,
     content: '',          // legacy markdown field, unused when contentHtml is set
     contentHtml: html,    // pre-rendered email-safe HTML
+    contentMarkdown: markdown,  // programmatic markdown view (per-section blocks for Beehiiv paste)
+    summary: summaryText, // editorial recap (separate from preheader)
+    tags: Array.isArray(structure.tags) ? structure.tags : [],
     structure,            // structured copy for debugging / migration
     mjml,                 // raw MJML for debugging
     images: opts._lastImages || [],  // image buffers for the iteration test to persist locally
-    assets,               // GitHub asset URLs (folder, html, images) — null in local mode
+    assets,               // GitHub asset URLs (folder, html, md, summary, images) — null in local mode
     meta,                 // per-step provider/model/cost/timing telemetry
   };
 }
 
+/**
+ * Send an internal alert email when Beehiiv draft creation fails so the
+ * brand team knows there's a ready newsletter waiting for manual upload.
+ *
+ * Uses `sender: 'internal'` which auto-resolves to `alerts@{brandDomain}` via
+ * the SENDERS table in email/constants.js. Recipient is the same alerts@
+ * address — a self-addressed operational alert, no human inbox involved.
+ *
+ * Errors here are logged but never thrown — the alert is best-effort. If
+ * brand.url is unset, the email is skipped entirely.
+ *
+ * @param {object} Manager
+ * @param {object} assistant
+ * @param {object} args
+ * @param {object} args.brand
+ * @param {string} args.subject - The newsletter's subject (used in the alert subject)
+ * @param {string} args.preheader
+ * @param {string[]} args.tags
+ * @param {string} args.htmlUrl - GitHub raw URL to the fully-rendered HTML
+ * @param {string} [args.markdownUrl] - GitHub raw URL to the per-section markdown
+ * @param {string} [args.summaryUrl] - GitHub raw URL to the 2-3 sentence summary
+ * @param {string} [args.folderUrl] - GitHub folder URL (browseable archive)
+ * @param {string} args.reason - Why Beehiiv upload failed (API error message)
+ */
+async function sendBeehiivFallbackEmail(Manager, assistant, args) {
+  // Send TO and FROM the same internal alerts inbox — alerts@{brandDomain}.
+  // The `sender: 'internal'` SENDERS entry already resolves the FROM address
+  // to this; we mirror the same domain for the TO so it's a self-addressed
+  // operational alert (no human inbox involved).
+  const brandDomain = (Manager.config?.brand?.url || '').replace(/^https?:\/\//, '').replace(/\/$/, '');
+
+  if (!brandDomain) {
+    assistant.log('Newsletter generator: Beehiiv fallback email skipped — no brand.url');
+    return;
+  }
+
+  const alertsEmail = `alerts@${brandDomain}`;
+
+  try {
+    const email = Manager.Email(assistant);
+    const messageLines = [];
+
+    messageLines.push(`<strong>Beehiiv draft creation failed</strong> — the newsletter is generated and archived, but needs to be manually uploaded to Beehiiv.`);
+    messageLines.push('');
+    messageLines.push(`<strong>Failure reason:</strong> ${args.reason}`);
+    messageLines.push('');
+    messageLines.push('<strong>Newsletter details:</strong>');
+    messageLines.push('<ul>');
+    messageLines.push(`<li><strong>Subject:</strong> ${args.subject}</li>`);
+    messageLines.push(`<li><strong>Preheader:</strong> ${args.preheader || '(none)'}</li>`);
+    if (args.tags?.length) {
+      messageLines.push(`<li><strong>Tags:</strong> ${args.tags.join(', ')}</li>`);
+    }
+    messageLines.push('</ul>');
+    messageLines.push('');
+    messageLines.push('<strong>Assets (manual upload links):</strong>');
+    messageLines.push('<ul>');
+    messageLines.push(`<li><strong>Full HTML</strong> (one-shot paste): <a href="${args.htmlUrl}">${args.htmlUrl}</a></li>`);
+    if (args.markdownUrl) {
+      messageLines.push(`<li><strong>Per-section markdown</strong> (paste as separate blocks, ads between): <a href="${args.markdownUrl}">${args.markdownUrl}</a></li>`);
+    }
+    if (args.summaryUrl) {
+      messageLines.push(`<li><strong>Summary</strong> (2-3 sentence recap): <a href="${args.summaryUrl}">${args.summaryUrl}</a></li>`);
+    }
+    if (args.folderUrl) {
+      messageLines.push(`<li><strong>All assets</strong>: <a href="${args.folderUrl}">${args.folderUrl}</a></li>`);
+    }
+    messageLines.push('</ul>');
+
+    await email.send({
+      sender: 'internal',  // resolves to alerts@{brandDomain}
+      to: alertsEmail,
+      copy: false,  // self-addressed operational alert — no CC/BCC clutter
+      subject: `Newsletter ready for manual Beehiiv upload: "${args.subject}"`,
+      template: 'core/card',
+      categories: ['marketing/newsletter-manual-upload'],
+      data: {
+        email: {
+          preview: `Beehiiv upload failed — newsletter awaiting manual upload from ${args.folderUrl || 'GitHub archive'}`,
+        },
+        body: {
+          title: 'Newsletter Ready for Manual Upload',
+          message: messageLines.join('\n'),
+        },
+      },
+    });
+
+    assistant.log(`Newsletter generator: Beehiiv fallback alert sent to ${alertsEmail}`);
+  } catch (e) {
+    // Best-effort — log and move on. We don't want a misconfigured email
+    // setup to break the cron's Firestore write.
+    assistant.error(`Newsletter generator: Beehiiv fallback email failed — ${e.message}`);
+  }
+}
+
 /**
  * Sum tokens + cost across all steps (filter, structure, all SVGs).
  */

package/src/manager/libraries/email/providers/beehiiv.js

@@ -329,6 +329,7 @@ async function resolveSegmentIds() {
  * @param {string} [options.subject] - Email subject line (defaults to title)
  * @param {string} [options.preheader] - Email preview text
  * @param {string} [options.content] - HTML content body
+ * @param {Array<string>} [options.contentTags] - Topical tags attached to the post (Beehiiv `content_tags`)
  * @param {string} [options.status] - 'draft' or 'confirmed' (default: confirmed = send)
  * @param {string} [options.sendAt] - ISO datetime to schedule, or null for immediate
  * @param {Array<string>} [options.segments] - Segment IDs to include
@@ -342,7 +343,7 @@ async function createPost(options) {
     return { success: false, error: 'Publication not found' };
   }
 
-  const { title, subject, preheader, content, status, sendAt, segments, excludeSegments } = options;
+  const { title, subject, preheader, content, contentTags, status, sendAt, segments, excludeSegments } = options;
 
   try {
     const body = {
@@ -355,6 +356,11 @@ async function createPost(options) {
       body.body_content = content;
     }
 
+    // Tags (Beehiiv field is `content_tags`, array of strings)
+    if (Array.isArray(contentTags) && contentTags.length) {
+      body.content_tags = contentTags;
+    }
+
     // Scheduling
     if (sendAt && sendAt !== 'now') {
       body.scheduled_at = new Date(sendAt).toISOString();

package/src/manager/routes/admin/post/post.js

@@ -82,7 +82,7 @@ module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
   settings.layout = settings.layout;
   settings.date = moment(settings.date || now).subtract(1, 'days').format('YYYY-MM-DD');
   settings.id = settings.id || Math.round(new Date(now).getTime() / 1000);
-  settings.path = `src/_posts/${moment(now).format('YYYY')}/${settings.postPath}`;
+  settings.directory = `src/_posts/${moment(now).format('YYYY')}/${settings.postPath}`;
   settings.githubUser = settings.githubUser || bemRepo.user;
   settings.githubRepo = settings.githubRepo || bemRepo.name;
 
@@ -108,7 +108,7 @@ module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
   );
 
   // Build post file entry
-  const postFilename = `${settings.path}/${settings.date}-${settings.url}.md`;
+  settings.path = `${settings.directory}/${settings.date}-${settings.url}.md`;
   const allFiles = [
     ...imageFiles.map(img => ({
       path: img.githubPath,
@@ -116,7 +116,7 @@ module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
       encoding: 'base64',
     })),
     {
-      path: postFilename,
+      path: settings.path,
       content: Buffer.from(formattedContent).toString('base64'),
       encoding: 'base64',
     },

package/src/manager/routes/test/health/get.js

@@ -1,5 +1,22 @@
+const path = require('path');
+const { readTestMode, applyEnvFromFile } = require('../../../../test/utils/test-mode-file.js');
+
 module.exports = async ({ assistant, Manager }) => {
 
+  // Belt-and-suspenders freshness check: re-read the test-mode file before
+  // reporting `testExtendedMode`. fs.watch installed in Manager.init usually
+  // catches changes within ~50ms, but this handler hits the disk directly to
+  // guarantee the runner sees the actual current value even if the watcher
+  // missed an event. ~1ms cost on a debug endpoint.
+  try {
+    const projectDir = path.dirname(Manager.cwd);
+    const data = readTestMode(projectDir);
+    applyEnvFromFile(data);
+  } catch (e) {
+    // Non-fatal — if the file can't be read, fall through to whatever
+    // process.env already has.
+  }
+
   const response = {
     status: 'healthy',
     timestamp: new Date().toISOString(),

package/src/test/run-tests.js

@@ -6,6 +6,13 @@
  * It reads configuration from BEM_TEST_CONFIG environment variable and runs the test suite
  */
 
+// Mark this process as the test runner BEFORE loading any BEM code. Manager.init()
+// auto-detects this and skips Firebase Functions / server / Sentry wiring (which
+// can't run outside a real Functions runtime). This is what lets tests receive a
+// fully-wired Manager + assistant in their context — no per-test stub.
+process.env.BEM_TEST_RUNNER = '1';
+
+const path = require('path');
 const TestRunner = require('./runner.js');
 
 async function main() {
@@ -33,10 +40,33 @@ async function main() {
     console.error('Warning: Could not initialize Firebase Admin:', error.message);
   }
 
+  // Boot a real Manager. With BEM_TEST_RUNNER set, init() loads libraries +
+  // resolves project config but skips the parts that need a Functions runtime
+  // (handler wiring, server boot, Sentry, admin.initializeApp re-init).
+  // The resulting Manager + assistant are passed into every test context, so
+  // tests can call Manager.AI(), Manager.Email(), Manager.User(), etc. exactly
+  // like production code does — no hand-rolled stubs.
+  let Manager = null;
+  let assistant = null;
+  try {
+    const projectDir = testConfig.projectDir || process.cwd();
+    const BackendManager = require('../manager/index.js');
+    Manager = new BackendManager();
+    Manager.init(null, {
+      cwd: path.join(projectDir, 'functions'),
+      log: false,
+    });
+    assistant = Manager.Assistant({}, { functionName: 'bem-test-runner', accept: 'json' });
+  } catch (error) {
+    console.error('Warning: Could not initialize BEM Manager for tests:', error.message);
+  }
+
   // Create and run the test runner
   const runner = new TestRunner({
     ...testConfig,
     admin,
+    Manager,
+    assistant,
   });
 
   const results = await runner.run();

package/src/test/runner.js

@@ -186,15 +186,13 @@ class TestRunner {
       if (response.success) {
         console.log(chalk.green('✓'));
 
-        // Warn if TEST_EXTENDED_MODE mismatch between test runner and emulator
-        const runnerExtended = !!process.env.TEST_EXTENDED_MODE;
+        // Report the live mode the emulator just confirmed. The test command
+        // writes `.temp/test-mode.json` before invoking us; the emulator's
+        // file-watcher mutates its `process.env.TEST_EXTENDED_MODE` to match;
+        // the health endpoint re-reads the file as a freshness guard. By
+        // construction these are equal — no mismatch warning needed.
         const emulatorExtended = !!response.data?.testExtendedMode;
-
-        if (runnerExtended !== emulatorExtended) {
-          console.log(chalk.red.bold(`\n  ⚠️⚠️⚠️  TEST_EXTENDED_MODE mismatch (runner=${runnerExtended}, emulator=${emulatorExtended})  ⚠️⚠️⚠️`));
-          console.log(chalk.red('  Both must match or tests will behave unexpectedly.'));
-          console.log(chalk.red(`  Restart with: ${runnerExtended ? '' : 'TEST_EXTENDED_MODE=true '}npx bm emulator\n`));
-        }
+        console.log(chalk.gray(`  Mode: ${emulatorExtended ? 'EXTENDED (real APIs)' : 'normal (mocked)'}`));
 
         return true;
       }
@@ -706,6 +704,11 @@ class TestRunner {
       pubsub,
       skip,
       admin: this.config.admin,
+      // Real BEM Manager + assistant, booted by run-tests.js with BEM_TEST_RUNNER=1.
+      // Tests can call Manager.AI(), Manager.Email(), Manager.User(), etc. exactly
+      // like production code — no stubs.
+      Manager: this.config.Manager,
+      assistant: this.config.assistant,
       rules: this.rulesContext,
       config: this.config,
     };

package/src/test/utils/test-mode-file.js

@@ -0,0 +1,192 @@
+/**
+ * Shared state file that lets the test command and the running emulator
+ * agree on a small set of env vars without coordinated shell flags.
+ *
+ * The test command writes this file pre-flight (before invoking the runner).
+ * The emulator process watches it and mutates the corresponding entries in
+ * `process.env` in place when it changes. All existing branch sites read
+ * `process.env.X` per call so the mutation is invisible to them — no
+ * code-branch refactor needed.
+ *
+ * File lives at `<consumerProject>/.temp/test-mode.json` — `.temp/` is the
+ * standard transient cache directory across UJM/BXM/EM/BEM consumer projects
+ * (sits at the repo root, gitignored by default).
+ *
+ * ## Allowlist
+ *
+ * `SYNCED_ENV_KEYS` is the explicit list of env vars allowed to flow from the
+ * test command into the emulator. Adding a new live-sync var = one-line addition.
+ *
+ * Why an allowlist (not "sync everything"):
+ *   - Some env vars are process-specific (e.g. FIRESTORE_EMULATOR_HOST is only
+ *     correct on the test runner, never on the emulator) and would break things
+ *     if synced. The allowlist prevents that.
+ *   - Sensitive values (API keys) shouldn't be silently overwritten on the
+ *     emulator just because the test runner happens to have them set.
+ *   - Keeps mutation explicit and reviewable.
+ *
+ * File format:
+ *   {
+ *     "env": {
+ *       "TEST_EXTENDED_MODE": "true"
+ *     },
+ *     "updatedAt": "2026-05-14T..."
+ *   }
+ *
+ * Values are strings to match `process.env` semantics. Empty string means
+ * "unset" — applyEnvFromFile() will `delete process.env[key]` when the value
+ * is empty, matching the way Node treats unset vs falsy env vars.
+ */
+const path = require('path');
+const jetpack = require('fs-jetpack');
+
+const TEST_MODE_FILENAME = 'test-mode.json';
+const TEMP_DIR_NAME = '.temp';
+
+// Explicit allowlist of env vars that flow from the test command into the
+// running emulator. Add a key here to make it live-syncable; nothing else
+// flows through.
+const SYNCED_ENV_KEYS = [
+  'TEST_EXTENDED_MODE',
+];
+
+/**
+ * Resolve the absolute path to the test-mode file for a given consumer project.
+ *
+ * @param {string} projectDir - Consumer project root (the directory that
+ *                               contains `firebase.json` / `functions/`).
+ * @returns {string} Absolute path to `<projectDir>/.temp/test-mode.json`.
+ */
+function getTestModeFilePath(projectDir) {
+  return path.join(projectDir, TEMP_DIR_NAME, TEST_MODE_FILENAME);
+}
+
+/**
+ * Read the current test-mode payload from disk. Tolerant — returns `null`
+ * if the file is missing or unreadable, never throws.
+ *
+ * @param {string} projectDir
+ * @returns {{ env: Object<string, string>, updatedAt: string } | null}
+ */
+function readTestMode(projectDir) {
+  const filePath = getTestModeFilePath(projectDir);
+
+  if (!jetpack.exists(filePath)) {
+    return null;
+  }
+
+  try {
+    const data = jetpack.read(filePath, 'json');
+    if (!data || typeof data !== 'object') {
+      return null;
+    }
+    return {
+      env: (data.env && typeof data.env === 'object') ? data.env : {},
+      updatedAt: data.updatedAt || null,
+    };
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Write the desired env subset to disk. Atomic via fs-jetpack. Creates the
+ * `.temp/` directory if missing. Filters input through SYNCED_ENV_KEYS so
+ * only allowlisted keys are persisted, even if the caller passes extras.
+ *
+ * @param {string} projectDir
+ * @param {Object<string, string|undefined>} envInput - Map of env vars to sync.
+ *                                                       Keys outside SYNCED_ENV_KEYS are dropped.
+ *                                                       Empty/undefined values are persisted as ''
+ *                                                       (meaning "unset on receiving side").
+ * @returns {string} Absolute path of the written file (for logging).
+ */
+function writeTestMode(projectDir, envInput) {
+  const filePath = getTestModeFilePath(projectDir);
+  const env = {};
+
+  for (const key of SYNCED_ENV_KEYS) {
+    const v = envInput?.[key];
+    env[key] = v == null ? '' : String(v);
+  }
+
+  const payload = {
+    env,
+    updatedAt: new Date().toISOString(),
+  };
+
+  jetpack.write(filePath, payload, { atomic: true });
+
+  return filePath;
+}
+
+/**
+ * Capture the allowlisted subset of `process.env` into a plain object.
+ * Convenience for callers that want to write "whatever I currently have".
+ *
+ * @param {NodeJS.ProcessEnv} [source=process.env]
+ * @returns {Object<string, string>}
+ */
+function captureSyncedEnv(source) {
+  const src = source || process.env;
+  const out = {};
+
+  for (const key of SYNCED_ENV_KEYS) {
+    out[key] = src[key] == null ? '' : String(src[key]);
+  }
+
+  return out;
+}
+
+/**
+ * Apply a `data.env` payload to the current process's `process.env`. Used by
+ * the watcher inside the emulator process. Returns a list of `{key, was, now}`
+ * for any key that actually changed (caller can log these).
+ *
+ * Empty-string values in the payload are treated as "unset" — the
+ * corresponding `process.env[key]` is deleted. This matches Node semantics
+ * where `delete process.env.X` makes `process.env.X === undefined` and
+ * `!!process.env.X === false`.
+ *
+ * @param {{ env: Object<string, string> } | null} data
+ * @returns {Array<{ key: string, was: string|undefined, now: string|undefined }>}
+ */
+function applyEnvFromFile(data) {
+  if (!data || !data.env) {
+    return [];
+  }
+
+  const changed = [];
+
+  for (const key of SYNCED_ENV_KEYS) {
+    if (!Object.prototype.hasOwnProperty.call(data.env, key)) {
+      continue;
+    }
+
+    const was = process.env[key];
+    const next = data.env[key];
+
+    if (next === '' || next == null) {
+      if (was != null) {
+        delete process.env[key];
+        changed.push({ key, was, now: undefined });
+      }
+    } else if (was !== next) {
+      process.env[key] = next;
+      changed.push({ key, was, now: next });
+    }
+  }
+
+  return changed;
+}
+
+module.exports = {
+  TEST_MODE_FILENAME,
+  TEMP_DIR_NAME,
+  SYNCED_ENV_KEYS,
+  getTestModeFilePath,
+  readTestMode,
+  writeTestMode,
+  captureSyncedEnv,
+  applyEnvFromFile,
+};