@intentius/chant-lexicon-pulumi 0.124.56 → 0.124.57

package/src/pulumi-up.test.ts

@@ -299,6 +299,63 @@ describe("releaseInputs (#4542)", () => {
   });
 });
 
+describe("the step's backend (plywood#22)", () => {
+  const store = "plunge+s3://plywood-tutorial-plunge?region=us-east-1&endpoint=http://floci:4566&s3ForcePathStyle=true";
+
+  test("plunge's preview, up and output read each get it as PULUMI_BACKEND_URL, over the job's", async () => {
+    const plunge = engine();
+    const cap = createPulumiUpCapability({ plunge: plunge.run, env: { PULUMI_BACKEND_URL: "file:///tmp/plywood-tutorial-backend" }, tmp: tmp(), snapshots: null });
+    const planned = await cap.plan!(ctx, step({ engine: "plunge", backend: store }));
+    await cap.run({ ...ctx, plans: { [member]: planned.artifact as PulumiUpArtifact } }, step({ engine: "plunge", backend: store }));
+    expect(plunge.calls.map((c) => c.args[0])).toEqual(["preview", "up", "stack"]);
+    for (const c of plunge.calls) expect(c.env?.PULUMI_BACKEND_URL).toBe(store);
+    // The preview keeps its streaming flag beside the backend.
+    expect(plunge.calls[0].env).toEqual({ [PULUMI_STREAMING_PREVIEW_ENV]: "true", PULUMI_BACKEND_URL: store });
+  });
+
+  test("stock Pulumi's preview, up and output read get it too, and outputs() reads through it", async () => {
+    const pulumi = engine();
+    const s3 = "s3://plywood-tutorial-state?region=us-east-1&endpoint=http://floci:4566&use_path_style=true";
+    const cap = createPulumiUpCapability({ run: pulumi.run, env: {}, tmp: tmp(), snapshots: null });
+    const planned = await cap.plan!(ctx, step({ engine: "pulumi", backend: s3 }));
+    await cap.run({ ...ctx, plans: { [member]: planned.artifact as PulumiUpArtifact } }, step({ engine: "pulumi", backend: s3 }));
+    await cap.outputs!(ctx, step({ engine: "pulumi", backend: s3 }));
+    expect(pulumi.calls.length).toBeGreaterThanOrEqual(4);
+    for (const c of pulumi.calls) expect(c.env?.PULUMI_BACKEND_URL).toBe(s3);
+  });
+
+  test("a plunge+ backend picks plunge where the job's PULUMI_BACKEND_URL would have picked stock Pulumi", async () => {
+    const plunge = engine();
+    const pulumi = engine();
+    const cap = createPulumiUpCapability({ run: pulumi.run, plunge: plunge.run, env: { PULUMI_BACKEND_URL: "file:///tmp/b" }, tmp: tmp(), snapshots: null });
+    const planned = await cap.plan!(ctx, step({ backend: store }));
+    expect((planned.artifact as PulumiUpArtifact).engine).toBe("plunge");
+    expect(pulumi.calls).toHaveLength(0);
+    expect(cap.defaultLockGrain!(step({ backend: store }))).toBe("resource");
+  });
+
+  test("the ledger lock (ruling for ci-products 2026-10-28): a stack's target row is its stack row, from Pulumi.yaml's name", () => {
+    const cap = createPulumiUpCapability({ env: {}, tmp: tmp(), snapshots: null });
+    expect(cap.targetLockRow!(step())).toEqual({ key: "stack corpus-aws-ts/floci", target: member, address: "corpus-aws-ts/floci" });
+    // A plunge stack on the resource grain still leases URN rows; the stack row it may also take meets this one.
+    expect(cap.targetLockRow!(step({ stack: "prod-us" }))).toMatchObject({ key: "stack corpus-aws-ts/prod-us" });
+  });
+
+  test("without it nothing changes: no PULUMI_BACKEND_URL is added", async () => {
+    const plunge = engine();
+    const cap = createPulumiUpCapability({ plunge: plunge.run, env: {}, tmp: tmp(), snapshots: null });
+    await cap.plan!(ctx, step({ engine: "plunge" }));
+    expect(plunge.calls[0].env).toEqual({ [PULUMI_STREAMING_PREVIEW_ENV]: "true" });
+  });
+
+  test("an empty backend is refused before anything runs", async () => {
+    const plunge = engine();
+    const cap = createPulumiUpCapability({ plunge: plunge.run, env: {}, tmp: tmp(), snapshots: null });
+    await expect(cap.plan!(ctx, step({ engine: "plunge", backend: " " }))).rejects.toThrow(/"backend" is the stack's backend URL/);
+    expect(plunge.calls).toHaveLength(0);
+  });
+});
+
 describe("a step pinned to its engine release (#4592)", () => {
   test("engineVersion runs the versioned binary, through the same argv checks", async () => {
     const pinned = engine();
@@ -423,6 +480,8 @@ describe("CrossGuard packs read at base (#4613)", () => {
     const stack = join(top, "stack");
     mkdirSync(join(stack, "guard"), { recursive: true });
     for (const f of ["Pulumi.yaml", "stack-export.json"]) copyFileSync(join(dir, f), join(stack, f));
+    // An installed checkout, so the step runs no install before the preview (plywood#22).
+    mkdirSync(join(stack, "node_modules"));
     writeFileSync(join(stack, "guard", "index.ts"), "// no-public-bucket: mandatory\n");
     git(top, "add", ".");
     git(top, "commit", "-q", "-m", "base");
@@ -468,3 +527,44 @@ describe("CrossGuard packs read at base (#4613)", () => {
     expect(pulumi.calls).toHaveLength(0);
   });
 });
+
+describe("an in-place checkout (plywood#22)", () => {
+  /** A checkout of the corpus program: Pulumi.yaml, package.json and, unless left out, a lockfile; no node_modules. */
+  function checkout(lockfile = true): string {
+    const stack = tmp();
+    for (const f of ["Pulumi.yaml", "stack-export.json"]) copyFileSync(join(dir, f), join(stack, f));
+    writeFileSync(join(stack, "package.json"), "{}\n");
+    if (lockfile) writeFileSync(join(stack, "package-lock.json"), "{}\n");
+    return stack;
+  }
+
+  test("a Node checkout with a lockfile and no node_modules gets one install, with the step's backend, before the first preview", async () => {
+    const stack = checkout();
+    const pulumi = engine();
+    const cap = createPulumiUpCapability({ run: pulumi.run, env: {}, tmp: tmp(), snapshots: null });
+    const planned = await cap.plan!(ctx, step({ dir: stack, engine: "pulumi", backend: "s3://shop-state" }));
+    expect(pulumi.calls[0]).toMatchObject({ args: ["install"], cwd: stack, env: { PULUMI_BACKEND_URL: "s3://shop-state" } });
+    expect(pulumi.calls[1]!.args[0]).toBe("preview");
+
+    await cap.run({ ...ctx, plans: { [planned.member]: planned.artifact as PulumiUpArtifact } }, step({ dir: stack, engine: "pulumi", backend: "s3://shop-state" }));
+    expect(pulumi.calls.filter((c) => c.args[0] === "install")).toHaveLength(1);
+    expect(pulumi.calls.some((c) => c.args[0] === "up")).toBe(true);
+  });
+
+  test("a Node checkout with no lockfile is refused by name before the engine runs", async () => {
+    const stack = checkout(false);
+    const pulumi = engine();
+    const cap = createPulumiUpCapability({ run: pulumi.run, env: {}, tmp: tmp(), snapshots: null });
+    await expect(cap.plan!(ctx, step({ dir: stack, engine: "pulumi" }))).rejects.toThrow(/no lockfile .* beside its package.json/);
+    expect(pulumi.calls).toHaveLength(0);
+  });
+
+  test("an installed checkout runs no install", async () => {
+    const stack = checkout();
+    mkdirSync(join(stack, "node_modules"));
+    const pulumi = engine();
+    const cap = createPulumiUpCapability({ run: pulumi.run, env: {}, tmp: tmp(), snapshots: null });
+    await cap.plan!(ctx, step({ dir: stack, engine: "pulumi" }));
+    expect(pulumi.calls.map((c) => c.args[0])).not.toContain("install");
+  });
+});

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
@@ -170,6 +176,7 @@ 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,
@@ -192,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). */
@@ -210,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
@@ -540,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 } : {}) };
 }
 
 /**
@@ -574,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 };
   }
@@ -583,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. */
@@ -695,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> {
@@ -708,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({
@@ -873,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;
@@ -1027,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.ts

@@ -644,11 +644,11 @@ export async function runReviewStackPlunge(run: PulumiRunner, args: string[], cw
 }
 
 /**
- * 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: readonly string[] = ["pulumi install", "plunge install"];
 

package/src/stack-export-snapshot.test.ts

@@ -9,7 +9,7 @@
  * `local` store in a temp directory, so no git ref is written, no engine
  * runs and nothing reaches a backend.
  */
-import { cpSync, mkdtempSync, readFileSync } from "node:fs";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, test } from "vitest";
@@ -42,6 +42,8 @@ const localStore = (): SnapshotStore => createSnapshotStore({ store: "local", di
 function unexportedStack(): string {
   const dir = tmp();
   cpSync(join(testdata, "pulumi-preview", "Pulumi.yaml"), join(dir, "Pulumi.yaml"));
+  // Installed, so the step runs no install before the preview (plywood#22).
+  mkdirSync(join(dir, "node_modules"));
   return dir;
 }