@caelo-cms/provisioning 0.10.61 → 0.10.62

package/src/stack-converge.ts

@@ -8,13 +8,17 @@
  *   - {@link planEnvUpdate}: the env-var flags for the `services update` that
  *     rolls the image, so env changes ride the same new revision — including
  *     moving a plain var to a Secret Manager reference.
- *   - {@link ensureStackInvariants}: IAM bindings + CDN settings. Each binding
+ *   - {@link ensureStackInvariants}: IAM bindings + CDN settings (incl. the
+ *     #891 response headers and the SVG backfill, static-svg-gcp.ts). Each binding
  *     is checked against the resource's policy first and only added when
  *     missing, so an operator without IAM-admin rights can still upgrade an
  *     install that is already in shape.
  *   - {@link ensureStackInvariants} also deletes the firewall rules GCP
  *     pre-populates on the `default` network (SSH, RDP, ICMP, internal)
  *     (default-firewall.ts), the one thing it removes.
+ *   - {@link ensureStackInvariants} opens a gcp-firebase gateway created
+ *     load-balancer-only to all traffic (#650, #732), before migrations:
+ *     the upgrade's own health check reaches it on its run.app URL.
  *   - {@link planMediaVolume}: the admin's media bucket volume (gen2 + Cloud
  *     Storage volume + mount), added in the same `services update` when
  *     missing.
@@ -55,6 +59,8 @@ import {
   stackIamInvariants,
   staticBackendBucketPrefix,
 } from "./stack-contract.js";
+import { GCP_STATIC_RESPONSE_HEADERS } from "./static-security-headers.js";
+import { ensureSvgDownloads } from "./static-svg-gcp.js";
 
 // ===========================================================================
 // Env vars
@@ -517,7 +523,10 @@ async function ensureIam(
   return outcomes;
 }
 
-/** Bring the `gcp` stack's static backend bucket to {@link STATIC_CDN_POLICY}. */
+/**
+ * Bring the `gcp` stack's static backend bucket to {@link STATIC_CDN_POLICY}
+ * and its custom response headers to {@link GCP_STATIC_RESPONSE_HEADERS}.
+ */
 async function ensureCdnPolicy(
   install: InstallTarget,
   run: GcloudRunner,
@@ -525,7 +534,7 @@ async function ensureCdnPolicy(
   const base = {
     id: `Cloud CDN policy of ${staticBackendBucketPrefix(install.env)}*`,
     onFailure: "warn" as const,
-    why: "immutable assets stay cached for a year instead of 1h (#555)",
+    why: "immutable assets stay cached for a year instead of 1h (#555), and every file is served nosniff (#891)",
   };
   const project = `--project=${install.projectId}`;
   const list = await run([
@@ -553,12 +562,18 @@ async function ensureCdnPolicy(
     "--format=json",
   ]);
   if (describe.ok) {
-    const cdn = (JSON.parse(describe.stdout) as { cdnPolicy?: Record<string, unknown> }).cdnPolicy;
+    const live = JSON.parse(describe.stdout) as {
+      cdnPolicy?: Record<string, unknown>;
+      customResponseHeaders?: unknown;
+    };
+    const cdn = live.cdnPolicy;
     const inShape =
       cdn !== undefined &&
       (Object.keys(STATIC_CDN_POLICY) as (keyof typeof STATIC_CDN_POLICY)[]).every(
         (k) => String(cdn[k]) === String(STATIC_CDN_POLICY[k]),
-      );
+      ) &&
+      JSON.stringify(live.customResponseHeaders ?? []) ===
+        JSON.stringify(GCP_STATIC_RESPONSE_HEADERS);
     if (inShape) return { ...base, status: "present" };
   }
   const update = await run([
@@ -571,6 +586,8 @@ async function ensureCdnPolicy(
     `--default-ttl=${STATIC_CDN_POLICY.defaultTtl}`,
     `--max-ttl=${STATIC_CDN_POLICY.maxTtl}`,
     `--client-ttl=${STATIC_CDN_POLICY.clientTtl}`,
+    // Replaces the bucket's list, so this is the complete set.
+    ...GCP_STATIC_RESPONSE_HEADERS.map((h) => `--custom-response-header=${h}`),
     "--quiet",
   ]);
   return update.ok
@@ -578,10 +595,62 @@ async function ensureCdnPolicy(
     : { ...base, status: "failed", error: update.stderr.trim() };
 }
 
+/** The ingress of a described service (`all`, `internal-and-cloud-load-balancing`, …; null: unset). */
+export function liveIngress(serviceJson: string): string | null {
+  const svc = JSON.parse(serviceJson) as {
+    metadata?: { annotations?: Record<string, string> };
+  };
+  return svc.metadata?.annotations?.["run.googleapis.com/ingress"] ?? null;
+}
+
+/**
+ * Open a gcp-firebase gateway to all traffic, as the stack declares it
+ * (`INGRESS_TRAFFIC_ALL` since #650). There is no load balancer on
+ * gcp-firebase: the staging domain mapping, remote-MCP clients and the
+ * upgrade's own health probe reach the gateway's run.app URL. A gateway
+ * created before #650 kept `internal-and-cloud-load-balancing` (only
+ * `pulumi up` would change it), answered those requests with Google's HTML
+ * 404, and every upgrade rolled back after its migrations (#732).
+ *
+ * Ingress is a service-level setting: the update creates no revision, so
+ * the serving one and the app-roll's rollback target stay as they are. On
+ * `gcp` the stack declares load-balancer-only and `staging-domain enable`
+ * (admin-domain.ts) opens it deliberately, so this never runs there.
+ */
+async function ensureGatewayIngress(
+  install: InstallTarget,
+  run: GcloudRunner,
+): Promise<InvariantOutcome> {
+  const service = install.services.gateway;
+  const base = {
+    id: `ingress all on ${service}`,
+    onFailure: "abort" as const,
+    why: "the gcp-firebase stack's gateway ingress (#650); the health check, the staging domain and remote MCP reach its run.app URL",
+  };
+  const where = [`--region=${install.region}`, `--project=${install.projectId}`];
+  const describe = await run(["run", "services", "describe", service, ...where, "--format=json"]);
+  if (!describe.ok) return { ...base, status: "failed", error: describe.stderr.trim() };
+  const live = liveIngress(describe.stdout);
+  if (live === "all") return { ...base, status: "present" };
+  const update = await run([
+    "run",
+    "services",
+    "update",
+    service,
+    ...where,
+    "--ingress=all",
+    "--quiet",
+  ]);
+  return update.ok
+    ? { ...base, id: `ingress ${live ?? "(unset)"} → all on ${service}`, status: "applied" }
+    : { ...base, status: "failed", error: update.stderr.trim() };
+}
+
 /**
  * Idempotently ensure every IAM binding and CDN setting the install's stack
- * declares (stack-contract.ts), and that the firewall rules GCP pre-populates
- * on the default network are gone (ABSENT_DEFAULT_FIREWALL_RULES). Bindings
+ * declares (stack-contract.ts), a gcp-firebase gateway's ingress, and that
+ * the firewall rules GCP pre-populates on the default network are gone
+ * (ABSENT_DEFAULT_FIREWALL_RULES). Bindings
  * are only added, never removed; those firewall rules are the only deletion. Never
  * throws for a gcloud failure; the report says what failed and whether the
  * upgrade must stop.
@@ -622,7 +691,11 @@ export async function ensureStackInvariants(
     ? invariants
     : invariants.filter((i) => i.member !== "iap-service-agent");
   outcomes.push(...(await ensureIam(checkable, install, projectNumber, run, sleep)));
-  if (install.provider === "gcp") outcomes.push(await ensureCdnPolicy(install, run));
+  if (install.provider === "gcp") {
+    outcomes.push(await ensureCdnPolicy(install, run));
+    outcomes.push(await ensureSvgDownloads(install, run));
+  }
+  if (install.provider === "gcp-firebase") outcomes.push(await ensureGatewayIngress(install, run));
   outcomes.push(...(await removeDefaultFirewallRules(install.projectId, { run })));
 
   return {

package/src/staging-admin.test.ts

@@ -22,7 +22,7 @@ const ok = (stdout = ""): GcloudResult => ({ ok: true, stdout, stderr: "", exitC
 const fail = (stderr: string): GcloudResult => ({ ok: false, stdout: "", stderr, exitCode: 1 });
 const SECRET = "s".repeat(40);
 const ADMIN = "https://caelo-production-admin-abc-ew.a.run.app";
-const target = { projectId: "proj", region: "europe-west1" };
+const target = { provider: "gcp-firebase" as const, projectId: "proj", region: "europe-west1" };
 
 function fakeGcloud(overrides: Record<string, GcloudResult> = {}) {
   const answers: Record<string, GcloudResult> = {

package/src/staging-admin.ts

@@ -20,7 +20,8 @@ import {
 export const STAGING_PROVISION_SCOPE = "staging.provision";
 const ENDPOINT = "/api/internal/staging/provision";
 
-export type StagingAdminTarget = AdminInternalTarget;
+/** `staging-domain enable` is gcp-firebase only (its domain mapping is). */
+export type StagingAdminTarget = Extract<AdminInternalTarget, { provider: "gcp-firebase" }>;
 export type StagingAdminDeps = AdminInternalDeps;
 
 /** Main's draft pages, as the admin reports them. */

package/src/state-backend.ts

@@ -127,8 +127,9 @@ export function localStateDir(installRoot: string): string {
  * Pulumi reaches the bucket and the KMS key with the operator's Application
  * Default Credentials. Both set `PULUMI_FALLBACK_TO_STATE_SECRETS_MANAGER`:
  * Pulumi then takes the secrets provider (KMS key or passphrase salt) from
- * the install's own state when the stack's config file in the package's
- * stack dir names none (wizards/gcp-pulumi.ts alignedStackSettings).
+ * the install's own state when the stack's settings file in its work dir
+ * (install-state.ts stackWorkDir) names none (wizards/gcp-pulumi.ts
+ * alignedStackSettings).
  *
  * @param meta the install (its `stateBackend`, absent = local)
  * @param opts.installRoot `~/.caelo-<id>`

package/src/state-command.test.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import type { GcloudResult } from "./gcloud.js";
+import { adcNote } from "./state-command.js";
+
+const result = (ok: boolean): GcloudResult => ({
+  ok,
+  stdout: ok ? "ya29.token" : "",
+  stderr: ok ? "" : "ERROR: Could not automatically determine credentials.",
+  exitCode: ok ? 0 : 1,
+});
+
+describe("adcNote (#816)", () => {
+  it("says nothing when this machine has working ADC", () => {
+    const calls: string[] = [];
+    expect(
+      adcNote((args) => {
+        calls.push(args.join(" "));
+        return result(true);
+      }),
+    ).toBeNull();
+    expect(calls).toEqual(["auth application-default print-access-token"]);
+  });
+
+  it("without ADC, says which commands need it and that upgrade does not", () => {
+    const note = adcNote(() => result(false));
+    expect(note).toContain("gcloud auth application-default login");
+    expect(note).toContain("upgrade, status and backup don't need them");
+  });
+});

package/src/state-command.ts

@@ -14,7 +14,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { confirm, isCancel, log, note } from "@clack/prompts";
 import { bold, red } from "kleur/colors";
-import { activeAccount } from "./gcloud.js";
+import { checkGcloudAuth } from "./gcloud.js";
 import {
   adoptStateBackend,
   currentMetadata,
@@ -30,6 +30,7 @@ import {
 } from "./install-state.js";
 import { installIapAllowlist } from "./operator-access.js";
 import { ensureOpsBackend } from "./ops-backend.js";
+import { writePlanFile } from "./preview-plan.js";
 import { provisionerServiceAccountEmail } from "./provisioner-identity.js";
 import { selfCommand } from "./self-command.js";
 import { attachInstall } from "./state-attach.js";
@@ -43,7 +44,7 @@ import {
 } from "./state-backend.js";
 import { migrateState } from "./state-migrate.js";
 import { realStatePulumiOps } from "./state-pulumi.js";
-import { acquireStateLock, GcsStateStore, realSyncGcloud } from "./state-store.js";
+import { acquireStateLock, GcsStateStore, realSyncGcloud, type SyncGcloud } from "./state-store.js";
 import { clackReporter } from "./upgrade/reporter.js";
 import { GCP_STACK_KNOB_DEFAULTS } from "./wizards/gcp-pulumi.js";
 
@@ -153,11 +154,12 @@ export async function stateCommand(argv: readonly string[]): Promise<void> {
     );
     process.exit(1);
   }
-  const operator = await activeAccount();
-  if (!operator) {
-    log.error(red("No active gcloud account. Run `gcloud auth login`, then re-run."));
+  const auth = await checkGcloudAuth();
+  if (!auth.ok) {
+    log.error(red(`Nothing was changed: ${auth.error}`));
     process.exit(1);
   }
+  const operator = auth.account;
   const provisioner = provisionerServiceAccountEmail(projectId);
   note(
     [
@@ -257,6 +259,7 @@ export async function stateCommand(argv: readonly string[]): Promise<void> {
         renameSync(dir, moved);
         return moved;
       },
+      writePlan: (label, steps) => writePlanFile(root, label, steps),
     },
   );
   if (!result.ok) {
@@ -272,6 +275,18 @@ export async function attachCommand(argv: readonly string[]): Promise<void> {
     console.log("Usage: cms-provision attach --project <gcp-project-id>");
     process.exit(2);
   }
+  attachProject(projectId);
+}
+
+/**
+ * Attach the install whose records live in `projectId`'s ops bucket (or
+ * refresh this machine's copy of them); exits with the reason when that
+ * fails. `upgrade --project` runs it first, so the break-glass upgrade
+ * needs nothing to survive in $HOME between runs (#816).
+ *
+ * @returns the attached install's id
+ */
+export function attachProject(projectId: string): string {
   const r = attachInstall(projectId, {
     run: realSyncGcloud,
     rootFor: installRoot,
@@ -287,7 +302,19 @@ export async function attachCommand(argv: readonly string[]): Promise<void> {
       ? `${r.domain} was already attached; its local copy of install.json is up to date.`
       : `Attached ${bold(r.domain)} (${r.installId}). status, upgrade, backup and re-running the installer now work from this machine.`,
   );
-  log.info(
-    "Infrastructure runs need Application Default Credentials once on this machine: gcloud auth application-default login",
-  );
+  const adc = adcNote(realSyncGcloud);
+  if (adc) log.info(adc);
+  return r.installId;
+}
+
+/**
+ * The note `attach` prints about Application Default Credentials, or null
+ * when this machine has working ones. Only infrastructure runs (re-running
+ * the installer, `state migrate`) use ADC; `upgrade`, `status` and `backup`
+ * do not, so a note on every attach sent Owners on a detour (#816).
+ */
+export function adcNote(run: SyncGcloud): string | null {
+  const r = run(["auth", "application-default", "print-access-token"]);
+  if (r.ok) return null;
+  return "No Application Default Credentials on this machine. upgrade, status and backup don't need them; re-running the installer or `state migrate` does: gcloud auth application-default login";
 }

package/src/state-migrate.test.ts

@@ -10,6 +10,7 @@
  */
 
 import { describe, expect, it } from "bun:test";
+import type { PlannedStep } from "./preview-plan.js";
 import {
   gcsBackendRecord,
   localStateNotice,
@@ -24,7 +25,7 @@ import {
   type StatePulumiOps,
   versionAtLeast,
 } from "./state-migrate.js";
-import { canonicalJson, changeCount } from "./state-pulumi.js";
+import { canonicalJson } from "./state-pulumi.js";
 import type { UpgradeReporter } from "./upgrade/reporter.js";
 
 interface FakeStack {
@@ -32,6 +33,20 @@ interface FakeStack {
   secretsProvider: string;
   pending: number;
   drift: number;
+  /** What the preview plans; `drift` in-place updates when unset. */
+  plan?: PlannedStep[];
+}
+
+/** `n` in-place updates of IAM members, the shape most drift has. */
+function updates(n: number): PlannedStep[] {
+  return Array.from({ length: n }, (_, i) => ({
+    op: "update" as const,
+    type: "gcp:projects/iAMMember:IAMMember",
+    name: `binding-${i}`,
+    urn: `urn:pulumi:production::caelo-gcp-firebase::gcp:projects/iAMMember:IAMMember::binding-${i}`,
+    diffs: ["member"],
+    replaceReasons: [],
+  }));
 }
 
 const ROOT = "/home/op/.caelo-gcp-firebase-acme";
@@ -60,7 +75,7 @@ function fakePulumi(version = "3.260.0") {
     async previewChanges(b) {
       const s = stacks.get(b.url);
       if (!s) throw new Error(`no stack in ${b.url}`);
-      return s.drift;
+      return s.plan ?? updates(s.drift);
     },
     async locked(b) {
       return faults.lockedUrl === b.url;
@@ -115,6 +130,7 @@ function recorder(): UpgradeReporter & { lines: string[] } {
         done: (m) => lines.push(`done ${m}`),
         failed: (m) => lines.push(`failed ${m}`),
         warned: (m) => lines.push(`warned ${m}`),
+        progress: (m) => lines.push(`progress ${m}`),
       };
     },
     info: (m) => lines.push(`info ${m}`),
@@ -137,6 +153,7 @@ function machine(initial: StateBackendRecord = { kind: "local" }) {
     locked: false,
     acceptCost: true,
     bucketRecord: (initial.kind === "gcs" ? "gcs" : null) as "gcs" | "local" | null,
+    planFiles: [] as { label: string; steps: number }[],
   };
   const meta = (): MigrateInstall => ({
     installId: "gcp-firebase-acme",
@@ -188,6 +205,10 @@ function machine(initial: StateBackendRecord = { kind: "local" }) {
       m.retired.push(`${ROOT}/state.migrated-x`);
       return `${ROOT}/state.migrated-x`;
     },
+    writePlan: (label, steps) => {
+      m.planFiles.push({ label, steps: steps.length });
+      return `${ROOT}/plan-${label}.txt`;
+    },
   };
   p.stacks.set(localUrl, {
     outputs: {
@@ -302,6 +323,8 @@ describe("migrateState — failures leave the source authoritative", () => {
     t.p.faults.driftOnTarget = 2;
     const r = await migrateState(t.meta(), { to: "remote", dryRun: false }, t.deps);
     expect(r.ok).toBe(false);
+    expect(t.report.lines.join("\n")).toContain("The copy's preview plans:");
+    expect(t.m.planFiles).toEqual([{ label: "state-migrate-copy", steps: 2 }]);
     expect(t.m.backend).toEqual({ kind: "local" });
     expect(t.p.stacks.has(t.gcsUrl)).toBe(false);
   });
@@ -327,6 +350,36 @@ describe("migrateState — failures leave the source authoritative", () => {
     expect(t.m.ensureRemoteCalls).toEqual([]);
   });
 
+  it("the refusal lists every planned step, replaces and data loss first, and writes the diff (#737)", async () => {
+    const t = machine();
+    const local = t.p.stacks.get(t.localUrl);
+    if (local) {
+      local.plan = [
+        ...updates(1),
+        {
+          op: "replace",
+          type: "gcp:sql/databaseInstance:DatabaseInstance",
+          name: "caelo-production-pg",
+          urn: "urn:pulumi:production::caelo-gcp-firebase::gcp:sql/databaseInstance:DatabaseInstance::caelo-production-pg",
+          diffs: ["region", "settings"],
+          replaceReasons: ["region"],
+        },
+      ];
+    }
+    const r = await migrateState(t.meta(), { to: "remote", dryRun: false }, t.deps);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error).toContain("a preview shows 2 change(s)");
+    expect(r.error).toContain(
+      "gcp:sql/databaseInstance:DatabaseInstance caelo-production-pg (replaced because region changes)  <-- LOSES DATA: Cloud SQL instance",
+    );
+    expect(r.error).toContain("gcp:projects/iAMMember:IAMMember binding-0 (member)");
+    expect(r.error.indexOf("REPLACES")).toBeLessThan(r.error.indexOf("Updates in place"));
+    expect(r.error).toContain(`Full diff: ${ROOT}/plan-state-migrate.txt`);
+    expect(t.m.planFiles).toEqual([{ label: "state-migrate", steps: 2 }]);
+    expect(t.m.backups).toBe(0);
+  });
+
   it("refuses a stack with pending operations", async () => {
     const t = machine();
     const local = t.p.stacks.get(t.localUrl);
@@ -448,6 +501,9 @@ describe("migrateState — dry run", () => {
     const out = t.report.lines.join("\n");
     expect(out).toContain("Dry run — nothing changed");
     expect(out).toContain("would create gs://acme-caelo-ops");
+    // #737 — the preview's list even when it would migrate.
+    expect(out).toContain("The preview plans no changes.");
+    expect(t.m.planFiles).toEqual([{ label: "state-migrate-dry-run", steps: 0 }]);
   });
 });
 
@@ -465,11 +521,6 @@ describe("helpers", () => {
     );
   });
 
-  it("changeCount ignores unchanged resources", () => {
-    expect(changeCount({ same: 120 })).toBe(0);
-    expect(changeCount({ same: 100, update: 2, create: 1 })).toBe(3);
-  });
-
   it("upgrade's notice points a local GCP install at state migrate, dry run first", () => {
     const n = localStateNotice({ installId: "gcp-firebase-viu-one", provider: "gcp-firebase" });
     expect(n).toContain("state migrate --install gcp-firebase-viu-one --dry-run");

package/src/state-migrate.ts

@@ -24,13 +24,19 @@
  *   6. flip — install.json records the new backend (locally and in the
  *      bucket); the old local state dir is renamed, never deleted.
  *
- * `--dry-run` runs the read-only preflight and reports what it would do.
+ * Every preview's planned changes are listed per resource (#737): grouped
+ * creates / updates / REPLACES / DELETES, data-bearing resources named, the
+ * full diff written to a file in the install dir.
+ *
+ * `--dry-run` runs the read-only preflight and reports what it would do,
+ * including the preview's list.
  * The engine takes its side effects as {@link MigrateDeps} so the whole
  * sequence is tested against fakes (state-migrate.test.ts); state-command.ts
  * wires the real Pulumi CLI, gcloud and file system.
  */
 
 import type { OpsBackendResult } from "./ops-backend.js";
+import { formatPlan, type PlannedStep } from "./preview-plan.js";
 import { selfCommand } from "./self-command.js";
 import {
   describeBackend,
@@ -56,8 +62,8 @@ export interface StatePulumiOps {
   stackExists(backend: ResolvedBackend): Promise<boolean>;
   /** Pending operations recorded in the stack's state (an interrupted run). */
   pendingOperations(backend: ResolvedBackend): Promise<number>;
-  /** Steps a preview would take other than "same". */
-  previewChanges(backend: ResolvedBackend): Promise<number>;
+  /** The changes a preview plans, per resource (none = converged). */
+  previewChanges(backend: ResolvedBackend): Promise<readonly PlannedStep[]>;
   /** sha256 of the stack outputs, secrets included. Never the values. */
   outputsDigest(backend: ResolvedBackend): Promise<string>;
   /** Whether a Pulumi operation holds the stack's lock in `backend` right now. */
@@ -106,6 +112,11 @@ export interface MigrateDeps {
   lock(): Promise<() => Promise<void>>;
   /** Rename the local state dir out of the way; returns where it went. */
   retireLocalState(): string | null;
+  /**
+   * Write a preview's full plan to a file in the install dir (preview-plan.ts
+   * writePlanFile); returns its path.
+   */
+  writePlan(label: string, steps: readonly PlannedStep[]): string;
 }
 
 export interface MigrateOptions {
@@ -141,6 +152,21 @@ export function versionAtLeast(a: string, b: string): boolean {
 
 const errorText = (e: unknown) => (e instanceof Error ? e.message : String(e));
 
+/**
+ * The plan's grouped list plus where its full diff was written, for a
+ * refusal or a dry run. A plan file that cannot be written is said, not
+ * fatal: the list is on screen anyway.
+ */
+function planReport(deps: MigrateDeps, label: string, steps: readonly PlannedStep[]): string {
+  let where: string;
+  try {
+    where = `Full diff: ${deps.writePlan(label, steps)}`;
+  } catch (e) {
+    where = `(The full diff could not be written: ${errorText(e)})`;
+  }
+  return [...formatPlan(steps).map((l) => `  ${l}`), where].join("\n");
+}
+
 /**
  * Run the migration. Never throws for an expected failure: the result says
  * what failed, and at every failure point the source backend is still the
@@ -198,6 +224,7 @@ export async function migrateState(
   let sourceDigest: string;
   /** The source's checkpoint, to notice another run writing it meanwhile. */
   let sourceState: string;
+  let sourcePlan: readonly PlannedStep[];
   try {
     const version = await pulumi.cliVersion();
     if (!version) {
@@ -232,12 +259,12 @@ export async function migrateState(
         error: `The stack records ${pending} pending operation(s) from an interrupted Pulumi run. Run upgrade first, then re-run the installer (${selfCommand()}, pick this install) so the stack is refreshed, and migrate after that. Nothing was changed.`,
       };
     }
-    const drift = await pulumi.previewChanges(from);
-    if (drift > 0) {
-      pre.failed(`A preview shows ${drift} change(s)`);
+    sourcePlan = await pulumi.previewChanges(from);
+    if (sourcePlan.length > 0) {
+      pre.failed(`A preview shows ${sourcePlan.length} change(s)`);
       return {
         ok: false,
-        error: `The stack is not converged (a preview shows ${drift} change(s)), so a copy can't be proven identical. Run upgrade first, then re-run the installer (${selfCommand()}, pick this install) until it reports no changes, and migrate after that. Nothing was changed.`,
+        error: `The stack is not converged (a preview shows ${sourcePlan.length} change(s)), so a copy can't be proven identical. Nothing was changed. The planned changes:\n${planReport(deps, "state-migrate", sourcePlan)}\nRun upgrade first, then re-run the installer (${selfCommand()}, pick this install): it shows this list again and asks before it replaces or deletes anything. Migrate once it reports no changes.`,
       };
     }
     sourceDigest = await pulumi.outputsDigest(from);
@@ -274,7 +301,12 @@ export async function migrateState(
         : []),
     );
     report.info(
-      ["Dry run — nothing changed. The migration would:", ...plan.map((p) => `  ${p}`)].join("\n"),
+      [
+        "Dry run — nothing changed. The migration would:",
+        ...plan.map((p) => `  ${p}`),
+        "The source stack's preview:",
+        planReport(deps, "state-migrate-dry-run", sourcePlan),
+      ].join("\n"),
     );
     return { ok: true, changed: false };
   }
@@ -385,8 +417,14 @@ export async function migrateState(
     }
     try {
       const changes = await pulumi.previewChanges(to);
-      if (changes > 0)
-        return abandon(`Verification failed: a preview of the copy shows ${changes} change(s)`);
+      if (changes.length > 0) {
+        report.info(
+          `The copy's preview plans:\n${planReport(deps, "state-migrate-copy", changes)}`,
+        );
+        return abandon(
+          `Verification failed: a preview of the copy shows ${changes.length} change(s) (listed above)`,
+        );
+      }
       if ((await pulumi.outputsDigest(to)) !== sourceDigest) {
         return abandon("Verification failed: the copy's outputs differ from the source's");
       }