backend-manager 5.0.89 → 5.0.92

package/CHANGELOG.md

@@ -33,7 +33,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Payment schemas for webhook and intent validation.
 - `payment.processors` config section for Stripe, PayPal, Chargebee, and Coinbase configuration.
 - `npx bm stripe` CLI command for standalone Stripe webhook forwarding.
-- Auto-start Stripe CLI webhook forwarding with `npx bm emulators` (gracefully skips when prerequisites are missing).
+- Auto-start Stripe CLI webhook forwarding with `npx bm emulator` (gracefully skips when prerequisites are missing).
 - `Manager.version` property exposing the BEM package version.
 - Journey test accounts for payment lifecycle testing (upgrade, cancel, suspend, trial).
 - Stripe fixture data for subscription states (active, trialing, canceled).
@@ -57,7 +57,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Firestore security rules testing support.
 - HTTP client with auth helpers (`http.as('admin').command()`).
 - Rich assertion library (`isSuccess`, `isError`, `hasProperty`, etc.).
-- New `bm emulators` command for standalone emulator management.
+- New `bm emulator` command for standalone emulator management.
 - Enhanced `bm test` with path filtering and parallel test support.
 
 ### Changed

package/CLAUDE.md

@@ -51,13 +51,19 @@ src/
     index.js                          # Main Manager class
     helpers/                          # Helper classes
       assistant.js                    # Request/response handling
-      user.js                         # User property structure
+      user.js                         # User property structure + schema
       analytics.js                    # GA4 integration
       usage.js                        # Rate limiting
       middleware.js                   # Request pipeline
       settings.js                     # Schema validation
       utilities.js                    # Batch operations
       metadata.js                     # Timestamps/tags
+    libraries/
+      payment-processors/             # Shared payment processor utilities
+        stripe.js                     # Stripe SDK init, fetchResource, toUnified*
+        test.js                       # Test processor (delegates to Stripe shapes)
+        order-id.js                   # Order ID generation (XXXX-XXXX-XXXX)
+        resolve-price-id.js           # Shared price ID resolver from config
     functions/core/                   # Built-in functions
       actions/
         api.js                        # Main bm_api handler
@@ -65,14 +71,35 @@ src/
       events/
         auth/                         # Auth event handlers
         firestore/                    # Firestore triggers
+          payments-webhooks/          # Webhook processing pipeline
+            on-write.js               # Orchestrator: fetch→transform→transition→write
+            analytics.js              # Payment analytics tracking (GA4, Meta, TikTok)
+            transitions/              # State transition detection + handlers
+              index.js                # Transition detection logic
+              send-email.js           # Shared email helper for handlers
+              subscription/           # Subscription transition handlers
+              one-time/               # One-time payment transition handlers
       cron/
         daily.js                      # Daily cron runner
         daily/{job}.js                # Individual cron jobs
     routes/                           # Built-in routes
+      payments/
+        intent/                       # POST /payments/intent
+          post.js                     # Intent creation orchestrator
+          processors/                 # Per-processor intent creators
+            stripe.js                 # Stripe Checkout Session creation
+            test.js                   # Test processor (auto-fires webhooks)
+        webhook/                      # POST /payments/webhook
+          post.js                     # Webhook ingestion + Firestore write
+          processors/                 # Per-processor webhook parsers
+            stripe.js                 # Stripe event parsing + categorization
+            test.js                   # Test processor (delegates to Stripe)
     schemas/                          # Built-in schemas
   cli/
     index.js                          # CLI entry point
     commands/                         # CLI commands
+  test/
+    test-accounts.js                  # Test account definitions (static + journey)
 templates/
   backend-manager-config.json         # Config template
 ```
@@ -387,10 +414,10 @@ Manager.handlers.bm_api = function (mod, position) {
 ### Running Tests
 ```bash
 # Option 1: Two terminals
-npx bm emulators  # Terminal 1 - keeps emulators running
-npx bm test       # Terminal 2 - runs tests
+npx bm emulator  # Terminal 1 - keeps emulator running
+npx bm test      # Terminal 2 - runs tests
 
-# Option 2: Single command (auto-starts emulators)
+# Option 2: Single command (auto-starts emulator)
 npx bm test
 ```
 
@@ -492,7 +519,7 @@ assert.fail(message)                           // Explicit fail
 
 ## Stripe Webhook Forwarding
 
-BEM auto-starts Stripe CLI webhook forwarding when running `npx bm serve` or `npx bm emulators`. This forwards Stripe test webhooks to the local server so the full payment pipeline works end-to-end during development.
+BEM auto-starts Stripe CLI webhook forwarding when running `npx bm serve` or `npx bm emulator`. This forwards Stripe test webhooks to the local server so the full payment pipeline works end-to-end during development.
 
 **Requirements:**
 - `STRIPE_SECRET_KEY` set in `functions/.env`
@@ -594,8 +621,10 @@ subscription: {
   },
   payment: {
     processor: null,               // 'stripe' | 'paypal' | etc.
+    orderId: null,                 // BEM order ID (e.g., '1234-5678-9012')
     resourceId: null,              // provider subscription ID (e.g., 'sub_xxx')
     frequency: null,               // 'monthly' | 'annually'
+    price: 0,                      // resolved from config (number, e.g., 4.99)
     startDate: { timestamp, timestampUNIX },
     updatedBy: {
       event: { name: null, id: null },
@@ -638,13 +667,14 @@ The `transitions/index.js` module compares the **before** state (current `users/
 | Transition | Before → After | File |
 |---|---|---|
 | `new-subscription` | basic/null → active paid | `transitions/subscription/new-subscription.js` |
-| `trial-started` | basic/null → active paid with trial | `transitions/subscription/trial-started.js` |
 | `payment-failed` | active → suspended | `transitions/subscription/payment-failed.js` |
 | `payment-recovered` | suspended → active | `transitions/subscription/payment-recovered.js` |
 | `cancellation-requested` | pending=false → pending=true | `transitions/subscription/cancellation-requested.js` |
 | `subscription-cancelled` | non-cancelled → cancelled | `transitions/subscription/subscription-cancelled.js` |
 | `plan-changed` | active product A → active product B | `transitions/subscription/plan-changed.js` |
 
+Note: Trials are NOT a separate transition. The `new-subscription` handler checks `after.trial.claimed` to determine if the subscription started with a trial.
+
 ### One-Time Transitions
 
 | Transition | Event Type | File |
@@ -672,6 +702,107 @@ module.exports = async function ({ before, after, uid, userDoc, admin, assistant
 2. Create handler file in `transitions/{category}/{name}.js`
 3. Handler receives full context — use `assistant.log()` for logging, `Manager.project.apiUrl` for API calls
 
+## Payment System Architecture
+
+### Pipeline
+
+The payment system follows a linear pipeline: **Intent → Webhook → On-Write → Transition**.
+
+1. **Intent** (`POST /payments/intent`): Client requests a payment session. BEM validates the product, generates an order ID (`XXXX-XXXX-XXXX`), and delegates to the processor module (e.g., Stripe creates a Checkout Session). Saves to `payments-intents/{orderId}`.
+
+2. **Webhook** (`POST /payments/webhook?processor=X&key=Y`): Processor sends event data. BEM parses and categorizes the event (`subscription` or `one-time`), extracts the UID, and saves to `payments-webhooks/{eventId}` with `status: 'pending'`.
+
+3. **On-Write** (Firestore trigger on `payments-webhooks/{eventId}`): Fetches the latest resource from the processor API (not stale webhook data), transforms it into a unified object, detects state transitions, dispatches handlers, tracks analytics, and writes to `users/{uid}.subscription` (subscriptions) and `payments-orders/{orderId}`.
+
+4. **Transitions** (fire-and-forget): Handler files run asynchronously after detection. Failures never block webhook processing. Skipped during tests unless `TEST_EXTENDED_MODE` is set.
+
+### Processor Interface
+
+Each processor implements two modules:
+
+**Intent processor** (`routes/payments/intent/processors/{processor}.js`):
+```javascript
+module.exports = {
+  async createIntent({ uid, orderId, product, productId, frequency, trial, confirmationUrl, cancelUrl, Manager, assistant }) {
+    return { id, url, raw };
+  },
+};
+```
+
+**Webhook processor** (`routes/payments/webhook/processors/{processor}.js`):
+```javascript
+module.exports = {
+  isSupported(eventType) { return boolean; },
+  parseWebhook(req) { return { eventId, eventType, category, resourceType, resourceId, raw, uid }; },
+};
+```
+
+**Shared library** (`libraries/payment-processors/{processor}.js`):
+```javascript
+module.exports = {
+  init() { /* return SDK instance */ },
+  async fetchResource(resourceType, resourceId, rawFallback, context) { /* return resource */ },
+  toUnifiedSubscription(rawSubscription, options) { /* return unified object */ },
+  toUnifiedOneTime(rawResource, options) { /* return unified object */ },
+};
+```
+
+### Product Configuration
+
+Products are defined in `backend-manager-config.json` under `payment.products`:
+
+```javascript
+payment: {
+  products: [
+    {
+      id: 'basic',           // Free tier (no prices)
+      name: 'Basic',
+      type: 'subscription',
+      limits: { requests: 100 },
+    },
+    {
+      id: 'premium',         // Paid subscription
+      name: 'Premium',
+      type: 'subscription',
+      limits: { requests: 1000 },
+      trial: { days: 14 },   // Optional trial period
+      prices: {
+        monthly:  { amount: 4.99,  stripe: 'price_xxx', paypal: null },
+        annually: { amount: 49.99, stripe: 'price_yyy', paypal: null },
+      },
+    },
+    {
+      id: 'credits-100',     // One-time purchase
+      name: '100 Credits',
+      type: 'one-time',
+      prices: {
+        once: { amount: 9.99, stripe: 'price_zzz' },
+      },
+    },
+  ],
+}
+```
+
+Key rules:
+- `type` is `'subscription'` (default) or `'one-time'`
+- Subscription prices are keyed by frequency: `monthly`, `annually`
+- One-time prices are keyed as `once`
+- Each price object has processor-specific IDs (`stripe`, `paypal`, etc.)
+- `basic` product has no `prices` — it's the free tier
+
+### Firestore Collections
+
+| Collection | Key | Purpose |
+|---|---|---|
+| `payments-intents/{orderId}` | Order ID | Intent metadata (processor, product, status) |
+| `payments-webhooks/{eventId}` | Processor event ID | Webhook processing state + transition result |
+| `payments-orders/{orderId}` | Order ID | Unified order data (single source of truth for orders) |
+| `users/{uid}.subscription` | User UID | Current subscription state (subscriptions only) |
+
+### Test Processor
+
+The `test` processor generates Stripe-shaped data and auto-fires webhooks to the local server. Only available in non-production environments. Use `processor: 'test'` in intent requests during testing. The test webhook processor delegates to Stripe's parser since it generates Stripe-shaped payloads.
+
 ## Common Mistakes to Avoid
 
 1. **Don't modify Manager internals directly** - Use factory methods and public APIs
@@ -699,14 +830,22 @@ module.exports = async function ({ before, after, uid, userDoc, admin, assistant
 | Middleware pipeline | `src/manager/helpers/middleware.js` |
 | Schema validation | `src/manager/helpers/settings.js` |
 | Rate limiting | `src/manager/helpers/usage.js` |
-| User properties | `src/manager/helpers/user.js` |
+| User properties + schema | `src/manager/helpers/user.js` |
 | Batch utilities | `src/manager/helpers/utilities.js` |
 | Main API handler | `src/manager/functions/core/actions/api.js` |
 | Config template | `templates/backend-manager-config.json` |
 | CLI entry | `src/cli/index.js` |
 | Stripe webhook forwarding | `src/cli/commands/stripe.js` |
+| Intent creation | `src/manager/routes/payments/intent/post.js` |
+| Webhook ingestion | `src/manager/routes/payments/webhook/post.js` |
+| Webhook processing (on-write) | `src/manager/events/firestore/payments-webhooks/on-write.js` |
+| Payment analytics | `src/manager/events/firestore/payments-webhooks/analytics.js` |
+| Transition detection | `src/manager/events/firestore/payments-webhooks/transitions/index.js` |
 | Payment processor libraries | `src/manager/libraries/payment-processors/` |
-| Payment transition handlers | `src/manager/events/firestore/payments-webhooks/transitions/` |
+| Stripe library | `src/manager/libraries/payment-processors/stripe.js` |
+| Price ID resolver | `src/manager/libraries/payment-processors/resolve-price-id.js` |
+| Order ID generator | `src/manager/libraries/payment-processors/order-id.js` |
+| Test accounts | `src/test/test-accounts.js` |
 
 ## Environment Detection
 

package/README.md

@@ -733,7 +733,7 @@ npx backend-manager <command>
 | `bem serve` | Start local Firebase emulator |
 | `bem deploy` | Deploy functions to Firebase |
 | `bem test [paths...]` | Run integration tests |
-| `bem emulators` | Start Firebase emulators (keep-alive mode) |
+| `bem emulator` | Start Firebase emulator (keep-alive mode) |
 | `bem stripe` | Start Stripe CLI webhook forwarding to local server |
 | `bem version`, `bem v` | Show BEM version |
 | `bem clear` | Clear cache and temp files |
@@ -749,7 +749,7 @@ Set these in your `functions/.env` file:
 | Variable | Description |
 |----------|-------------|
 | `BACKEND_MANAGER_KEY` | Admin authentication key |
-| `STRIPE_SECRET_KEY` | Stripe secret key (enables auto webhook forwarding in `serve`/`emulators`) |
+| `STRIPE_SECRET_KEY` | Stripe secret key (enables auto webhook forwarding in `serve`/`emulator`) |
 
 ## Response Headers
 
@@ -761,16 +761,16 @@ bm-properties: {"code":200,"tag":"functionName/executionId","usage":{...},"schem
 
 ## Testing
 
-BEM includes an integration test framework that runs against Firebase emulators.
+BEM includes an integration test framework that runs against the Firebase emulator.
 
 ### Running Tests
 
 ```bash
 # Option 1: Two terminals (recommended for development)
-npx bm emulators  # Terminal 1 - keeps emulators running
-npx bm test       # Terminal 2 - runs tests
+npx bm emulator  # Terminal 1 - keeps emulator running
+npx bm test      # Terminal 2 - runs tests
 
-# Option 2: Single command (auto-starts emulators, shuts down after)
+# Option 2: Single command (auto-starts emulator, shuts down after)
 npx bm test
 ```
 

package/TODO-MARKETING.md

@@ -0,0 +1,3 @@
+1. Determine name via AI on signup
+2. Add to sendgrid marketig cotacts
+3. then, develop a way to SYNC them to the marketing contacts. we coould sync on payment changes (liek newly subscribed, cancelled, etc) so we can segment them??

package/TODO-PAYMENT-v2.md

@@ -0,0 +1,71 @@
+TODO payments
+
+would it be beneficial to... check the time on the event and the time in our datbase and skip if the time in oour database is nwer than the vent, indicatig that it is stale? or is this redundatn since we fetch the latest resource anyway?
+
+next, we need to do certain things based on the CHANGE thats happening to the resource (subscription or one time) that is different that simply updating the user doc and the payments-subscriptions or payments-one-time collection. For example:
+  * if a new subscription is created, we send a welcome email and grant access to the product (but this cant happen when a user fixes their payment method from a failed payment, only when a new subscription is created)
+  * if a subscription is cancelled, we send a cancellation email
+  * if a subscription payment fails, we send a paymetn failed "please update your payment method" email
+  * if a subscription payment succeeds after previously failing, we send a "payment successful, your access has been restored" email
+
+more endpoints to build
+payments/cancel
+  * takes a subscrition id and requests to cancel at the end of the billing period (not immediately). this can only be done if the user has an non cancelled subscription.
+  * there should be an accompanying frontend form that asks some outboardig quetsions
+    * Why are you cancelling (checkboxes + textbox) with randomzed order of the checkboes
+  * after doing this, users should still be able to reactivate it
+payments/manage
+  * fetches the customer portal link from the payment processor and redirects the user there
+  * acessible from the user's account page in biling setion
+  * only accessible if the user has a non cancelled subscription
+
+Note: * for managing and cancelling, they should be under a sinlge button/dropdown called "manage subscription".
+  * it could have links to the 2 pages as items in the dropdown, or we could take them to a dedicated page (or expand an accordian) that has more information about managing it
+  * we need to make it hard to cancel, buried in some info, and make it more prominent to manage it, since we want to encourage users to manage their subscription rather than cancelling it.
+
+payments/refund
+  * takes a subscription id and requests a refund.
+  * we can only refund the most recent payment and we can only refund if the subscription is cancelled.
+  * we can only refund if the most recent payment in FULL was made less than 7 days ago, otherwise we can only refund a prorated amount.
+payments/reactivate
+  * takes a subscription id and reactivates a cancelled subscription. this can only be done if the subscription is still within its billing period, otherwise the user would have to create a new subscription.
+payments/upgrade
+  * takes a subscription id and a new plan id and upgrades the user's subscription to the new plan. this can only be done if the user has an active subscription.
+
+
+trial support:
+when a peyment intent happens, we can only grant a trial if the user has never had a trial which involves checking the paymetns-subscriptions collection for the user to see if any exist. if any exist in any form, then we dont give a trial.
+we also need a test for this
+
+block multipl epayments
+check if user has a non-cancelled sub during payment intent creation, if so, block the payment intent from being created. this will prevent multiple payments from being made at the same time and causing issues. we can check the payments-subscriptions collection for ALL usbcriptions belonging to the UID. we can use this for the trial check as well (recycle the results).
+we also need a test for this
+
+
+
+also, can you check and confirm if the usage.js sends back the users current usage in th headers? i think it does? maybe it our tests we can check to ensure that the user is probably having their usage set this way?
+
+
+MANAGEMENT LINK
+we need an endpoint that returns a management link for the user to manage their subscription. this will involve us looking up the users current subscription, then calling the appropriate method on the payment processor to get a management link. we can only return a management link if the user has an active subscription.
+
+
+TODO
+
+* authorizations ystem that tries to charge the card to see if its valid?
+* bm_cronDaily task that doublechecks subscriptions??
+  * could check existing ones eveyr month to ensure they are still vlaud and not messed up from failed webhook processing or could check every day to ensure theres no users with multiple subscirptions active simultaneously?
+* bm_cronDaily yto handle disputes?
+  * automatically provide evidence?
+
+ATTRIBUTIONS!!!
+// Filter attribution entries older than 30 days
+const attribution = webManager.storage().get('attribution', {});
+const maxAge = 30 * 24 * 60 * 60 * 1000; // 30 days in ms
+const filtered = {};
+
+for (const [key, entry] of Object.entries(attribution)) {
+  if (!entry?.timestamp) continue;
+  if ((Date.now() - new Date(entry.timestamp).getTime()) < maxAge) {
+    filtered[key] = entry;
+  }

package/TODO.md

@@ -23,11 +23,18 @@ BEM
   * Teach it how to mock requests and use test user's SECRET API KEYS to authenticate requests
   * BEM should create a few test accounts: basic, then one for each plan level
 
+TODO
+Update deps!!!! theres lots
+* we culd have a test that TRIES EACH IMPORT ?? incase updating it fails due to ESM VULLSHIT?
+
 
 ADD HEALTHCHECK TO BEM!!!
   ✗ https://api.clockii.com/backend-manager?command=healthcheck → fetch failed
 
 TODO
+PAYMENT
+https://hookdeck.com/webhooks/platforms/guide-to-paypal-webhooks-features-and-best-practices
+
 
 # TEST REWRRK
 btw... the account.json needs to be removed. remove it from BEM and the consumong project. when we make our test system, we DO NOT NEED TO STORE THE ACCOUBT IN A JSON file. we just need a source of truth in BEM for what uid/emails to look for

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "backend-manager",
-  "version": "5.0.89",
+  "version": "5.0.92",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {
-    "bem": "./bin/bem",
-    "bm": "./bin/bem"
+    "bm": "./bin/backend-manager",
+    "bem": "./bin/backend-manager",
+    "backend-manager": "./bin/backend-manager",
+    "mgr": "./bin/backend-manager"
   },
   "scripts": {
     "start": "node src/manager/index.js",
@@ -18,7 +20,7 @@
   "projectScripts": {
     "start": "npx bm setup && npx bm serve",
     "deploy": "npx bm setup && npx bm deploy",
-    "emulators": "npx bm setup && npx bm emulators",
+    "emulator": "npx bm setup && npx bm emulator",
     "test": "npx bm setup && npx bm test",
     "setup": "npx bm setup"
   },
@@ -47,7 +49,7 @@
     "@google-cloud/pubsub": "^5.3.0",
     "@google-cloud/storage": "^7.19.0",
     "@octokit/rest": "^19.0.13",
-    "@sendgrid/mail": "^7.7.0",
+    "@sendgrid/mail": "^8.1.6",
     "@sentry/node": "^6.19.7",
     "body-parser": "^1.20.4",
     "busboy": "^1.6.0",

package/src/cli/commands/{emulators.js → emulator.js}

@@ -5,12 +5,12 @@ const jetpack = require('fs-jetpack');
 const JSON5 = require('json5');
 const powertools = require('node-powertools');
 const WatchCommand = require('./watch');
-const { DEFAULT_EMULATOR_PORTS } = require('./setup-tests/emulators-config');
+const { DEFAULT_EMULATOR_PORTS } = require('./setup-tests/emulator-config');
 
-class EmulatorsCommand extends BaseCommand {
+class EmulatorCommand extends BaseCommand {
   async execute() {
-    this.log(chalk.cyan('\n  Starting Firebase emulators (keep-alive mode)...\n'));
-    this.log(chalk.gray('  Emulators will stay running until you press Ctrl+C\n'));
+    this.log(chalk.cyan('\n  Starting Firebase emulator (keep-alive mode)...\n'));
+    this.log(chalk.gray('  Emulator will stay running until you press Ctrl+C\n'));
 
     // Warn if TEST_EXTENDED_MODE is enabled
     if (process.env.TEST_EXTENDED_MODE) {
@@ -26,29 +26,29 @@ class EmulatorsCommand extends BaseCommand {
     // Start Stripe webhook forwarding in background
     this.startStripeWebhookForwarding();
 
-    // Run emulators with keep-alive command (use single quotes since runWithEmulators wraps in double quotes)
-    const keepAliveCommand = "echo ''; echo 'Emulators ready. Press Ctrl+C to shut down...'; sleep 86400";
+    // Run emulator with keep-alive command (use single quotes since runWithEmulator wraps in double quotes)
+    const keepAliveCommand = "echo ''; echo 'Emulator ready. Press Ctrl+C to shut down...'; sleep 86400";
 
     try {
-      await this.runWithEmulators(keepAliveCommand);
+      await this.runWithEmulator(keepAliveCommand);
     } catch (error) {
       // User pressed Ctrl+C - this is expected
-      this.log(chalk.gray('\n  Emulators stopped.\n'));
+      this.log(chalk.gray('\n  Emulator stopped.\n'));
     }
   }
 
   /**
-   * Run a command with Firebase emulators
-   * @param {string} command - The command to execute inside emulators:exec
+   * Run a command with Firebase emulator
+   * @param {string} command - The command to execute inside the Firebase emulator
    * @returns {Promise<void>}
    */
-  async runWithEmulators(command) {
+  async runWithEmulator(command) {
     const projectDir = this.main.firebaseProjectPath;
 
     // Load emulator ports from firebase.json
     const emulatorPorts = this.loadEmulatorPorts(projectDir);
 
-    // Check for port conflicts before starting emulators
+    // Check for port conflicts before starting emulator
     const canProceed = await this.checkAndKillBlockingProcesses(emulatorPorts);
     if (!canProceed) {
       throw new Error('Port conflicts could not be resolved');
@@ -58,9 +58,9 @@ class EmulatorsCommand extends BaseCommand {
     // hosting is included so localhost:5002 rewrites work (e.g., /backend-manager -> bm_api)
     // pubsub is included so scheduled functions (bm_cronDaily) can be triggered in tests
     // Use double quotes for command wrapper since the command may contain single quotes (JSON strings)
-    const emulatorsCommand = `BEM_TESTING=true firebase emulators:exec --only functions,firestore,auth,database,hosting,pubsub --ui "${command}"`;
+    const emulatorCommand = `BEM_TESTING=true firebase emulators:exec --only functions,firestore,auth,database,hosting,pubsub --ui "${command}"`;
 
-    await powertools.execute(emulatorsCommand, {
+    await powertools.execute(emulatorCommand, {
       log: true,
       cwd: projectDir,
     });
@@ -90,4 +90,4 @@ class EmulatorsCommand extends BaseCommand {
   }
 }
 
-module.exports = EmulatorsCommand;
+module.exports = EmulatorCommand;

package/src/cli/commands/index.js

@@ -8,7 +8,7 @@ module.exports = {
   ServeCommand: require('./serve'),
   DeployCommand: require('./deploy'),
   TestCommand: require('./test'),
-  EmulatorsCommand: require('./emulators'),
+  EmulatorCommand: require('./emulator'),
   CleanCommand: require('./clean'),
   IndexesCommand: require('./indexes'),
   WatchCommand: require('./watch'),

package/src/cli/commands/setup-tests/{emulators-config.js → emulator-config.js}

@@ -25,9 +25,9 @@ const REQUIRED_EMULATORS = {
   ui: { enabled: true, port: DEFAULT_EMULATOR_PORTS.ui },
 };
 
-class EmulatorsConfigTest extends BaseTest {
+class EmulatorConfigTest extends BaseTest {
   getName() {
-    return 'emulators config in firebase.json';
+    return 'emulator config in firebase.json';
   }
 
   async run() {
@@ -75,5 +75,5 @@ class EmulatorsConfigTest extends BaseTest {
   }
 }
 
-module.exports = EmulatorsConfigTest;
-module.exports.DEFAULT_EMULATOR_PORTS = DEFAULT_EMULATOR_PORTS;
+module.exports = EmulatorConfigTest;
+module.exports.DEFAULT_EMULATOR_PORTS = DEFAULT_EMULATOR_PORTS;

package/src/cli/commands/setup-tests/index.js

@@ -24,7 +24,7 @@ const FirestoreIndexesInJsonTest = require('./firestore-indexes-in-json');
 const RealtimeRulesInJsonTest = require('./realtime-rules-in-json');
 const StorageRulesInJsonTest = require('./storage-rules-in-json');
 const RemoteconfigTemplateInJsonTest = require('./remoteconfig-template-in-json');
-const EmulatorsConfigTest = require('./emulators-config');
+const EmulatorConfigTest = require('./emulator-config');
 const HostingRewritesTest = require('./hosting-rewrites');
 const FirestoreIndexesSyncedTest = require('./firestore-indexes-synced');
 const StorageLifecyclePolicyTest = require('./storage-lifecycle-policy');
@@ -64,7 +64,7 @@ function getTests(context) {
     new RealtimeRulesInJsonTest(context),
     new StorageRulesInJsonTest(context),
     new RemoteconfigTemplateInJsonTest(context),
-    new EmulatorsConfigTest(context),
+    new EmulatorConfigTest(context),
     new HostingRewritesTest(context),
     new FirestoreIndexesSyncedTest(context),
     new StorageLifecyclePolicyTest(context),

package/src/cli/commands/setup-tests/project-id-consistency.js

@@ -9,7 +9,7 @@ const chalk = require('chalk');
  * - functions/backend-manager-config.json (firebaseConfig.projectId)
  * - functions/service-account.json (project_id)
  *
- * Mismatches cause tests to fail when running emulators in separate terminals
+ * Mismatches cause tests to fail when running emulator in separate terminals
  * because different parts of the system connect to different Firestore databases.
  */
 class ProjectIdConsistencyTest extends BaseTest {

package/src/cli/commands/test.js

@@ -4,8 +4,8 @@ const chalk = require('chalk');
 const jetpack = require('fs-jetpack');
 const JSON5 = require('json5');
 const powertools = require('node-powertools');
-const { DEFAULT_EMULATOR_PORTS } = require('./setup-tests/emulators-config');
-const EmulatorsCommand = require('./emulators');
+const { DEFAULT_EMULATOR_PORTS } = require('./setup-tests/emulator-config');
+const EmulatorCommand = require('./emulator');
 
 class TestCommand extends BaseCommand {
   async execute() {
@@ -42,14 +42,14 @@ class TestCommand extends BaseCommand {
     // Build the test command
     const testCommand = this.buildTestCommand(testConfig);
 
-    // Check if emulators are already running
-    const emulatorsRunning = this.areEmulatorsRunning(emulatorPorts);
+    // Check if emulator is already running
+    const emulatorRunning = this.isEmulatorRunning(emulatorPorts);
 
-    if (emulatorsRunning) {
-      this.log(chalk.cyan('Running tests against EXISTING emulators'));
+    if (emulatorRunning) {
+      this.log(chalk.cyan('Running tests against EXISTING emulator'));
       await this.runTestsDirectly(testCommand, functionsDir, emulatorPorts);
     } else {
-      this.log(chalk.cyan('Starting emulators and running tests...'));
+      this.log(chalk.cyan('Starting emulator and running tests...'));
       await this.runEmulatorTests(testCommand);
     }
   }
@@ -164,16 +164,16 @@ class TestCommand extends BaseCommand {
   }
 
   /**
-   * Check if emulators are already running
+   * Check if emulator is already running
    */
-  areEmulatorsRunning(emulatorPorts) {
+  isEmulatorRunning(emulatorPorts) {
     // Check if functions emulator port is in use
-    // If it is, assume all emulators are running
+    // If it is, assume emulator is running
     return this.isPortInUse(emulatorPorts.functions);
   }
 
   /**
-   * Run tests directly (emulators already running)
+   * Run tests directly (emulator already running)
    */
   async runTestsDirectly(testCommand, functionsDir, emulatorPorts) {
     this.log(chalk.gray(`  Hosting: http://127.0.0.1:${emulatorPorts.hosting}`));
@@ -192,16 +192,16 @@ class TestCommand extends BaseCommand {
   }
 
   /**
-   * Run tests with Firebase emulators (starts emulators, runs tests, shuts down)
+   * Run tests with Firebase emulator (starts emulator, runs tests, shuts down)
    */
   async runEmulatorTests(testCommand) {
-    this.log(chalk.gray('  Starting Firebase emulators...\n'));
+    this.log(chalk.gray('  Starting Firebase emulator...\n'));
 
-    // Use EmulatorsCommand to run tests with emulators
-    const emulatorsCmd = new EmulatorsCommand(this.main);
+    // Use EmulatorCommand to run tests with emulator
+    const emulatorCmd = new EmulatorCommand(this.main);
 
     try {
-      await emulatorsCmd.runWithEmulators(testCommand);
+      await emulatorCmd.runWithEmulator(testCommand);
     } catch (error) {
       // Only exit with error if it wasn't a user-initiated exit
       if (error.code !== 0) {