@intentius/chant-lexicon-pulumi 0.124.55 → 0.124.57

package/src/pulumi-up.ts

@@ -107,11 +107,17 @@
  *
  * The cut records tracked files, so a Node program's copy has no
  * `node_modules`. Before the copy's first preview, `plan` and `run` call
- * `prepareReleaseCopy` (`./release-copy.ts`), which runs `pulumi install`
+ * `prepareProgram` (`./release-copy.ts`), which runs `pulumi install`
  * (`plunge install`) in the copy when its runtime needs one, and refuses a
  * Node copy with no lockfile by name, since an install would take today's
  * versions rather than the release's.
  *
+ * A CI job's checkout has the same gap, so the same call prepares the
+ * step's own directory by the same rule (plywood#22): a Node program with
+ * no `node_modules` in its directory or above it, and a lockfile beside its
+ * package.json, gets one `<engine> install` before the job's first engine
+ * run; with no lockfile the step refuses by name.
+ *
  * ## review stacks (#4609)
  *
  * When `DeployContext.env` is a pull request's environment `pr-<n>` (`chant
@@ -167,8 +173,10 @@ import { pulumiExitOf } from "./exit-codes";
 import { pulumiMemberEngine, type PulumiMemberEngine, type PulumiMemberEngineSource } from "./member-engine";
 import { ciEngineDir, ciRelease, CI_ENGINE_ROOT } from "./ci-setup";
 import { pulumiMemberPlannedOutputs } from "./member-outputs";
+import type { PulumiOutputChange } from "./planned-output-changes";
 import { pulumiPlanShape, pulumiShapeDifferences } from "./plan-shape";
 import { pulumiLockRows } from "./lock-rows";
+import { stackRowKey } from "@intentius/chant/lifecycle/lock-rows";
 import { pulumiTraceFacts } from "./trace-facts";
 import {
   defaultPlungeRunner,
@@ -191,7 +199,7 @@ import type { PulumiStep } from "./change-set";
 import { writePulumiExportSnapshot, type PulumiExportWrite } from "./stack-export-snapshot";
 import { pointerSegment, pulumiStackReferences, stackReferenceOwner } from "./stack-references";
 import { isObject } from "./values";
-import { prepareReleaseCopy } from "./release-copy";
+import { prepareProgram } from "./release-copy";
 import { initReviewStack, reviewConfigSource, reviewStackFor, reviewStackLocation } from "./review-stack";
 
 /** The lock grain values of `ci.lockGrain` (#4552's ruling A). */
@@ -209,6 +217,15 @@ export interface PulumiUpStepInput {
   config?: Record<string, unknown>;
   /** `pulumi` or `plunge`; see `pulumiMemberEngine`. */
   engine?: PulumiMemberEngine;
+  /**
+   * The stack's backend URL (INTENTIUS/plywood#22), such as
+   * `plunge+s3://...` or `s3://...`: every engine command the step runs
+   * (preview, up, the stack output and export reads, a review stack's init)
+   * gets it as `PULUMI_BACKEND_URL`, over the job's own. It also answers the
+   * engine where `pulumiMemberEngine` would read `PULUMI_BACKEND_URL`.
+   * Absent: the job's `PULUMI_BACKEND_URL` or `Pulumi.yaml`'s, as before.
+   */
+  backend?: string;
   /**
    * The engine release this stack is pinned to (#4592): the step runs
    * `<engineRoot>/<engine>-<engineVersion>/<engine>`, the path the pulumi
@@ -300,6 +317,13 @@ export interface PulumiUpArtifact {
    * outside reference stale, current or unknown.
    */
   stackReferences?: { read: string[]; outside: { name: string; why: string }[]; lastUpdate?: string };
+  /**
+   * Each stack output's verdict from the preview (#4635,
+   * `./planned-output-changes.ts`): `changing` and `untraced` ones are
+   * unknown to the stacks that read them, `unchanged` ones keep the
+   * export's value. Absent when the preview planned nothing to apply.
+   */
+  plannedOutputs?: PulumiOutputChange[];
 }
 
 /** The CrossGuard packs a plan read at base (#4613). */
@@ -532,18 +556,34 @@ interface Resolved {
   engineSource: PulumiMemberEngineSource;
   engineBecause: string;
   grain: PulumiLockGrain;
+  /** The step's `backend`, every engine command's `PULUMI_BACKEND_URL`. */
+  backend?: string;
+}
+
+/** The environment the engine is picked from: the job's, with the step's backend as `PULUMI_BACKEND_URL`. */
+function engineEnv(input: Pick<PulumiUpStepInput, "backend">, opts: PulumiUpOptions): { env?: Record<string, string | undefined> } {
+  if (input.backend === undefined) return opts.env ? { env: opts.env } : {};
+  return { env: { ...(opts.env ?? process.env), PULUMI_BACKEND_URL: input.backend } };
+}
+
+/** `run` with `PULUMI_BACKEND_URL` set to the step's backend over whatever env the call passes. */
+function withBackend(run: PulumiRunner, backend: string): PulumiRunner {
+  return (args, o) => run(args, { ...o, env: { ...(o.env ?? {}), PULUMI_BACKEND_URL: backend } });
 }
 
 function resolveStep(input: PulumiUpStepInput, opts: PulumiUpOptions, declared?: PulumiLockGrain): Resolved {
   requireInput(input);
+  if (input.backend !== undefined && (typeof input.backend !== "string" || input.backend.trim() === "")) {
+    throw new Error('pulumi-up: "backend" is the stack\'s backend URL, such as plunge+s3://<bucket> or s3://<bucket>');
+  }
   const dir = stackDir(input);
   const member = pulumiUpMember(input);
-  const picked = pulumiMemberEngine(dir, input.engine, opts.env ? { env: opts.env } : {});
+  const picked = pulumiMemberEngine(dir, input.engine, engineEnv(input, opts));
   // #4552: the step's own grain, else ci.lockGrain as the caller read it at base, else the engine's default.
   const grain = input.lockGrain ?? declared ?? pulumiDefaultLockGrain(picked.engine);
   if (grain === "resource" && picked.engine === "pulumi") throw new PulumiResourceGrainRefusedError(member);
   const engineBin = pulumiUpEngineBin(input, picked.engine);
-  return { dir, member, engine: picked.engine, ...(engineBin ? { engineBin } : {}), engineSource: picked.source, engineBecause: picked.because, grain };
+  return { dir, member, engine: picked.engine, ...(engineBin ? { engineBin } : {}), engineSource: picked.source, engineBecause: picked.because, grain, ...(input.backend ? { backend: input.backend } : {}) };
 }
 
 /**
@@ -566,8 +606,8 @@ export function pulumiUpEngineBin(input: Pick<PulumiUpStepInput, "engineVersion"
 }
 
 /** The `run` and `plunge` options for the stack output and export reads: the pinned binary's for both when the step names one (#4592), else the caller's. */
-function runnerOptions(r: Pick<Resolved, "engineBin">, opts: PulumiUpOptions): { run?: PulumiRunner; plunge?: PulumiRunner } {
-  if (r.engineBin) {
+function runnerOptions(r: Pick<Resolved, "engineBin" | "backend">, opts: PulumiUpOptions): { run?: PulumiRunner; plunge?: PulumiRunner } {
+  if (r.engineBin || r.backend) {
     const { pulumi, plunge } = runnersFor(r, opts);
     return { run: pulumi, plunge };
   }
@@ -575,12 +615,16 @@ function runnerOptions(r: Pick<Resolved, "engineBin">, opts: PulumiUpOptions): {
 }
 
 /** The runners a resolved step uses: the pinned binary's when it names one, else the options' or the PATH default. */
-function runnersFor(r: Pick<Resolved, "engineBin">, opts: PulumiUpOptions): { pulumi: PulumiRunner; plunge: PulumiRunner } {
+function runnersFor(r: Pick<Resolved, "engineBin" | "backend">, opts: PulumiUpOptions): { pulumi: PulumiRunner; plunge: PulumiRunner } {
+  let out: { pulumi: PulumiRunner; plunge: PulumiRunner };
   if (r.engineBin) {
     const pinned = opts.runAt ? opts.runAt(r.engineBin) : engineRunnerAt(r.engineBin);
-    return { pulumi: pinned, plunge: pinned };
+    out = { pulumi: pinned, plunge: pinned };
+  } else {
+    out = { pulumi: opts.run ?? defaultPulumiRunner, plunge: opts.plunge ?? defaultPlungeRunner };
   }
-  return { pulumi: opts.run ?? defaultPulumiRunner, plunge: opts.plunge ?? defaultPlungeRunner };
+  // plywood#22: the step's backend reaches every command, whichever call site runs it.
+  return r.backend ? { pulumi: withBackend(out.pulumi, r.backend), plunge: withBackend(out.plunge, r.backend) } : out;
 }
 
 /** The scratch directory, the config copy in it and plunge's plan file path. */
@@ -619,7 +663,10 @@ async function previewStack(
     stack: input.stack,
     ...(files.planFile ? { savePlan: files.planFile } : {}),
     ...(files.configFile ? { configFile: files.configFile } : {}),
+    // #4627: --refresh and --target-dependents pass to the preview as they came.
+    ...(ctx.refresh ? { refresh: true } : {}),
     ...(targets ? { targets } : {}),
+    ...(targets && ctx.targetDependents ? { targetDependents: true } : {}),
     ...(packs.length ? { policyPacks: packs } : {}),
   });
   let stdout: string;
@@ -684,10 +731,10 @@ function isArtifact(value: unknown): value is PulumiUpArtifact {
   return v?.kind === "pulumi-up" && typeof v.planDigest === "string" && typeof v.shape === "object" && v.shape !== null;
 }
 
-/** A release's copy of the program, made runnable before its first engine run (#4542). */
-async function readyCopy(r: Resolved, opts: PulumiUpOptions): Promise<void> {
+/** The program's directory, a release's copy (#4542) or the checkout in place (plywood#22), made runnable before its first engine run. */
+async function readyProgram(r: Resolved, opts: PulumiUpOptions): Promise<void> {
   const runners = runnersFor(r, opts);
-  await prepareReleaseCopy({ dir: r.dir, member: r.member, engine: r.engine, run: r.engine === "plunge" ? runners.plunge : runners.pulumi });
+  await prepareProgram({ dir: r.dir, member: r.member, engine: r.engine, run: r.engine === "plunge" ? runners.plunge : runners.pulumi });
 }
 
 async function planStack(ctx: DeployContext, original: PulumiUpStepInput, opts: PulumiUpOptions): Promise<CapabilityPlan> {
@@ -697,7 +744,7 @@ async function planStack(ctx: DeployContext, original: PulumiUpStepInput, opts:
   const location = review ? { location: locationOf(r, review.stack) } : {};
   const unresolved = [...(ctx.unresolvedInputs ?? [])].sort();
   if (unresolved.length > 0) return { ...waitingStack(ctx, r, input, unresolved), ...location };
-  await readyCopy(r, opts);
+  await readyProgram(r, opts);
   if (review) {
     const runners = runnersFor(r, opts);
     await initReviewStack({
@@ -720,7 +767,12 @@ async function planStack(ctx: DeployContext, original: PulumiUpStepInput, opts:
   }
   const planDigest = read.part.member.planDigest!;
   const references = stackReferencesOf(read.prior, input);
-  const planned = pulumiMemberPlannedOutputs(r.member, { part: read.part, preview: read.preview, ...(read.prior !== undefined ? { exported: read.prior } : {}) });
+  const planned = pulumiMemberPlannedOutputs(r.member, {
+    part: read.part,
+    preview: read.preview,
+    ...(read.prior !== undefined ? { exported: read.prior } : {}),
+    ...(ctx.targets?.length ? { targeted: true } : {}),
+  });
   const artifact: PulumiUpArtifact = {
     kind: "pulumi-up",
     member: r.member,
@@ -736,6 +788,7 @@ async function planStack(ctx: DeployContext, original: PulumiUpStepInput, opts:
     policy: read.policy,
     ...(packs.read ? { policyPacks: packs.read } : {}),
     ...(references ? { stackReferences: references } : {}),
+    ...(planned.outputChanges ? { plannedOutputs: planned.outputChanges } : {}),
   };
   return {
     member: r.member,
@@ -856,7 +909,7 @@ async function runStack(ctx: DeployContext, original: PulumiUpStepInput, opts: P
   const handed = ctx.plans?.[r.member];
   const fromWave = isArtifact(handed);
   const targets = ctx.targets && ctx.targets.length > 0 ? ctx.targets : undefined;
-  await readyCopy(r, opts);
+  await readyProgram(r, opts);
 
   // Ruling D: no approved plan handed in, so plan here and apply that.
   let approved: PulumiUpArtifact;
@@ -892,6 +945,7 @@ async function runStack(ctx: DeployContext, original: PulumiUpStepInput, opts: P
   const tail = {
     ...(configFile ? { configFile } : {}),
     ...(targets ? { targets } : {}),
+    ...(targets && ctx.targetDependents ? { targetDependents: true } : {}),
     ...(policyPacks?.length ? { policyPacks } : {}),
   };
 
@@ -914,7 +968,8 @@ async function runStack(ctx: DeployContext, original: PulumiUpStepInput, opts: P
         if (differences.length > 0) throw new PlanShapeMovedError(r.member, differences);
       }
       try {
-        ({ stdout } = await runApplyPulumi(runnersFor(r, opts).pulumi, pulumiUpArgs({ stack: input.stack, ...tail }), r.dir));
+        // #4627: stock up plans again, so it refreshes as its preview did; plunge applies the saved plan, whose preview refreshed.
+        ({ stdout } = await runApplyPulumi(runnersFor(r, opts).pulumi, pulumiUpArgs({ stack: input.stack, ...tail, ...(ctx.refresh ? { refresh: true } : {}) }), r.dir));
       } catch (err) {
         throw upFailure(r, err, approved.policy);
       }
@@ -989,6 +1044,8 @@ export function createPulumiUpCapability(opts: PulumiUpOptions = {}): Capability
     rollbackPolicy: "needs-opt-out",
     // Each target passes as `--target <urn>` to the preview and to `up`.
     targets: "accept",
+    // #4627: `--refresh` and `--target-dependents` pass to the preview, and to `pulumi up`; the digest binds them.
+    planFlags: { refresh: "accept", targetDependents: "accept" },
     plan: (ctx, input) => planStack(ctx, input, opts),
     run: (ctx, input) => runStack(ctx, input, opts),
     // The outputs standing now, for a dependent planned before this stack applies.
@@ -1006,15 +1063,24 @@ export function createPulumiUpCapability(opts: PulumiUpOptions = {}): Capability
     // #4552: resource on plunge, the stack (target) on stock Pulumi.
     defaultLockGrain(input) {
       requireInput(input);
-      return pulumiDefaultLockGrain(pulumiMemberEngine(stackDir(input), input.engine, opts.env ? { env: opts.env } : {}).engine);
+      return pulumiDefaultLockGrain(pulumiMemberEngine(stackDir(input), input.engine, engineEnv(input, opts)).engine);
     },
     // Stock Pulumi keeps the stack grain: its backend's stack lock already orders updates, and nothing in it is per resource.
     lockGrainRefusal(input, grain) {
       if (grain !== "resource") return undefined;
       requireInput(input);
-      const engine = pulumiMemberEngine(stackDir(input), input.engine, opts.env ? { env: opts.env } : {}).engine;
+      const engine = pulumiMemberEngine(stackDir(input), input.engine, engineEnv(input, opts)).engine;
       return engine === "pulumi" ? new PulumiResourceGrainRefusedError(pulumiUpMember(input)).message : undefined;
     },
+    // The ruling for ci-products (2026-10-28): a stock stack waits for its stack row on the ledger in place of the backend's lock.
+    // plunge keeps the resource grain, and a plunge stack declared on the target grain waits on the same row.
+    targetLockRow(input, plan) {
+      requireInput(input);
+      const project = readProject(stackDir(input))?.name;
+      const stack = plan && isArtifact(plan.artifact) ? plan.artifact.stack : input.stack;
+      if (typeof project !== "string" || !stack) return undefined;
+      return { key: stackRowKey(project, stack), target: pulumiUpMember(input), address: `${project}/${stack}` };
+    },
     // URN rows, object rows, and the stack row when something may appear only at apply (./lock-rows.ts).
     lockRows(input, plan) {
       if (!plan.changeSet) return [];

package/src/release-copy.test.ts

@@ -2,13 +2,24 @@
  * A release's copy of a Pulumi program (#4542 item 3): `pulumi install` (or
  * `plunge install`) runs in the copy when its runtime needs one, a Node copy
  * with no lockfile is refused by name, and a directory that is not a copy is
- * never touched. The runner is a fake, so nothing installs.
+ * left alone by `prepareReleaseCopy`. `prepareProgram` prepares an in-place
+ * checkout by the same rule (plywood#22). The runner is a fake, so nothing
+ * installs.
  */
 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { beforeEach, describe, expect, test } from "vitest";
-import { isReleaseCopy, prepareReleaseCopy, PulumiReleaseCopyRefusedError, releaseCopyNeeds, resetPreparedReleaseCopies } from "./release-copy";
+import {
+  isReleaseCopy,
+  prepareProgram,
+  prepareReleaseCopy,
+  programNeeds,
+  PulumiProgramNotReadyError,
+  PulumiReleaseCopyRefusedError,
+  releaseCopyNeeds,
+  resetPreparedReleaseCopies,
+} from "./release-copy";
 import { runReleaseInstall, type PulumiRunner } from "./run";
 
 function copy(pulumiYaml: string, files: Record<string, string> = {}): string {
@@ -72,3 +83,80 @@ describe("a release copy", () => {
     expect(calls).toEqual([]);
   });
 });
+
+/** An in-place checkout: a directory outside any release copy, with its files. */
+function checkout(pulumiYaml: string, files: Record<string, string> = {}): string {
+  const dir = join(mkdtempSync(join(tmpdir(), "checkout-")), "shop");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "Pulumi.yaml"), pulumiYaml);
+  for (const [name, text] of Object.entries(files)) writeFileSync(join(dir, name), text);
+  return dir;
+}
+
+describe("an in-place checkout (plywood#22)", () => {
+  const node = "name: shop\nruntime: nodejs\n";
+  const locked = { "package.json": "{}", "package-lock.json": "{}" };
+
+  test("a Node checkout with a lockfile and no node_modules gets one install, whichever engine asks", async () => {
+    const dir = checkout(node, locked);
+    const plunge = runner();
+    const pulumi = runner();
+    const [a, b] = await Promise.all([
+      prepareProgram({ dir, member: "shop/dev", engine: "plunge", run: plunge.run }),
+      prepareProgram({ dir, member: "shop/staging", engine: "pulumi", run: pulumi.run }),
+    ]);
+    expect(a).toEqual({ place: "checkout", action: "installed", command: "plunge install" });
+    expect(b).toEqual(a);
+    expect(plunge.calls).toEqual([{ args: ["install"], cwd: dir }]);
+    expect(pulumi.calls).toEqual([]);
+  });
+
+  test("node_modules here or above, or Yarn's Plug'n'Play loader, counts as installed", () => {
+    const here = checkout(node, locked);
+    mkdirSync(join(here, "node_modules"));
+    expect(programNeeds(here, "shop/dev", "checkout").install).toBe(false);
+
+    const hoisted = checkout(node, { "package.json": "{}" });
+    mkdirSync(join(hoisted, "..", "node_modules"));
+    expect(programNeeds(hoisted, "shop/dev", "checkout")).toMatchObject({ install: false, reason: expect.stringContaining("node_modules") });
+
+    const pnp = checkout(node, { "package.json": "{}", "yarn.lock": "", ".pnp.cjs": "" });
+    expect(programNeeds(pnp, "shop/dev", "checkout").install).toBe(false);
+  });
+
+  test("a Node checkout with no lockfile is refused by name, and nothing runs", async () => {
+    const dir = checkout(node, { "package.json": "{}" });
+    const { run, calls } = runner();
+    await expect(prepareProgram({ dir, member: "shop/dev", engine: "pulumi", run })).rejects.toThrow(PulumiProgramNotReadyError);
+    await expect(prepareProgram({ dir, member: "shop/dev", engine: "pulumi", run })).rejects.toThrow(/no lockfile .* beside its package.json/);
+    expect(calls).toEqual([]);
+  });
+
+  test("a failed install names the command, and the next call tries again", async () => {
+    const dir = checkout(node, locked);
+    let fail = true;
+    const calls: string[][] = [];
+    const run: PulumiRunner = async (args) => {
+      calls.push(args);
+      if (fail) throw Object.assign(new Error("exit 1"), { code: 1, stderr: "npm error ERESOLVE" });
+      return { stdout: "" };
+    };
+    await expect(prepareProgram({ dir, member: "shop/dev", engine: "pulumi", run })).rejects.toThrow(/pulumi install failed: npm error ERESOLVE/);
+    fail = false;
+    expect(await prepareProgram({ dir, member: "shop/dev", engine: "pulumi", run })).toMatchObject({ action: "installed" });
+    expect(calls).toEqual([["install"], ["install"]]);
+  });
+
+  test("Python, Go and YAML follow the copy's rules", () => {
+    expect(programNeeds(checkout("name: a\nruntime:\n  name: python\n  options:\n    virtualenv: venv\n"), "a", "checkout").install).toBe(true);
+    expect(programNeeds(checkout("name: a\nruntime: python\n"), "a", "checkout").install).toBe(false);
+    expect(programNeeds(checkout("name: a\nruntime: go\n"), "a", "checkout").install).toBe(false);
+    expect(programNeeds(checkout("name: a\nruntime: yaml\n"), "a", "checkout").install).toBe(false);
+  });
+
+  test("a release copy keeps the copy's rule: node_modules above the copy does not count", () => {
+    const dir = copy("name: shop\nruntime: nodejs\n", { "package.json": "{}", "package-lock.json": "{}" });
+    mkdirSync(join(dir, "..", "node_modules"));
+    expect(releaseCopyNeeds(dir, "shop/prod").install).toBe(true);
+  });
+});

package/src/release-copy.ts

@@ -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 type { PulumiMemberEngine } from "./member-engine";
 import { pulumiRunFailure, runReleaseInstall, type PulumiRunner } from "./run";
@@ -73,31 +91,78 @@ export class PulumiReleaseCopyRefusedError extends Error {
   }
 }
 
+/** An in-place program that cannot be made runnable, with the reason (plywood#22). */
+export class PulumiProgramNotReadyError extends Error {
+  constructor(
+    public readonly member: string,
+    public readonly dir: string,
+    reason: string,
+  ) {
+    super(`pulumi-up: "${member}": the program in ${dir} cannot run: ${reason}`);
+    this.name = "PulumiProgramNotReadyError";
+  }
+}
+
 /** What preparing a copy did. */
 export type ReleaseCopyPrepared =
   | { action: "not-a-copy" }
   | { action: "none"; reason: string }
   | { action: "installed"; command: string };
 
+/** What preparing a program's directory did: a release copy or an in-place checkout. */
+export type ProgramPrepared = { place: "copy" | "checkout" } & ({ action: "none"; reason: string } | { action: "installed"; command: string });
+
+/** 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: string): string | undefined {
+  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: string, member: string): { install: boolean; reason: string } {
+  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: string, member: string, place: "copy" | "checkout"): { install: boolean; reason: string } {
   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;
       const toolchain = typeof options.toolchain === "string" ? options.toolchain : undefined;
       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` };
+      if (venv && !existsSync(join(dir, venv))) 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:
@@ -105,38 +170,54 @@ export function releaseCopyNeeds(dir: string, member: string): { install: boolea
   }
 }
 
-const prepared = new Map<string, Promise<ReleaseCopyPrepared>>();
+const prepared = new Map<string, Promise<ProgramPrepared>>();
 
 /**
- * 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: { dir: string; member: string; engine: PulumiMemberEngine; run: PulumiRunner }): Promise<ReleaseCopyPrepared> {
-  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: { dir: string; member: string; engine: PulumiMemberEngine; run: PulumiRunner }): Promise<ProgramPrepared> {
+  const dir = resolve(opts.dir);
+  const place = isReleaseCopy(dir) ? "copy" : "checkout";
+  let done = prepared.get(dir);
   if (!done) {
-    done = (async (): Promise<ReleaseCopyPrepared> => {
-      const needs = releaseCopyNeeds(opts.dir, opts.member);
-      if (!needs.install) return { action: "none", reason: needs.reason };
+    done = (async (): Promise<ProgramPrepared> => {
+      const needs = programNeeds(dir, opts.member, place);
+      if (!needs.install) 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: { dir: string; member: string; engine: PulumiMemberEngine; run: PulumiRunner }): Promise<ReleaseCopyPrepared> {
+  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(): void {
   prepared.clear();
 }

package/src/run-plan-flags.test.ts

@@ -0,0 +1,53 @@
+/**
+ * `--refresh` and `--target-dependents` through the pulumi lexicon's
+ * allowlists (#4627): both in the preview and in stock `pulumi up`, in the
+ * tail's order, `--target-dependents` only after a `--target`, and no
+ * `--refresh` on plunge's `up --plan`, which applies a saved plan whose
+ * preview refreshed. Written for the ci-products post-merge pass.
+ */
+import { describe, expect, test } from "vitest";
+import { plungeUpArgs, pulumiUpArgs, pulumiUpPreviewArgs, runAllowedPlunge, runAllowedPulumi, runApplyPlunge, runApplyPulumi, type PulumiRunner } from "./run";
+import { createPulumiUpCapability } from "./pulumi-up";
+
+function fake(): { run: PulumiRunner; calls: string[][] } {
+  const calls: string[][] = [];
+  return { run: async (args) => (calls.push(args), { stdout: "" }), calls };
+}
+
+describe("--refresh and --target-dependents (#4627)", () => {
+  test("the preview carries them in the tail's order", async () => {
+    const args = pulumiUpPreviewArgs({ stack: "dev", refresh: true, targets: ["urn:a"], targetDependents: true });
+    expect(args).toEqual(["preview", "--json", "--show-sames", "--stack", "dev", "--refresh", "--target", "urn:a", "--target-dependents"]);
+    const { run, calls } = fake();
+    await runAllowedPulumi(run, args, "/tmp");
+    await runAllowedPlunge(run, args, "/tmp");
+    expect(calls).toHaveLength(2);
+  });
+
+  test("--target-dependents is dropped without a target", () => {
+    expect(pulumiUpPreviewArgs({ stack: "dev", targetDependents: true })).not.toContain("--target-dependents");
+  });
+
+  test("stock up takes both; plunge up --plan takes --target-dependents and no --refresh", async () => {
+    const { run, calls } = fake();
+    await runApplyPulumi(run, pulumiUpArgs({ stack: "dev", refresh: true, targets: ["urn:a"], targetDependents: true }), "/tmp");
+    await runApplyPlunge(run, plungeUpArgs({ plan: "/tmp/p.json", stack: "dev", targets: ["urn:a"], targetDependents: true }), "/tmp");
+    expect(calls).toEqual([
+      ["up", "--yes", "--json", "--stack", "dev", "--refresh", "--target", "urn:a", "--target-dependents"],
+      ["up", "--plan", "/tmp/p.json", "--yes", "--json", "--stack", "dev", "--target", "urn:a", "--target-dependents"],
+    ]);
+    await expect(runApplyPlunge(run, ["up", "--plan", "/tmp/p.json", "--yes", "--json", "--stack", "dev", "--refresh"], "/tmp")).rejects.toThrow(/applies a plunge stack only as/);
+  });
+
+  test("out of order, or --target-dependents with no target, is refused", async () => {
+    const { run, calls } = fake();
+    for (const tail of [["--target-dependents"], ["--target", "urn:a", "--refresh"], ["--target-dependents", "--target", "urn:a"], ["--refresh", "--refresh"]]) {
+      await expect(runApplyPulumi(run, ["up", "--yes", "--json", "--stack", "dev", ...tail], "/tmp"), tail.join(" ")).rejects.toThrow(/applies a Pulumi stack only as/);
+    }
+    expect(calls).toEqual([]);
+  });
+
+  test("the capability says it takes both", () => {
+    expect(createPulumiUpCapability().planFlags).toEqual({ refresh: "accept", targetDependents: "accept" });
+  });
+});

package/src/run.test.ts

@@ -464,7 +464,7 @@ describe("the apply entry points (#4541)", () => {
   test("anything off the list is refused before the runner", async () => {
     const { run, calls } = fake(() => "");
     const base = pulumiUpArgs({ stack: "floci" });
-    for (const extra of [["--skip-preview"], ["--refresh"], ["--show-secrets"], ["--replace", "urn:a"], ["--target-replace", "urn:a"], ["--target-dependents"], ["--exclude", "urn:a"], ["--remote"], ["--continue-on-error"], ["--config", "k=v"], ["--plan", "/tmp/p.json"]]) {
+    for (const extra of [["--skip-preview"], ["--show-secrets"], ["--replace", "urn:a"], ["--target-replace", "urn:a"], ["--target-dependents"], ["--exclude", "urn:a"], ["--remote"], ["--continue-on-error"], ["--config", "k=v"], ["--plan", "/tmp/p.json"]]) {
       await expect(runApplyPulumi(run, [...base, ...extra], "/tmp")).rejects.toThrow(/applies a Pulumi stack only as/);
     }
     for (const args of [