@caelo-cms/provisioning 0.10.46 → 0.10.48

package/src/wizard.ts

@@ -0,0 +1,425 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * `bunx @caelo-cms/provisioning` — interactive wizard.
+ *
+ * Per CLAUDE.md §11.C, this is the primary surface OSS users interact
+ * with: one command, end-to-end, < 20 min, on the user's own cloud.
+ *
+ * Top-level shape:
+ *   1. Pick provider (gcp / aws / azure / self-hosted)
+ *   2. Detect existing install at `~/.caelo-<id>/` and offer to resume
+ *   3. Prompt for the few inputs the provider needs (domain, owner email,
+ *      region — detect-then-confirm, fixed after install (#607),
+ *      project id, Anthropic key — input-hidden)
+ *   4. Show cost estimate + final confirm
+ *   5. Delegate to the provider-specific wizard which handles project
+ *      bootstrap → Pulumi up → DNS → cert → IAP enable → bootstrap URL
+ *
+ * Each provider wizard is a separate file under `wizards/<provider>.ts`
+ * so adding a new provider is one new file, not a sprawling switch.
+ */
+
+import { defaultStagingHost, normalizeStagingHost, stagingHostProblem } from "@caelo-cms/shared";
+import {
+  cancel,
+  confirm,
+  intro,
+  isCancel,
+  log,
+  outro,
+  select,
+  spinner,
+  text,
+} from "@clack/prompts";
+import { bold, cyan, dim, yellow } from "kleur/colors";
+import {
+  currentMetadata,
+  deriveInstallId,
+  ensureInstallDir,
+  type InstallMetadata,
+  listInstalls,
+  type Provider,
+  readMetadata,
+  resumedMetadata,
+  scrubInstallProgress,
+  writeMetadata,
+} from "./install-state.js";
+import type { RunMode } from "./run-mode.js";
+import { selfCommand } from "./self-command.js";
+import { runGcpWizard } from "./wizards/gcp.js";
+import { runGcpFirebaseWizard } from "./wizards/gcp-firebase.js";
+
+export interface WizardOptions {
+  /** Skip prompts; require all inputs via flags. CI-friendly. */
+  nonInteractive?: boolean;
+  /** Pre-supplied provider — skips the picker. */
+  provider?: Provider;
+  /** Pre-supplied domain — skips the prompt. */
+  domain?: string;
+  /**
+   * #650 — `--staging-domain`: the protected staging site's host; skips the
+   * prompt. Default `staging.<domain>`.
+   */
+  stagingDomain?: string;
+  /** Pre-supplied owner email — skips the prompt. */
+  ownerEmail?: string;
+  /** Pre-supplied GCP project id — skips the prompt for gcp. */
+  projectId?: string;
+  /**
+   * #607 — cloud region for a new install; skips the prompt. Required with
+   * `nonInteractive` for a new install. Fixed after install: on an existing
+   * install a different value is refused.
+   */
+  region?: string;
+  /**
+   * #696 — where `pulumi up` and the rest of a GCP install run
+   * (run-mode.ts): `job` (default in Cloud Shell) or `local`.
+   */
+  runMode?: RunMode;
+}
+
+export async function runWizard(opts: WizardOptions = {}): Promise<void> {
+  intro(bold(cyan("Caelo CMS provisioner")) + dim(" — one-command deploy"));
+
+  // 1. Resume-existing-install fast path. Before prompting for anything,
+  //    scan ~/.caelo-* for installs and offer them as "resume X" options.
+  //    Picking an existing install carries domain + owner + projectId
+  //    over and skips re-prompting; "new install" falls through to the
+  //    fresh-flow below.
+  //
+  //    v0.3.18 — previously the wizard re-asked for provider + domain +
+  //    owner-email + project EVERY re-run. With this fast path, a
+  //    re-run is a single Enter to "resume <id>".
+  let provider: Provider;
+  let domain: string;
+  let ownerEmail: string;
+  let projectIdHint: string | null;
+  let installId: string;
+
+  // #696 — job mode (Cloud Shell): the project comes first and is the
+  // source of truth; this machine's ~/.caelo-* is not consulted.
+  const runMode = opts.runMode ?? "local";
+  let jobModeProjectId: string | null = null;
+  let jobModeExisting: InstallMetadata | null = null;
+  let jobModeProvider: Provider | null = null;
+  if (runMode === "job") {
+    jobModeProvider = opts.provider ?? (await pickProvider());
+    if (jobModeProvider !== "gcp" && jobModeProvider !== "gcp-firebase") {
+      cancel(
+        `The install job runs gcp and gcp-firebase installs; for ${jobModeProvider} run the installer with --local.`,
+      );
+      process.exit(1);
+    }
+    const { prepareJobModeInstall } = await import("./wizards/gcp-install-job.js");
+    const prep = await prepareJobModeInstall(opts.projectId ? { projectId: opts.projectId } : {});
+    if (prep.kind === "handled") {
+      outro(bold("Done."));
+      return;
+    }
+    if (prep.kind === "existing") jobModeExisting = prep.meta;
+    else jobModeProjectId = prep.projectId;
+  }
+
+  const existing = opts.nonInteractive || runMode === "job" ? [] : listInstalls();
+  const picked =
+    existing.length > 0 && !opts.provider && !opts.domain && !opts.ownerEmail
+      ? await pickInstallToResume(existing)
+      : null;
+  // #696 — the bucket's copy for an install whose state lives there: another
+  // machine may have changed its domain or owner since this mirror was written.
+  const resumeChoice = jobModeExisting ?? (picked ? currentMetadata(picked) : null);
+  if (jobModeExisting && jobModeProvider && jobModeExisting.provider !== jobModeProvider) {
+    log.warn(
+      yellow(
+        `This project's install is ${jobModeExisting.provider}, not ${jobModeProvider}; continuing it as ${jobModeExisting.provider}.`,
+      ),
+    );
+  }
+
+  if (resumeChoice) {
+    provider = resumeChoice.provider;
+    domain = resumeChoice.domain;
+    ownerEmail = resumeChoice.ownerEmail;
+    projectIdHint = resumeChoice.projectId;
+    installId = resumeChoice.installId;
+    ensureInstallDir(installId);
+  } else {
+    provider = jobModeProvider ?? opts.provider ?? (await pickProvider());
+    domain = opts.domain ?? (await promptDomain());
+    const stagingDomain = await resolveStagingDomain(domain, provider, opts);
+    ownerEmail = opts.ownerEmail ?? (await promptOwnerEmail());
+    projectIdHint = jobModeProjectId ?? opts.projectId ?? null;
+    installId = deriveInstallId(provider, projectIdHint ?? domain);
+    ensureInstallDir(installId);
+
+    // If the user picked "new install" but the derived id collides with
+    // an existing one (e.g. retyped the same domain), confirm resume.
+    const existingForId = readMetadata(installId);
+    if (existingForId && !opts.nonInteractive) {
+      const resume = await confirm({
+        message: `Existing install '${installId}' detected (created ${dim(existingForId.createdAt)}). Resume?`,
+        initialValue: true,
+      });
+      if (isCancel(resume)) {
+        cancel("Cancelled.");
+        process.exit(0);
+      }
+      if (!resume) {
+        cancel(`Aborted. Run with a different domain or remove ~/.caelo-${installId}/ first.`);
+        process.exit(0);
+      }
+    } else if (existingForId) {
+      // Non-interactive re-run of an existing install: resume it. Keep its
+      // metadata (createdAt, region, the recorded release in imageDigests)
+      // so the re-run converges infrastructure instead of looking like a
+      // new install that deploys `:latest`.
+      writeMetadata(installId, {
+        ...resumedMetadata(existingForId, { domain, ownerEmail, projectId: projectIdHint }),
+        ...(opts.stagingDomain ? { stagingDomain } : {}),
+      });
+    } else {
+      writeMetadata(installId, {
+        installId,
+        provider,
+        projectId: projectIdHint,
+        domain,
+        stagingDomain,
+        ownerEmail,
+        region: null,
+        createdAt: new Date().toISOString(),
+      });
+    }
+  }
+
+  // 3.5. #656 — a re-run of an install an earlier CLI set up: drop the
+  // secrets that CLI checkpointed (database passwords, the setup link)
+  // before any step writes progress.json again, and say what to rotate.
+  for (const line of scrubInstallProgress(installId)) log.warn(yellow(line));
+
+  // 4. Delegate to the provider-specific wizard.
+  switch (provider) {
+    case "gcp":
+      await runGcpWizard({
+        installId,
+        domain,
+        ownerEmail,
+        projectId: projectIdHint,
+        nonInteractive: opts.nonInteractive ?? false,
+        ...(opts.region ? { region: opts.region } : {}),
+        runMode,
+      });
+      break;
+    case "gcp-firebase":
+      await runGcpFirebaseWizard({
+        installId,
+        domain,
+        ownerEmail,
+        projectId: projectIdHint,
+        nonInteractive: opts.nonInteractive ?? false,
+        ...(opts.region ? { region: opts.region } : {}),
+        runMode,
+      });
+      break;
+    case "self-hosted":
+      cancel(
+        `Self-hosted wizard is the existing \`cms-provision init\` flow. Run \`${selfCommand("init", "--domain", "...", "--owner-email", "...")}\` for now; wizard polish lands in a follow-up commit.`,
+      );
+      process.exit(0);
+      break;
+    case "aws":
+    case "azure":
+      cancel(
+        `${provider.toUpperCase()} provider wizard not yet implemented. GCP is the first cloud target; AWS + Azure follow the same shape and land in upcoming commits.`,
+      );
+      process.exit(0);
+      break;
+  }
+
+  outro(bold("Done. Welcome to Caelo CMS."));
+}
+
+/**
+ * Offer the operator the list of existing installs (newest first)
+ * plus a "start a new install" option. Returning `null` means the
+ * operator picked "new" and the wizard falls through to the fresh-
+ * inputs prompts. Returning an install means resume — every input
+ * (provider, domain, owner, project) carries over from metadata.
+ */
+async function pickInstallToResume(installs: InstallMetadata[]): Promise<InstallMetadata | null> {
+  const first = installs[0];
+  // v0.5.14 — added per-install "Upgrade" entries that route to
+  // upgradeCommand (Cloud Run image roll) without re-running the
+  // wizard. Operator complaint: running bare `bunx @caelo-cms/
+  // provisioning@latest` on a working install dropped them into
+  // the wizard and they assumed it would upgrade. It didn't — the
+  // wizard provisions, only `upgrade` rolls a running deployment.
+  // Surfacing both intents in the same picker closes the gap.
+  const choice = await select<string>({
+    message:
+      installs.length === 1 && first
+        ? `What do you want to do with '${first.installId}'?`
+        : "Pick an existing install (or start a new one):",
+    options: [
+      ...installs.flatMap((m) => [
+        {
+          value: `upgrade:${m.installId}`,
+          label: `Upgrade ${bold(m.installId)} ${dim(`(${m.provider}, ${m.domain})`)}`,
+          hint: `roll Cloud Run to the latest image — does not re-run the wizard`,
+        },
+        {
+          value: `resume:${m.installId}`,
+          label: `Resume wizard for ${bold(m.installId)} ${dim(`(${m.provider}, ${m.domain})`)}`,
+          hint: `created ${m.createdAt.slice(0, 10)} — re-runs provisioning steps`,
+        },
+      ]),
+      { value: "__new__", label: "Start a new install", hint: "fresh inputs" },
+    ],
+  });
+  if (isCancel(choice)) {
+    cancel("Cancelled.");
+    process.exit(0);
+  }
+  if (choice === "__new__") return null;
+  // v0.5.14 — upgrade short-circuit. Dispatch to upgradeCommand
+  // directly and exit; we don't fall through to runWizard's main flow.
+  if (choice.startsWith("upgrade:")) {
+    const installId = choice.slice("upgrade:".length);
+    const target = installs.find((m) => m.installId === installId);
+    if (!target) {
+      cancel(`Could not find install metadata for '${installId}'.`);
+      process.exit(1);
+    }
+    const { upgradeCommand } = await import("./lifecycle.js");
+    // Defaults to channel=stable / tag=:latest — explicit-version is
+    // available via `cms-provision upgrade --version vX.Y.Z`. The picked
+    // install is passed on: without it upgrade would choose again (and,
+    // before that was fixed, took the first ~/.caelo-* it found).
+    await upgradeCommand({ installId: target.installId });
+    process.exit(0);
+  }
+  const installId = choice.startsWith("resume:") ? choice.slice("resume:".length) : choice;
+  return installs.find((m) => m.installId === installId) ?? null;
+}
+
+async function pickProvider(): Promise<Provider> {
+  const choice = await select<Provider>({
+    message: "Where do you want to deploy?",
+    options: [
+      {
+        value: "gcp",
+        label: "Google Cloud Platform",
+        hint: "Cloud Run + Cloud SQL + Cloud Storage + Cloud CDN. Single LB serves admin + gateway + static.",
+      },
+      {
+        value: "gcp-firebase",
+        label: "Google Cloud Platform (Firebase Hosting)",
+        hint: "Cloud Run + Cloud SQL + Firebase Hosting (no LB). Lower fixed cost, native clean URLs + preview channels. Gateway via Firebase rewrites (no Cloud Armor).",
+      },
+      {
+        value: "self-hosted",
+        label: "Self-hosted (Docker Compose)",
+        hint: "Single Linux box. Postgres + Caddy + the admin + the gateway.",
+      },
+      {
+        value: "aws",
+        label: "Amazon Web Services",
+        hint: "Lambda + RDS + S3 + CloudFront. Lands in a follow-up commit.",
+      },
+      {
+        value: "azure",
+        label: "Microsoft Azure",
+        hint: "Container Apps + Azure DB + Blob + Front Door. Lands in a follow-up commit.",
+      },
+    ],
+  });
+  if (isCancel(choice)) {
+    cancel("Cancelled.");
+    process.exit(0);
+  }
+  return choice as Provider;
+}
+
+async function promptDomain(): Promise<string> {
+  const value = await text({
+    message: "Domain you'd like to use",
+    placeholder: "mysite.com",
+    validate: (v) => {
+      if (!v || v.length === 0) return "Domain is required";
+      if (
+        !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/.test(v)
+      ) {
+        return "Looks like an invalid domain (e.g. mysite.com)";
+      }
+      return undefined;
+    },
+  });
+  if (isCancel(value)) {
+    cancel("Cancelled.");
+    process.exit(0);
+  }
+  return value as string;
+}
+
+/**
+ * #650 — the protected staging site's host: `--staging-domain`, else asked
+ * (default `staging.<domain>`; any other FQDN, also on another domain),
+ * else — non-interactive — the default. Never the live or admin host.
+ */
+async function resolveStagingDomain(
+  domain: string,
+  provider: Provider,
+  opts: Pick<WizardOptions, "stagingDomain" | "nonInteractive">,
+): Promise<string> {
+  const reserved = { liveHosts: [domain, `www.${domain}`], adminHosts: [`admin.${domain}`] };
+  const problemOf = (host: string) => stagingHostProblem(host, reserved, { provider });
+  if (opts.stagingDomain) {
+    const problem = problemOf(opts.stagingDomain);
+    if (problem) {
+      cancel(`--staging-domain: ${problem}`);
+      process.exit(1);
+    }
+    return normalizeStagingHost(opts.stagingDomain);
+  }
+  const suggested = defaultStagingHost(domain);
+  if (opts.nonInteractive) {
+    // The default can be too long for the provider (gcp-firebase: 64).
+    const problem = problemOf(suggested);
+    if (problem) {
+      cancel(`the default staging host ${problem}. Pass --staging-domain <host>.`);
+      process.exit(1);
+    }
+    return suggested;
+  }
+  const value = await text({
+    message: "Host of the protected staging site (where you review changes before they go live)",
+    placeholder: suggested,
+    initialValue: suggested,
+    validate: (v) => problemOf(v || suggested) ?? undefined,
+  });
+  if (isCancel(value)) {
+    cancel("Cancelled.");
+    process.exit(0);
+  }
+  return normalizeStagingHost((value as string) || suggested);
+}
+
+async function promptOwnerEmail(): Promise<string> {
+  const value = await text({
+    message: "Owner email (you'll be the IAP allowlisted Owner; can add more later)",
+    placeholder: "you@example.com",
+    validate: (v) => {
+      if (!v || v.length === 0) return "Email is required";
+      if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v)) return "Looks like an invalid email";
+      return undefined;
+    },
+  });
+  if (isCancel(value)) {
+    cancel("Cancelled.");
+    process.exit(0);
+  }
+  return value as string;
+}
+
+// Re-export the spinner factory so per-provider wizards use a consistent UX.
+export { spinner };

package/src/wizards/gcp-cost.ts

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Per-resource static price table for the GCP stack — used by the
+ * wizard's pre-flight cost estimate. Prices are EUR/USD per month at
+ * `europe-west1` list rates as of 2026-05; ship updates with each
+ * Caelo release.
+ *
+ * The estimate is intentionally OVER-conservative — it shows the
+ * floor cost (idle + scale-to-zero traffic). Real usage adds egress
+ * + AI calls + storage growth on top.
+ */
+
+import { ADMIN_MEMORY_DEFAULT, memoryQuantityMiB } from "../stack-contract.js";
+
+export interface CostLine {
+  name: string;
+  monthlyUsd: number;
+  notes?: string;
+}
+
+export interface CostEstimateInputs {
+  cloudSqlTier: string; // e.g. "db-f1-micro"
+  cloudSqlHa: boolean;
+  adminMinInstances: number;
+  /**
+   * #553 — admin memory (`2Gi`). Cloud Run bills memory only while an
+   * instance runs, so it costs nothing extra at scale-to-zero and
+   * ~$6.50/mo per GiB above 1 GiB for each always-on min instance.
+   */
+  adminMemory?: string;
+  gatewayMinInstances: number;
+  wafAdaptiveProtection: boolean;
+  /**
+   * v0.3.3 — provider variant. 'gcp' is the LB-fronted topology
+   * (+$18 LB + Cloud CDN + Cloud Armor lines). 'gcp-firebase'
+   * drops all three (no LB, Firebase Hosting native CDN, no Cloud
+   * Armor) — saves ~$19/mo. Defaults to 'gcp' for backwards
+   * compatibility.
+   */
+  provider?: "gcp" | "gcp-firebase";
+  /** #607 — the install region; shown in the table (prices are {@link PRICED_REGION} rates). */
+  region: string;
+}
+
+/** The region the price table's list rates are for. */
+const PRICED_REGION = "europe-west1";
+
+const SQL_TIER_USD: Record<string, number> = {
+  // Shared-core legacy tiers, ENTERPRISE edition
+  "db-f1-micro": 9.5,
+  "db-g1-small": 30,
+  // Per-N tiers (ENTERPRISE_PLUS only)
+  "db-perf-optimized-N-2": 50,
+  "db-perf-optimized-N-4": 95,
+  "db-perf-optimized-N-8": 180,
+  // Custom-machine fallback (rough)
+  "db-custom-1-3840": 35,
+  "db-custom-2-7680": 65,
+  "db-custom-4-15360": 130,
+};
+
+export function estimateGcpCost(inputs: CostEstimateInputs): {
+  lines: CostLine[];
+  totalUsd: number;
+  /** The region line the pre-flight table shows above the costs. */
+  regionNote: string;
+} {
+  const sqlBase = SQL_TIER_USD[inputs.cloudSqlTier] ?? 30;
+  const sqlMultiplier = inputs.cloudSqlHa ? 2.0 : 1.0;
+  const sqlMonthly = Math.round(sqlBase * sqlMultiplier);
+
+  const provider = inputs.provider ?? "gcp";
+  const adminMemory = inputs.adminMemory ?? ADMIN_MEMORY_DEFAULT;
+  const adminMiB = memoryQuantityMiB(adminMemory);
+  if (adminMiB === null) {
+    throw new Error(`adminMemory "${adminMemory}" is not a memory quantity (e.g. 2Gi)`);
+  }
+  const adminGiB = adminMiB / 1024;
+  // An always-on instance is priced at 1 GiB (the $15 line); extra memory
+  // is billed per GiB-second (~$6.50 per GiB-month).
+  const perMinInstanceUsd = 15 + Math.max(0, adminGiB - 1) * 6.5;
+
+  const lines: CostLine[] = [
+    {
+      name: `Cloud SQL Postgres (${inputs.cloudSqlTier}${inputs.cloudSqlHa ? ", HA" : ""})`,
+      monthlyUsd: sqlMonthly,
+      notes: inputs.cloudSqlHa
+        ? "REGIONAL availability (synchronous replica)"
+        : "ZONAL — single zone, automated backups",
+    },
+    {
+      name: `Cloud Run admin (${adminMemory})`,
+      monthlyUsd:
+        inputs.adminMinInstances === 0
+          ? 1
+          : Math.round(1 + inputs.adminMinInstances * perMinInstanceUsd),
+      notes:
+        inputs.adminMinInstances === 0
+          ? "scale-to-zero; ~$1/mo light editorial use"
+          : `${inputs.adminMinInstances} min-instance${inputs.adminMinInstances > 1 ? "s" : ""} (no cold start)`,
+    },
+    {
+      name: "Quality checks (Lighthouse on the admin)",
+      monthlyUsd: 1,
+      notes:
+        "~1-2 min of admin CPU per audited Stage (up to 5 pages x 3 runs); ~$1/mo at a few Stages a day",
+    },
+    {
+      name: "Cloud Run gateway",
+      monthlyUsd: inputs.gatewayMinInstances === 0 ? 1 : 1 + inputs.gatewayMinInstances * 15,
+      notes:
+        inputs.gatewayMinInstances === 0
+          ? "scale-to-zero; ~$1/mo light traffic"
+          : `${inputs.gatewayMinInstances} min-instance${inputs.gatewayMinInstances > 1 ? "s" : ""}`,
+    },
+    // v0.3.3 — LB / Cloud CDN / Cloud Armor lines apply only to the
+    // gcp variant. gcp-firebase has no LB (Firebase Hosting is the
+    // edge); no Cloud CDN line (Firebase Hosting has its own CDN
+    // included in free tier); no Cloud Armor (admin is gated by
+    // Cloud Run IAP, gateway by run.invoker IAM).
+    ...(provider === "gcp"
+      ? ([
+          {
+            name: "Load balancer + managed SSL cert",
+            monthlyUsd: 18,
+            notes: "Global LB base fee + cert (free) — flat",
+          },
+          {
+            name: "Cloud CDN cache",
+            monthlyUsd: 1,
+            notes: "Free egress at edge cache hits",
+          },
+          {
+            name: "Cloud Armor WAF",
+            monthlyUsd: inputs.wafAdaptiveProtection ? 5 : 0,
+            notes: inputs.wafAdaptiveProtection
+              ? "Adaptive protection (ML-based bot mitigation)"
+              : "Free tier — rate limit + OWASP basic rules",
+          },
+        ] satisfies CostLine[])
+      : ([
+          {
+            name: "Firebase Hosting",
+            monthlyUsd: 0,
+            notes: "Free tier: 10 GB storage + 360 MB/day egress",
+          },
+        ] satisfies CostLine[])),
+    {
+      name:
+        provider === "gcp"
+          ? "Cloud Storage (static + media)"
+          : "Cloud Storage (media only — static lives on Firebase)",
+      monthlyUsd: 1,
+      notes: "~5 GB storage + low egress; growth roughly $0.02/GB",
+    },
+    {
+      name: "Secret Manager (5 secrets)",
+      monthlyUsd: 0,
+      notes: "Free tier",
+    },
+    {
+      name: "BigQuery edge log sink",
+      monthlyUsd: 0,
+      notes: "Free tier — pay only on >1 TB/mo query",
+    },
+    {
+      name: "Install state (ops bucket + Cloud KMS key)",
+      monthlyUsd: 0.06,
+      notes:
+        "< $0.10/mo — versioned bucket with Pulumi state + install metadata, 1 KMS key version ($0.06)",
+    },
+    {
+      name: "Operator-access sync (Cloud Run job + Cloud Scheduler)",
+      monthlyUsd: 0,
+      notes:
+        "Hourly ~20 s job keeps Google IAP in step with the user list; within the Cloud Run free tier, 1 of 3 free scheduler jobs",
+    },
+  ];
+
+  // Cents, so a sub-dollar line (the KMS key) doesn't print float noise.
+  const totalUsd = Math.round(lines.reduce((sum, l) => sum + l.monthlyUsd, 0) * 100) / 100;
+  const regionNote =
+    inputs.region === PRICED_REGION
+      ? `Region: ${inputs.region} (fixed after install)`
+      : `Region: ${inputs.region} (fixed after install) — prices below are ${PRICED_REGION} list rates; ${inputs.region} rates may differ`;
+  return { lines, totalUsd, regionNote };
+}

package/src/wizards/gcp-firebase.ts

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * v0.3.0 — GCP Firebase Hosting provider wizard.
+ *
+ * Architectural differences from the `gcp` wizard:
+ *   - No load balancer / url-map / TLS cert / BackendBucket
+ *   - Static site → Firebase Hosting (apex domain)
+ *   - admin.<domain> → Cloud Run direct + IAP-on-Cloud-Run
+ *   - <domain>/api/* → Firebase Hosting `rewrites` → Cloud Run gateway
+ *
+ * The Pulumi stack at packages/provisioning/stacks/gcp-firebase/
+ * provisions all of the above. The wizard's pre-Pulumi work
+ * (gcloud auth, project, billing, APIs, SA, secrets, anthropic-api-key
+ * capture) is structurally identical to the `gcp` wizard — same
+ * helpers, same flow — only the final Pulumi invocation differs.
+ *
+ * For v0.3.0 the wizard delegates to the same gcp pre-Pulumi steps
+ * via the shared `runGcpWizard` flow and only swaps the Pulumi
+ * runtime target. If `runGcpWizard`'s flow needs to diverge further
+ * (e.g. Firebase API enablement, Firebase project initialization),
+ * we'll split it. Until then the duplication is one fn call.
+ */
+
+import { log, note } from "@clack/prompts";
+import { bold, cyan } from "kleur/colors";
+import type { RunMode } from "../run-mode.js";
+
+export interface GcpFirebaseWizardOpts {
+  installId: string;
+  domain: string;
+  ownerEmail: string;
+  projectId: string | null;
+  nonInteractive: boolean;
+  /** #607 — `--region`; see {@link GcpWizardOpts.region}. */
+  region?: string;
+  /** #696 — see {@link GcpWizardOpts.runMode}. */
+  runMode?: RunMode;
+}
+
+export async function runGcpFirebaseWizard(opts: GcpFirebaseWizardOpts): Promise<void> {
+  log.step(bold("GCP Firebase Hosting provider"));
+  note(
+    [
+      "This provider variant uses:",
+      `  ${cyan("Firebase Hosting")} for the static site (clean URLs + native preview channels)`,
+      `  ${cyan("Cloud Run direct")} for admin (admin.<domain>, IAP-on-Cloud-Run)`,
+      `  ${cyan("Firebase rewrites")} for the gateway (no LB, no Cloud Armor)`,
+      "",
+      "Lower fixed cost than the `gcp` provider (no LB ~$18/mo savings).",
+      "Trade-off: no Cloud Armor on the gateway — in-app rate limits + Firebase Edge DDoS only.",
+    ].join("\n"),
+  );
+
+  // v0.3.1 — the gcloud pre-Pulumi steps are structurally identical
+  // (project, billing, APIs, SA, secrets capture) and the shared
+  // `runGcpWizard` flow now accepts a `provider` arg that:
+  //   - enables the additional Firebase APIs in stepEnableApis
+  //   - routes the final pulumiUpGcp at stacks/gcp-firebase
+  //   - uses the caelo-gcp-firebase config namespace
+  const { runGcpWizard } = await import("./gcp.js");
+  await runGcpWizard({
+    installId: opts.installId,
+    domain: opts.domain,
+    ownerEmail: opts.ownerEmail,
+    projectId: opts.projectId,
+    nonInteractive: opts.nonInteractive,
+    ...(opts.region ? { region: opts.region } : {}),
+    ...(opts.runMode ? { runMode: opts.runMode } : {}),
+    provider: "gcp-firebase",
+  });
+}