backend-manager 5.0.102 → 5.0.103

package/CLAUDE.md

@@ -535,6 +535,62 @@ If any prerequisite is missing, webhook forwarding is silently skipped with an i
 
 The forwarding URL is: `http://localhost:{hostingPort}/backend-manager/payments/webhook?processor=stripe&key={BACKEND_MANAGER_KEY}`
 
+## CLI Utility Commands
+
+Quick commands for reading/writing Firestore and managing Auth users directly from the terminal. Works in any BEM consumer project (requires `functions/service-account.json` for production, or `--emulator` for local).
+
+### Firestore Commands
+
+```bash
+npx bm firestore:get <path>                          # Read a document
+npx bm firestore:set <path> '<json>'                 # Write/merge a document
+npx bm firestore:set <path> '<json>' --no-merge      # Overwrite a document entirely
+npx bm firestore:query <collection>                  # Query a collection (default limit 25)
+  --where "field==value"                              #   Filter (repeatable for AND)
+  --orderBy "field:desc"                              #   Sort
+  --limit N                                           #   Limit results
+npx bm firestore:delete <path>                       # Delete a document (prompts for confirmation)
+```
+
+### Auth Commands
+
+```bash
+npx bm auth:get <uid-or-email>                       # Get user by UID or email (auto-detected via @)
+npx bm auth:list [--limit N] [--page-token T]        # List users (default 100)
+npx bm auth:delete <uid-or-email>                    # Delete user (prompts for confirmation)
+npx bm auth:set-claims <uid-or-email> '<json>'       # Set custom claims
+```
+
+### Shared Flags
+
+| Flag | Description |
+|------|-------------|
+| `--emulator` | Target local emulator instead of production |
+| `--force` | Skip confirmation on destructive operations |
+| `--raw` | Compact JSON output (for piping to `jq` etc.) |
+
+### Examples
+
+```bash
+# Read a user document from production
+npx bm firestore:get users/abc123
+
+# Write to emulator
+npx bm firestore:set users/test123 '{"name":"Test User"}' --emulator
+
+# Query with filters
+npx bm firestore:query users --where "subscription.status==active" --limit 10
+
+# Look up auth user by email
+npx bm auth:get user@example.com
+
+# Set admin claims
+npx bm auth:set-claims user@example.com '{"admin":true}'
+
+# Delete from emulator (no confirmation needed)
+npx bm firestore:delete users/test123 --emulator
+```
+
 ## Usage & Rate Limiting
 
 ### Overview
@@ -836,6 +892,9 @@ The `test` processor generates Stripe-shaped data and auto-fires webhooks to the
 | Config template | `templates/backend-manager-config.json` |
 | CLI entry | `src/cli/index.js` |
 | Stripe webhook forwarding | `src/cli/commands/stripe.js` |
+| Firebase init helper (CLI) | `src/cli/commands/firebase-init.js` |
+| Firestore CLI commands | `src/cli/commands/firestore.js` |
+| Auth CLI commands | `src/cli/commands/auth.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` |

package/README.md

@@ -741,6 +741,16 @@ npx backend-manager <command>
 | `bem clean:npm` | Clean and reinstall npm modules |
 | `bem firestore:indexes:get` | Get Firestore indexes |
 | `bem cwd` | Show current working directory |
+| `bem firestore:get <path>` | Read a Firestore document |
+| `bem firestore:set <path> '<json>'` | Write/merge a Firestore document |
+| `bem firestore:query <collection>` | Query a Firestore collection |
+| `bem firestore:delete <path>` | Delete a Firestore document |
+| `bem auth:get <uid-or-email>` | Get an Auth user by UID or email |
+| `bem auth:list` | List Auth users |
+| `bem auth:delete <uid-or-email>` | Delete an Auth user |
+| `bem auth:set-claims <uid-or-email> '<json>'` | Set custom claims on an Auth user |
+
+All Firestore and Auth commands support `--emulator` to target the local emulator, `--force` to skip confirmation, and `--raw` for compact JSON output.
 
 ## Environment Variables
 

package/TODO-MARKETING.md

@@ -1,3 +1,56 @@
 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??
+
+
+When user sings up, use AI to generate first name, last name, company???
+When user doc is updated, sync with sendgrid and beehiiv?? like name, premium status, etc
+if admin is set to true from something else then we send an emergency critical email to alert us
+
+need to confirm we hv hooks/events setup properly
+      handlerPath = `${Manager.cwd}/events/${handlerName}.js`;
+liek bm_cronDaily, is it able to find the BEM path right? what about if we want to add our own per project?
+
+implement BEM hooks (removed in muddleware semantic system)
+
+https://firebase.google.com/docs/functions/2nd-gen-upgrade
+
+------------
+You are to extract the first name, last name, and company from the provided email.
+
+If you can get the company from the email domain, include that as well but DO NOT set the company to generic email providers like gmail, yahoo, etc.
+
+You may use a single initial if the email does not provide a full first name.
+
+For example:
+jonsnow123@gmail.com, jon.snow123@gmail.com
+First Name: Jon
+Last Name: Snow
+Company:
+
+jsnow123@gmail.com, j.snow123@gmail.com
+First Name: J
+Last Name: Snow
+Company:
+
+jon.snow@acme.com
+First Name: Jon
+Last Name: Snow
+Company: Acme
+
+jsnow@acme.com
+First Name: J
+Last Name: Snow
+Company: Acme
+
+jon123@gmail.com
+First Name: Jon
+Last Name:
+Company:
+
+every time we touch, cascada
+just dance, lady gaga
+over drake,
+Time, hans zimmer
+yellow, coldplay
+yess bitch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.102",
+  "version": "5.0.103",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/cli/commands/auth.js

@@ -0,0 +1,226 @@
+const BaseCommand = require('./base-command');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const { initFirebase } = require('./firebase-init');
+
+class AuthCommand extends BaseCommand {
+  async execute() {
+    const argv = this.main.argv;
+    const args = argv._ || [];
+    const subcommand = args[0]; // e.g., 'auth:get' or 'auth:set-claims'
+    const action = subcommand.split(':').slice(1).join(':'); // handles 'auth:set-claims'
+
+    // Initialize Firebase
+    const isEmulator = argv.emulator || false;
+    let firebase;
+
+    try {
+      firebase = initFirebase({
+        firebaseProjectPath: this.firebaseProjectPath,
+        emulator: isEmulator,
+      });
+    } catch (error) {
+      this.logError(`Firebase init failed: ${error.message}`);
+      return;
+    }
+
+    const { admin, projectId } = firebase;
+    const target = isEmulator ? 'emulator' : 'production';
+    this.log(chalk.gray(`  Target: ${projectId} (${target})\n`));
+
+    // Dispatch to subcommand handler
+    switch (action) {
+      case 'get':
+        return await this.get(admin, args, argv);
+      case 'list':
+        return await this.list(admin, args, argv);
+      case 'delete':
+        return await this.del(admin, args, argv, isEmulator);
+      case 'set-claims':
+        return await this.setClaims(admin, args, argv);
+      default:
+        this.logError(`Unknown auth subcommand: ${action}`);
+        this.log(chalk.gray('  Available: auth:get, auth:list, auth:delete, auth:set-claims'));
+    }
+  }
+
+  /**
+   * Resolve a user identifier to a UserRecord.
+   * Accepts UID or email address (auto-detected via @).
+   */
+  async resolveUser(admin, identifier) {
+    if (!identifier) {
+      return null;
+    }
+
+    // If it contains '@', treat as email
+    if (identifier.includes('@')) {
+      return await admin.auth().getUserByEmail(identifier);
+    }
+
+    return await admin.auth().getUser(identifier);
+  }
+
+  /**
+   * Get a user by UID or email.
+   * Usage: npx bm auth:get user@email.com
+   *        npx bm auth:get abc123uid
+   */
+  async get(admin, args, argv) {
+    const identifier = args[1];
+
+    if (!identifier) {
+      this.logError('Usage: npx bm auth:get <uid-or-email>');
+      return;
+    }
+
+    try {
+      const user = await this.resolveUser(admin, identifier);
+      this.output(user.toJSON(), argv);
+    } catch (error) {
+      if (error.code === 'auth/user-not-found') {
+        this.logWarning(`User not found: ${identifier}`);
+        return;
+      }
+      this.logError(`Failed to get user: ${error.message}`);
+    }
+  }
+
+  /**
+   * List users.
+   * Usage: npx bm auth:list [--limit 100] [--page-token TOKEN]
+   */
+  async list(admin, args, argv) {
+    const limit = parseInt(argv.limit, 10) || 100;
+    const pageToken = argv['page-token'] || argv.pageToken || undefined;
+
+    try {
+      const result = await admin.auth().listUsers(limit, pageToken);
+
+      const users = result.users.map(user => ({
+        uid: user.uid,
+        email: user.email || null,
+        displayName: user.displayName || null,
+        disabled: user.disabled,
+        createdAt: user.metadata.creationTime,
+        lastSignIn: user.metadata.lastSignInTime,
+        customClaims: user.customClaims || {},
+      }));
+
+      this.log(chalk.gray(`  Found ${users.length} user(s)\n`));
+
+      if (result.pageToken) {
+        this.log(chalk.gray(`  Next page: --page-token ${result.pageToken}\n`));
+      }
+
+      this.output(users, argv);
+    } catch (error) {
+      this.logError(`Failed to list users: ${error.message}`);
+    }
+  }
+
+  /**
+   * Delete a user.
+   * Usage: npx bm auth:delete user@email.com [--force]
+   */
+  async del(admin, args, argv, isEmulator) {
+    const identifier = args[1];
+
+    if (!identifier) {
+      this.logError('Usage: npx bm auth:delete <uid-or-email> [--force]');
+      return;
+    }
+
+    // Resolve user first to show who we're deleting
+    let user;
+    try {
+      user = await this.resolveUser(admin, identifier);
+    } catch (error) {
+      if (error.code === 'auth/user-not-found') {
+        this.logWarning(`User not found: ${identifier}`);
+        return;
+      }
+      this.logError(`Failed to resolve user: ${error.message}`);
+      return;
+    }
+
+    this.log(chalk.gray(`  User: ${user.uid} (${user.email || 'no email'})`));
+
+    // Require confirmation for production (skip for emulator or --force)
+    if (!isEmulator && !argv.force) {
+      const { confirmed } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'confirmed',
+        message: `Delete user "${user.uid}" (${user.email || 'no email'}) from PRODUCTION?`,
+        default: false,
+      }]);
+
+      if (!confirmed) {
+        this.log(chalk.gray('  Aborted.'));
+        return;
+      }
+    }
+
+    try {
+      await admin.auth().deleteUser(user.uid);
+      this.logSuccess(`User deleted: ${user.uid}`);
+    } catch (error) {
+      this.logError(`Failed to delete user: ${error.message}`);
+    }
+  }
+
+  /**
+   * Set custom claims on a user.
+   * Usage: npx bm auth:set-claims user@email.com '{"admin": true}'
+   */
+  async setClaims(admin, args, argv) {
+    const identifier = args[1];
+    const jsonString = args[2];
+
+    if (!identifier || !jsonString) {
+      this.logError('Usage: npx bm auth:set-claims <uid-or-email> \'<json>\'');
+      return;
+    }
+
+    let claims;
+    try {
+      claims = JSON.parse(jsonString);
+    } catch (error) {
+      this.logError(`Invalid JSON: ${error.message}`);
+      return;
+    }
+
+    let user;
+    try {
+      user = await this.resolveUser(admin, identifier);
+    } catch (error) {
+      if (error.code === 'auth/user-not-found') {
+        this.logWarning(`User not found: ${identifier}`);
+        return;
+      }
+      this.logError(`Failed to resolve user: ${error.message}`);
+      return;
+    }
+
+    try {
+      await admin.auth().setCustomUserClaims(user.uid, claims);
+      this.logSuccess(`Custom claims set for ${user.uid}:`);
+      this.output(claims, argv);
+    } catch (error) {
+      this.logError(`Failed to set claims: ${error.message}`);
+    }
+  }
+
+  /**
+   * Output data as JSON.
+   */
+  output(data, argv) {
+    if (argv.raw) {
+      this.log(JSON.stringify(data));
+    } else {
+      this.log(JSON.stringify(data, null, 2));
+    }
+  }
+}
+
+module.exports = AuthCommand;

package/src/cli/commands/firebase-init.js

@@ -0,0 +1,121 @@
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const JSON5 = require('json5');
+const { DEFAULT_EMULATOR_PORTS } = require('./setup-tests/emulator-config');
+
+/**
+ * Initialize firebase-admin for CLI commands.
+ *
+ * @param {object} options
+ * @param {string} options.firebaseProjectPath - Project root (from main.firebaseProjectPath)
+ * @param {boolean} options.emulator - Whether to target the local emulator
+ * @returns {{ admin: object, projectId: string }}
+ */
+function initFirebase({ firebaseProjectPath, emulator }) {
+  const functionsDir = path.join(firebaseProjectPath, 'functions');
+
+  // Load .env so env vars like GCLOUD_PROJECT are available
+  const envPath = path.join(functionsDir, '.env');
+  if (jetpack.exists(envPath)) {
+    require('dotenv').config({ path: envPath });
+  }
+
+  // Resolve firebase-admin from the consumer project's node_modules (peer dep)
+  const admin = require(path.join(functionsDir, 'node_modules', 'firebase-admin'));
+
+  // Already initialized
+  if (admin.apps.length > 0) {
+    const projectId = admin.apps[0].options.projectId || 'unknown';
+    return { admin, projectId };
+  }
+
+  if (emulator) {
+    // Load emulator ports from firebase.json
+    const emulatorPorts = loadEmulatorPorts(firebaseProjectPath);
+
+    // Set emulator env vars so firebase-admin connects to emulator
+    process.env.FIRESTORE_EMULATOR_HOST = process.env.FIRESTORE_EMULATOR_HOST
+      || `127.0.0.1:${emulatorPorts.firestore}`;
+    process.env.FIREBASE_AUTH_EMULATOR_HOST = process.env.FIREBASE_AUTH_EMULATOR_HOST
+      || `127.0.0.1:${emulatorPorts.auth}`;
+
+    const projectId = resolveProjectId(firebaseProjectPath, functionsDir);
+
+    admin.initializeApp({ projectId });
+
+    return { admin, projectId };
+  }
+
+  // Production: use service-account.json
+  const serviceAccountPath = path.join(functionsDir, 'service-account.json');
+  if (!jetpack.exists(serviceAccountPath)) {
+    throw new Error(
+      `Missing service-account.json at ${serviceAccountPath}\n`
+      + `  Download it from Firebase Console > Project Settings > Service Accounts`,
+    );
+  }
+
+  const serviceAccount = JSON.parse(jetpack.read(serviceAccountPath));
+  const projectId = serviceAccount.project_id;
+
+  admin.initializeApp({
+    credential: admin.credential.cert(serviceAccount),
+    databaseURL: `https://${projectId}.firebaseio.com`,
+  });
+
+  return { admin, projectId };
+}
+
+function loadEmulatorPorts(projectDir) {
+  const emulatorPorts = { ...DEFAULT_EMULATOR_PORTS };
+  const firebaseJsonPath = path.join(projectDir, 'firebase.json');
+
+  if (jetpack.exists(firebaseJsonPath)) {
+    try {
+      const firebaseConfig = JSON5.parse(jetpack.read(firebaseJsonPath));
+
+      if (firebaseConfig.emulators) {
+        for (const name of Object.keys(DEFAULT_EMULATOR_PORTS)) {
+          emulatorPorts[name] = firebaseConfig.emulators[name]?.port || DEFAULT_EMULATOR_PORTS[name];
+        }
+      }
+    } catch (e) {
+      // Use defaults
+    }
+  }
+
+  return emulatorPorts;
+}
+
+function resolveProjectId(projectDir, functionsDir) {
+  // Try backend-manager-config.json
+  const configPath = path.join(functionsDir, 'backend-manager-config.json');
+  if (jetpack.exists(configPath)) {
+    try {
+      const config = JSON5.parse(jetpack.read(configPath));
+      if (config.firebaseConfig?.projectId) {
+        return config.firebaseConfig.projectId;
+      }
+    } catch (e) {
+      // Fall through
+    }
+  }
+
+  // Try .firebaserc
+  const rcPath = path.join(projectDir, '.firebaserc');
+  if (jetpack.exists(rcPath)) {
+    try {
+      const rc = JSON.parse(jetpack.read(rcPath));
+      if (rc.projects?.default) {
+        return rc.projects.default;
+      }
+    } catch (e) {
+      // Fall through
+    }
+  }
+
+  // Fallback to env
+  return process.env.GCLOUD_PROJECT || 'demo-project';
+}
+
+module.exports = { initFirebase };