@caelo-cms/provisioning 0.10.60 → 0.10.62

package/src/upgrader-gcp.ts

@@ -28,7 +28,7 @@ import { acquireBucketStateLock, GcsStateStore, realSyncGcloud } from "./state-s
 import type { AppRollPlan } from "./upgrade/app-roll.js";
 import { findServiceUrl } from "./upgrade/gcp-lookup.js";
 import { createIapHealthProbe } from "./upgrade/health.js";
-import { restIamTester } from "./upgrader-iam-preflight.js";
+import { type IamTester, restIamTester } from "./upgrader-iam-preflight.js";
 import type { UpdateQueue, UpgraderJobDeps } from "./upgrader-job.js";
 import type { JobLog } from "./upgrader-reporter.js";
 import { UPGRADER_TASK_TIMEOUT_MINUTES } from "./upgrader-setup.js";
@@ -59,9 +59,16 @@ export async function upgraderDatabaseHost(
 
 /**
  * The IAP-backed deep health probe for `plan`'s install (the upgrader job;
- * the converge job, #819, too).
+ * the converge job, #819, too). `accessJustChanged`: a converge right
+ * before changed access the probe relies on (health.ts); the upgrader job
+ * changes none.
  */
-export async function healthProbeFor(run: GcloudRunner, http: HttpFetch, plan: AppRollPlan) {
+export async function healthProbeFor(
+  run: GcloudRunner,
+  http: HttpFetch,
+  plan: AppRollPlan,
+  context: { readonly accessJustChanged: boolean },
+) {
   const { install } = plan;
   const urls: Partial<Record<"admin" | "gateway", string>> = {};
   for (const s of plan.services) {
@@ -81,11 +88,26 @@ export async function healthProbeFor(run: GcloudRunner, http: HttpFetch, plan: A
         adminServiceUrl: urls.admin as string,
         gatewayServiceUrl: urls.gateway as string,
       },
-      { run, http, sleep: realSleep },
+      { run, http, sleep: realSleep, accessJustChanged: context.accessJustChanged },
     ),
   };
 }
 
+/**
+ * The IAM self-check's tester as this job's own account: gcloud's token from
+ * the metadata server, so it sees exactly the job's grants (#818, #884).
+ */
+export function gcloudIamTester(run: GcloudRunner, http: HttpFetch): IamTester {
+  return restIamTester({
+    http,
+    token: async () => {
+      const t = await run(["auth", "print-access-token"]);
+      if (!t.ok) throw new Error(`gcloud auth print-access-token: ${t.stderr.trim()}`);
+      return t.stdout.trim();
+    },
+  });
+}
+
 /** Every dependency of {@link runUpgraderJob} except the database and the log. */
 export function gcpUpgraderDeps(
   placement: UpgraderPlacement,
@@ -109,14 +131,7 @@ export function gcpUpgraderDeps(
     execution: placement.execution,
     // #818 — the IAM self-check asks as the job's own account (gcloud's
     // token from the metadata server), so it sees exactly the job's grants.
-    iam: restIamTester({
-      http,
-      token: async () => {
-        const t = await run(["auth", "print-access-token"]);
-        if (!t.ok) throw new Error(`gcloud auth print-access-token: ${t.stderr.trim()}`);
-        return t.stdout.trim();
-      },
-    }),
+    iam: gcloudIamTester(run, http),
     // The default deps: the fixed registry and signer, never overridden.
     fetchManifest: (version) => fetchVerifiedReleaseManifest(version),
     // #815 — the lock names this execution, so a later run can break it
@@ -155,7 +170,7 @@ export function gcpUpgraderDeps(
         { projectId: placement.projectId, region: placement.region, imageOverride: imageRef },
         { run },
       ),
-    healthProbe: (plan) => healthProbeFor(run, http, plan),
+    healthProbe: (plan) => healthProbeFor(run, http, plan, { accessJustChanged: false }),
     now: () => new Date(),
     log,
   };

package/src/upgrader-iam-preflight.test.ts

@@ -19,6 +19,7 @@ import {
   restIamTester,
   runIamPreflight,
   testIamCall,
+  UPGRADER_PREFLIGHT_VOICE,
   upgraderAccessChecks,
 } from "./upgrader-iam-preflight.js";
 import {
@@ -127,7 +128,9 @@ describe("upgraderAccessChecks", () => {
         ["iam.serviceAccounts.actAs"],
       ],
     ]);
-    expect(preflightMissingReason(r.missing)).toContain("quality-audit job");
+    expect(preflightMissingReason(r.missing, UPGRADER_PREFLIGHT_VOICE)).toContain(
+      "quality-audit job",
+    );
   });
 
   it("never needs a permission only a forbidden role would give (no compute, no IAM admin)", () => {
@@ -185,7 +188,7 @@ describe("runIamPreflight", () => {
       "run.jobs.run",
       "storage.objects.list",
     ]);
-    const reason = preflightMissingReason(r.missing);
+    const reason = preflightMissingReason(r.missing, UPGRADER_PREFLIGHT_VOICE);
     expect(reason).toContain("run the database migrations");
     expect(reason).toContain("missing storage.objects.list on gs://acme-caelo-ops");
     expect(reason).toContain("Run the upgrade once with Cloud Shell");
@@ -209,7 +212,7 @@ describe("runIamPreflight", () => {
     if (r.kind !== "missing") return;
     expect(r.missing.flatMap((m) => m.missing)).not.toContain("storage.objects.get");
     expect(r.missing.flatMap((m) => m.unchecked ?? [])).toEqual(["storage.objects.get"]);
-    expect(preflightMissingReason(r.missing)).toContain(
+    expect(preflightMissingReason(r.missing, UPGRADER_PREFLIGHT_VOICE)).toContain(
       "storage.objects.get on gs://acme-caelo-ops/install/ could not be checked",
     );
   });

package/src/upgrader-iam-preflight.ts

@@ -84,7 +84,7 @@ export type IamResource =
 
 /** One thing the run will do, the permissions it takes, and where. */
 export interface AccessCheck {
-  /** What the upgrader could not do without them, in plain words. */
+  /** What the job could not do without them, in plain words. */
   readonly need: string;
   readonly resource: IamResource;
   readonly permissions: readonly string[];
@@ -304,11 +304,32 @@ export async function runIamPreflight(
 const OBJECT_LIST = "storage.objects.list";
 const OBJECT_GET = "storage.objects.get";
 
+/**
+ * Who ran a self-check and how its access is repaired, for the request's
+ * end reason. The upgrader and the converge job (converge-job-preflight.ts)
+ * share the check; their identities and their repair differ.
+ */
+export interface PreflightVoice {
+  /** The job, as the sentence names it: "the upgrader". */
+  readonly subject: string;
+  /** The one next step that re-converges its grants. */
+  readonly repair: string;
+}
+
+/** The upgrader job's voice: Cloud Shell's upgrade re-converges upgrader-setup.ts. */
+export const UPGRADER_PREFLIGHT_VOICE: PreflightVoice = {
+  subject: "the upgrader",
+  repair: "Run the upgrade once with Cloud Shell; it repairs the upgrader's access.",
+};
+
 /**
  * The request's end reason for missing permissions: every one of them, each
  * with what it is for, then the one next step.
  */
-export function preflightMissingReason(missing: readonly MissingAccess[]): string {
+export function preflightMissingReason(
+  missing: readonly MissingAccess[],
+  voice: PreflightVoice,
+): string {
   const lines = missing.map((m) => {
     const where = resourceName(m.check.resource);
     const parts = [
@@ -321,12 +342,12 @@ export function preflightMissingReason(missing: readonly MissingAccess[]): strin
     ];
     return `it ${m.missing.length > 0 ? "cannot" : "may not be able to"} ${m.check.need} (${parts.join("; ")})`;
   });
-  return `Nothing was changed: the upgrader checked its access before starting and is missing permissions this update needs — ${lines.join("; ")}. Run the upgrade once with Cloud Shell; it repairs the upgrader's access.`;
+  return `Nothing was changed: ${voice.subject} checked its access before starting and is missing permissions this update needs — ${lines.join("; ")}. ${voice.repair}`;
 }
 
 /** The request's end reason when IAM could not be asked. */
-export function preflightErrorReason(errors: readonly string[]): string {
-  return `Nothing was changed: the upgrader could not check its access before starting (${errors.join("; ")}). Try again in a few minutes; if it keeps failing, run the upgrade once with Cloud Shell.`;
+export function preflightErrorReason(errors: readonly string[], voice: PreflightVoice): string {
+  return `Nothing was changed: ${voice.subject} could not check its access before starting (${errors.join("; ")}). Try again in a few minutes; if it keeps failing: ${voice.repair}`;
 }
 
 /** A resource's full name, as IAM and the messages name it. */

package/src/upgrader-job.ts

@@ -70,6 +70,7 @@ import {
 import { restoreCommand, takeSqlBackup } from "./upgrade/backup.js";
 import {
   findServingImage,
+  lookupFailure,
   resolveGcpResourceName,
   servingImageDigests,
 } from "./upgrade/gcp-lookup.js";
@@ -81,6 +82,7 @@ import {
   preflightErrorReason,
   preflightMissingReason,
   runIamPreflight,
+  UPGRADER_PREFLIGHT_VOICE,
   upgraderAccessChecks,
 } from "./upgrader-iam-preflight.js";
 import {
@@ -467,11 +469,15 @@ export async function runUpgraderJob(deps: UpgraderJobDeps): Promise<UpgraderRun
       return stopWith(
         "needs_cloud_shell",
         ["iam-preflight"],
-        preflightMissingReason(access.missing),
+        preflightMissingReason(access.missing, UPGRADER_PREFLIGHT_VOICE),
       );
     }
     if (access.kind === "error") {
-      return stopWith("failed", ["iam-preflight"], preflightErrorReason(access.errors));
+      return stopWith(
+        "failed",
+        ["iam-preflight"],
+        preflightErrorReason(access.errors, UPGRADER_PREFLIGHT_VOICE),
+      );
     }
     r.info("The upgrader has every permission this update needs.");
 
@@ -491,6 +497,7 @@ export async function runUpgraderJob(deps: UpgraderJobDeps): Promise<UpgraderRun
         env: deps.env,
         domain: meta.domain,
         stagingHost: meta.stagingDomain ?? `staging.${meta.domain}`,
+        credentials: "job",
       },
       images,
       deps.run,
@@ -510,7 +517,7 @@ export async function runUpgraderJob(deps: UpgraderJobDeps): Promise<UpgraderRun
     const sBak = r.step("Backing up the database before anything changes...");
     const backup = await takeSqlBackup(
       deps.run,
-      { projectId: deps.projectId, env: deps.env },
+      { projectId: deps.projectId, env: deps.env, credentials: "job" },
       `pre-upgrade to ${m.version}`,
       deps.now,
     );
@@ -665,9 +672,10 @@ async function servingDigests(
       deps.projectId,
       deps.region,
     );
-    const image = service
-      ? await findServingImage(deps.run, deps.projectId, deps.region, service)
-      : null;
+    if (service.status !== "found") {
+      return { ok: false, error: lookupFailure(service, `${prefix}* Cloud Run service`, "job") };
+    }
+    const image = await findServingImage(deps.run, deps.projectId, deps.region, service.name);
     if (!image) return { ok: false, error: `could not read which image the ${slug} serves` };
     digests[slug] = servingImageDigests(image);
   }

package/src/upgrader-reporter.ts

@@ -96,6 +96,7 @@ export function eventReporter(sink: EventSink, log: JobLog, requestId: string):
         done: (m) => emit("success", m),
         failed: (m) => emit("error", m),
         warned: (m) => emit("warn", m),
+        progress: (m) => emit("info", m),
       };
     },
     info: (m) => emit("info", m),

package/src/wizards/gcp-pulumi.test.ts

@@ -193,7 +193,7 @@ describe("pulumiGcpEnv with the install's ops bucket (#696)", () => {
   });
 });
 
-describe("alignedStackSettings (#696 — the package's stale Pulumi.production.yaml)", () => {
+describe("alignedStackSettings (#696 — a settings file the state moved away from)", () => {
   const KMS =
     "gcpkms://projects/acme/locations/europe-west1/keyRings/caelo/cryptoKeys/pulumi-state";
   const gcs = { kind: "gcs" as const, secretsProvider: KMS };

package/src/wizards/gcp-pulumi.ts

@@ -11,12 +11,14 @@
  * config and up; failures surface inline with provider errors.
  */
 
-import { resolve as resolvePath } from "node:path";
+import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { join, relative, resolve as resolvePath } from "node:path";
 import * as pulumi from "@pulumi/pulumi/automation";
 import { AUDIT_PARALLELISM_DEFAULT } from "../audit-job-setup.js";
 import { checkpointableOutputs } from "../checkpoint-secrets.js";
 import { GCP_STACK_ENV } from "../gcp-names.js";
-import type { ImageDigests } from "../install-state.js";
+import { type ImageDigests, stackWorkDir } from "../install-state.js";
+import { collectPreviewSteps, type PlannedStep } from "../preview-plan.js";
 import {
   AMBIENT_GOOGLE_CREDENTIAL_ENV,
   withoutAmbientGoogleCredentials,
@@ -102,18 +104,99 @@ export interface PulumiUpResult {
 }
 
 /**
- * Resolve the GCP stack workdir relative to the installed package.
- * Works whether the CLI runs from source (apps/admin/scripts/...)
- * or from the published npm tarball (node_modules/@caelo-cms/...).
+ * The stack program shipped in the package (`stacks/<provider>/`: its
+ * Pulumi.yaml and index.ts), whether the CLI runs from source or from the
+ * published tarball. Read-only at runtime: Pulumi runs in the install's own
+ * work dir (install-state.ts `stackWorkDir`, {@link prepareStackWorkDir}),
+ * never here.
  */
-export function gcpStackWorkDir(provider: "gcp" | "gcp-firebase" = "gcp"): string {
-  // The Pulumi.yaml + stacks/<provider>/index.ts ship in the npm
-  // tarball under `stacks/<provider>/`. From this file's location at
-  // runtime (dist/wizards/gcp-pulumi.js), the stack dir is two
-  // levels up + into the provider-specific stack folder.
+export function packageStackDir(provider: "gcp" | "gcp-firebase"): string {
+  // From this file at runtime (src/ or dist/wizards/), two levels up.
   return resolvePath(import.meta.dir, `../../stacks/${provider}`);
 }
 
+/**
+ * The package's project file with `main` pointing from `workDir` at the
+ * package's stack program, so Pulumi runs that program (its relative
+ * imports, tsconfig and node_modules resolve from the package) while the
+ * stack settings file stays in `workDir`. Pulumi joins `main` to the
+ * project dir, so it must be relative — and computed between real paths:
+ * Pulumi resolves the project dir through symlinks (macOS `/var` →
+ * `/private/var`, a symlinked home or package cache), so a path relative to
+ * the symlinked spelling points nowhere.
+ *
+ * @param programDir the package's stack dir, symlinks resolved
+ * @param workDir the install's work dir, symlinks resolved
+ */
+export function workDirProjectFile(
+  projectYaml: string,
+  programDir: string,
+  workDir: string,
+): string {
+  const mains = [...projectYaml.matchAll(/^main:\s*(\S+)\s*$/gm)];
+  if (mains.length !== 1) {
+    throw new Error(
+      `${join(programDir, "Pulumi.yaml")} must name its program in exactly one top-level "main:" line (found ${mains.length}); the CLI points the install's stack work dir at it.`,
+    );
+  }
+  const program = resolvePath(programDir, (mains[0] as RegExpMatchArray)[1] as string);
+  return projectYaml.replace(/^main:\s*\S+\s*$/m, `main: ${relative(workDir, program)}`);
+}
+
+/**
+ * Create or refresh the install's stack work dir (install-state.ts
+ * `stackWorkDir`) and
+ * return it. The project file is rewritten on every run: each `bunx`
+ * version unpacks the package somewhere else. The settings file is left as
+ * it is (it is the install's own). Atomic (temp file + rename), so two runs
+ * for the same install never leave a half-written project file.
+ */
+export function prepareStackWorkDir(
+  installRoot: string,
+  provider: "gcp" | "gcp-firebase",
+  programDir: string = packageStackDir(provider),
+): string {
+  const workDir = stackWorkDir(installRoot, provider);
+  mkdirSync(workDir, { recursive: true, mode: 0o700 });
+  const project = workDirProjectFile(
+    readFileSync(join(programDir, "Pulumi.yaml"), "utf8"),
+    realpathSync(programDir),
+    realpathSync(workDir),
+  );
+  const target = join(workDir, "Pulumi.yaml");
+  const tmp = `${target}.${process.pid}.tmp`;
+  writeFileSync(tmp, project, { mode: 0o600 });
+  renameSync(tmp, target);
+  return workDir;
+}
+
+/**
+ * Refuse to run Pulumi when the stack config names another project than
+ * the install's (#736, CLAUDE.md §2): a preview or `up` would plan the
+ * install's state against another install's project — replacing its
+ * Firebase site, buckets and IAM members. Defense in depth: each install
+ * has its own work dir, so nothing should ever put another project there.
+ */
+export async function assertStackProject(
+  stack: pulumi.Stack,
+  provider: "gcp" | "gcp-firebase",
+  projectId: string,
+): Promise<void> {
+  const key = `caelo-${provider}:project`;
+  const configured = await stack.getConfig(key).then(
+    (v) => v.value,
+    (e: unknown) => {
+      if (/not found/i.test(String(e))) return undefined;
+      throw e;
+    },
+  );
+  if (configured !== projectId) {
+    throw new Error(
+      `the stack config ${join(stack.workspace.workDir, `Pulumi.${GCP_STACK_ENV}.yaml`)} names project ${configured ?? "(none)"}, but this install is ${projectId}. Nothing was run. Delete that file and re-run: the CLI writes the install's config again.`,
+    );
+  }
+}
+
 /**
  * The stack config keys that pin each Cloud Run service's image
  * (`<ns>:image-digest-<service>`, read by `imageRef` / `imageTag` in the
@@ -144,16 +227,17 @@ export function imageDigestConfig(
  * @returns the override keys it removed.
  */
 export async function writeImageDigestsToStack(inputs: {
+  installRoot: string;
   backend: ResolvedBackend;
   provider: "gcp" | "gcp-firebase";
   digests: ImageDigests;
 }): Promise<{ removedOverrides: string[] }> {
-  const stack = await selectInstallStack(inputs.backend, inputs.provider);
+  const stack = await selectInstallStack(inputs.installRoot, inputs.backend, inputs.provider);
   await stack.setAllConfig(imageDigestConfig(inputs.provider, inputs.digests));
   // Read the settings file, not `getAllConfig()`: `pulumi config` refuses
   // to list a stack whose required keys (domain, project, …) are unset, and
-  // the settings file in a freshly unpacked `bunx` package holds only what
-  // this call just wrote — so every upgrade from a new CLI version failed.
+  // a settings file the installer never wrote (an install from before the
+  // per-install work dir, #736) holds only what this call just wrote.
   const settings = await stack.workspace.stackSettings(stack.name);
   const removedOverrides = presentImageOverrides(inputs.provider, settings.config);
   if (removedOverrides.length > 0) await stack.removeAllConfig(removedOverrides);
@@ -180,24 +264,24 @@ export function presentImageOverrides(
  * @returns the output's value, or undefined when the stack has no such output
  */
 export async function readStackOutput(inputs: {
+  installRoot: string;
   backend: ResolvedBackend;
   provider: "gcp" | "gcp-firebase";
   name: string;
 }): Promise<unknown> {
-  const stack = await selectInstallStack(inputs.backend, inputs.provider);
+  const stack = await selectInstallStack(inputs.installRoot, inputs.backend, inputs.provider);
   const outputs = await stack.outputs();
   return outputs[inputs.name]?.value;
 }
 
 /**
- * The stack's settings file in the package's stack dir with secrets
- * settings that can't contradict the install's state, or null when it is
- * already fine (#696).
+ * The install's stack settings file with secrets settings that can't
+ * contradict its state, or null when it is already fine (#696).
  *
- * That file (`Pulumi.production.yaml`) lives in the package, not with the
- * state: every `bunx` version unpacks its own, and installs of the same
- * provider on one machine share it, so it can name another install's
- * passphrase salt or KMS key. A file naming anything but the install's own
+ * That file (`Pulumi.production.yaml`, in the install's work dir) is not
+ * the state: `state migrate` moves the state to another backend and secrets
+ * provider, and the file can still name the old passphrase salt or KMS key.
+ * A file naming anything but the install's own
  * KMS key loses its secrets-provider fields and the `secure:` values
  * encrypted under them (no stack config the CLI sets is secret);
  * `PULUMI_FALLBACK_TO_STATE_SECRETS_MANAGER` (resolveBackend) then makes
@@ -230,17 +314,16 @@ export function alignedStackSettings(
 }
 
 /**
- * Bring the package's stack settings file in line with the install's backend
+ * Bring the install's stack settings file in line with its backend
  * ({@link alignedStackSettings}) before Pulumi reads it.
+ *
+ * @param workDir the install's prepared work dir ({@link prepareStackWorkDir})
  */
 export async function alignStackSettingsFile(
+  workDir: string,
   backend: ResolvedBackend,
-  provider: "gcp" | "gcp-firebase",
 ): Promise<void> {
-  const ws = await pulumi.LocalWorkspace.create({
-    workDir: gcpStackWorkDir(provider),
-    envVars: stateOnlyEnv(backend),
-  });
+  const ws = await pulumi.LocalWorkspace.create({ workDir, envVars: stateOnlyEnv(backend) });
   let settings: pulumi.StackSettings;
   try {
     settings = await ws.stackSettings(GCP_STACK_ENV);
@@ -266,14 +349,16 @@ export function stateOnlyEnv(backend: Pick<ResolvedBackend, "envVars">): Record<
   };
 }
 
-/** The install's existing stack, on its backend. */
+/** The install's existing stack, on its backend, in its own work dir. */
 export async function selectInstallStack(
+  installRoot: string,
   backend: ResolvedBackend,
   provider: "gcp" | "gcp-firebase",
 ): Promise<pulumi.Stack> {
-  await alignStackSettingsFile(backend, provider);
+  const workDir = prepareStackWorkDir(installRoot, provider);
+  await alignStackSettingsFile(workDir, backend);
   return pulumi.LocalWorkspace.selectStack(
-    { stackName: GCP_STACK_ENV, workDir: gcpStackWorkDir(provider) },
+    { stackName: GCP_STACK_ENV, workDir },
     { envVars: stateOnlyEnv(backend) },
   );
 }
@@ -318,8 +403,8 @@ export interface StateResource {
 /**
  * The region an existing stack was deployed in, read from its state (the
  * stacks' explicit `gcp.Provider` carries it), or null for a stack with
- * nothing deployed. State, not stack config: the config file lives in the
- * package's stack dir, which a newer `bunx` version doesn't share.
+ * nothing deployed. State, not stack config: the state is authoritative,
+ * and the settings file of an install from before #736 starts empty.
  */
 export function deployedStackRegion(resources: ReadonlyArray<StateResource>): string | null {
   const regions = new Set(
@@ -368,10 +453,10 @@ export type StackConfigInputs = Pick<
 
 /**
  * Set every config value the stack reads, then its `secretReplication`
- * ({@link resolveSecretReplication}). The config file lives in the package's
- * stack dir, so every run sets all of it — the wizard before `up`, and
- * `state migrate` before the previews that prove a migration changed
- * nothing (#696).
+ * ({@link resolveSecretReplication}). The wizard sets all of it before every
+ * `up`, so install.json stays the source of truth; `state migrate` sets it
+ * before the previews that prove a migration changed nothing (#696) when
+ * the install's settings file does not hold it yet.
  *
  * @returns the secret replication now configured
  */
@@ -449,22 +534,34 @@ export function pulumiGcpEnv(
   };
 }
 
+/** Thrown when the review (preview-plan.ts planGate) stops `pulumi up` after the preview. */
+export class PulumiUpDeclinedError extends Error {
+  override readonly name = "PulumiUpDeclinedError";
+}
+
 /**
  * Run `pulumi up` against the GCP stack via the Automation SDK.
  * Streams resource-create events to the supplied onEvent callback so
  * the wizard can render a live progress bar.
+ *
+ * On a stack that already holds resources, a preview runs first (#737) and
+ * `review` sees its planned steps: it lists them and decides (planGate)
+ * whether `up` may apply them. Nothing is applied when it says no.
+ *
+ * @throws PulumiUpDeclinedError when `review` declines the plan
  */
 export async function pulumiUpGcp(
   inputs: PulumiUpInputs,
   onEvent: (kind: "resource" | "error" | "log", message: string) => void,
+  review: (steps: readonly PlannedStep[]) => Promise<boolean>,
 ): Promise<PulumiUpResult> {
   const env = pulumiGcpEnv(process.env, inputs);
 
   const provider = inputs.provider ?? "gcp";
   const stackName = GCP_STACK_ENV;
-  const workDir = gcpStackWorkDir(provider);
+  const workDir = prepareStackWorkDir(inputs.installRoot, provider);
 
-  await alignStackSettingsFile(inputs.backend, provider);
+  await alignStackSettingsFile(workDir, inputs.backend);
   const workspaceOpts = {
     envVars: env,
     // Used when the stack is created: a new install's secrets are
@@ -506,8 +603,20 @@ export async function pulumiUpGcp(
   }
 
   // Refresh state first to detect drift from any out-of-band changes.
+  await assertStackProject(stack, provider, inputs.projectId);
   await stack.refresh({ onOutput: (msg) => onEvent("log", msg) });
 
+  // #737 — never `up` a deployed stack blind: list what it would change
+  // (replaces and deletes first) and let the review stop it. A first run
+  // on an empty stack only creates, so it skips the extra preview.
+  if (stateResources.length > 0) {
+    const collector = collectPreviewSteps();
+    await stack.preview({ onEvent: collector.onEvent });
+    if (!(await review(collector.steps()))) {
+      throw new PulumiUpDeclinedError("pulumi up was not run: the planned changes were declined.");
+    }
+  }
+
   // Run `up`. The onEvent callback receives the same JSON-RPC events
   // Pulumi prints to stdout in --json mode.
   const result = await stack.up({