@omega.js/manager 0.1.0

package/dist/services/cloud/ensure/authentication.js

@@ -0,0 +1,267 @@
+/**
+ * Ensure Firebase Authentication is configured: Identity Platform enabled,
+ * email/password sign-in, email-enumeration privacy, anonymous-user
+ * auto-delete, the password policy, authorized domains — all diffed via the
+ * Identity Toolkit API — plus Google sign-in.
+ *
+ * Google sign-in's OAuth client CANNOT be created programmatically (no Google
+ * API exists); omega-manager opened a browser and polled. Not-enabled prints
+ * the console instructions and warns — reruns converge once it's enabled
+ * (the API verifies). The OAuth client's redirect URIs have no API either:
+ * instructions + an interactive confirm. A confirmation nothing can re-check
+ * is the one kind of reconcile flag config keeps (#434): it lands at
+ * `cloud.oauthRedirectsConfigured`. Non-interactive runs warn.
+ *
+ * OAuth client credentials land in the brand's gitignored
+ * .omega/secrets/google-oauth.json (never in omega.json5).
+ */
+const { join } = require('node:path');
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+const { confirm, pressEnterToOpen } = require('../../../vendor/devkit/prompt.js');
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+const { canPrompt, dryRunPlan } = require('../../../lib/run-gates.js');
+
+const OAUTH_REDIRECTS_PATH = 'cloud.oauthRedirectsConfigured';
+
+module.exports = async function ensureAuthentication(context) {
+  const { firebaseApi: api, brandConfig, brandRoot, projectId, domain, options = {} } = context;
+
+  // What warned, by name (#643) — the run summary prints these as the
+  // operation's reason
+  const warnings = [];
+  let needsInteractive = null; // #32: set when a step steps aside for lack of a TTY
+
+  // === Identity Platform (upgrade only when the config GET says it's absent) ===
+  let config = await api.getIdentityConfig(projectId);
+
+  if (!config) {
+    if (options.dryRun) {
+      return dryRunPlan('enable Identity Platform', { output: { authentication: { planned: 'initialize' } } });
+    }
+
+    try {
+      await api.initializeIdentityPlatform(projectId);
+      console.log(`      ${chalk.green('✓')} Identity Platform enabled`);
+    } catch (error) {
+      if (!/409|ALREADY_EXISTS|already/.test(error.message || '')) {
+        console.log(`      ${chalk.yellow('⚠')} Could not enable Identity Platform${chalk.dim(`: ${error.message}`)}`);
+      }
+    }
+
+    config = await api.getIdentityConfig(projectId);
+    if (!config) {
+      console.log(`      ${chalk.yellow('⚠')} Could not get Identity Platform config`);
+      console.log(`      ${chalk.dim('→')} Enable Identity Platform in the Firebase Console, then rerun`);
+      return { status: 'warned', reason: 'no Identity Platform config — enable it in the Firebase Console', output: { authentication: { error: 'no identity config' } } };
+    }
+  } else {
+    console.log(`      ${chalk.green('✓')} Identity Platform enabled`);
+  }
+
+  const enabled = [];
+
+  // Helper: diff-gated PATCH of one identity-config slice
+  const patchConfig = async (label, needsUpdate, payload) => {
+    if (!needsUpdate) {
+      console.log(`      ${chalk.green('✓')} ${label} already configured`);
+      return;
+    }
+    if (options.dryRun) {
+      return dryRunPlan(`configure ${label}`);
+    }
+    try {
+      await api.updateIdentityConfig(projectId, payload);
+      console.log(`      ${chalk.green('✓')} ${label} configured`);
+    } catch (error) {
+      console.log(`      ${chalk.yellow('⚠')} Could not configure ${label}${chalk.dim(`: ${error.message}`)}`);
+    }
+  };
+
+  // === Email/password sign-in ===
+  const signInConfig = config.signIn || {};
+  await patchConfig('Email/password sign-in', !signInConfig.email?.enabled, {
+    signIn: {
+      ...signInConfig,
+      email: { enabled: true, passwordRequired: true },
+    },
+  });
+  enabled.push('email');
+
+  // === Email privacy (prevents email-enumeration attacks) ===
+  await patchConfig('Email privacy', !config.emailPrivacyConfig?.enableImprovedEmailPrivacy, {
+    emailPrivacyConfig: { enableImprovedEmailPrivacy: true },
+  });
+
+  // === Auto-delete anonymous users (30 days) ===
+  await patchConfig('Anonymous-user auto-delete', !config.autodeleteAnonymousUsers, {
+    autodeleteAnonymousUsers: true,
+  });
+
+  // === Password policy (8–128 chars, enforced) ===
+  const currentPolicy = config.passwordPolicyConfig || {};
+  const currentConstraints = currentPolicy.passwordPolicyVersions?.[0]?.customStrengthOptions || {};
+  const policyDrifted = currentPolicy.passwordPolicyEnforcementState !== 'ENFORCE'
+    || currentPolicy.forceUpgradeOnSignin !== false
+    || currentConstraints.minPasswordLength !== 8
+    || currentConstraints.maxPasswordLength !== 128;
+  await patchConfig('Password policy', policyDrifted, {
+    passwordPolicyConfig: {
+      passwordPolicyEnforcementState: 'ENFORCE',
+      forceUpgradeOnSignin: false,
+      passwordPolicyVersions: [{
+        customStrengthOptions: {
+          minPasswordLength: 8,
+          maxPasswordLength: 128,
+        },
+      }],
+    },
+  });
+
+  // === Google sign-in ===
+  const googleConfig = await api.getIdpConfig(projectId, 'google.com');
+  const firebaseAuthUrl = `https://console.firebase.google.com/project/${projectId}/authentication/providers`;
+  let googleClientId = null;
+
+  // OAuth client IDs start with the project number — a mismatch means the
+  // wrong project's credentials got attached
+  let projectNumber = null;
+  try {
+    projectNumber = await api.getProjectNumber(projectId);
+  } catch {
+    // Validation is best-effort without it
+  }
+
+  if (googleConfig?.enabled && googleConfig.clientId && googleConfig.clientSecret) {
+    const clientProjectNumber = googleConfig.clientId.split('-')[0];
+
+    if (projectNumber && clientProjectNumber !== projectNumber) {
+      console.log(`      ${chalk.yellow('⚠')} Google sign-in has the WRONG OAuth client (project ${clientProjectNumber}, expected ${projectNumber})`);
+      console.log(`      ${chalk.dim('→')} Delete Google sign-in in the Firebase Console and re-enable it: ${chalk.cyan(firebaseAuthUrl)}`);
+      warnings.push('Google sign-in has the wrong OAuth client');
+    } else {
+      console.log(`      ${chalk.green('✓')} Google sign-in enabled`);
+      enabled.push('google');
+      googleClientId = googleConfig.clientId;
+
+      // Secrets belong in the gitignored secrets dir, never state/omega.json5.
+      // Read-compare first (#590's idiom, #623): the console's credentials
+      // barely ever move, and a manage run that rewrites an identical secret
+      // file on every pass churns the mtime every watcher and backup sees.
+      const secretsPath = join(brandRoot, '.omega', 'secrets', 'google-oauth.json');
+      const secrets = {
+        clientId: googleConfig.clientId,
+        clientSecret: googleConfig.clientSecret,
+      };
+      // A truncated write to this machine-owned file is an expected external
+      // condition: treat unparseable as absent so the next run self-heals.
+      let stored;
+      try {
+        stored = jetpack.read(secretsPath, 'json');
+      } catch {
+        stored = undefined;
+      }
+      const drifted = stored?.clientId !== secrets.clientId || stored?.clientSecret !== secrets.clientSecret;
+
+      if (drifted && !options.dryRun) {
+        jetpack.write(secretsPath, secrets);
+      }
+    }
+  } else if (googleConfig?.enabled) {
+    console.log(`      ${chalk.yellow('⚠')} Google sign-in enabled but OAuth credentials missing (corrupted config)`);
+    console.log(`      ${chalk.dim('→')} Delete Google sign-in and re-enable it: ${chalk.cyan(firebaseAuthUrl)}`);
+    warnings.push('Google sign-in is missing its OAuth credentials');
+  } else {
+    // No API to create the OAuth client — manual enable in the console
+    console.log(`      ${chalk.yellow('⚠')} Google sign-in not enabled — requires one-time manual setup`);
+    console.log(`      ${chalk.dim('→')} Enable "Google", pick a support email, Save — then rerun`);
+    if (canPrompt(options)) {
+      await pressEnterToOpen(firebaseAuthUrl, 'the sign-in providers page');
+    } else {
+      console.log(`      ${chalk.dim('→')} ${chalk.cyan(firebaseAuthUrl)}`);
+    }
+    warnings.push('Google sign-in not enabled — one-time manual setup');
+  }
+
+  // === OAuth client redirect URIs (no API — instructions + confirm until done) ===
+  let oauthRedirectsConfigured = brandConfig.cloud?.oauthRedirectsConfigured === true;
+  if (googleClientId && !oauthRedirectsConfigured) {
+    const gcpCredentialsUrl = `https://console.cloud.google.com/apis/credentials/oauthclient/${googleClientId}?project=${projectId}`;
+    const authorizedOrigins = [
+      'https://localhost',
+      'https://localhost:5000',
+      `https://${projectId}.firebaseapp.com`,
+      `https://${domain}`,
+    ];
+    const redirectUris = [
+      `https://${projectId}.firebaseapp.com/__/auth/handler`,
+      'https://localhost:5000/__/auth/handler',
+      `https://${domain}/__/auth/handler`,
+    ];
+    console.log(`      ${chalk.yellow('⚠')} OAuth client redirect URIs need one-time manual configuration`);
+    console.log(`      ${chalk.dim('→')} Authorized origins:`);
+    for (const origin of authorizedOrigins) {
+      console.log(`        ${chalk.cyan(origin)}`);
+    }
+    console.log(`      ${chalk.dim('→')} Redirect URIs:`);
+    for (const uri of redirectUris) {
+      console.log(`        ${chalk.cyan(uri)}`);
+    }
+
+    if (canPrompt(options)) {
+      await pressEnterToOpen(gcpCredentialsUrl, 'the OAuth client settings');
+      const done = await confirm({ message: 'Origins + redirect URIs configured in the OAuth client?', default: false });
+      if (done) {
+        oauthRedirectsConfigured = true;
+        writeBrandConfig(context, { [OAUTH_REDIRECTS_PATH]: true });
+        console.log(`      ${chalk.green('✓')} OAuth client redirect URIs confirmed`);
+      } else {
+        warnings.push('OAuth client redirect URIs not confirmed');
+      }
+    } else {
+      console.log(`      ${chalk.dim('→')} ${chalk.cyan(gcpCredentialsUrl)}`);
+      console.log(`      ${chalk.dim('→')} (rerun in an interactive terminal to confirm)`);
+      needsInteractive = 'confirm the OAuth client origins + redirect URIs (the run opens the console for you)';
+      warnings.push('OAuth client redirect URIs not confirmed');
+    }
+  } else if (googleClientId) {
+    console.log(`      ${chalk.green('✓')} OAuth client redirect URIs configured`);
+  }
+
+  // === Authorized domains ===
+  const authorizedDomains = config.authorizedDomains || [];
+  const domainsToAdd = [
+    domain,
+    `${projectId}.firebaseapp.com`,
+    `${projectId}.web.app`,
+    'localhost',
+  ].filter((d) => !authorizedDomains.includes(d));
+
+  if (domainsToAdd.length === 0) {
+    console.log(`      ${chalk.green('✓')} Authorized domains configured`);
+  } else if (options.dryRun) {
+    dryRunPlan(`add ${domainsToAdd.length} authorized domain(s)`);
+  } else {
+    try {
+      await api.updateIdentityConfig(projectId, {
+        authorizedDomains: [...authorizedDomains, ...domainsToAdd],
+      });
+      console.log(`      ${chalk.green('✓')} Added ${chalk.bold(domainsToAdd.length)} authorized domain(s)`);
+    } catch (error) {
+      console.log(`      ${chalk.yellow('⚠')} Could not update authorized domains${chalk.dim(`: ${error.message}`)}`);
+    }
+  }
+
+  return {
+    status: warnings.length > 0 ? 'warned' : 'success',
+    ...(warnings.length > 0 ? { reason: warnings.join('; ') } : {}),
+    output: {
+      authentication: {
+        enabled,
+        authorizedDomains: [domain, `${projectId}.firebaseapp.com`, `${projectId}.web.app`],
+        oauthRedirectsConfigured,
+        ...(needsInteractive ? { needsInteractive } : {}),
+      },
+    },
+  };
+};

package/dist/services/cloud/ensure/billing.js

@@ -0,0 +1,120 @@
+/**
+ * Ensure the project is on the Blaze plan.
+ *
+ * omega-manager silently linked a hardcoded company billing account; the
+ * account is tri-state config now (#33) — `cloud.billingAccount` set →
+ * link it, `false` → the user chose Spark (silent, no nagging), missing →
+ * ask in an interactive run (pick from the accounts the authed user can
+ * see, or create one in the console; the answer lands in omega.json5) and
+ * warn with guidance otherwise.
+ */
+const chalk = require('chalk').default;
+const { resolveConfigValue } = require('../../../lib/config-flow.js');
+const { dryRunPlan, needsInteractiveSkip } = require('../../../lib/run-gates.js');
+
+/** Interactive pick/create/opt-out flow — the answer lands in omega.json5. */
+function resolveBillingAccount(context, api) {
+  return resolveConfigValue(context, {
+    path: 'cloud.billingAccount',
+    label: 'Billing account',
+    instructions: [
+      'Blaze (pay-as-you-go) unlocks functions deploys and outbound network.',
+      'The account you pick links to this brand\'s projects from now on.',
+    ],
+    choices: () => api.listBillingAccounts(),
+    getName: (account) => `${account.displayName} (${account.name.replace('billingAccounts/', '')})${account.open === false ? ' [closed]' : ''}`,
+    getValue: (account) => account.name,
+    createNew: {
+      label: 'billing account',
+      url: 'https://console.cloud.google.com/billing/create',
+      refreshChoices: true,
+    },
+    optOut: { label: 'Stay on the Spark plan (free) — don\'t ask again' },
+  });
+}
+
+module.exports = async function ensureBilling(context) {
+  const { firebaseApi: api, brandConfig, projectId, options = {} } = context;
+
+  // === READ ===
+  const billingInfo = await api.getProjectBillingInfo(projectId);
+
+  if (billingInfo?.billingEnabled) {
+    console.log(`      ${chalk.green('✓')} Blaze plan enabled`);
+    return {
+      state: {
+        billing: {
+          enabled: true,
+          billingAccountName: billingInfo.billingAccountName,
+        },
+      },
+    };
+  }
+
+  // A failed READ is not a Spark verdict (#56): getProjectBillingInfo() turns
+  // every failure (auth timeout, permission denied, disabled API) into null,
+  // and a live run announced "on the Spark plan" right after its auth attempt
+  // timed out. "Could not check" and "checked: Spark" are separate outputs.
+  if (!billingInfo) {
+    console.log(`      ${chalk.yellow('⚠')} Could not check the billing plan ${chalk.dim('(the billing API read failed: unauthenticated, no permission, or the API is off)')}`);
+    console.log(`      ${chalk.dim('→')} Rerun once Google auth succeeds: ${chalk.cyan(`https://console.firebase.google.com/project/${projectId}/usage/details`)}`);
+    return {
+      status: 'warned',
+      reason: 'could not check the billing plan',
+      output: { billing: { error: 'billing plan unknown: could not check (the billing API read failed)' } },
+    };
+  }
+
+  // Tri-state (#33): false = the user chose Spark — a clean state, not a warning
+  if (brandConfig.cloud?.billingAccount === false) {
+    console.log(`      ${chalk.dim('⊘ Billing opted out (cloud.billingAccount: false) — staying on the Spark plan')}`);
+    return { output: { billing: { note: 'billing opted out — Spark plan' } } };
+  }
+
+  console.log(`      ${chalk.yellow('⚠')} Project is on the Spark plan (free tier)`);
+
+  const billingAccountName = brandConfig.cloud?.billingAccount
+    || await resolveBillingAccount(context, api);
+
+  // The flow may have just landed the opt-out
+  if (brandConfig.cloud?.billingAccount === false) {
+    return { output: { billing: { note: 'billing opted out — Spark plan' } } };
+  }
+
+  if (!billingAccountName) {
+    console.log(`      ${chalk.dim('→')} Set cloud.billingAccount ("billingAccounts/XXXXXX-XXXXXX-XXXXXX") in company/brand config to auto-upgrade`);
+    console.log(`      ${chalk.dim('→')} Or upgrade manually: ${chalk.cyan(`https://console.firebase.google.com/project/${projectId}/usage/details`)}`);
+    return needsInteractiveSkip(
+      'billing',
+      'pick or create a billing account (the answer lands in omega.json5)',
+      'no cloud.billingAccount configured',
+    );
+  }
+
+  // === WRITE ===
+  if (options.dryRun) {
+    return dryRunPlan(`link ${billingAccountName} (Blaze plan)`, { output: { billing: { planned: 'link' } } });
+  }
+
+  console.log(`      ${chalk.yellow('⏳')} Upgrading to Blaze plan...`);
+  try {
+    await api.linkBillingAccount(projectId, billingAccountName);
+    console.log(`      ${chalk.green('✓')} Upgraded to Blaze plan`);
+    return {
+      state: {
+        billing: {
+          enabled: true,
+          billingAccountName,
+        },
+      },
+    };
+  } catch (error) {
+    console.log(`      ${chalk.yellow('⚠')} Could not upgrade${chalk.dim(`: ${error.message}`)}`);
+    return {
+      status: 'warned',
+      reason: 'could not upgrade the billing plan',
+      state: { billing: { enabled: false } },
+      output: { billing: { error: error.message } },
+    };
+  }
+};

package/dist/services/cloud/ensure/cloud-messaging.js

@@ -0,0 +1,105 @@
+/**
+ * Ensure Firebase Cloud Messaging is ready: the FCM API is enabled and a
+ * VAPID key pair (web push) is on hand.
+ *
+ * There is no public API for Web Push certificates — missing keys print the
+ * console URL and, in an interactive terminal, prompt to paste both back
+ * (length-validated; omega-manager's auto-open of the console is dropped —
+ * the URL is printed and clickable). Non-interactive runs warn and move on.
+ *
+ * The halves go to their own homes (#434): the PUBLIC key to
+ * `cloud.messaging.vapidKey` in omega.json5 (it ships to every browser — the
+ * client reads it from there), the PRIVATE key to VAPID_PRIVATE_KEY in the
+ * gitignored brand .env.
+ */
+const chalk = require('chalk').default;
+const { input, pressEnterToOpen } = require('../../../vendor/devkit/prompt.js');
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+const { writeEnvValue } = require('../../../lib/env-secret.js');
+const { canPrompt, dryRunPlan, needsInteractiveSkip } = require('../../../lib/run-gates.js');
+
+const VAPID_PUBLIC_PATH = 'cloud.messaging.vapidKey';
+const VAPID_PRIVATE_ENV = 'VAPID_PRIVATE_KEY';
+
+module.exports = async function ensureCloudMessaging(context) {
+  const { firebaseApi: api, brandConfig, brandRoot, projectId, options = {} } = context;
+
+  // === FCM API ===
+  const fcmEnabled = await api.isServiceEnabled(projectId, 'fcm.googleapis.com');
+
+  if (fcmEnabled) {
+    console.log(`      ${chalk.green('✓')} FCM API enabled`);
+  } else if (options.dryRun) {
+    dryRunPlan('enable the FCM API');
+  } else {
+    console.log('      Enabling FCM API...');
+    try {
+      await api.enableService(projectId, 'fcm.googleapis.com');
+      console.log(`      ${chalk.green('✓')} FCM API enabled`);
+    } catch (error) {
+      console.log(`      ${chalk.yellow('⚠')} Failed to enable FCM API${chalk.dim(`: ${error.message}`)}`);
+      return { status: 'warned', reason: 'failed to enable the FCM API', output: { cloudMessaging: { error: error.message } } };
+    }
+  }
+
+  // === VAPID key pair (config + .env — no API to create or read them) ===
+  const existingPublicKey = brandConfig.cloud?.messaging?.vapidKey;
+
+  if (existingPublicKey && process.env[VAPID_PRIVATE_ENV]) {
+    console.log(`      ${chalk.green('✓')} VAPID key pair exists ${chalk.dim(`(${existingPublicKey.substring(0, 20)}...)`)}`);
+    return {};
+  }
+
+  const consoleUrl = `https://console.firebase.google.com/project/${projectId}/settings/cloudmessaging`;
+  console.log(`      ${chalk.yellow('⚠')} No VAPID key pair — web push won't work without one`);
+  console.log(`      ${chalk.dim('→')} Under "Web Push certificates": generate (or reveal via ⋮) the key pair`);
+
+  if (!canPrompt(options)) {
+    console.log(`      ${chalk.dim('→')} ${chalk.cyan(consoleUrl)}`);
+    console.log(`      ${chalk.dim('→')} Rerun in an interactive terminal to paste both keys; the public half lands in omega.json5 (${chalk.cyan(VAPID_PUBLIC_PATH)}), the private half in the brand .env (${chalk.cyan(VAPID_PRIVATE_ENV)})`);
+    return needsInteractiveSkip(
+      'cloudMessaging',
+      'paste the VAPID key pair from the Cloud Messaging settings',
+      'no VAPID key pair (needs an interactive run)',
+    );
+  }
+
+  await pressEnterToOpen(consoleUrl, 'the Cloud Messaging settings');
+
+  const vapidPublicKey = await input({
+    message: '    VAPID public key:',
+    validate: (value) => {
+      if (!value?.trim()) {
+        return 'Required — copy the Key pair value from the Firebase Console';
+      }
+      if (value.trim().length !== 87) {
+        return `VAPID public key must be exactly 87 characters (got ${value.trim().length})`;
+      }
+      return true;
+    },
+  });
+
+  const vapidPrivateKey = await input({
+    message: '    VAPID private key:',
+    validate: (value) => {
+      if (!value?.trim()) {
+        return 'Required — click the ⋮ menu next to the key pair to reveal it';
+      }
+      if (value.trim() === vapidPublicKey.trim()) {
+        return 'That\'s the public key again — click ⋮ to reveal the private key (shorter, 43 chars)';
+      }
+      if (value.trim().length !== 43) {
+        return `VAPID private key must be exactly 43 characters (got ${value.trim().length})`;
+      }
+      return true;
+    },
+  });
+
+  writeBrandConfig(context, { [VAPID_PUBLIC_PATH]: vapidPublicKey.trim() });
+  writeEnvValue(brandRoot, VAPID_PRIVATE_ENV, vapidPrivateKey.trim());
+  process.env[VAPID_PRIVATE_ENV] = vapidPrivateKey.trim();
+
+  console.log(`      ${chalk.green('✓')} VAPID key pair saved ${chalk.dim(`(${VAPID_PUBLIC_PATH} + .env ${VAPID_PRIVATE_ENV})`)}`);
+
+  return {};
+};

package/dist/services/cloud/ensure/database.js

@@ -0,0 +1,60 @@
+/**
+ * Ensure the Realtime Database default instance exists
+ * ({projectId}-default-rtdb in us-central1).
+ */
+const chalk = require('chalk').default;
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+module.exports = async function ensureDatabase(context) {
+  const { firebaseApi: api, projectId, options = {} } = context;
+
+  // === READ ===
+  const existing = await api.listRealtimeDatabases(projectId);
+
+  if (existing.length > 0) {
+    const db = existing[0];
+    console.log(`      ${chalk.green('✓')} Realtime Database exists`);
+    return {
+      state: {
+        database: {
+          databaseURL: db.databaseUrl,
+          name: db.name,
+        },
+      },
+    };
+  }
+
+  // === WRITE ===
+  if (options.dryRun) {
+    return dryRunPlan('create the Realtime Database', { output: { database: { planned: 'create' } } });
+  }
+
+  console.log('      Creating Realtime Database...');
+  try {
+    const result = await api.createRealtimeDatabase(projectId, 'us-central1');
+    console.log(`      ${chalk.green('✓')} Created Realtime Database`);
+
+    return {
+      state: {
+        database: {
+          databaseURL: result.databaseUrl || `https://${projectId}-default-rtdb.firebaseio.com`,
+          name: result.name,
+        },
+      },
+    };
+  } catch (error) {
+    if (error.message?.includes('already exists')) {
+      console.log(`      ${chalk.green('✓')} Realtime Database exists`);
+      return {
+        state: {
+          database: {
+            databaseURL: `https://${projectId}-default-rtdb.firebaseio.com`,
+          },
+        },
+      };
+    }
+
+    console.log(`      ${chalk.yellow('⚠')} Could not create database${chalk.dim(`: ${error.message}`)}`);
+    return { status: 'warned', reason: 'could not create the Realtime Database', output: { database: { error: error.message } } };
+  }
+};

package/dist/services/cloud/ensure/firestore.js

@@ -0,0 +1,79 @@
+/**
+ * Ensure the Firestore database exists (nam5 US multi-region) with
+ * Point-in-Time Recovery enabled (7-day disaster recovery).
+ */
+const chalk = require('chalk').default;
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+module.exports = async function ensureFirestore(context) {
+  const { firebaseApi: api, projectId, options = {} } = context;
+
+  // === READ ===
+  const existing = await api.getFirestoreDatabase(projectId);
+
+  if (existing) {
+    console.log(`      ${chalk.green('✓')} Firestore database exists`);
+    await ensurePITR(api, projectId, existing, options);
+
+    return {
+      state: {
+        firestore: {
+          databaseId: '(default)',
+          locationId: existing.locationId,
+          pitrEnabled: true,
+        },
+      },
+    };
+  }
+
+  // === WRITE ===
+  if (options.dryRun) {
+    return dryRunPlan('create Firestore database (nam5) + enable PITR', { output: { firestore: { planned: 'create' } } });
+  }
+
+  console.log('      Creating Firestore database...');
+  try {
+    const result = await api.createFirestoreDatabase(projectId, 'nam5');
+    console.log(`      ${chalk.green('✓')} Created Firestore database`);
+
+    await ensurePITR(api, projectId, result, options);
+
+    return {
+      state: {
+        firestore: {
+          databaseId: '(default)',
+          locationId: result?.locationId || 'nam5',
+          pitrEnabled: true,
+        },
+      },
+    };
+  } catch (error) {
+    if (error.message?.includes('already exists')) {
+      console.log(`      ${chalk.green('✓')} Firestore database exists`);
+      await ensurePITR(api, projectId, null, options);
+      return { state: { firestore: { databaseId: '(default)', pitrEnabled: true } } };
+    }
+
+    console.log(`      ${chalk.yellow('⚠')} Could not create Firestore${chalk.dim(`: ${error.message}`)}`);
+    return { status: 'warned', reason: 'could not create the Firestore database', output: { firestore: { error: error.message } } };
+  }
+};
+
+async function ensurePITR(api, projectId, database, options) {
+  if (database?.pointInTimeRecoveryEnablement === 'POINT_IN_TIME_RECOVERY_ENABLED') {
+    console.log(`      ${chalk.green('✓')} PITR enabled (7-day recovery)`);
+    return;
+  }
+
+  if (options.dryRun) {
+    return dryRunPlan('enable PITR');
+  }
+
+  console.log('      Enabling PITR (Point-in-Time Recovery)...');
+  try {
+    await api.enableFirestorePITR(projectId);
+    console.log(`      ${chalk.green('✓')} PITR enabled (7-day recovery)`);
+  } catch (error) {
+    console.log(`      ${chalk.yellow('⚠')} Could not enable PITR${chalk.dim(`: ${error.message}`)}`);
+  }
+}

package/dist/services/cloud/ensure/functions.js

@@ -0,0 +1,49 @@
+/**
+ * Verify Cloud Functions prerequisites are ready (the services operation
+ * enables them; this is a read-only readiness check).
+ */
+const chalk = require('chalk').default;
+
+const REQUIRED_SERVICES = [
+  'cloudfunctions.googleapis.com',
+  'cloudbuild.googleapis.com',
+  'run.googleapis.com',
+];
+
+module.exports = async function ensureFunctions(context) {
+  const { firebaseApi: api, projectId } = context;
+
+  let allEnabled = true;
+  const status = {};
+
+  for (const service of REQUIRED_SERVICES) {
+    try {
+      const enabled = await api.isServiceEnabled(projectId, service);
+      status[service.replace('.googleapis.com', '')] = enabled;
+
+      if (!enabled) {
+        allEnabled = false;
+      }
+    } catch {
+      allEnabled = false;
+    }
+  }
+
+  if (allEnabled) {
+    console.log(`      ${chalk.green('✓')} Cloud Functions ready`);
+  } else {
+    console.log(`      ${chalk.yellow('⚠')} Some Cloud Functions APIs not enabled`);
+    console.log(`      ${chalk.dim('→')} The services operation enables them — rerun`);
+  }
+
+  return {
+    status: allEnabled ? 'success' : 'warned',
+    ...(allEnabled ? {} : { reason: 'some Cloud Functions APIs are not enabled' }),
+    state: {
+      functions: {
+        ready: allEnabled,
+        services: status,
+      },
+    },
+  };
+};