@intentius/chant-lexicon-pulumi 0.124.56 → 0.124.57

package/dist/release-copy.js

@@ -24,10 +24,28 @@
  * - `go`, `dotnet`, `java`, `yaml`: never; their tools fetch what the
  *   program needs on the run.
  *
- * A directory that is not a release copy is never touched.
+ * ## In-place checkouts (plywood#22)
+ *
+ * A CI job's checkout has the same gap: git cloned the tracked files, and
+ * nothing installed the program's dependencies before the step's first
+ * preview. {@link prepareProgram}, which `pulumi-up`'s plan and run call,
+ * prepares a release copy as above and an in-place directory by the same
+ * install and the same lockfile rule, with two differences for a directory
+ * that sits in a working tree:
+ *
+ * - `nodejs`: `node_modules` in the directory or any directory above it (a
+ *   workspace's hoisted install), or a Yarn Plug'n'Play `.pnp.cjs` or
+ *   `.pnp.js` there, counts as installed, since Node resolves the SDK
+ *   from either.
+ * - The refusal for a Node program with no lockfile names the checkout, and
+ *   says to commit a lockfile or install before the run.
+ *
+ * Preparation runs once per directory per process, whichever engine asks
+ * first, so two stacks of one project on different engines never install
+ * into the same directory at once.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { join, sep } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { parseYAML } from "@intentius/chant/yaml";
 import { pulumiRunFailure, runReleaseInstall } from "./run.js";
 import { isObject } from "./values.js";
@@ -68,17 +86,57 @@ export class PulumiReleaseCopyRefusedError extends Error {
         this.name = "PulumiReleaseCopyRefusedError";
     }
 }
+/** An in-place program that cannot be made runnable, with the reason (plywood#22). */
+export class PulumiProgramNotReadyError extends Error {
+    constructor(member, dir, reason) {
+        super(`pulumi-up: "${member}": the program in ${dir} cannot run: ${reason}`);
+        this.member = member;
+        this.dir = dir;
+        this.name = "PulumiProgramNotReadyError";
+    }
+}
+/** Whether `dir` or a directory above it holds what Node resolves a package from: `node_modules`, or Yarn Plug'n'Play's loader. */
+function nodeResolvesAbove(dir) {
+    let at = resolve(dir);
+    for (;;) {
+        for (const f of ["node_modules", ".pnp.cjs", ".pnp.js"])
+            if (existsSync(join(at, f)))
+                return join(at, f);
+        const up = dirname(at);
+        if (up === at)
+            return undefined;
+        at = up;
+    }
+}
 /** Why the copy needs an install, or why not; throws when it cannot be prepared. */
 export function releaseCopyNeeds(dir, member) {
+    return programNeeds(dir, member, "copy");
+}
+/**
+ * Why a program's directory needs an install, or why not: a release copy
+ * (`copy`) or an in-place checkout (`checkout`). Throws when it cannot be
+ * prepared: a Node program with no lockfile beside its package.json.
+ */
+export function programNeeds(dir, member, place) {
     const { name, options } = pulumiRuntime(dir);
     switch (name) {
         case "nodejs": {
-            if (existsSync(join(dir, "node_modules")))
-                return { install: false, reason: "the copy has node_modules" };
+            if (place === "copy") {
+                if (existsSync(join(dir, "node_modules")))
+                    return { install: false, reason: "the copy has node_modules" };
+            }
+            else {
+                const found = nodeResolvesAbove(dir);
+                if (found)
+                    return { install: false, reason: `Node resolves the program's packages from ${found}` };
+            }
             if (!NODE_LOCKFILES.some((f) => existsSync(join(dir, f)))) {
+                if (place === "checkout") {
+                    throw new PulumiProgramNotReadyError(member, dir, `the program is Node, nothing installed its dependencies (no node_modules here or above), and there is no lockfile (${NODE_LOCKFILES.join(", ")}) beside its package.json, so an install would take whatever versions resolve today; commit a lockfile, or install the dependencies before the run`);
+                }
                 throw new PulumiReleaseCopyRefusedError(member, `the program is Node, and the release recorded no lockfile (${NODE_LOCKFILES.join(", ")}) beside its package.json, so an install would take today's versions, not the release's; commit a lockfile and cut the release again`);
             }
-            return { install: true, reason: "a Node program's copy has no node_modules" };
+            return { install: true, reason: place === "copy" ? "a Node program's copy has no node_modules" : "a Node program's checkout has no node_modules" };
         }
         case "python": {
             const venv = typeof options.virtualenv === "string" ? options.virtualenv : undefined;
@@ -86,7 +144,7 @@ export function releaseCopyNeeds(dir, member) {
             if (toolchain === "poetry" || toolchain === "uv")
                 return { install: true, reason: `a Python program on ${toolchain} installs its environment` };
             if (venv && !existsSync(join(dir, venv)))
-                return { install: true, reason: `the virtualenv ${venv} is not in the copy` };
+                return { install: true, reason: `the virtualenv ${venv} is not in the ${place}` };
             return { install: false, reason: "the Python program names no virtualenv to build" };
         }
         default:
@@ -95,37 +153,53 @@ export function releaseCopyNeeds(dir, member) {
 }
 const prepared = new Map();
 /**
- * Make a release copy runnable, once per directory in this process: `install`
- * in the copy when {@link releaseCopyNeeds} says so. Throws for a copy that
- * cannot be prepared, or an install that fails.
+ * Make a program's directory runnable before its first engine run, once per
+ * directory in this process: `install` there when {@link programNeeds} says
+ * so. A release copy follows the copy's rules, any other directory the
+ * checkout's. Throws for a directory that cannot be prepared, or an install
+ * that fails. The first caller's engine runs the install; a second engine
+ * asking for the same directory waits on it.
  */
-export function prepareReleaseCopy(opts) {
-    if (!isReleaseCopy(opts.dir))
-        return Promise.resolve({ action: "not-a-copy" });
-    const key = `${opts.engine}\0${opts.dir}`;
-    let done = prepared.get(key);
+export function prepareProgram(opts) {
+    const dir = resolve(opts.dir);
+    const place = isReleaseCopy(dir) ? "copy" : "checkout";
+    let done = prepared.get(dir);
     if (!done) {
         done = (async () => {
-            const needs = releaseCopyNeeds(opts.dir, opts.member);
+            const needs = programNeeds(dir, opts.member, place);
             if (!needs.install)
-                return { action: "none", reason: needs.reason };
+                return { place, action: "none", reason: needs.reason };
             const command = `${opts.engine} install`;
             try {
-                await runReleaseInstall(opts.run, ["install"], opts.dir);
+                await runReleaseInstall(opts.run, ["install"], dir);
             }
             catch (err) {
                 const f = pulumiRunFailure(err);
                 const why = f.missingBinary ? `the ${opts.engine} binary was not found on PATH` : (f.stderr?.trim() || f.message).split("\n").slice(-3).join("\n");
-                throw new PulumiReleaseCopyRefusedError(opts.member, `${command} in the copy failed: ${why}`);
+                if (place === "copy")
+                    throw new PulumiReleaseCopyRefusedError(opts.member, `${command} in the copy failed: ${why}`);
+                throw new PulumiProgramNotReadyError(opts.member, dir, `${command} failed: ${why}`);
             }
-            return { action: "installed", command };
+            return { place, action: "installed", command };
         })();
-        prepared.set(key, done);
-        done.catch(() => prepared.delete(key));
+        prepared.set(dir, done);
+        done.catch(() => prepared.delete(dir));
     }
     return done;
 }
-/** Forget every prepared copy. For tests. */
+/**
+ * Make a release copy runnable, once per directory in this process: `install`
+ * in the copy when {@link releaseCopyNeeds} says so. Throws for a copy that
+ * cannot be prepared, or an install that fails. A directory that is not a
+ * copy is left alone; {@link prepareProgram} prepares both.
+ */
+export async function prepareReleaseCopy(opts) {
+    if (!isReleaseCopy(opts.dir))
+        return { action: "not-a-copy" };
+    const done = await prepareProgram(opts);
+    return done.action === "none" ? { action: "none", reason: done.reason } : { action: "installed", command: done.command };
+}
+/** Forget every prepared directory. For tests. */
 export function resetPreparedReleaseCopies() {
     prepared.clear();
 }

package/dist/run.d.ts

@@ -254,11 +254,11 @@ export declare function runReviewStackPlunge(run: PulumiRunner, args: string[],
     stdout: string;
 }>;
 /**
- * The install chant runs in a release's recorded copy of a program (#4542),
+ * The install chant runs in a program's directory before its first engine
+ * run, a release's recorded copy (#4542) or a job's checkout (plywood#22),
  * for `./release-copy.ts` alone: exactly `pulumi install` or `plunge
- * install`, no flag. The cut records tracked files only, so the copy has no
- * `node_modules` or virtualenv; the CLI's install follows `Pulumi.yaml`'s
- * runtime options and the recorded lockfile.
+ * install`, no flag. Neither has `node_modules` or a virtualenv; the CLI's
+ * install follows `Pulumi.yaml`'s runtime options and the lockfile.
  */
 export declare const PULUMI_INSTALL_COMMANDS: readonly string[];
 /** Run `install` with no flag in a release copy, refusing any other argv. The runner picks the binary. */

package/dist/run.js

@@ -577,11 +577,11 @@ export async function runReviewStackPlunge(run, args, cwd, env) {
     return run(args, env ? { cwd, env } : { cwd });
 }
 /**
- * The install chant runs in a release's recorded copy of a program (#4542),
+ * The install chant runs in a program's directory before its first engine
+ * run, a release's recorded copy (#4542) or a job's checkout (plywood#22),
  * for `./release-copy.ts` alone: exactly `pulumi install` or `plunge
- * install`, no flag. The cut records tracked files only, so the copy has no
- * `node_modules` or virtualenv; the CLI's install follows `Pulumi.yaml`'s
- * runtime options and the recorded lockfile.
+ * install`, no flag. Neither has `node_modules` or a virtualenv; the CLI's
+ * install follows `Pulumi.yaml`'s runtime options and the lockfile.
  */
 export const PULUMI_INSTALL_COMMANDS = ["pulumi install", "plunge install"];
 /** Run `install` with no flag in a release copy, refusing any other argv. The runner picks the binary. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-pulumi",
-  "version": "0.124.56",
+  "version": "0.124.57",
   "type": "module",
   "files": [
     "src/",
@@ -54,7 +54,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.56",
+    "@intentius/chant": "^0.124.57",
     "zod": "^4.3.6"
   },
   "description": "pulumi lexicon for chant: a Pulumi program as a workspace member, its preview in the change set and its refresh as drift records",

package/src/changed-units.test.ts

@@ -0,0 +1,87 @@
+/**
+ * The stacks a change touched (INTENTIUS/plywood#22): plywood's bench edits
+ * `Pulumi.dev.yaml` in a pull request, and `chant components pr-plan`
+ * selected nothing because no lexicon claimed the file. Fixture repositories
+ * on disk; nothing here runs Pulumi or git.
+ */
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { pulumiChangedUnits, pulumiStackUnit } from "./changed-units";
+import { pulumiPlugin } from "./plugin";
+
+function repo(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), "pulumi-changed-units-"));
+  for (const [f, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, f)), { recursive: true });
+    writeFileSync(join(root, f), text);
+  }
+  return root;
+}
+
+/** plywood's bench shop: one project at the root with four stacks, and a nested project. */
+const SHOP = {
+  "Pulumi.yaml": "name: shop\nruntime: nodejs\n",
+  "Pulumi.dev.yaml": "config: {}\n",
+  "Pulumi.staging.yaml": "config: {}\n",
+  "Pulumi.prod-us.yaml": "config: {}\n",
+  "Pulumi.prod-eu.yaml": "config: {}\n",
+  "index.ts": "export {};\n",
+  "package.json": "{}\n",
+  "plywood.yml": "stacks: {}\n",
+  ".forgejo/workflows/plywood.yml": "name: plywood\n",
+  "net/Pulumi.yaml": "name: net\nruntime: nodejs\n",
+  "net/Pulumi.qa.yaml": "config: {}\n",
+  "net/vpc.ts": "export {};\n",
+  "docs/notes.md": "x\n",
+};
+
+describe("pulumiChangedUnits", () => {
+  test("a changed stack config touches that stack alone: the PR-2 case from the bench", () => {
+    const root = repo(SHOP);
+    expect(pulumiChangedUnits(root, ["Pulumi.dev.yaml"])).toEqual(["dev"]);
+    expect(pulumiChangedUnits(root, ["Pulumi.prod-us.yaml", "Pulumi.prod-eu.yaml"])).toEqual(["prod-eu", "prod-us"]);
+    expect(pulumiChangedUnits(root, ["net/Pulumi.qa.yaml"])).toEqual(["net/qa"]);
+  });
+
+  test("a program file touches every stack of its project, and only that project", () => {
+    const root = repo(SHOP);
+    expect(pulumiChangedUnits(root, ["index.ts"])).toEqual(["dev", "prod-eu", "prod-us", "staging"]);
+    expect(pulumiChangedUnits(root, ["Pulumi.yaml"])).toEqual(["dev", "prod-eu", "prod-us", "staging"]);
+    // The nested project owns its files; the root project does not reach into it.
+    expect(pulumiChangedUnits(root, ["net/vpc.ts"])).toEqual(["net/qa"]);
+    // A file under the root project's tree but in no nested project is the root project's program.
+    expect(pulumiChangedUnits(root, ["docs/notes.md"])).toEqual(["dev", "prod-eu", "prod-us", "staging"]);
+  });
+
+  test("dot directories, node_modules and files outside the project root are not the program", () => {
+    const root = repo(SHOP);
+    expect(pulumiChangedUnits(root, [".forgejo/workflows/plywood.yml", ".chant/op-waves/pulumi-up.spec.json", "node_modules/x/index.js", "../shared/lib.ts"])).toEqual([]);
+  });
+
+  test("a deleted stack config still names its stack, and a program change reaches it", () => {
+    const root = repo(SHOP);
+    expect(pulumiChangedUnits(root, ["Pulumi.old.yaml"])).toEqual(["old"]);
+    expect(pulumiChangedUnits(root, ["index.ts", "Pulumi.old.yaml"])).toEqual(["dev", "old", "prod-eu", "prod-us", "staging"]);
+  });
+
+  test("a deleted Pulumi.yaml still names its project", () => {
+    const root = repo({ "app/Pulumi.dev.yaml": "config: {}\n", "app/index.ts": "export {};\n" });
+    expect(pulumiChangedUnits(root, ["app/Pulumi.yaml", "app/index.ts"])).toEqual(["app/dev"]);
+  });
+
+  test("a file in no Pulumi project touches nothing", () => {
+    const root = repo({ "README.md": "x\n", "tf/main.tf": "\n" });
+    expect(pulumiChangedUnits(root, ["README.md", "tf/main.tf"])).toEqual([]);
+  });
+
+  test("units are named as core names a pulumi-up step's deploy unit", () => {
+    expect([pulumiStackUnit(".", "dev"), pulumiStackUnit("./infra/", "dev"), pulumiStackUnit("apps\\web", "qa")]).toEqual(["dev", "infra/dev", "apps/web/qa"]);
+  });
+
+  test("the plugin answers changedUnits from the changed files", async () => {
+    const root = repo(SHOP);
+    expect(await pulumiPlugin.changedUnits!({ projectRoot: root, config: {}, changedFiles: ["Pulumi.dev.yaml"] })).toEqual(["dev"]);
+  });
+});

package/src/changed-units.ts

@@ -0,0 +1,96 @@
+/**
+ * The Pulumi stacks a change touched, judged from the changed files alone
+ * (`LexiconPlugin.changedUnits`, #3183; INTENTIUS/plywood#22). A Pulumi
+ * program and its stack configs are not chant source, so `chant lifecycle
+ * affected`'s artifact diff never shows them, and without this a pull request
+ * that edits `Pulumi.dev.yaml` selects no component at all.
+ *
+ * A file belongs to the nearest directory at or above it holding a
+ * `Pulumi.yaml` (or `Pulumi.yml`), the project, never above the project root:
+ *
+ *   - `Pulumi.<stack>.yaml` in that directory is the stack's config, so it
+ *     touches that stack alone;
+ *   - any other file there or below (the program, `Pulumi.yaml`, the
+ *     package files) touches every stack of the project, which is each
+ *     `Pulumi.<stack>.yaml` beside `Pulumi.yaml` at head and any the change
+ *     deleted. A stack with no config file has no file to find it by, so a
+ *     program change does not reach it.
+ *
+ * Files under a directory whose name starts with a dot (`.forgejo`, `.chant`,
+ * `.git`) or under `node_modules` are not the program. A file outside every
+ * project, such as a module the program imports from `../shared`, is not
+ * claimed.
+ *
+ * Each unit is named as core's `DEPLOY_UNIT_RULES` names a `pulumi-up` step:
+ * `<dir>/<stack>`, or `<stack>` for a project at the project root.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join, posix } from "node:path";
+
+const PROJECT_FILES = ["Pulumi.yaml", "Pulumi.yml"];
+const STACK_CONFIG = /^Pulumi\.(.+)\.ya?ml$/;
+
+/** The unit core names for a `pulumi-up` step on `stack` in `dir` (deploy-units.ts `pulumiStackUnit`). */
+export function pulumiStackUnit(dir: string, stack: string): string {
+  const d = dir.replace(/\\/g, "/").replace(/^(\.\/)+/, "").replace(/\/+$/, "");
+  return d === "" || d === "." ? stack : `${d}/${stack}`;
+}
+
+/** The project directory (relative, `""` for the root) holding `file`, or undefined when none does. */
+function projectOf(projectRoot: string, file: string, changed: ReadonlySet<string>): string | undefined {
+  let dir = posix.dirname(file);
+  for (;;) {
+    const rel = dir === "." ? "" : dir;
+    for (const name of PROJECT_FILES) {
+      const p = rel === "" ? name : `${rel}/${name}`;
+      // A deleted Pulumi.yaml still names its project for the change that deleted it.
+      if (existsSync(join(projectRoot, p)) || changed.has(p)) return rel;
+    }
+    if (rel === "") return undefined;
+    dir = posix.dirname(dir);
+  }
+}
+
+/** The stacks of the project in `dir`: the stack configs at head, and the ones the change names. */
+function stacksOf(projectRoot: string, dir: string, changed: readonly string[]): string[] {
+  const out = new Set<string>();
+  let names: string[] = [];
+  try {
+    names = readdirSync(join(projectRoot, dir));
+  } catch {
+    // The project directory is gone at head; the change's own files still name stacks.
+  }
+  for (const n of names) {
+    const m = STACK_CONFIG.exec(n);
+    if (m) out.add(m[1]!);
+  }
+  for (const f of changed) {
+    if (posix.dirname(f) !== (dir === "" ? "." : dir)) continue;
+    const m = STACK_CONFIG.exec(posix.basename(f));
+    if (m) out.add(m[1]!);
+  }
+  return [...out];
+}
+
+function ignored(file: string): boolean {
+  const parts = file.split("/");
+  return parts.slice(0, -1).some((p) => p.startsWith(".") || p === "node_modules");
+}
+
+/** The stack units `changedFiles` (relative to `projectRoot`, `/` separators) touch, sorted. */
+export function pulumiChangedUnits(projectRoot: string, changedFiles: readonly string[]): string[] {
+  const files = changedFiles.map((f) => f.replace(/\\/g, "/").replace(/^\.\//, "")).filter((f) => f !== "" && !f.startsWith("../") && !ignored(f));
+  const changed = new Set(files);
+  const units = new Set<string>();
+  const whole = new Set<string>();
+  for (const f of files) {
+    const dir = projectOf(projectRoot, f, changed);
+    if (dir === undefined) continue;
+    const here = posix.dirname(f) === (dir === "" ? "." : dir);
+    const m = STACK_CONFIG.exec(posix.basename(f));
+    if (here && m && !PROJECT_FILES.includes(posix.basename(f))) units.add(pulumiStackUnit(dir, m[1]!));
+    else whole.add(dir);
+  }
+  for (const dir of whole) for (const stack of stacksOf(projectRoot, dir, files)) units.add(pulumiStackUnit(dir, stack));
+  return [...units].sort();
+}

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/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,
 );

package/src/plugin.ts

@@ -136,6 +136,18 @@ export const pulumiPlugin: LexiconPlugin = {
     return { entities: read.entities, warnings: read.warnings };
   },
 
+  /**
+   * The stacks a change touched (#3183, INTENTIUS/plywood#22): a changed
+   * `Pulumi.<stack>.yaml` is that stack, any other file of a project is every
+   * stack with a config beside its `Pulumi.yaml`. Named as a `pulumi-up`
+   * step's deploy unit, so `chant components pr-plan` and `fan-out --base`
+   * select the components that update them. See ./changed-units.ts.
+   */
+  async changedUnits(ctx) {
+    const { pulumiChangedUnits } = await import("./changed-units");
+    return pulumiChangedUnits(ctx.projectRoot, ctx.changedFiles);
+  },
+
   graphMeta() {
     const report = lastMemberReport();
     return report ? { pulumiMember: report } : undefined;