@caelo-cms/provisioning 0.10.61 → 0.10.64

package/src/owner-reset.ts

@@ -1,24 +1,29 @@
 // SPDX-License-Identifier: MPL-2.0
 
 /**
- * #769 — `cms-provision owner-reset` — get an Owner back into a locked-out admin
- * when the install cannot email a reset link (no email transport set up).
+ * #769 / #770 — `cms-provision owner-reset` — get an Owner back into a
+ * locked-out admin when the install cannot email a reset link (no email
+ * transport set up).
  *
- * The root of trust is the operator's cloud identity: whoever may read the
- * install's internal secret and pass the admin's IAP already controls its
- * database and deploys, so issuing them a reset link grants nothing new. The
- * admin issues the one-hour, single-use token (`auth.issue_owner_reset`,
- * audited) and hands it back over the admin-internal.ts channel; the CLI
- * prints the link once. It is never logged, so it does not land in the
- * project's Cloud Logging the way a "log the link" fallback would.
+ * The root of trust is the operator's control of the install: on Google
+ * Cloud, whoever may read the install's internal secret and pass the
+ * admin's IAP already controls its database and deploys; on self-hosted,
+ * whoever may run `docker compose` for it already controls the host. Issuing
+ * them a reset link grants nothing new. The admin issues the one-hour,
+ * single-use token (`auth.issue_owner_reset`, audited) and hands it back over
+ * the admin-internal.ts channel; the CLI prints the link once. It is never
+ * logged, so it does not land in the project's Cloud Logging or the host's
+ * container logs the way a "log the link" fallback would.
  *
- * The request carries the operator's gcloud account so the admin's audit row
- * names who asked. That account is self-asserted (the admin sees the shared
- * `caelo-mcp` identity and the shared internal secret), and labelled so; the
- * authoritative record is Google's Data Access audit log for the IAM
- * Credentials and Secret Manager calls this command makes as the operator.
+ * The request names who asked, for the admin's audit row: the operator's
+ * gcloud account on Google Cloud, `<user>@<host>` of the CLI process on
+ * self-hosted. Either is self-asserted (the admin sees a shared identity and
+ * the shared internal secret) and labelled so; the authoritative record is
+ * Google's Data Access audit log for the IAM Credentials and Secret Manager
+ * calls, or the host's own login records.
  */
 
+import { hostname, userInfo } from "node:os";
 import {
   type AdminInternalDeps,
   type AdminInternalResult,
@@ -26,11 +31,57 @@ import {
   callAdminInternal,
 } from "./admin-internal.js";
 import { activeAccount, gcloud as defaultGcloud } from "./gcloud.js";
+import type { InstallMetadata } from "./install-state.js";
 
 /** Token scope the admin endpoint checks (apps/admin …/api/internal/owner-reset). */
 export const OWNER_RESET_SCOPE = "auth.owner_reset";
 const ENDPOINT = "/api/internal/owner-reset";
 
+/** Where another Owner or the email setup gets a locked-out Owner back in meanwhile. */
+const OTHER_WAYS_IN =
+  "Until then, another Owner can set a new password under Settings -> Users, or set up email under Settings -> Email so /forgot can send the link.";
+
+/**
+ * The admin of a cloud install recorded in install.json, or why this
+ * command cannot reach it. aws and azure have no channel to the admin's
+ * internal endpoints yet (#952); a self-hosted install is found by its
+ * `.caelo/` directory, not by install.json.
+ */
+export function ownerResetTarget(
+  meta: Pick<InstallMetadata, "installId" | "provider" | "projectId" | "region" | "domain">,
+): AdminInternalResult<AdminInternalTarget> {
+  const unrecorded = (what: string) => ({
+    ok: false as const,
+    error: `install ${meta.installId} has no ${what} recorded in install.json; re-run the wizard to record it.`,
+  });
+  switch (meta.provider) {
+    case "gcp-firebase":
+      if (!meta.projectId || !meta.region) return unrecorded("project or region");
+      return {
+        ok: true,
+        value: { provider: "gcp-firebase", projectId: meta.projectId, region: meta.region },
+      };
+    case "gcp":
+      if (!meta.projectId || !meta.domain) return unrecorded("project or domain");
+      return {
+        ok: true,
+        value: { provider: "gcp", projectId: meta.projectId, domain: meta.domain },
+      };
+    case "self-hosted":
+      return {
+        ok: false,
+        error:
+          "this install is self-hosted: run `cms-provision owner-reset` without --install in the directory that holds its .caelo/ (or with CAELO_SELF_HOSTED_DIR set to that .caelo/).",
+      };
+    case "aws":
+    case "azure":
+      return {
+        ok: false,
+        error: `owner-reset cannot reach the admin of ${meta.provider} installs yet (issue #952). ${OTHER_WAYS_IN}`,
+      };
+  }
+}
+
 /** What the admin issued: whose account, the link to open, and until when it works. */
 export interface OwnerReset {
   readonly email: string;
@@ -45,10 +96,10 @@ export interface OwnerReset {
 export async function requestOwnerReset(
   target: AdminInternalTarget,
   request: { readonly email?: string },
-  deps: AdminInternalDeps = {},
+  deps: OwnerResetDeps = {},
 ): Promise<AdminInternalResult<OwnerReset>> {
-  const account = await readGcloudAccount(deps.run ?? defaultGcloud);
-  if (!account.ok) return account;
+  const requester = await readRequester(target, deps);
+  if (!requester.ok) return requester;
   const r = await callAdminInternal<{ email: string; token: string; expiresAt: string }>(
     target,
     {
@@ -56,9 +107,9 @@ export async function requestOwnerReset(
       scope: OWNER_RESET_SCOPE,
       body: {
         ...(request.email !== undefined ? { email: request.email } : {}),
-        requestedBy: account.value,
+        ...requester.value,
       },
-      introducedBy: "#769",
+      introducedBy: target.provider === "self-hosted" ? "#770" : "#769",
     },
     deps,
   );
@@ -72,6 +123,44 @@ export async function requestOwnerReset(
   return { ok: true, value: { email, resetUrl, expiresAt } };
 }
 
+/** {@link requestOwnerReset}'s seams; `localUser` names the host user on self-hosted. */
+export interface OwnerResetDeps extends AdminInternalDeps {
+  readonly localUser?: () => { readonly user: string; readonly host: string };
+}
+
+/**
+ * Who asks, as the admin's body field for it: `requestedBy` (a gcloud
+ * account) on Google Cloud — the field #769's admins accept — and
+ * `requestedByHostUser` on self-hosted, where only admins from #770 on hold
+ * the internal secret at all.
+ */
+async function readRequester(
+  target: AdminInternalTarget,
+  deps: OwnerResetDeps,
+): Promise<AdminInternalResult<{ requestedBy: string } | { requestedByHostUser: string }>> {
+  if (target.provider !== "self-hosted") {
+    const account = await readGcloudAccount(deps.run ?? defaultGcloud);
+    return account.ok ? { ok: true, value: { requestedBy: account.value } } : account;
+  }
+  const { user, host } = (deps.localUser ?? defaultLocalUser)();
+  // The admin accepts exactly this shape (…/api/internal/owner-reset).
+  if (!HOST_USER.test(user) || !HOST_NAME.test(host)) {
+    return {
+      ok: false,
+      error: `name this host's user for the admin's audit row: ${JSON.stringify(`${user}@${host}`)} is not <user>@<host> in letters, digits, '.', '_' and '-'. Run the command as a user (and on a host) named that way.`,
+    };
+  }
+  return { ok: true, value: { requestedByHostUser: `${user}@${host}` } };
+}
+
+/** The pieces of `requestedByHostUser`, as the admin validates them. */
+const HOST_USER = /^[A-Za-z0-9._-]{1,64}$/;
+const HOST_NAME = /^[A-Za-z0-9.-]{1,253}$/;
+
+function defaultLocalUser(): { user: string; host: string } {
+  return { user: userInfo().username, host: hostname() };
+}
+
 /**
  * The gcloud account this command runs as, for the admin's audit row. Without
  * one there is nobody to name, and the IAP step after this would fail anyway.

package/src/preview-plan.test.ts

@@ -0,0 +1,233 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * preview-plan.ts against an engine event stream in the shape
+ * `stack.preview({ onEvent })` delivers (#737): one planned step per
+ * resource, replace sub-steps folded in, bookkeeping dropped, and every
+ * data-bearing replace or delete named.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { closeSync, fstatSync, mkdtempSync, openSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { EngineEvent, OpType } from "@pulumi/pulumi/automation";
+import {
+  collectPreviewSteps,
+  formatPlan,
+  hasReplaceOrDelete,
+  losesData,
+  type PlannedStep,
+  planGate,
+  writePlanFile,
+} from "./preview-plan.js";
+
+const URN = "urn:pulumi:production::caelo-gcp-firebase::";
+let sequence = 0;
+
+/** A `resourcePreEvent` as the engine sends it. */
+function pre(
+  op: OpType,
+  type: string,
+  name: string,
+  extra: { diffs?: string[]; keys?: string[] } = {},
+): EngineEvent {
+  return {
+    sequence: sequence++,
+    timestamp: 1_760_000_000,
+    resourcePreEvent: {
+      metadata: {
+        op,
+        urn: `${URN}${type}::${name}`,
+        type,
+        provider: `${URN}pulumi:providers:gcp::default_8_10_0::04da6b54`,
+        ...extra,
+      },
+    },
+  };
+}
+
+/** A preview of a drifted gcp-firebase install, as recorded from the engine. */
+const RECORDED: EngineEvent[] = [
+  { sequence: sequence++, timestamp: 1_760_000_000, preludeEvent: { config: {} } },
+  pre("same", "pulumi:pulumi:Stack", "caelo-gcp-firebase-production"),
+  pre("create", "pulumi:providers:gcp", "default_8_10_0"),
+  pre("refresh", "gcp:run/v2Service:V2Service", "caelo-production-admin"),
+  pre("same", "gcp:run/v2Service:V2Service", "caelo-production-admin"),
+  pre("update", "gcp:cloudrunv2/service:Service", "caelo-production-gateway", {
+    diffs: ["template", "ingress"],
+  }),
+  pre("create", "gcp:projects/iAMMember:IAMMember", "admin-run-invoker"),
+  pre("replace", "gcp:sql/databaseInstance:DatabaseInstance", "caelo-production-pg", {
+    diffs: ["region", "settings"],
+    keys: ["region"],
+  }),
+  pre("create-replacement", "gcp:sql/databaseInstance:DatabaseInstance", "caelo-production-pg", {
+    keys: ["region"],
+  }),
+  pre("delete-replaced", "gcp:sql/databaseInstance:DatabaseInstance", "caelo-production-pg"),
+  pre("delete", "gcp:storage/bucket:Bucket", "caelo-production-media"),
+  pre("replace", "gcp:secretmanager/secret:Secret", "caelo-production-postgres-password", {
+    keys: ["replication"],
+  }),
+  pre("delete", "gcp:firebase/project:Project", "firebase"),
+  pre("delete", "gcp:compute/firewall:Firewall", "allow-health-checks"),
+  pre("read", "gcp:organizations/getProject:getProject", "project"),
+  {
+    sequence: sequence++,
+    timestamp: 1_760_000_001,
+    summaryEvent: {
+      maybeCorrupt: false,
+      durationSeconds: 12,
+      resourceChanges: { same: 2, update: 1, create: 1, replace: 2, delete: 3 },
+      policyPacks: {},
+    },
+  },
+];
+
+function recordedPlan(): PlannedStep[] {
+  const c = collectPreviewSteps();
+  for (const e of RECORDED) c.onEvent(e);
+  return c.steps();
+}
+
+describe("collectPreviewSteps", () => {
+  it("one step per changed resource; same, refresh, read, providers and the stack drop out", () => {
+    const steps = recordedPlan();
+    expect(steps.map((s) => `${s.op} ${s.name}`)).toEqual([
+      "update caelo-production-gateway",
+      "create admin-run-invoker",
+      "replace caelo-production-pg",
+      "delete caelo-production-media",
+      "replace caelo-production-postgres-password",
+      "delete firebase",
+      "delete allow-health-checks",
+    ]);
+  });
+
+  it("a replace keeps why it is replaced; its sub-steps do not overwrite it", () => {
+    const sql = recordedPlan().find((s) => s.name === "caelo-production-pg");
+    expect(sql).toEqual({
+      op: "replace",
+      type: "gcp:sql/databaseInstance:DatabaseInstance",
+      name: "caelo-production-pg",
+      urn: `${URN}gcp:sql/databaseInstance:DatabaseInstance::caelo-production-pg`,
+      diffs: ["region", "settings"],
+      replaceReasons: ["region"],
+    });
+  });
+});
+
+describe("losesData", () => {
+  it("flags the Cloud SQL instance, a bucket, a secret and the Firebase project", () => {
+    const lost = recordedPlan()
+      .filter(losesData)
+      .map((s) => s.type);
+    expect(lost).toEqual([
+      "gcp:sql/databaseInstance:DatabaseInstance",
+      "gcp:storage/bucket:Bucket",
+      "gcp:secretmanager/secret:Secret",
+      "gcp:firebase/project:Project",
+    ]);
+  });
+
+  it("an in-place update or a create of a data-bearing resource loses nothing", () => {
+    const step = (op: PlannedStep["op"]): PlannedStep => ({
+      op,
+      type: "gcp:sql/databaseInstance:DatabaseInstance",
+      name: "pg",
+      urn: "u",
+      diffs: [],
+      replaceReasons: [],
+    });
+    expect(losesData(step("update"))).toBe(false);
+    expect(losesData(step("create"))).toBe(false);
+    expect(losesData(step("delete"))).toBe(true);
+  });
+
+  it("a firewall delete is a delete, but not data loss", () => {
+    const fw = recordedPlan().find((s) => s.name === "allow-health-checks");
+    expect(fw && losesData(fw)).toBe(false);
+    expect(hasReplaceOrDelete(recordedPlan())).toBe(true);
+    expect(hasReplaceOrDelete(recordedPlan().filter((s) => s.op === "update"))).toBe(false);
+  });
+});
+
+describe("formatPlan", () => {
+  it("groups destructive steps first and names what each data loss destroys", () => {
+    expect(formatPlan(recordedPlan())).toEqual([
+      "DELETES (3):",
+      "  gcp:storage/bucket:Bucket caelo-production-media  <-- LOSES DATA: Cloud Storage bucket (media, published site or state)",
+      "  gcp:firebase/project:Project firebase  <-- LOSES DATA: Firebase project",
+      "  gcp:compute/firewall:Firewall allow-health-checks",
+      "REPLACES (delete + create) (2):",
+      "  gcp:sql/databaseInstance:DatabaseInstance caelo-production-pg (replaced because region changes)  <-- LOSES DATA: Cloud SQL instance (all site data)",
+      "  gcp:secretmanager/secret:Secret caelo-production-postgres-password (replaced because replication changes)  <-- LOSES DATA: Secret Manager secret",
+      "Updates in place (1):",
+      "  gcp:cloudrunv2/service:Service caelo-production-gateway (template, ingress)",
+      "Creates (1):",
+      "  gcp:projects/iAMMember:IAMMember admin-run-invoker",
+      "",
+      "4 of these would destroy data: Cloud SQL instance (all site data) caelo-production-pg; Cloud Storage bucket (media, published site or state) caelo-production-media; Secret Manager secret caelo-production-postgres-password; Firebase project firebase.",
+    ]);
+  });
+
+  it("an empty plan says so", () => {
+    expect(formatPlan([])).toEqual(["The preview plans no changes."]);
+  });
+});
+
+describe("writePlanFile", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "caelo-plan-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  it("writes every step with its URN and changed properties, mode 600", () => {
+    const path = writePlanFile(dir, "installer", recordedPlan(), new Date("2026-10-21T10:00:00Z"));
+    expect(path).toBe(join(dir, "plan-installer-2026-10-21T10-00-00-000Z.txt"));
+    // One descriptor for the mode and the content (no check-then-read race).
+    const fd = openSync(path, "r");
+    let text: string;
+    try {
+      expect(fstatSync(fd).mode & 0o777).toBe(0o600);
+      text = readFileSync(fd, "utf8");
+    } finally {
+      closeSync(fd);
+    }
+    expect(text).toContain("7 change(s)");
+    expect(text).toContain(
+      `- replace ${URN}gcp:sql/databaseInstance:DatabaseInstance::caelo-production-pg\n    replaced because: region\n    changes: region, settings`,
+    );
+  });
+});
+
+describe("planGate", () => {
+  const only = (pred: (s: PlannedStep) => boolean) => recordedPlan().filter(pred);
+  const typed = (type: string) => only((s) => s.type === type);
+
+  it.each([
+    ["the Cloud SQL instance", "gcp:sql/databaseInstance:DatabaseInstance"],
+    ["a bucket", "gcp:storage/bucket:Bucket"],
+    ["a secret", "gcp:secretmanager/secret:Secret"],
+    ["the Firebase project", "gcp:firebase/project:Project"],
+  ])("replacing or deleting %s needs an explicit yes no flag can give", (_name, type) => {
+    const steps = typed(type);
+    expect(steps).toHaveLength(1);
+    expect(planGate(steps, { interactive: true })).toEqual({ kind: "confirm", losesData: true });
+    expect(planGate(steps, { interactive: false })).toEqual({ kind: "refuse" });
+  });
+
+  it("a replace or delete without data is asked about, and goes ahead unattended", () => {
+    const steps = only((s) => s.name === "allow-health-checks");
+    expect(planGate(steps, { interactive: true })).toEqual({ kind: "confirm", losesData: false });
+    expect(planGate(steps, { interactive: false })).toEqual({ kind: "proceed" });
+  });
+
+  it("creates and updates only: no question", () => {
+    const steps = only((s) => s.op === "create" || s.op === "update");
+    expect(planGate(steps, { interactive: true })).toEqual({ kind: "proceed" });
+    expect(planGate([], { interactive: false })).toEqual({ kind: "proceed" });
+  });
+});

package/src/preview-plan.ts

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * What a Pulumi preview would change, per resource (#737). `state migrate`
+ * used to refuse with "a preview shows 36 change(s)" and the installer ran
+ * `pulumi up` blind, so an operator could not tell an IAM tweak from a
+ * Cloud SQL replace without assembling a `pulumi preview --diff` by hand.
+ *
+ * {@link collectPreviewSteps} turns the Automation API's engine events into
+ * {@link PlannedStep}s; {@link formatPlan} groups them (creates / updates /
+ * REPLACES / DELETES) and names the resources whose replace or delete loses
+ * data; {@link writePlanFile} keeps the full diff next to the install.
+ */
+
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { EngineEvent, OpType } from "@pulumi/pulumi/automation";
+
+/** The operations a plan lists; the rest (same, read, refresh) change nothing. */
+export type PlannedOp = "create" | "update" | "replace" | "delete" | "import";
+
+/** One resource a preview would change. */
+export interface PlannedStep {
+  readonly op: PlannedOp;
+  /** The Pulumi type token, e.g. `gcp:sql/databaseInstance:DatabaseInstance`. */
+  readonly type: string;
+  /** The resource's name in the program (the URN's last segment). */
+  readonly name: string;
+  readonly urn: string;
+  /** Properties that change. */
+  readonly diffs: readonly string[];
+  /** Properties that force the replace (replace steps only). */
+  readonly replaceReasons: readonly string[];
+}
+
+/**
+ * The step ops that make one planned change. A replace also emits
+ * `create-replacement` / `delete-replaced` sub-steps for the same URN; they
+ * are the same change and are not counted again.
+ */
+const PLANNED: Readonly<Partial<Record<OpType, PlannedOp>>> = {
+  create: "create",
+  update: "update",
+  replace: "replace",
+  delete: "delete",
+  import: "import",
+  "import-replacement": "replace",
+};
+
+/**
+ * Resources whose replace or delete loses data, by Pulumi type token, with
+ * the name an operator knows them by. Replacing any of them is never a
+ * "state catching up" detail.
+ */
+const DATA_BEARING: Readonly<Record<string, string>> = {
+  "gcp:sql/databaseInstance:DatabaseInstance": "Cloud SQL instance (all site data)",
+  "gcp:sql/database:Database": "Cloud SQL database",
+  "gcp:storage/bucket:Bucket": "Cloud Storage bucket (media, published site or state)",
+  "gcp:secretmanager/secret:Secret": "Secret Manager secret",
+  "gcp:secretmanager/secretVersion:SecretVersion": "Secret Manager secret value",
+  "gcp:firebase/project:Project": "Firebase project",
+  "gcp:firebase/hostingSite:HostingSite": "Firebase Hosting site",
+  "gcp:kms/keyRing:KeyRing": "Cloud KMS key ring",
+  "gcp:kms/cryptoKey:CryptoKey": "Cloud KMS key (decrypts the install's state)",
+  "gcp:bigquery/dataset:Dataset": "BigQuery dataset (edge logs)",
+};
+
+/** What a data-bearing resource holds, or null for any other type. */
+export function dataBearingKind(type: string): string | null {
+  return DATA_BEARING[type] ?? null;
+}
+
+/** Whether `step` would destroy data: a replace or delete of a data-bearing resource. */
+export function losesData(step: PlannedStep): boolean {
+  return (step.op === "replace" || step.op === "delete") && dataBearingKind(step.type) !== null;
+}
+
+/** Whether the plan replaces or deletes anything. */
+export function hasReplaceOrDelete(steps: readonly PlannedStep[]): boolean {
+  return steps.some((s) => s.op === "replace" || s.op === "delete");
+}
+
+/** The URN's last `::` segment: the name the program gave the resource. */
+function urnName(urn: string): string {
+  return urn.split("::").at(-1) ?? urn;
+}
+
+/**
+ * Collects a preview's planned steps from its engine events: pass
+ * {@link PreviewCollector.onEvent} as the preview's `onEvent`, read
+ * {@link PreviewCollector.steps} afterwards. One step per URN.
+ */
+export interface PreviewCollector {
+  readonly onEvent: (event: EngineEvent) => void;
+  steps(): PlannedStep[];
+}
+
+/** A fresh {@link PreviewCollector}. */
+export function collectPreviewSteps(): PreviewCollector {
+  const byUrn = new Map<string, PlannedStep>();
+  return {
+    onEvent: (event) => {
+      const m = event.resourcePreEvent?.metadata;
+      if (!m) return;
+      const op = PLANNED[m.op];
+      // The stack resource itself and providers are bookkeeping, not cloud changes.
+      if (!op || m.type === "pulumi:pulumi:Stack" || m.type.startsWith("pulumi:providers:")) {
+        return;
+      }
+      const prior = byUrn.get(m.urn);
+      if (prior?.op === "replace") return;
+      byUrn.set(m.urn, {
+        op,
+        type: m.type,
+        name: urnName(m.urn),
+        urn: m.urn,
+        diffs: [...(m.diffs ?? [])],
+        replaceReasons: op === "replace" ? [...(m.keys ?? [])] : [],
+      });
+    },
+    steps: () => [...byUrn.values()],
+  };
+}
+
+const GROUPS: readonly { readonly op: PlannedOp; readonly title: string }[] = [
+  { op: "delete", title: "DELETES" },
+  { op: "replace", title: "REPLACES (delete + create)" },
+  { op: "update", title: "Updates in place" },
+  { op: "create", title: "Creates" },
+  { op: "import", title: "Imports" },
+];
+
+/** One line for `step`: type, name, what changes and why it is replaced. */
+function stepLine(step: PlannedStep): string {
+  const kind = dataBearingKind(step.type);
+  const data = losesData(step) && kind ? `  <-- LOSES DATA: ${kind}` : "";
+  const why =
+    step.op === "replace" && step.replaceReasons.length > 0
+      ? ` (replaced because ${step.replaceReasons.join(", ")} changes)`
+      : step.diffs.length > 0 && step.op !== "create"
+        ? ` (${step.diffs.join(", ")})`
+        : "";
+  return `  ${step.type} ${step.name}${why}${data}`;
+}
+
+/**
+ * The plan as grouped lines, destructive groups first. Empty plan: one line
+ * saying so.
+ */
+export function formatPlan(steps: readonly PlannedStep[]): string[] {
+  if (steps.length === 0) return ["The preview plans no changes."];
+  const lines: string[] = [];
+  for (const g of GROUPS) {
+    const inGroup = steps.filter((s) => s.op === g.op);
+    if (inGroup.length === 0) continue;
+    lines.push(`${g.title} (${inGroup.length}):`, ...inGroup.map(stepLine));
+  }
+  const lost = steps.filter(losesData);
+  if (lost.length > 0) {
+    lines.push(
+      "",
+      `${lost.length} of these would destroy data: ${lost.map((s) => `${dataBearingKind(s.type)} ${s.name}`).join("; ")}.`,
+    );
+  }
+  return lines;
+}
+
+/**
+ * Write the full plan (every step with every changed property) to a file in
+ * `installRoot` and return its path. Names and property paths only, never
+ * values: the file holds no secret.
+ *
+ * @param label what the preview was for, part of the file name (`state-migrate`, `installer`)
+ */
+export function writePlanFile(
+  installRoot: string,
+  label: string,
+  steps: readonly PlannedStep[],
+  now: Date = new Date(),
+): string {
+  const path = join(installRoot, `plan-${label}-${now.toISOString().replace(/[:.]/g, "-")}.txt`);
+  const body = [
+    `Pulumi preview (${label}), ${now.toISOString()}: ${steps.length} change(s)`,
+    "",
+    ...formatPlan(steps),
+    "",
+    "Every step:",
+    ...steps.map((s) =>
+      [
+        `- ${s.op} ${s.urn}`,
+        ...(s.replaceReasons.length > 0
+          ? [`    replaced because: ${s.replaceReasons.join(", ")}`]
+          : []),
+        ...(s.diffs.length > 0 ? [`    changes: ${s.diffs.join(", ")}`] : []),
+      ].join("\n"),
+    ),
+    "",
+  ].join("\n");
+  writeFileSync(path, body, { mode: 0o600 });
+  return path;
+}
+
+/** What the installer does with a plan before `pulumi up` (#737). */
+export type PlanGate =
+  /** Nothing is replaced or deleted: apply. */
+  | { readonly kind: "proceed" }
+  /** Ask the operator y/N; `losesData` makes the question explicit about it. */
+  | { readonly kind: "confirm"; readonly losesData: boolean }
+  /** Nobody can be asked and data would be lost: stop, nothing applied. */
+  | { readonly kind: "refuse" };
+
+/**
+ * The gate for `steps`. A replace or delete is asked about whenever someone
+ * can answer. Without a terminal (`--non-interactive`, the install job)
+ * replaces and deletes of resources without data go ahead, already listed;
+ * a data-bearing one is refused: no flag stands in for that yes.
+ */
+export function planGate(
+  steps: readonly PlannedStep[],
+  opts: { readonly interactive: boolean },
+): PlanGate {
+  if (!hasReplaceOrDelete(steps)) return { kind: "proceed" };
+  const lost = steps.some(losesData);
+  if (opts.interactive) return { kind: "confirm", losesData: lost };
+  return lost ? { kind: "refuse" } : { kind: "proceed" };
+}

package/src/public-role-isolation.test.ts

@@ -46,7 +46,7 @@ describe("revokePublicRoleMembershipsArgs (#633)", () => {
 });
 
 describe("revokePublicRoleMemberships", () => {
-  const install = { projectId: "acme", env: "production" };
+  const install = { projectId: "acme", env: "production", credentials: "operator" } as const;
 
   it("finds the instance, then revokes", async () => {
     const { run, calls } = fake((l) => (l.startsWith("sql instances list") ? ok("pg-1\n") : ok()));
@@ -73,7 +73,18 @@ describe("revokePublicRoleMemberships", () => {
     const { run, calls } = fake(() => ok(""));
     const r = await revokePublicRoleMemberships(install, { run, sleep: noSleep });
     expect(r.status).toBe("failed");
-    expect(r.error).toBe("the Cloud SQL instance was not found");
+    expect(r.error).toBe("Could not find the Cloud SQL instance");
+    expect(calls).toHaveLength(1);
+  });
+
+  it("a failed listing is reported as such, not as a missing instance (#630)", async () => {
+    const { run, calls } = fake(() =>
+      fail("ERROR: Reauthentication failed. cannot prompt during non-interactive execution."),
+    );
+    const r = await revokePublicRoleMemberships(install, { run, sleep: noSleep });
+    expect(r.status).toBe("failed");
+    expect(r.error).toContain("gcloud auth login");
+    expect(r.error).not.toContain("Could not find");
     expect(calls).toHaveLength(1);
   });