@omega.js/manager 0.1.0

package/dist/services/cloud/ensure/project-settings.js

@@ -0,0 +1,72 @@
+/**
+ * Ensure project identity: the GCP display name matches the brand and a web
+ * app named 'Web App' exists.
+ *
+ * omega-manager PATCHed the project name on every run; this diffs first —
+ * a converged project is a zero-mutation no-op.
+ */
+const chalk = require('chalk').default;
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+const WEB_APP_NAME = 'Web App';
+
+module.exports = async function ensureProjectSettings(context) {
+  const { firebaseApi: api, brandConfig, projectId, options = {} } = context;
+  const brandName = brandConfig.brand?.name;
+
+  const updates = {};
+
+  // === Project display name ===
+  const gcpProject = await api.getGcpProject(projectId);
+
+  if (gcpProject?.displayName === brandName) {
+    console.log(`      ${chalk.green('✓')} Project name: ${chalk.cyan(brandName)}`);
+    updates.projectName = brandName;
+  } else if (options.dryRun) {
+    dryRunPlan(`rename project ${gcpProject?.displayName || '(unknown)'} → ${brandName}`);
+  } else {
+    try {
+      await api.updateProjectName(projectId, brandName);
+      console.log(`      ${chalk.green('✓')} Project name set to ${chalk.cyan(brandName)}`);
+      updates.projectName = brandName;
+    } catch (error) {
+      console.log(`      ${chalk.yellow('⚠')} Could not update project name${chalk.dim(`: ${error.message}`)}`);
+    }
+  }
+
+  // === Web app ===
+  try {
+    const apps = await api.listWebApps(projectId);
+
+    if (apps.length === 0) {
+      if (options.dryRun) {
+        dryRunPlan(`create web app "${WEB_APP_NAME}"`);
+      } else {
+        console.log('      Creating web app...');
+        await api.createWebApp(projectId, WEB_APP_NAME);
+        console.log(`      ${chalk.green('✓')} Created web app: ${chalk.cyan(WEB_APP_NAME)}`);
+        updates.webAppName = WEB_APP_NAME;
+      }
+    } else if (apps[0].displayName !== WEB_APP_NAME) {
+      if (options.dryRun) {
+        dryRunPlan(`rename web app ${apps[0].displayName} → ${WEB_APP_NAME}`);
+      } else {
+        try {
+          await api.updateWebAppDisplayName(projectId, apps[0].appId, WEB_APP_NAME);
+          console.log(`      ${chalk.green('✓')} Renamed web app: ${chalk.cyan(apps[0].displayName)} → ${chalk.cyan(WEB_APP_NAME)}`);
+          updates.webAppName = WEB_APP_NAME;
+        } catch (error) {
+          console.log(`      ${chalk.yellow('⚠')} Could not rename web app${chalk.dim(`: ${error.message}`)}`);
+          updates.webAppName = apps[0].displayName;
+        }
+      }
+    } else {
+      console.log(`      ${chalk.green('✓')} Web app: ${chalk.cyan(WEB_APP_NAME)}`);
+      updates.webAppName = WEB_APP_NAME;
+    }
+  } catch (error) {
+    console.log(`      ${chalk.yellow('⚠')} Could not configure web app${chalk.dim(`: ${error.message}`)}`);
+  }
+
+  return { state: { settings: updates } };
+};

package/dist/services/cloud/ensure/sdk-config.js

@@ -0,0 +1,95 @@
+/**
+ * Ensure the web SDK config is fetched into state — and that the brand's
+ * omega.json5 `cloud.config` section matches it.
+ *
+ * authDomain is the BRAND host (Ian's ruling 2026-07-23): a first-party
+ * authDomain keeps signInWithRedirect working under browser storage
+ * partitioning, and the site self-hosts Firebase's /__/auth/* helper files
+ * at build time (`omega build` fetches them from
+ * {projectId}.firebaseapp.com), so the handler no longer 404s on site
+ * domains (the 2026-07-19 live find). The API base derives from brand.url,
+ * never authDomain.
+ * omega.json5 is the fetched config's ONE home: drift against it is written
+ * back into the file key-by-key (comment-preserving), so per-key comments
+ * survive. Dry-run prints the paste-able block instead and warns.
+ */
+const chalk = require('chalk').default;
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+// The canonical cloud.config keys frameworks read from omega.json5
+const SDK_KEYS = ['apiKey', 'authDomain', 'databaseURL', 'projectId', 'storageBucket', 'messagingSenderId', 'appId', 'measurementId'];
+
+module.exports = async function ensureSdkConfig(context) {
+  const { firebaseApi: api, brandConfig, projectId, domain, options = {} } = context;
+
+  // === READ (web app must exist; project-settings creates it too) ===
+  const apps = await api.listWebApps(projectId);
+  let appId = apps[0]?.appId;
+
+  if (!appId) {
+    if (options.dryRun) {
+      return dryRunPlan('create a web app and fetch its SDK config', { output: { sdkConfig: { planned: 'create-web-app' } } });
+    }
+
+    console.log('      Creating web app...');
+    appId = await api.createWebApp(projectId, 'Web App');
+
+    if (!appId) {
+      console.log(`      ${chalk.yellow('⚠')} Could not get or create a web app`);
+      return { status: 'warned', reason: 'could not get or create a web app', output: { sdkConfig: { error: 'no web app' } } };
+    }
+  }
+
+  const raw = await api.getWebAppConfig(projectId, appId);
+
+  const sdkConfig = {
+    apiKey: raw.apiKey,
+    authDomain: domain || raw.authDomain, // brand host — the build self-hosts /__/auth/* (header comment)
+    databaseURL: raw.databaseURL || `https://${projectId}-default-rtdb.firebaseio.com`,
+    projectId: raw.projectId,
+    storageBucket: raw.storageBucket,
+    messagingSenderId: raw.messagingSenderId,
+    appId: raw.appId,
+    measurementId: raw.measurementId || '',
+  };
+
+  console.log(`      ${chalk.green('✓')} Got SDK config ${chalk.dim(`(apiKey: ${sdkConfig.apiKey.substring(0, 10)}...)`)}`);
+
+  // === Drift check: omega.json5's cloud.config is what the targets run on ===
+  const configured = brandConfig.cloud?.config || {};
+  const drifted = SDK_KEYS.filter((key) => (configured[key] || '') !== (sdkConfig[key] || ''));
+
+  if (drifted.length === 0) {
+    console.log(`      ${chalk.green('✓')} omega.json5 cloud.config matches`);
+    return { state: { sdkConfig } };
+  }
+
+  console.log(`      ${chalk.yellow('↻')} omega.json5 cloud.config ${Object.keys(configured).length === 0 ? 'is missing' : `drifts (${drifted.join(', ')})`}`);
+
+  const edits = {};
+  if (brandConfig.cloud?.provider !== 'firebase') {
+    edits['cloud.provider'] = 'firebase';
+  }
+  for (const key of drifted) {
+    edits[`cloud.config.${key}`] = sdkConfig[key];
+  }
+  writeBrandConfig(context, edits);
+
+  if (options.dryRun) {
+    // The file wasn't touched — hand over the paste block
+    console.log(`      ${chalk.dim('→')} Set this in config/omega.json5:`);
+    console.log(chalk.cyan(`      cloud: { provider: 'firebase', config: ${JSON.stringify(sdkConfig, null, 2).replace(/\n/g, '\n      ')} },`));
+    return {
+      status: 'warned',
+      reason: 'dry run — the SDK config in config/omega.json5 is out of date',
+      state: { sdkConfig },
+      output: { sdkConfig: { drifted } },
+    };
+  }
+
+  return {
+    state: { sdkConfig },
+    output: { sdkConfig: { updated: drifted } },
+  };
+};

package/dist/services/cloud/ensure/service-account.js

@@ -0,0 +1,152 @@
+/**
+ * Ensure the Firebase Admin SDK service account exists with the roles @omega.js/backend
+ * needs, and its key is downloaded.
+ *
+ * Google shows service account keys ONCE at creation — they can't be
+ * re-downloaded. The key's ONE home is the brand's gitignored
+ * .omega/secrets/service-account.json — the backend's stage step (`omega
+ * build`, src/dist pillar) reads it from there and carries it into the
+ * staged dist/ tree; no per-target copy exists anymore.
+ *
+ * The IAM role grant diffs the policy first (omega-manager PUT the policy on
+ * every run) — a converged account is a zero-mutation no-op.
+ */
+const { join } = require('node:path');
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+const REQUIRED_ROLES = [
+  'roles/firebase.admin',
+  'roles/firebaseauth.admin',
+  'roles/datastore.owner',
+  'roles/serviceusage.serviceUsageConsumer',
+];
+
+/**
+ * Grant any missing REQUIRED_ROLES to the account. Reads the policy, diffs,
+ * and only writes when a binding actually changed.
+ */
+async function ensureRoles(api, projectId, serviceAccountEmail, options) {
+  const member = `serviceAccount:${serviceAccountEmail}`;
+  const policy = await api.getIamPolicy(projectId);
+  let changed = false;
+
+  for (const role of REQUIRED_ROLES) {
+    let binding = policy.bindings?.find((b) => b.role === role);
+    if (!binding) {
+      binding = { role, members: [] };
+      policy.bindings = policy.bindings || [];
+      policy.bindings.push(binding);
+    }
+    if (!binding.members.includes(member)) {
+      binding.members.push(member);
+      changed = true;
+    }
+  }
+
+  if (!changed) {
+    console.log(`      ${chalk.green('✓')} IAM roles verified`);
+    return;
+  }
+
+  if (options.dryRun) {
+    return dryRunPlan('grant missing IAM roles');
+  }
+
+  await api.setIamPolicy(projectId, policy);
+  console.log(`      ${chalk.green('✓')} Granted IAM roles`);
+}
+
+module.exports = async function ensureServiceAccount(context) {
+  const { firebaseApi: api, brandConfig, brandRoot, projectId, options = {} } = context;
+  const brandName = brandConfig.brand?.name || context.brandId;
+
+  // The key's ONE home — the backend stage step reads it from here
+  const sourceKeyPath = join(brandRoot, '.omega', 'secrets', 'service-account.json');
+
+  // === Key already downloaded — verify roles ===
+  if (jetpack.exists(sourceKeyPath)) {
+    const existingKey = jetpack.read(sourceKeyPath, 'json');
+    const serviceAccountEmail = existingKey?.client_email;
+
+    console.log(`      ${chalk.green('✓')} Service account key exists`);
+
+    try {
+      await ensureRoles(api, projectId, serviceAccountEmail, options);
+    } catch (error) {
+      console.log(`      ${chalk.yellow('⚠')} Could not verify roles${chalk.dim(`: ${error.message}`)}`);
+    }
+
+    return { state: { serviceAccount: { email: serviceAccountEmail } } };
+  }
+
+  // === Find or create the firebase-adminsdk account ===
+  // Firebase Console creates these with random suffixes (firebase-adminsdk-abc12@…)
+  const existingAccounts = await api.listServiceAccounts(projectId);
+  const existing = existingAccounts.find((a) => a.email.startsWith('firebase-adminsdk'));
+  let serviceAccountEmail;
+
+  if (existing) {
+    serviceAccountEmail = existing.email;
+    console.log(`      ${chalk.green('✓')} Service account exists`);
+  } else {
+    serviceAccountEmail = `firebase-adminsdk@${projectId}.iam.gserviceaccount.com`;
+
+    if (options.dryRun) {
+      return dryRunPlan('create service account + key', { output: { serviceAccount: { planned: 'create' } } });
+    }
+
+    console.log('      Creating service account...');
+    try {
+      await api.createServiceAccount(projectId, 'firebase-adminsdk', `Firebase Admin SDK Service Account for ${brandName}`);
+      console.log(`      ${chalk.green('✓')} Created service account`);
+
+      // Eventual consistency — the account isn't immediately grantable
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+    } catch (error) {
+      if (!error.message?.includes('already exists')) {
+        console.log(`      ${chalk.yellow('⚠')} Could not create service account${chalk.dim(`: ${error.message}`)}`);
+        return { status: 'warned', reason: 'could not create the service account', output: { serviceAccount: { error: error.message } } };
+      }
+    }
+  }
+
+  try {
+    await ensureRoles(api, projectId, serviceAccountEmail, options);
+  } catch (error) {
+    console.log(`      ${chalk.yellow('⚠')} Could not verify roles${chalk.dim(`: ${error.message}`)}`);
+  }
+
+  // === Create + download a new key (up to 10 per account) ===
+  if (options.dryRun) {
+    dryRunPlan('create + download a service account key');
+    return {
+      state: { serviceAccount: { email: serviceAccountEmail } },
+      output: { serviceAccount: { planned: 'create-key' } },
+    };
+  }
+
+  console.log('      Creating service account key...');
+  try {
+    const keyData = await api.createServiceAccountKey(projectId, serviceAccountEmail);
+
+    jetpack.write(sourceKeyPath, keyData);
+    console.log(`      ${chalk.green('✓')} Saved key to ${chalk.cyan('.omega/secrets/')}`);
+
+    return { state: { serviceAccount: { email: serviceAccountEmail } } };
+  } catch (error) {
+    if (error.message?.includes('not allowed') || error.message?.includes('policy')) {
+      console.log(`      ${chalk.yellow('⚠')} Key creation blocked by organization policy`);
+      console.log(`      ${chalk.dim('→')} Download manually: ${chalk.cyan(`https://console.firebase.google.com/project/${projectId}/settings/serviceaccounts/adminsdk`)}`);
+    } else {
+      console.log(`      ${chalk.yellow('⚠')} Could not create key${chalk.dim(`: ${error.message}`)}`);
+    }
+    return {
+      status: 'warned',
+      reason: 'could not create the service account key',
+      state: { serviceAccount: { email: serviceAccountEmail } },
+      output: { serviceAccount: { error: error.message } },
+    };
+  }
+};

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

@@ -0,0 +1,103 @@
+/**
+ * Ensure required Google Cloud APIs are enabled + the compute service account
+ * carries the roles Cloud Functions deploys need.
+ *
+ * omega-manager batch-enabled the full list on every run; this reads the
+ * enabled set first and only enables what's missing, so a converged project
+ * is a zero-mutation no-op. The IAM grant was already diff-based — kept.
+ */
+const chalk = require('chalk').default;
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+const REQUIRED_SERVICES = [
+  'serviceusage.googleapis.com', // Must be first — Firebase CLI v15.20.0+ pre-flight checks require it
+  'firebase.googleapis.com',
+  'firestore.googleapis.com',
+  'firebasestorage.googleapis.com',
+  'firebasehosting.googleapis.com',
+  'firebasedatabase.googleapis.com',
+  'identitytoolkit.googleapis.com',
+  'cloudfunctions.googleapis.com',
+  'cloudbuild.googleapis.com',
+  'run.googleapis.com',
+  'artifactregistry.googleapis.com',
+  'iap.googleapis.com', // OAuth consent screen
+  'recaptchaenterprise.googleapis.com',
+  'fcm.googleapis.com', // Firebase Cloud Messaging V1 API
+];
+
+// Roles the default compute service account needs for Cloud Functions deploys
+const COMPUTE_ROLES = [
+  'roles/storage.objectAdmin',
+  'roles/cloudbuild.builds.builder',
+  'roles/artifactregistry.writer',
+];
+
+module.exports = async function ensureServices(context) {
+  const { firebaseApi: api, projectId, options = {} } = context;
+
+  // === READ ===
+  const enabledServices = await api.listEnabledServices(projectId);
+  const missing = REQUIRED_SERVICES.filter((s) => !enabledServices.includes(s));
+
+  // === WRITE: enable missing APIs ===
+  if (missing.length === 0) {
+    console.log(`      ${chalk.green('✓')} All ${chalk.bold(REQUIRED_SERVICES.length)} required APIs enabled`);
+  } else if (options.dryRun) {
+    dryRunPlan(`enable ${missing.length} API(s): ${missing.join(', ')}`);
+  } else {
+    console.log(`      Enabling ${chalk.bold(missing.length)} missing API(s)...`);
+    try {
+      await api.enableServices(projectId, missing);
+      console.log(`      ${chalk.green('✓')} Enabled ${chalk.bold(missing.length)} APIs`);
+    } catch (error) {
+      // Batch can fail on partially-restricted projects — fall back per-service
+      console.log(`      ${chalk.yellow('⚠')} Batch enable failed, trying individually...`);
+
+      for (const service of missing) {
+        try {
+          await api.enableService(projectId, service);
+        } catch (err) {
+          console.log(`      ${chalk.yellow('⚠')} ${chalk.cyan(service)}${chalk.dim(`: ${err.message}`)}`);
+        }
+      }
+    }
+  }
+
+  // === WRITE: compute service account roles (diff-based) ===
+  try {
+    const projectNumber = await api.getProjectNumber(projectId);
+    const member = `serviceAccount:${projectNumber}-compute@developer.gserviceaccount.com`;
+
+    const policy = await api.getIamPolicy(projectId);
+    let changed = false;
+
+    for (const role of COMPUTE_ROLES) {
+      const binding = policy.bindings?.find((b) => b.role === role);
+      if (binding) {
+        if (!binding.members?.includes(member)) {
+          binding.members.push(member);
+          changed = true;
+        }
+      } else {
+        policy.bindings = policy.bindings || [];
+        policy.bindings.push({ role, members: [member] });
+        changed = true;
+      }
+    }
+
+    if (changed) {
+      if (options.dryRun) {
+        dryRunPlan('grant compute service account deploy roles');
+      } else {
+        await api.setIamPolicy(projectId, policy);
+        console.log(`      ${chalk.green('✓')} Granted compute service account deploy roles`);
+      }
+    }
+  } catch (error) {
+    // Non-fatal — the account may already have the roles or the project structure differs
+    console.log(`      ${chalk.yellow('⚠')} Could not verify compute roles${chalk.dim(`: ${error.message}`)}`);
+  }
+
+  return { output: { services: { required: REQUIRED_SERVICES.length, enabled: missing.length } } };
+};

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

@@ -0,0 +1,47 @@
+/**
+ * Ensure the Firebase Storage default bucket exists and is linked
+ * (new buckets: {projectId}.firebasestorage.app; pre-Oct-2024:
+ * {projectId}.appspot.com).
+ */
+const chalk = require('chalk').default;
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+module.exports = async function ensureStorage(context) {
+  const { firebaseApi: api, projectId, options = {} } = context;
+
+  // === READ ===
+  const existing = await api.getStorageBucket(projectId);
+
+  if (existing) {
+    console.log(`      ${chalk.green('✓')} Storage bucket exists: ${chalk.cyan(existing.name)}`);
+    return { state: { storage: { bucket: existing.name } } };
+  }
+
+  // === WRITE ===
+  if (options.dryRun) {
+    return dryRunPlan('create the default storage bucket', { output: { storage: { planned: 'create' } } });
+  }
+
+  console.log('      Creating storage bucket...');
+  try {
+    const result = await api.createDefaultStorageBucket(projectId);
+
+    if (result.alreadyLinked) {
+      console.log(`      ${chalk.green('✓')} Storage bucket exists: ${chalk.cyan(result.bucket)}`);
+    } else {
+      console.log(`      ${chalk.green('✓')} Storage bucket created: ${chalk.cyan(result.bucket)}`);
+    }
+
+    return { state: { storage: { bucket: result.bucket } } };
+  } catch (error) {
+    console.log(`      ${chalk.yellow('⚠')} Could not create storage bucket${chalk.dim(`: ${error.message}`)}`);
+
+    if (error.message?.includes('BILLING')) {
+      console.log(`      ${chalk.dim('→')} Project must be on the Blaze plan to create storage buckets`);
+    } else {
+      console.log(`      ${chalk.dim('→')} Create manually: ${chalk.cyan(`https://console.firebase.google.com/project/${projectId}/storage`)}`);
+    }
+
+    return { status: 'warned', reason: 'could not create the storage bucket', output: { storage: { error: error.message } } };
+  }
+};

package/dist/services/cloud/index.js

@@ -0,0 +1,130 @@
+/**
+ * Cloud service (Firebase provider) — reconciles the brand's Firebase/GCP project to
+ * `cloud: {}` in omega.json5: Blaze billing, required Google Cloud APIs,
+ * project identity, OAuth consent screen, Admin SDK service account + key,
+ * Hosting api.{domain} custom domains (DNS via Cloudflare), Firestore (+PITR),
+ * Realtime Database, Authentication (Identity Platform + sign-in methods),
+ * Storage, Cloud Functions readiness, Cloud Messaging, and the web SDK config.
+ *
+ * Auth: GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET in the brand .env (OAuth2;
+ * tokens cache to .omega/auth/google-tokens.json — the first run prints an
+ * auth URL). Missing credentials go through the shared setup contract (#608):
+ * an interactive run asks for them right here, a headless one steps aside
+ * loudly. No cloud.config.projectId → interactive runs offer the project
+ * selection/creation flow (lib/project-flow.js, lands the id in omega.json5);
+ * otherwise skip with guidance.
+ *
+ * `cloud.shared: true` (project shared by multiple brands) filters to the
+ * per-brand operations only (service-account, sdk-config) so one brand never
+ * rewrites a shared project's settings.
+ */
+const { googleTokenStorePath } = require('../../lib/google-auth.js');
+const { ensureProjectAccess } = require('./lib/access-heal.js');
+const { isDemoProject } = require('../../vendor/config/index.js');
+const chalk = require('chalk').default;
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { CloudflareAPI } = require('../edge/lib/cloudflare-api.js');
+const { getApexDomain } = require('../../lib/domain-utils.js');
+const { FirebaseAPI } = require('./lib/firebase-api.js');
+const { resolveFirebaseProject } = require('./lib/project-flow.js');
+
+// Operations that stay on for shared projects (per-brand, not project-level)
+const SHARED_OPERATIONS = new Set(['service-account', 'sdk-config']);
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const cloud = context.brandConfig.cloud || {};
+
+    if (cloud.enabled === false) {
+      return { skip: true, reason: 'cloud.enabled = false' };
+    }
+
+    // The shared setup contract (#608): an interactive run asks for the
+    // Google OAuth client right here — provide, skip this run, or disable the
+    // service for good — before anything decides there is nothing to do.
+    let gate = null;
+    if (!context.firebaseApi) {
+      gate = await requestServiceInput(context, serviceInputSpec('cloud'));
+    }
+    const haveCreds = Boolean(
+      context.firebaseApi
+      || (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET),
+    );
+
+    // Tests inject fake clients via context.firebaseApi / context.cloudflareApi.
+    // Cloudflare is only needed by the hosting operation (custom-domain DNS);
+    // without a token the operation reports the required records instead.
+    const makeApi = () => context.firebaseApi || new FirebaseAPI({
+      tokenStorePath: googleTokenStorePath(context.brandRoot),
+    });
+
+    // ONE home (#23): cloud.config.projectId, where the framework flow
+    // (setup/dev) already names the project. Missing → offer the interactive
+    // selection/creation flow (lands it in omega.json5); needs credentials
+    let projectId = cloud.config?.projectId;
+    if (!projectId && haveCreds) {
+      projectId = await resolveFirebaseProject(context, makeApi());
+    }
+    if (!projectId) {
+      return { skip: true, reason: 'no cloud.config.projectId configured (rerun interactively to select/create the project)' };
+    }
+
+    // demo-* = emulator-only by Firebase's own convention: no real GCP
+    // project exists to reconcile (found live 2026-07-19 — the omega brand's
+    // offline demo-omega id sent the ensure at real Google APIs → 403,
+    // killing the whole manage boot).
+    if (isDemoProject(projectId)) {
+      return { skip: true, reason: `${projectId} is a demo-* (emulator-only) project — no real cloud to reconcile` };
+    }
+
+    if (!haveCreds) {
+      return gate || { skip: true, reason: 'no GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET configured (set them in the brand .env)' };
+    }
+
+    // Hostname-only (cp268): this value feeds authDomain + api.{domain} — a
+    // brand.url carrying a path or port must never leak them into either.
+    const brandUrl = context.brandConfig.brand?.url;
+    const domain = brandUrl ? new URL(brandUrl).hostname : '';
+    if (!domain) {
+      return { skip: true, reason: 'no brand.url configured' };
+    }
+
+    const firebaseApi = makeApi();
+
+    // The identity seam self-heals HERE, before any op runs (Ian
+    // 2026-07-19: wrapped in `npm start`, never a hand-run command): a
+    // manage identity with no role on the project gets granted owner via a
+    // local gcloud account that can, and the run proceeds normally.
+    // Idempotent — an accessible project is one probe and done.
+    const access = await ensureProjectAccess({
+      firebaseApi,
+      projectId,
+      ...(context.gcloudExec ? { exec: context.gcloudExec, delayMs: 0 } : {}),
+    });
+    if (access.healed) {
+      console.log(`    ${chalk.green('✓')} Access healed — ${chalk.cyan(access.grantor)} granted ${chalk.cyan(access.manageEmail)} ${chalk.cyan(access.roles.join(' + '))} on ${chalk.cyan(projectId)}`);
+    }
+
+    const shared = cloud.shared === true;
+    console.log(`    Project: ${chalk.cyan(projectId)}${shared ? chalk.dim(' (shared)') : ''}`);
+    const cloudflareApi = context.cloudflareApi
+      || (process.env.CLOUDFLARE_TOKEN ? new CloudflareAPI() : null);
+
+    const apexDomain = getApexDomain(domain);
+
+    return {
+      firebaseApi,
+      cloudflareApi,
+      projectId,
+      domain,
+      apexDomain,
+      isSubdomainProject: domain !== apexDomain,
+      operations: shared
+        ? context.operations.filter((op) => SHARED_OPERATIONS.has(op.name))
+        : context.operations,
+    };
+  },
+});