@intentius/chant-lexicon-pulumi 0.124.55 → 0.124.57

package/src/check-step.ts

@@ -0,0 +1,316 @@
+/**
+ * The pulumi lexicon's steps in chant's check stage (#4633). `chant ci
+ * check` runs them after the `ci.hooks.check` hooks, for each workspace
+ * member of kind `pulumi` (`LexiconPlugin.checkSteps`,
+ * `@intentius/chant/components/check-steps`), so a product's check
+ * (`plywood check`) gets them through chant with nothing of its own:
+ *
+ * - `pulumi-install`: `pulumi install` (`plunge install` for a member on
+ *   plunge, `./member-engine.ts`) in the member's directory, which fetches
+ *   the program's dependencies and plugins the way `Pulumi.yaml` says;
+ * - `stack-config`: each stack's `Pulumi.<stack>.yaml` checked against the
+ *   project's config schema in `Pulumi.yaml`, with no command run (a key
+ *   with a type and no default must be set, a value must read as its type,
+ *   and a `secret: true` key must be encrypted). The stacks are the ones the
+ *   project lists by their files, plus the member's declared stack;
+ * - `pulumi-about`: `pulumi about --json`, which reports the engine, its
+ *   plugins and the backend for the report.
+ *
+ * The argv go through `runCheckPulumi` (`./run.ts`), which refuses any
+ * other. The environment is the check job's ({@link CheckStepsContext.env}):
+ * no forge token, no OIDC request variables, no cloud credential, so neither
+ * command can write a stack. A failure names the member and stack, and the
+ * check exits with chant's `failed` code.
+ *
+ * The runner is injectable, so the tests run no binary.
+ */
+import { execFile } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import type { CheckStageMember, CheckStepOutcome, CheckStepsAdapter, CheckStepsContext } from "@intentius/chant/components/check-steps";
+import { parseYAML } from "@intentius/chant/yaml";
+import { pulumiMemberEngine, type PulumiMemberEngine } from "./member-engine";
+import { engineEnv, pulumiRunFailure, runCheckPulumi, type PulumiRunner } from "./run";
+
+const execFileAsync = promisify(execFile);
+
+/** The lexicon name the report carries. */
+const LEXICON = "pulumi";
+
+/** A runner for `bin` with exactly `env` (the check job's), never the process's whole environment. */
+export function checkRunner(bin: PulumiMemberEngine, env: Record<string, string>): PulumiRunner {
+  return (args, opts) => execFileAsync(bin, args, { cwd: opts.cwd, maxBuffer: 64 * 1024 * 1024, env: engineEnv({ ...env, ...opts.env }) });
+}
+
+// ── Stack config against the project's schema ───────────────────────
+
+/** One key the project declares in `Pulumi.yaml`'s `config:`. */
+export interface PulumiConfigKey {
+  /** The full key, `<project>:<name>` for a project key. */
+  key: string;
+  type?: string;
+  items?: { type?: string };
+  secret: boolean;
+  /** Whether it has a `default` or a project-level `value`. */
+  hasDefault: boolean;
+}
+
+/** The project's config schema: its name, the keys it declares, and where its stack files are. */
+export interface PulumiProjectSchema {
+  project: string;
+  keys: PulumiConfigKey[];
+  /** The directory the stack files are in, relative to the project (`stackConfigDir`), or "." */
+  stackConfigDir: string;
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** The key in its full form: a bare name belongs to the project. */
+function fullKey(project: string, key: string): string {
+  return key.includes(":") ? key : `${project}:${key}`;
+}
+
+/** Read `Pulumi.yaml`'s schema from its parsed document. A short-form entry (`key: value`) is a value with no type. */
+export function pulumiProjectSchema(doc: unknown): PulumiProjectSchema {
+  const d = isRecord(doc) ? doc : {};
+  const project = typeof d.name === "string" ? d.name : "";
+  const config = isRecord(d.config) ? d.config : {};
+  const keys: PulumiConfigKey[] = [];
+  for (const [name, entry] of Object.entries(config)) {
+    const key = fullKey(project, name);
+    const schema = isRecord(entry) && ("type" in entry || "default" in entry || "value" in entry || "secret" in entry || "description" in entry || "items" in entry);
+    if (!schema) {
+      keys.push({ key, secret: false, hasDefault: true });
+      continue;
+    }
+    const e = entry as Record<string, unknown>;
+    keys.push({
+      key,
+      ...(typeof e.type === "string" ? { type: e.type } : {}),
+      ...(isRecord(e.items) && typeof e.items.type === "string" ? { items: { type: e.items.type } } : {}),
+      secret: e.secret === true,
+      hasDefault: "default" in e || "value" in e,
+    });
+  }
+  return { project, keys, stackConfigDir: typeof d.stackConfigDir === "string" && d.stackConfigDir.length > 0 ? d.stackConfigDir : "." };
+}
+
+const isSecure = (v: unknown): boolean => isRecord(v) && typeof v.secure === "string";
+
+/** Whether a scalar stack value reads as `type`. Values are strings once Pulumi reads them, so `"3"` is an integer. */
+function readsAs(type: string, value: unknown): boolean {
+  switch (type) {
+    case "string":
+      return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+    case "integer":
+      return (typeof value === "number" && Number.isInteger(value)) || (typeof value === "string" && /^-?[0-9]+$/.test(value.trim()));
+    case "boolean":
+      return typeof value === "boolean" || value === "true" || value === "false";
+    case "array":
+      return Array.isArray(value);
+    default:
+      return true;
+  }
+}
+
+/**
+ * What is wrong with one stack's config (`config:` of its
+ * `Pulumi.<stack>.yaml`, parsed) against the project's schema, as lines
+ * naming the stack and key. Empty when it passes. Keys of other namespaces
+ * (a provider's `aws:region`) are not checked: the project declares no type
+ * for them.
+ */
+export function pulumiStackConfigProblems(schema: PulumiProjectSchema, stack: string, stackDoc: unknown): string[] {
+  const raw = isRecord(stackDoc) && isRecord(stackDoc.config) ? stackDoc.config : {};
+  const values = new Map<string, unknown>();
+  for (const [k, v] of Object.entries(raw)) values.set(fullKey(schema.project, k), v);
+  const problems: string[] = [];
+  for (const k of schema.keys) {
+    if (!k.type && !k.secret) continue;
+    if (!values.has(k.key)) {
+      if (k.type && !k.hasDefault) problems.push(`stack ${stack} is missing the configuration value ${k.key} (type ${k.type}, no default)`);
+      continue;
+    }
+    const value = values.get(k.key);
+    if (k.secret && !isSecure(value)) {
+      problems.push(`stack ${stack} sets ${k.key} in plain text, and the project declares it secret; set it with pulumi config set --secret`);
+      continue;
+    }
+    if (isSecure(value) || !k.type) continue;
+    if (!readsAs(k.type, value)) {
+      problems.push(`stack ${stack} sets ${k.key} to ${JSON.stringify(value)}, which is not of type ${k.type}`);
+      continue;
+    }
+    if (k.type === "array" && k.items?.type && Array.isArray(value)) {
+      const bad = value.findIndex((item) => !isSecure(item) && !readsAs(k.items!.type!, item));
+      if (bad >= 0) problems.push(`stack ${stack} sets ${k.key}[${bad}] to ${JSON.stringify(value[bad])}, which is not of type ${k.items.type}`);
+    }
+  }
+  return problems;
+}
+
+/** The project's file in `dir`, `Pulumi.yaml` or `Pulumi.yml`. */
+function projectFile(dir: string): string | undefined {
+  return ["Pulumi.yaml", "Pulumi.yml"].map((f) => join(dir, f)).find((f) => existsSync(f));
+}
+
+/** The stacks the project lists by their `Pulumi.<stack>.yaml` files in `dir`, sorted. */
+export function listedStacks(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .map((f) => /^Pulumi\.(.+)\.ya?ml$/.exec(f)?.[1])
+    .filter((s): s is string => s !== undefined)
+    .sort();
+}
+
+/** The stack file for `stack` in `dir`, if there is one. */
+function stackFile(dir: string, stack: string): string | undefined {
+  return [`Pulumi.${stack}.yaml`, `Pulumi.${stack}.yml`].map((f) => join(dir, f)).find((f) => existsSync(f));
+}
+
+// ── pulumi about ────────────────────────────────────────────────────
+
+/** What `pulumi about --json` reported, for the check report. */
+export interface PulumiAboutDetail {
+  engine: PulumiMemberEngine;
+  version?: string;
+  plugins: Array<{ name: string; version?: string }>;
+  backend?: { name?: string; url?: string; user?: string };
+}
+
+/** Read `pulumi about --json`'s document. Undefined when it is not JSON. */
+export function pulumiAboutDetail(engine: PulumiMemberEngine, stdout: string | undefined): PulumiAboutDetail | undefined {
+  if (!stdout) return undefined;
+  let doc: unknown;
+  try {
+    doc = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(doc)) return undefined;
+  const cli = isRecord(doc.cli) ? doc.cli : {};
+  const plugins = Array.isArray(doc.plugins)
+    ? doc.plugins.filter(isRecord).map((p) => ({ name: String(p.name ?? ""), ...(typeof p.version === "string" ? { version: p.version } : {}) })).filter((p) => p.name)
+    : [];
+  const b = isRecord(doc.backend) ? doc.backend : undefined;
+  const backend = b
+    ? { ...(typeof b.name === "string" ? { name: b.name } : {}), ...(typeof b.url === "string" ? { url: b.url } : {}), ...(typeof b.user === "string" ? { user: b.user } : {}) }
+    : undefined;
+  return { engine, ...(typeof cli.version === "string" ? { version: cli.version } : {}), plugins, ...(backend ? { backend } : {}) };
+}
+
+// ── The steps ───────────────────────────────────────────────────────
+
+/** The last lines of what a failed run printed, for its reason. */
+function tail(text: string | undefined): string {
+  const lines = (text ?? "").trim().split("\n").filter(Boolean);
+  return lines.slice(-3).join(" | ");
+}
+
+export interface PulumiCheckStepsOptions {
+  /** The runner for an engine, given the check job's environment. Default {@link checkRunner}. */
+  runner?: (engine: PulumiMemberEngine, env: Record<string, string>) => PulumiRunner;
+}
+
+/** The steps for one member, in order: install, each stack's config, about. */
+export async function pulumiMemberCheck(member: CheckStageMember, ctx: Pick<CheckStepsContext, "env" | "log">, opts: PulumiCheckStepsOptions = {}): Promise<CheckStepOutcome[]> {
+  const fields = member.fields ?? {};
+  const declaredEngine = fields.engine === "pulumi" || fields.engine === "plunge" ? fields.engine : undefined;
+  const declaredStack = typeof fields.stack === "string" && fields.stack.length > 0 ? fields.stack : undefined;
+  const { engine } = pulumiMemberEngine(member.dir, declaredEngine, { env: ctx.env });
+  const run = (opts.runner ?? checkRunner)(engine, ctx.env);
+  const out: CheckStepOutcome[] = [];
+  const base = { lexicon: LEXICON, member: member.name };
+
+  const file = projectFile(member.dir);
+  if (!file) {
+    out.push({ ...base, step: "pulumi-install", exit: 1, outcome: "failed", reason: `member ${member.name} has no Pulumi.yaml in ${member.dir}` });
+    return out;
+  }
+
+  // pulumi install
+  let installed = true;
+  try {
+    await runCheckPulumi(run, ["install"], member.dir);
+    out.push({ ...base, step: "pulumi-install", exit: 0, outcome: "passed" });
+  } catch (err) {
+    installed = false;
+    const f = pulumiRunFailure(err);
+    const why = f.missingBinary ? `${engine} is not installed in the check job` : tail(f.stderr) || tail(f.stdout) || f.message;
+    out.push({ ...base, step: "pulumi-install", exit: f.exitCode ?? 1, outcome: "failed", reason: `${engine} install failed for member ${member.name}: ${why}` });
+  }
+
+  // Stack config, run by nothing but this module.
+  let schema: PulumiProjectSchema | undefined;
+  try {
+    schema = pulumiProjectSchema(parseYAML(readFileSync(file, "utf-8")));
+  } catch (err) {
+    out.push({ ...base, step: "stack-config", exit: 1, outcome: "failed", reason: `member ${member.name}: ${file} does not read as YAML (${err instanceof Error ? err.message : String(err)})` });
+  }
+  if (schema) {
+    const stackDir = join(member.dir, schema.stackConfigDir);
+    const stacks = [...new Set([...listedStacks(stackDir), ...(declaredStack ? [declaredStack] : [])])].sort();
+    if (stacks.length === 0) out.push({ ...base, step: "stack-config", exit: 0, outcome: "skipped", reason: `member ${member.name} lists no stack (no Pulumi.<stack>.yaml in ${stackDir})` });
+    for (const stack of stacks) {
+      const at = stackFile(stackDir, stack);
+      let doc: unknown = {};
+      if (at) {
+        try {
+          doc = parseYAML(readFileSync(at, "utf-8"));
+        } catch (err) {
+          out.push({ ...base, step: "stack-config", stack, exit: 1, outcome: "failed", reason: `member ${member.name}, stack ${stack}: ${at} does not read as YAML (${err instanceof Error ? err.message : String(err)})` });
+          continue;
+        }
+      }
+      const problems = pulumiStackConfigProblems(schema, stack, doc);
+      out.push(
+        problems.length === 0
+          ? { ...base, step: "stack-config", stack, exit: 0, outcome: "passed" }
+          : { ...base, step: "stack-config", stack, exit: 1, outcome: "failed", reason: `member ${member.name}: ${problems.join("; ")}`, detail: { problems } },
+      );
+    }
+  }
+
+  // pulumi about --json
+  if (!installed) {
+    out.push({ ...base, step: "pulumi-about", exit: 0, outcome: "skipped", reason: `member ${member.name}: ${engine} install failed, so about did not run` });
+    return out;
+  }
+  const aboutArgs = declaredStack ? ["about", "--json", "--stack", declaredStack] : ["about", "--json"];
+  const stackPart = declaredStack ? { stack: declaredStack } : {};
+  try {
+    const { stdout } = await runCheckPulumi(run, aboutArgs, member.dir);
+    const detail = pulumiAboutDetail(engine, stdout);
+    out.push(
+      detail
+        ? { ...base, step: "pulumi-about", ...stackPart, exit: 0, outcome: "passed", detail }
+        : { ...base, step: "pulumi-about", ...stackPart, exit: 1, outcome: "failed", reason: `${engine} about --json for member ${member.name} printed no JSON` },
+    );
+  } catch (err) {
+    const f = pulumiRunFailure(err);
+    // about exits non-zero when one of its reads fails (no backend login in a check job), and still prints what it read.
+    const detail = pulumiAboutDetail(engine, f.stdout);
+    if (detail) {
+      ctx.log(`pulumi check: ${engine} about for ${member.name} exited ${f.exitCode ?? 1} and reported: ${tail(f.stderr) || "no reason"}`);
+      out.push({ ...base, step: "pulumi-about", ...stackPart, exit: f.exitCode ?? 1, outcome: "passed", detail });
+    } else {
+      const why = f.missingBinary ? `${engine} is not installed in the check job` : tail(f.stderr) || f.message;
+      out.push({ ...base, step: "pulumi-about", ...stackPart, exit: f.exitCode ?? 1, outcome: "failed", reason: `${engine} about failed for member ${member.name}${declaredStack ? `, stack ${declaredStack}` : ""}: ${why}` });
+    }
+  }
+  return out;
+}
+
+/** The pulumi lexicon's check steps, for `LexiconPlugin.checkSteps`. */
+export function pulumiCheckSteps(opts: PulumiCheckStepsOptions = {}): CheckStepsAdapter {
+  return {
+    lexicon: LEXICON,
+    kinds: ["pulumi"],
+    async run(ctx) {
+      const out: CheckStepOutcome[] = [];
+      for (const member of ctx.members) out.push(...(await pulumiMemberCheck(member, ctx, opts)));
+      return out;
+    },
+  };
+}

package/src/composites/pulumi-adopt-op.test.ts

@@ -79,6 +79,23 @@ describe("PulumiAdoptOp", () => {
     expect(preview.args?.file).toMatchObject({ step: "export-1", path: "file" });
   });
 
+  test("the stack's backend reaches all four steps, Preview and Adopt included", () => {
+    const backend = "plunge+s3://state?region=us-east-1";
+    const op = props({
+      name: "adopt",
+      stacks: [
+        { member: "infra", dir: "./infra", stack: "dev", backend },
+        { member: "web", dir: "./web", stack: "dev" },
+      ],
+    });
+    const steps = op.phases.flatMap((p) => p.steps as ActivityStep[]).filter((s) => s.fn?.startsWith("pulumiAdopt"));
+    const infra = steps.filter((s) => s.args?.member === "infra");
+    expect(infra.map((s) => s.fn)).toEqual(["pulumiAdoptCheck", "pulumiAdoptExport", "pulumiAdoptPreview", "pulumiAdopt"]);
+    for (const s of infra) expect(s.args?.backend).toBe(backend);
+    // A stack without one leaves each step to resolve it (plywood.yml, PULUMI_BACKEND_URL, Pulumi.yaml).
+    for (const s of steps.filter((s) => s.args?.member === "web")) expect(s.args?.backend).toBeUndefined();
+  });
+
   test("its steps validate against the activities' contracts", () => {
     const op = props({
       name: "adopt",
@@ -207,6 +224,24 @@ describe("the activities", () => {
     await expect(adoptPreview(stack, { plunge: refused })).rejects.toThrow(/pending-operations: the checkpoint has 1 pending operation\. Nothing was written/);
   });
 
+  test("preview and adopt hand plunge the stack's backend, resolved as the Check step resolves it", async () => {
+    const envs: (Record<string, string> | undefined)[] = [];
+    const plunge: PulumiRunner = async (_args, opts) => {
+      envs.push(opts.env);
+      return { stdout: view("would-adopt") };
+    };
+    const backend = "plunge+s3://state?region=us-east-1";
+    await adoptPreview({ ...stack, backend }, { plunge, env: { PULUMI_BACKEND_URL: "file:///tmp/elsewhere" } });
+    await adoptStack({ ...stack, backend }, { plunge, env: { PULUMI_BACKEND_URL: "file:///tmp/elsewhere" } });
+    expect(envs).toEqual([{ PULUMI_BACKEND_URL: backend }, { PULUMI_BACKEND_URL: backend }]);
+    // With no step backend, the environment's is the one named.
+    envs.length = 0;
+    const dir = mkdtempSync(join(tmpdir(), "adopt-test-"));
+    await adoptPreview({ ...stack, dir }, { plunge, env: { PULUMI_BACKEND_URL: "plunge+file:///tmp/s" } });
+    await adoptPreview({ ...stack, dir }, { plunge, env: {} });
+    expect(envs).toEqual([{ PULUMI_BACKEND_URL: "plunge+file:///tmp/s" }, undefined]);
+  });
+
   test("adopt runs the --yes form and says whether it matched the approved digest", async () => {
     const seen: string[][] = [];
     const plunge: PulumiRunner = async (args) => {

package/src/composites/pulumi-adopt-op.ts

@@ -153,9 +153,11 @@ export function PulumiAdoptOp(config: PulumiAdoptOpConfig): PulumiAdoptOpResourc
 
   const waves = config.stacks.flatMap((s, i) => {
     const file = s.from ? { file: exports[i]!.out.file } : {};
-    const preview = pulumiAdoptPreview(s.member, { dir: s.dir, stack: s.stack, ...where, ...file, id: `preview-${i}` });
+    // Every step gets the stack's backend, so Preview and Adopt read the store Check and Export read.
+    const backend = s.backend ? { backend: s.backend } : {};
+    const preview = pulumiAdoptPreview(s.member, { dir: s.dir, stack: s.stack, ...where, ...file, ...backend, id: `preview-${i}` });
     preview.outcomeAttribute = { name: single ? "Adoptable" : `Adoptable-${slug(s.member)}-${slug(s.stack)}`, from: "resources" };
-    const adopt = pulumiAdopt(s.member, { dir: s.dir, stack: s.stack, ...where, ...file, planDigest: preview.out.planDigest, id: `adopt-${i}` });
+    const adopt = pulumiAdopt(s.member, { dir: s.dir, stack: s.stack, ...where, ...file, ...backend, planDigest: preview.out.planDigest, id: `adopt-${i}` });
     adopt.outcomeAttribute = { name: single ? "Adopted" : `Adopted-${slug(s.member)}-${slug(s.stack)}`, from: "resources" };
     const label = single ? "" : ` ${s.member}/${s.stack}`;
     return [

package/src/index.ts

@@ -132,3 +132,5 @@ export { parsePlungeAdoptView, pulumiAdoptDigest, adoptBucketTarget, type Plunge
 export { pulumiPreview as pulumiPreviewStep, pulumiDrift as pulumiDriftStep } from "./op/builders";
 // Pulumi and plunge exit statuses on chant's exit-code table (#4553).
 export { pulumiExitOf, pulumiPlanMoved, PULUMI_EXIT, PLUNGE_PLAN_MOVED_EXIT } from "./exit-codes";
+// Which stack outputs a preview changes, traced through the export (#4635).
+export { pulumiPlannedOutputChanges, type PulumiOutputChange, type PulumiPlannedOutputChanges } from "./planned-output-changes";

package/src/member-outputs.test.ts

@@ -11,8 +11,10 @@
  * program on floci (see their READMEs): `stack output --json
  * --show-secrets=false` prints a secret output as the string `"[secret]"`,
  * and `preview --json` plans no stack outputs, so a settled preview gives
- * the export's and a preview with changes leaves every output unknown. No
- * binary runs here.
+ * the export's. A preview with changes traces each output to the export's
+ * resources (#4635): the replaced VPC's and security group's ids, the
+ * deleted parameter's name and the deleted queue's URL are unknown, and the
+ * rest keep the export's value. No binary runs here.
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -48,6 +50,9 @@ const withoutSecret = (file: string): Record<string, unknown> =>
   Object.fromEntries(Object.entries(JSON.parse(text(file, "stack-output.json")) as Record<string, unknown>).filter(([, v]) => v !== "[secret]"));
 const APPLIED = withoutSecret("pulumi-outputs");
 const PLUNGE_APPLIED = withoutSecret("plunge-outputs");
+/** The outputs preview-replaced.json moves (#4635): the replaced VPC's and security group's ids, the deleted parameter's name, the deleted queue's URL. */
+const MOVED = ["securityGroupId", "vpcId", "vpcParameterName", "workerQueueUrls"];
+const KEPT = Object.fromEntries(Object.entries(APPLIED).filter(([k]) => !MOVED.includes(k)));
 
 function fake(answer: (args: string[]) => string): { run: PulumiRunner; calls: string[][] } {
   const calls: string[][] = [];
@@ -126,11 +131,12 @@ describe("pulumiOutputSource", () => {
     expect(cli.calls).toEqual([["preview", "--json", "--show-sames", "--stack", "floci"]]);
   });
 
-  test("planned values: a preview with changes (a replaced VPC) leaves every output unknown, the secret neither known nor unknown", async () => {
+  test("planned values: a preview with changes (a replaced VPC) leaves the outputs it moves unknown and keeps the rest, the secret neither known nor unknown", async () => {
     const read = await previewPulumiMemberRead({ member: "aws", dir: AWS_DIR, run: awsCli({ preview: "preview-replaced.json" }).run });
     const planned = pulumiMemberPlannedOutputs("aws", { ...read, exported: JSON.parse(text("pulumi-outputs", "stack-export.json")) });
-    expect(planned).toMatchObject({ known: {}, unknown: Object.keys(APPLIED).sort(), changes: true, planDigest: read.part.member.planDigest });
+    expect(planned).toMatchObject({ known: KEPT, unknown: MOVED, changes: true, planDigest: read.part.member.planDigest });
     expect(planned.unknown).not.toContain("dbPasswordValue");
+    expect(planned.known).not.toHaveProperty("dbPasswordValue");
   });
 
   test("a member on plunge runs the same commands under plunge, never pulumi", async () => {
@@ -279,9 +285,9 @@ describe("dns against a Pulumi output (#4455)", () => {
     const records = set.members.find((m) => m.member === "records")!;
     expect(records.unknownInputs).toEqual(["aws.vpcId"]);
     expect(records.reads).toEqual([{ upstream: "aws", outputs: ["vpcId"], unknown: ["vpcId"] }]);
-    // Every output the stack publishes is unknown while its preview has changes: one hole each.
+    // Each output the preview moves is unknown while it has changes: one hole each (#4635).
     const holes = set.doc.members.find((m) => m.member === memberOutputsMemberName("aws"))!.holes;
-    expect(holes).toHaveLength(Object.keys(APPLIED).length);
+    expect(holes.map((h) => h.address)).toEqual(MOVED.map((o) => `aws.${o}`));
     expect(holes).toContainEqual({ address: "aws.vpcId", type: "output", reason: "aws.vpcId is known only after aws applies; what reads it is planned again then" });
 
     // Merged before aws's own pipeline applied: the read refuses, so records is blocked behind it.
@@ -307,6 +313,22 @@ describe("dns against a Pulumi output (#4455)", () => {
     expect(w.state.recordsRan).toEqual([]);
   });
 
+  test("a reader of an output the preview leaves alone plans now with the export's value (#4635)", async () => {
+    const w = world({ preview: "preview-replaced.json" });
+    const estate: DriverComponent[] = [
+      ESTATE[0]!,
+      { ...ESTATE[1]!, deploy: [{ phase: "Apply", steps: [{ kind: "fake-records", inputs: { bucket: { stackOutput: { stack: "aws", name: "siteBucketName" } } } }] }] } as DriverComponent,
+    ];
+    const plan = planFanOut({ components: estate, changed: ["aws"] });
+    const set = await planPrSet({ components: estate, plan, registry: w.registry, env: "local" });
+    expect(set.failed).toBe(false);
+    expect(w.state.recordsPlanned).toEqual([{ inputs: { bucket: "rec-ts-site" } }]);
+    const records = set.members.find((m) => m.member === "records")!;
+    expect(records.unknownInputs).toBeUndefined();
+    expect(records.reads).toEqual([{ upstream: "aws", outputs: ["siteBucketName"] }]);
+    expect(set.plannedOutputs).toEqual({ aws: Object.keys(KEPT).sort() });
+  });
+
   test("run refuses while the stack's preview has changes left", async () => {
     const w = world({ preview: "preview-replaced.json" });
     const capability = w.registry.resolve(MEMBER_OUTPUTS_KIND);

package/src/member-outputs.ts

@@ -19,6 +19,13 @@
  *   The plan digest is the member part's (`computePlanDigest("pulumi-preview",
  *   ...)`), so a preview that moves after review moves the consumer's digest.
  *
+ * A preview with changes that plans no stack outputs (every real one,
+ * #4475) traces each output to the export's resources
+ * (`./planned-output-changes.ts`, #4635): an output whose resources the
+ * preview leaves alone keeps the export's value, and the others are
+ * unknown. A stack that reads only unchanged outputs plans now; one that
+ * reads a changing one waits for the producer's `up`.
+ *
  * A member on plunge (`pulumiMemberEngine`: the member config, then a
  * `plunge` backend URL in `Pulumi.yaml`) runs the same two commands under
  * `plunge`.
@@ -39,6 +46,7 @@
 import type { DeployContext } from "@intentius/chant/components/capability";
 import type { EngineMemberRef, EngineOutputSource, EnginePlannedOutputs } from "@intentius/chant/components/verbs/member-outputs";
 import type { ChangeSetPart } from "@intentius/chant/change-set";
+import { pulumiPlannedOutputChanges, type PulumiOutputChange } from "./planned-output-changes";
 import { pulumiPlannedStackOutputs, pulumiExportedStackOutputs, type PulumiStackOutput } from "./stack-outputs";
 import { memberExportOf, previewPulumiMemberRead, pulumiMemberStackOutputs, type PulumiMemberEngine, type PulumiRunner } from "./run";
 import { isSecret } from "./values";
@@ -88,10 +96,16 @@ export function pulumiPartHasChanges(part: ChangeSetPart): boolean {
  * the preview's error. A preview that plans no stack outputs (no stack step,
  * or one without outputs, which is what a real `pulumi preview --json`
  * prints, #4475) gives the export's outputs when it plans nothing to apply,
- * since no apply will move them, and names every output the export holds
- * unknown otherwise, so nothing reads a value the preview did not plan.
+ * since no apply will move them. With changes, each output is traced to the
+ * export's resources (#4635, {@link pulumiPlannedOutputChanges}): the ones
+ * the preview leaves alone keep their value, and the rest are unknown, so
+ * nothing reads a value the preview may move. `outputChanges` lists each
+ * output's verdict and why.
  */
-export function pulumiMemberPlannedOutputs(member: string, read: { part: ChangeSetPart; preview: unknown; exported?: unknown }): EnginePlannedOutputs {
+export function pulumiMemberPlannedOutputs(
+  member: string,
+  read: { part: ChangeSetPart; preview: unknown; exported?: unknown; targeted?: boolean },
+): EnginePlannedOutputs & { outputChanges?: PulumiOutputChange[] } {
   const { part } = read;
   if (part.member.status === "failed" || part.member.planDigest === null) {
     throw new Error(`member-outputs: the preview of Pulumi member "${member}" failed: ${part.member.error ?? "no plan"}`);
@@ -101,7 +115,11 @@ export function pulumiMemberPlannedOutputs(member: string, read: { part: ChangeS
   if (planned === undefined) {
     const exported = read.exported === undefined ? [] : pulumiExportedStackOutputs(read.exported);
     if (!changes) return { known: knownValues(exported), unknown: [], planDigest: part.member.planDigest, changes };
-    return { known: {}, unknown: exported.filter((o) => !o.secret).map((o) => o.name), planDigest: part.member.planDigest, changes };
+    if (part.member.holes.length > 0 || read.exported === undefined) {
+      return { known: {}, unknown: exported.filter((o) => !o.secret).map((o) => o.name), planDigest: part.member.planDigest, changes };
+    }
+    const traced = pulumiPlannedOutputChanges({ part, exported: read.exported, ...(read.targeted ? { targeted: true } : {}) });
+    return { known: traced.known, unknown: traced.unknown, planDigest: part.member.planDigest, changes, outputChanges: traced.outputs };
   }
   const unknown = planned.filter((o) => o.unknown).map((o) => o.name);
   return { known: knownValues(planned), unknown, planDigest: part.member.planDigest, changes: changes || unknown.length > 0 };

package/src/op/activities/pulumi-adopt.ts

@@ -118,6 +118,11 @@ export interface PulumiAdoptExportResult {
 export interface PulumiAdoptPreviewArgs extends PulumiAdoptStackArgs {
   /** `--file`: the export to adopt, from the Export step when `adoptFromFile`. */
   file?: string;
+  /**
+   * The plunge backend URL plunge adopts onto, passed as `PULUMI_BACKEND_URL`. Default, as the Check
+   * step resolves it: `plywood.yml`'s, `PULUMI_BACKEND_URL`, `Pulumi.yaml`'s.
+   */
+  backend?: string;
 }
 
 export interface PulumiAdoptPreviewResult {
@@ -292,12 +297,18 @@ function summary(a: PulumiAdoptStackArgs, view: PlungeAdoptView): PulumiAdoptPre
   };
 }
 
+/** The backend plunge adopts onto, resolved as the Check step resolves it, as plunge's environment. */
+function adoptEnv(a: PulumiAdoptPreviewArgs, dir: string, deps: PulumiAdoptDeps): Record<string, string> | undefined {
+  const backend = pulumiStackBackend(dir, { ...(a.backend ? { configured: a.backend } : {}), env: deps.env ?? process.env });
+  return backend ? { PULUMI_BACKEND_URL: backend.url } : undefined;
+}
+
 /** `plunge stack adopt --json`: the classification, written nowhere. A refusal fails the step. */
 export async function adoptPreview(a: PulumiAdoptPreviewArgs, deps: PulumiAdoptDeps = {}): Promise<PulumiAdoptPreviewResult> {
   requireStack(a, "pulumiAdoptPreview");
   const dir = stackDir(a);
   const args = plungeAdoptArgs({ stack: a.stack, ...(a.file ? { file: a.file } : {}) });
-  const view = await adoptView(() => runAllowedPlunge(deps.plunge ?? defaultPlungeRunner, args, dir), "pulumiAdoptPreview", `plunge ${args.join(" ")}`);
+  const view = await adoptView(() => runAllowedPlunge(deps.plunge ?? defaultPlungeRunner, args, dir, adoptEnv(a, dir, deps)), "pulumiAdoptPreview", `plunge ${args.join(" ")}`);
   if (view.status === "refused") {
     throw new Error(`pulumiAdoptPreview: plunge refuses to adopt "${a.member}/${a.stack}": ${refusalText(view.refusals)}. Nothing was written.`);
   }
@@ -309,7 +320,7 @@ export async function adoptStack(a: PulumiAdoptArgs, deps: PulumiAdoptDeps = {})
   requireStack(a, "pulumiAdopt");
   const dir = stackDir(a);
   const args = plungeAdoptArgs({ stack: a.stack, yes: true, ...(a.file ? { file: a.file } : {}) });
-  const view = await adoptView(() => runAdoptPlunge(deps.plunge ?? defaultPlungeRunner, args, dir), "pulumiAdopt", `plunge ${args.join(" ")}`);
+  const view = await adoptView(() => runAdoptPlunge(deps.plunge ?? defaultPlungeRunner, args, dir, adoptEnv(a, dir, deps)), "pulumiAdopt", `plunge ${args.join(" ")}`);
   if (view.status === "refused") {
     throw new Error(`pulumiAdopt: plunge refused to adopt "${a.member}/${a.stack}": ${refusalText(view.refusals)}. Nothing was written.`);
   }

package/src/op/activity-contracts.ts

@@ -116,14 +116,14 @@ export const pulumiAdoptExportContract = activityContract(
 
 export const pulumiAdoptPreviewContract = activityContract(
   "pulumiAdoptPreview",
-  z.strictObject({ ...adoptStackArgs, file: z.string().optional() }),
+  z.strictObject({ ...adoptStackArgs, file: z.string().optional(), backend: z.string().optional() }),
   z.object(adoptPreviewReturns),
   memberEntity,
 );
 
 export const pulumiAdoptContract = activityContract(
   "pulumiAdopt",
-  z.strictObject({ ...adoptStackArgs, file: z.string().optional(), planDigest: z.string().optional() }),
+  z.strictObject({ ...adoptStackArgs, file: z.string().optional(), backend: z.string().optional(), planDigest: z.string().optional() }),
   z.object({ ...adoptPreviewReturns, matchesApproved: z.boolean().optional() }),
   memberEntity,
 );