@intentius/chant-lexicon-pulumi 0.124.57 → 0.124.59

package/dist/stack-ops.js

@@ -16,6 +16,7 @@
  * | export | `stack-export` | `<stack>` | `stack`, `engine`, `deliver: requester` |
  * | cancel | `stack-cancel` | `<stack>` | `stack`, `lockId` |
  * | move | `stack-move` | `move:<source>:<dest>` | `source`, `dest`, `engine`, `urns` (sorted, comma-joined) |
+ * | action | `stack-action` | `action:<stack>:<name>` (the URN without a name) | `stack`, `urn`, `engine`, `preview` (the preview's digest), `name` when given |
  *
  * The first call records the pending fact and answers `waiting` with the
  * `chant approve` command. A later call with the same request reuses the
@@ -47,17 +48,30 @@
  *   again afterwards; a change left on either finishes the request `failed`
  *   with the changes named.
  *
+ * - action (#4654): a day-2 action is a `command:` resource
+ *   (`command:local:Command`, `command:remote:Command`) whose replacement is
+ *   the operation. Its type is checked before anything runs (`action-type`).
+ *   Each call previews `preview --json --target <urn> --replace <urn>`, and
+ *   refuses (`action-scope`) unless the preview changes that URN alone, by
+ *   a replacement. The request binds the preview's digest, so a preview
+ *   that moved after the approval asks again. Once approved, `up --yes
+ *   --target <urn> --replace <urn> --stack <s>` under the stack's engine,
+ *   and the finished line keeps chant's `applied | failed` with
+ *   `detail.result` `ok` or `failed`, the exit code and the output's last
+ *   lines. A request that applied answers `spent` to the same call, unless
+ *   the caller asks `anew`.
+ *
  * The writes go through `runGatedPulumi` and `runGatedPlunge`
  * (`./run.ts`), whose fixed forms are the whole of what may run.
  */
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
-import { pulumiNodeKey } from "@intentius/chant/pulumi-urn";
+import { parsePulumiUrn, pulumiNodeKey } from "@intentius/chant/pulumi-urn";
 import { pulumiStackBackend } from "./adopt.js";
-import { pulumiExportResources } from "./change-set.js";
+import { pulumiExportResources, pulumiPreviewDigest, pulumiSteps, PULUMI_UNCHANGED_OPS } from "./change-set.js";
 import { pulumiMemberEngine } from "./member-engine.js";
-import { defaultPlungeRunner, defaultPulumiRunner, plungeMoveArgs, previewPulumiMemberRead, pulumiCancelArgs, pulumiRunFailure, pulumiStateMoveArgs, runAllowedPlunge, runAllowedPulumi, runGatedPlunge, runGatedPulumi, } from "./run.js";
+import { defaultPlungeRunner, defaultPulumiRunner, plungeMoveArgs, previewPulumiMemberRead, pulumiActionPreviewArgs, pulumiActionUpArgs, pulumiCancelArgs, pulumiRunFailure, pulumiStateMoveArgs, runAllowedPlunge, runAllowedPulumi, runGatedPlunge, runGatedPulumi, } from "./run.js";
 import { isObject } from "./values.js";
 /** The op the requests are recorded under, unless the caller names its own. */
 export const PULUMI_STACK_OPS_OP = "pulumi-stack-ops";
@@ -80,12 +94,13 @@ const sameFields = (a, b) => Object.keys(a).length === Object.keys(b).length &&
  * every operation. `precheck` runs after the approval and before the request
  * is spent, so a refusal there leaves the approval unspent.
  */
-async function askThenAct(common, kind, subject, fields, description, act, precheck) {
+async function askThenAct(common, kind, subject, fields, description, act, precheck, options = {}) {
     const api = await gatedApi(common.gated);
     const op = common.op ?? PULUMI_STACK_OPS_OP;
     const cwd = common.ledgerCwd ?? process.cwd();
+    // With reuseApplied (#4654), a request with these fields that applied already is asked again as itself, so it answers `spent`.
     const standing = (await api.readGatedRequests(op, { cwd }).catch(() => []))
-        .filter((r) => !r.applied && r.request.kind === kind && r.request.subject === subject && r.request.by === common.by && sameFields(r.request.fields, fields))
+        .filter((r) => (options.reuseApplied || !r.applied) && r.request.kind === kind && r.request.subject === subject && r.request.by === common.by && sameFields(r.request.fields, fields))
         .at(-1);
     const request = { kind, subject, by: common.by, at: standing?.request.at ?? common.now ?? new Date().toISOString(), fields };
     const asked = await api.requestGate({
@@ -398,3 +413,121 @@ export async function gatedStackMove(opts) {
         }
     });
 }
+/** A stack action refused before its request: `code` says why, `urns` names what the preview changed besides the action, for `action-scope`. */
+export class PulumiStackActionRefused extends Error {
+    constructor(code, message, urns = []) {
+        super(`${code}: ${message}`);
+        this.name = "PulumiStackActionRefused";
+        this.code = code;
+        this.urns = urns;
+    }
+}
+/** The resource types an action may name: the command provider's (`command:local:Command`, `command:remote:Command`). */
+export const PULUMI_ACTION_TYPE_PREFIX = "command:";
+/** An action's name as a caller's config gives it, for the request's subject. */
+const ACTION_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,99}$/;
+/** The subject an action's request is asked and approved under: `action:<stack>:<name>`, or the URN in place of a name. */
+export const stackActionSubject = (stack, nameOrUrn) => `action:${stack}:${nameOrUrn}`;
+/** The last `n` lines of `text`, trimmed. */
+const lastLines = (text, n) => (text ?? "").trim().split("\n").slice(-n).join("\n");
+/**
+ * Check an action's URN before anything runs: a Pulumi URN on `stack` whose
+ * type is a command provider's. Throws {@link PulumiStackActionRefused}.
+ */
+export function checkStackActionUrn(stack, urn) {
+    const parsed = parsePulumiUrn(urn);
+    if (!parsed)
+        throw new PulumiStackActionRefused("action-urn", `${JSON.stringify(urn)} is not a resource URN (urn:pulumi:<stack>::<project>::<type>::<name>)`);
+    const stackName = stack.split("/").at(-1);
+    if (parsed.stack !== stackName)
+        throw new PulumiStackActionRefused("action-urn", `${urn} names stack ${parsed.stack}, and the action runs on ${stack}`);
+    if (!parsed.type.startsWith(PULUMI_ACTION_TYPE_PREFIX)) {
+        throw new PulumiStackActionRefused("action-type", `${urn} is a ${parsed.type}, and an action is a command resource (command:local:Command or command:remote:Command), whose replacement runs it; replacing any other resource is an update`);
+    }
+}
+/**
+ * What a preview changes besides the action's replacement (#4654): each URN
+ * with a changing step other than `urn`, and `urn` itself when it changes
+ * other than by replacement or is not replaced at all. Empty when the
+ * preview replaces `urn` and nothing else.
+ */
+export function stackActionScope(urn, preview) {
+    const steps = pulumiSteps(preview) ?? [];
+    const others = new Set();
+    let replaced = false;
+    let problem;
+    for (const s of steps) {
+        const op = s.op ?? "";
+        if (PULUMI_UNCHANGED_OPS.has(op))
+            continue;
+        if (s.urn !== urn) {
+            others.add(s.urn);
+            continue;
+        }
+        if (op === "replace" || op === "create-replacement" || op === "delete-replaced")
+            replaced = true;
+        else
+            problem = `the preview shows ${op} of ${urn}, not its replacement`;
+    }
+    if (!problem && !replaced)
+        problem = `the preview does not replace ${urn}`;
+    return { others: [...others].sort(), ...(problem ? { problem } : {}) };
+}
+/**
+ * A day-2 action on a stack (#4654): the replacement of one `command:`
+ * resource, previewed, asked for under a gated request, and run once a
+ * second identity approves. Refused before anything runs for a URN that is
+ * not a command resource's (`action-type`), and before anything is asked for
+ * a preview that changes more than that replacement (`action-scope`).
+ */
+export async function gatedStackAction(opts) {
+    checkStackActionUrn(opts.stack, opts.urn);
+    if (opts.name !== undefined && !ACTION_NAME.test(opts.name))
+        throw new Error(`an action's name is letters, digits, "_", "." and "-", not ${JSON.stringify(opts.name)}`);
+    const env = opts.env ?? process.env;
+    const dir = stackDirOf(opts.dir, opts.cwd);
+    const engine = engineOf(dir, opts.engine, env);
+    const target = { stack: opts.stack, urn: opts.urn };
+    const previewArgs = pulumiActionPreviewArgs(target);
+    let stdout;
+    try {
+        ({ stdout } = engine === "plunge" ? await runAllowedPlunge(opts.plunge ?? defaultPlungeRunner, previewArgs, dir) : await runAllowedPulumi(opts.run ?? defaultPulumiRunner, previewArgs, dir));
+    }
+    catch (err) {
+        throw new Error(`${engine} ${previewArgs.join(" ")} failed: ${why(err, engine)}`);
+    }
+    let preview;
+    try {
+        preview = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`${engine} ${previewArgs.join(" ")} printed no JSON`);
+    }
+    const scope = stackActionScope(opts.urn, preview);
+    if (scope.others.length > 0) {
+        throw new PulumiStackActionRefused("action-scope", `the preview of ${opts.stack} replacing ${opts.urn} also changes ${scope.others.join(", ")}, and an action replaces its command resource alone; nothing was asked for`, scope.others);
+    }
+    if (scope.problem)
+        throw new PulumiStackActionRefused("action-scope", `${scope.problem}; nothing was asked for`);
+    const digest = pulumiPreviewDigest(preview, { changedOnly: true });
+    const subject = stackActionSubject(opts.stack, opts.name ?? opts.urn);
+    const fields = { stack: opts.stack, urn: opts.urn, engine, preview: digest, ...(opts.name ? { name: opts.name } : {}) };
+    return askThenAct(opts, "stack-action", subject, fields, `action ${opts.name ?? opts.urn} on stack ${opts.stack}: replace ${opts.urn}, requested by ${opts.by}`, async () => {
+        const args = pulumiActionUpArgs(target);
+        try {
+            const done = engine === "plunge" ? await runGatedPlunge(opts.plunge ?? defaultPlungeRunner, args, dir) : await runGatedPulumi(opts.run ?? defaultPulumiRunner, args, dir);
+            const tail = lastLines(done.stdout, 10);
+            return { result: { urn: opts.urn, engine, preview: digest, exit: 0, tail }, detail: { result: "ok", exit: 0, tail: tail.slice(-400), urn: opts.urn } };
+        }
+        catch (err) {
+            const f = pulumiRunFailure(err);
+            const exit = f.exitCode ?? 1;
+            const tail = lastLines(`${f.stdout ?? ""}\n${f.stderr ?? ""}`, 10);
+            return {
+                result: { urn: opts.urn, engine, preview: digest, exit, tail },
+                detail: { result: "failed", exit, tail: tail.slice(-400), urn: opts.urn },
+                failed: `${engine} ${args.join(" ")} failed: ${why(err, engine)}`,
+            };
+        }
+    }, undefined, { reuseApplied: !opts.anew });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-pulumi",
-  "version": "0.124.57",
+  "version": "0.124.59",
   "type": "module",
   "files": [
     "src/",
@@ -54,7 +54,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.57",
+    "@intentius/chant": "^0.124.59",
     "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/drift-read.test.ts

@@ -9,13 +9,16 @@
  * `plunge-member`'s export is a cut of the recorded plunge stack's. No binary
  * runs here.
  */
-import { 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";
+import { createSnapshotStore } from "@intentius/chant/lifecycle/snapshot-store";
 import { foldDriftLines, type ReadDriftOptions } from "@intentius/chant/drift-record";
 import { readPulumiDrift } from "./drift-read";
 import { pulumiPlugin } from "./plugin";
 import type { PulumiRunner } from "./run";
+import { writePulumiExportSnapshot } from "./stack-export-snapshot";
 
 const testdata = join(import.meta.dirname, "testdata");
 const text = (...path: string[]) => readFileSync(join(testdata, ...path), "utf-8");
@@ -104,3 +107,72 @@ describe("readPulumiDrift", () => {
     expect(never.calls).toEqual([]);
   });
 });
+
+describe("readPulumiDrift with --stack", () => {
+  const exportText = text("pulumi-preview", "stack-export.json");
+
+  /** A member directory with Pulumi.yaml and no checked-in export, and a store holding the stacks named. */
+  async function memberWithStore(stacks: string[]) {
+    const dir = mkdtempSync(join(tmpdir(), "pulumi-drift-stack-"));
+    cpSync(join(testdata, "pulumi-preview", "Pulumi.yaml"), join(dir, "Pulumi.yaml"));
+    mkdirSync(join(dir, "node_modules"));
+    const store = createSnapshotStore({ store: "local", dir: mkdtempSync(join(tmpdir(), "pulumi-drift-store-")) });
+    for (const stack of stacks) {
+      const wrote = await writePulumiExportSnapshot({
+        dir,
+        stack,
+        environment: "prod",
+        engine: "pulumi",
+        run: async () => ({ stdout: exportText }),
+        store,
+      });
+      expect(wrote.written, JSON.stringify(wrote)).toBe(true);
+    }
+    return { dir, store };
+  }
+
+  test("reads the named stack's stored export and passes that stack to every refresh", async () => {
+    const { dir, store } = await memberWithStore(["staging", "prod-eu"]);
+    const pulumi = fake(() => text("pulumi-refresh", "bucket-edited.json"));
+    const answer = await readPulumiDrift(options(dir, { stack: "prod-eu" }), { run: pulumi.run, plunge: never.run, exportStore: store });
+    if (!("lines" in answer)) throw new Error(JSON.stringify(answer));
+    expect(pulumi.calls.length).toBeGreaterThan(0);
+    for (const call of pulumi.calls) expect(call.slice(call.indexOf("--stack"), call.indexOf("--stack") + 2)).toEqual(["--stack", "prod-eu"]);
+  });
+
+  test("beats the member's declared stack", async () => {
+    const { dir, store } = await memberWithStore(["staging", "prod-eu"]);
+    const pulumi = fake(() => text("pulumi-refresh", "bucket-edited.json"));
+    const config = { pulumi: { member: { dir, label: "site", stack: "staging" } } };
+    const answer = await readPulumiDrift({ ...options(dir, { stack: "prod-eu", resource: bucket }), config }, { run: pulumi.run, plunge: never.run, exportStore: store });
+    expect("lines" in answer).toBe(true);
+    expect(pulumi.calls).toEqual([["refresh", "--preview-only", "--json", "--stack", "prod-eu", "--target", bucket]]);
+  });
+
+  test("a store with no export for that stack is an error naming the stack, and nothing runs", async () => {
+    const { dir, store } = await memberWithStore(["staging"]);
+    const spy = fake(() => text("pulumi-refresh", "bucket-edited.json"));
+    const answer = await readPulumiDrift(options(dir, { stack: "prod-eu" }), { run: spy.run, plunge: never.run, exportStore: store });
+    expect(answer).toMatchObject({ refused: { code: "no-drift-read" } });
+    expect("refused" in answer && answer.refused.message).toMatch(/holds no export for stack prod-eu of site/);
+    expect(spy.calls).toEqual([]);
+  });
+
+  test("an empty store is refused too, though a checked-in export sits beside the member", async () => {
+    const dir = join(testdata, "pulumi-preview");
+    const store = createSnapshotStore({ store: "local", dir: mkdtempSync(join(tmpdir(), "pulumi-drift-store-")) });
+    const spy = fake(() => text("pulumi-refresh", "bucket-edited.json"));
+    const answer = await readPulumiDrift(options(dir, { stack: "floci" }), { run: spy.run, plunge: never.run, exportStore: store });
+    expect(answer).toMatchObject({ refused: { code: "no-drift-read" } });
+    expect(spy.calls).toEqual([]);
+  });
+
+  test("without --stack the read is as before: the checked-in export when the store has none", async () => {
+    const dir = join(testdata, "pulumi-preview");
+    const store = createSnapshotStore({ store: "local", dir: mkdtempSync(join(tmpdir(), "pulumi-drift-store-")) });
+    const pulumi = fake(() => text("pulumi-refresh", "bucket-edited.json"));
+    const answer = await readPulumiDrift(options(dir, { resource: bucket }), { run: pulumi.run, plunge: never.run, exportStore: store });
+    expect("lines" in answer).toBe(true);
+    expect(pulumi.calls).toEqual([["refresh", "--preview-only", "--json", "--stack", "floci", "--target", bucket]]);
+  });
+});

package/src/drift-read.ts

@@ -13,8 +13,12 @@
  * | plunge | unset | `plunge drift --resource <urn> --stream`, once per resource in the export |
  * | plunge | `<urn>` | the same, for that URN alone |
  *
- * Each read passes `--stack` (#4496): the member's declared
- * `pulumi.member.stack`, else the stack the export's URNs name.
+ * Each read passes `--stack` (#4496): the stack asked for (`chant workspace
+ * drift --stack`), else the member's declared `pulumi.member.stack`, else the
+ * stack the export's URNs name. A stack asked for is read from that stack's
+ * export in the index store alone; with none there the read is refused
+ * (`no-drift-read`), where without `--stack` the member reads the store's
+ * export, then the checked-in file.
  *
  * The one read is `refresh`. The member's engine is `pulumiMemberEngine`'s:
  * the member config's `engine`, then a plunge backend URL in `Pulumi.yaml`.
@@ -27,11 +31,15 @@ import type { DriftLine, DriftRecord, ReadDriftOptions, ReadDriftResult } from "
 import { driftRecordLine, driftSettle, driftStart } from "@intentius/chant/drift-record";
 import type { PulumiConfig } from "./config";
 import { pulumiMemberEngine, refreshPulumiMember, type PulumiRunner } from "./run";
+import { readStoredPulumiExport } from "./stack-export-snapshot";
+import type { SnapshotStore } from "@intentius/chant/lifecycle/snapshot-store";
 
 /** The runners, injectable so the tests run no binary. */
 export interface PulumiDriftRunners {
   run?: PulumiRunner;
   plunge?: PulumiRunner;
+  /** The index store the exports are read from. Default: the project's. */
+  exportStore?: SnapshotStore | null;
 }
 
 /** `LexiconPlugin.readDrift` for the pulumi lexicon. */
@@ -42,6 +50,18 @@ export async function readPulumiDrift(options: ReadDriftOptions, runners: Pulumi
     return { refused: { code: "read-unsupported", message: `a Pulumi member answers refresh, not ${options.read}` } };
   }
   const { engine } = pulumiMemberEngine(member.dir, member.engine);
+  const stack = options.stack ?? member.stack;
+  if (options.stack !== undefined) {
+    const stored = await readStoredPulumiExport({ dir: member.dir, stack: options.stack, ...(runners.exportStore !== undefined ? { store: runners.exportStore } : {}) });
+    if (!stored) {
+      return {
+        refused: {
+          code: "no-drift-read",
+          message: `the index store holds no export for stack ${options.stack} of ${options.member}; the pulumi-up capability writes one after each apply through chant, so apply that stack once, or read without --stack`,
+        },
+      };
+    }
+  }
   let records: DriftRecord[];
   try {
     records = await refreshPulumiMember({
@@ -49,7 +69,8 @@ export async function readPulumiDrift(options: ReadDriftOptions, runners: Pulumi
       dir: member.dir,
       observedAt: options.observedAt,
       ...(member.engine ? { engine: member.engine } : {}),
-      ...(member.stack ? { stack: member.stack } : {}),
+      ...(stack ? { stack } : {}),
+      ...(runners.exportStore !== undefined ? { exportStore: runners.exportStore } : {}),
       ...(options.resource !== undefined ? { urns: [options.resource] } : {}),
       ...(runners.run ? { run: runners.run } : {}),
       ...(runners.plunge ? { plunge: runners.plunge } : {}),

package/src/index.ts

@@ -108,7 +108,7 @@ export { readPulumiDrift, type PulumiDriftRunners } from "./drift-read";
 export { pulumiAuditCatalog } from "./lint/audit-catalog";
 // The Preview/Drift watch composite and its step builders (#4494).
 export { PulumiWatchOp, type PulumiWatchOpConfig, type PulumiWatchOpResources } from "./composites/pulumi-watch-op";
-export { gatedStackExport, gatedStackCancel, gatedStackMove, moveLeftovers, diyStackLockIds, pulumiStackLockIds, type PulumiStackLocks, PULUMI_STACK_OPS_OP, type PulumiStackOpOutcome, type PulumiStackOpCommon, type PulumiStackOpKind } from "./stack-ops";
+export { gatedStackExport, gatedStackCancel, gatedStackMove, gatedStackAction, checkStackActionUrn, stackActionScope, stackActionSubject, PulumiStackActionRefused, PULUMI_ACTION_TYPE_PREFIX, type PulumiStackActionOptions, type PulumiStackActionResult, type PulumiStackActionRefusal, moveLeftovers, diyStackLockIds, pulumiStackLockIds, type PulumiStackLocks, PULUMI_STACK_OPS_OP, type PulumiStackOpOutcome, type PulumiStackOpCommon, type PulumiStackOpKind } from "./stack-ops";
 // Review stacks (INTENTIUS/plywood#15): pr-<n> stacks only.
 export {
   initReviewStack,

package/src/lint/post-synth/post-synth.test.ts

@@ -1,5 +1,7 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, describe, expect, test } from "vitest";
+import { afterEach, describe, expect, test, vi } from "vitest";
 import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
 import { PULUMI_SECRET_SIG, PULUMI_SIG_KEY } from "../../values";
 import { setLastMemberRead, setLastMemberReport } from "../../workspace-member";
@@ -23,6 +25,7 @@ import { pul015 } from "./pul015";
 const ctx = { outputs: new Map(), entities: new Map() } as unknown as PostSynthContext;
 
 afterEach(() => {
+  vi.unstubAllEnvs();
   setLastMemberReport(undefined);
   setLastMemberRead(undefined);
 });
@@ -196,4 +199,47 @@ describe("pulumi post-synth checks", () => {
     readWith([], { dir: stockDir, engine: "plunge" });
     expect(pul015.check(ctx)).toEqual([]);
   });
+
+  test("PUL015 names the source of the resolved plunge engine", () => {
+    // Pulumi.yaml
+    readWith([], { dir: plungeDir, engine: "pulumi" });
+    expect(pul015.check(ctx)[0].message).toContain("Pulumi.yaml names the plunge backend");
+
+    // PULUMI_BACKEND_URL, on a program whose Pulumi.yaml names no backend
+    vi.stubEnv("PULUMI_BACKEND_URL", "plunge+s3://bucket/state");
+    readWith([], { dir: stockDir, engine: "pulumi" });
+    const fromEnv = pul015.check(ctx);
+    expect(fromEnv).toHaveLength(1);
+    expect(fromEnv[0].message).toContain("PULUMI_BACKEND_URL names the plunge backend plunge+s3://bucket/state");
+    readWith([], { dir: stockDir, engine: "plunge" });
+    expect(pul015.check(ctx)).toEqual([]);
+    vi.stubEnv("PULUMI_BACKEND_URL", "s3://bucket/state");
+    readWith([], { dir: stockDir, engine: "pulumi" });
+    expect(pul015.check(ctx)).toEqual([]);
+    vi.unstubAllEnvs();
+
+    // plywood.yml, engine and backend
+    const root = mkdtempSync(join(tmpdir(), "pul015-"));
+    mkdirSync(join(root, ".git"));
+    const member = join(root, "infra");
+    mkdirSync(member);
+    writeFileSync(join(member, "Pulumi.yaml"), "name: app\nruntime: nodejs\n");
+    writeFileSync(join(root, "plywood.yml"), "engine: plunge\n");
+    readWith([], { dir: member, engine: "pulumi" });
+    const fromEngine = pul015.check(ctx);
+    expect(fromEngine).toHaveLength(1);
+    expect(fromEngine[0].message).toContain("plywood.yml says engine: plunge");
+    writeFileSync(join(root, "plywood.yml"), "backend: plunge+file:///state\n");
+    const fromBackend = pul015.check(ctx);
+    expect(fromBackend).toHaveLength(1);
+    expect(fromBackend[0].message).toContain("plywood.yml names the plunge backend plunge+file:///state");
+    writeFileSync(join(root, "plywood.yml"), "engine: pulumi\n");
+    expect(pul015.check(ctx)).toEqual([]);
+  });
+
+  test("PUL015 does not report the other direction: engine plunge on a stock backend", () => {
+    vi.stubEnv("PULUMI_BACKEND_URL", "s3://bucket/state");
+    readWith([], { dir: stockDir, engine: "plunge" });
+    expect(pul015.check(ctx)).toEqual([]);
+  });
 });

package/src/lint/post-synth/pul015.ts

@@ -9,8 +9,9 @@
  * `plunge+file://...` or `plunge://...` runs stock `pulumi` against a
  * backend scheme only plunge opens, and every read fails.
  *
- * The other direction, `engine: "plunge"` with a stock backend, is not
- * reported: plunge is a Pulumi fork and the config may mean it.
+ * One direction only, by maintainer ruling (#4559): `engine: "plunge"` with a
+ * stock backend is not reported, because plunge opens stock backends and the
+ * config may mean it.
  */
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import { pulumiMemberEngine } from "../../run";
@@ -19,7 +20,7 @@ import { finding } from "./member-read-helpers";
 
 export const pul015: PostSynthCheck = {
   id: "PUL015",
-  description: "pulumi.member.engine says pulumi, but Pulumi.yaml names a plunge backend",
+  description: "pulumi.member.engine says pulumi, but the resolved engine is plunge",
 
   check(_ctx: PostSynthContext): PostSynthDiagnostic[] {
     const read = lastMemberRead();

package/src/run.test.ts

@@ -14,6 +14,8 @@ import {
   plungeAdoptArgs,
   plungeGraphArgs,
   plungeMoveArgs,
+  pulumiActionPreviewArgs,
+  pulumiActionUpArgs,
   pulumiCancelArgs,
   pulumiStateMoveArgs,
   runGatedPlunge,
@@ -93,6 +95,44 @@ describe("gated stack operations (#4578)", () => {
   });
 });
 
+describe("a stack action's forms (#4654)", () => {
+  const u = "urn:pulumi:prod-us::shop::command:local:Command::rotate";
+  const other = "urn:pulumi:prod-us::shop::command:local:Command::flush";
+  test("the preview is a read; the update passes the gated entry points only", async () => {
+    const { run, calls } = fake(() => "{}");
+    await runAllowedPulumi(run, pulumiActionPreviewArgs({ stack: "prod-us", urn: u }), "/tmp");
+    await runAllowedPlunge(run, pulumiActionPreviewArgs({ stack: "prod-us", urn: u }), "/tmp");
+    await runGatedPulumi(run, pulumiActionUpArgs({ stack: "prod-us", urn: u }), "/tmp");
+    await runGatedPlunge(run, pulumiActionUpArgs({ stack: "prod-us", urn: u }), "/tmp");
+    const up = ["up", "--yes", "--target", u, "--replace", u, "--stack", "prod-us"];
+    expect(calls.map((c) => c.args)).toEqual([
+      ["preview", "--json", "--target", u, "--replace", u, "--stack", "prod-us"],
+      ["preview", "--json", "--target", u, "--replace", u, "--stack", "prod-us"],
+      up,
+      up,
+    ]);
+  });
+
+  test("no other update form gets through", async () => {
+    const { run, calls } = fake(() => "{}");
+    const up = pulumiActionUpArgs({ stack: "prod-us", urn: u });
+    await expect(runAllowedPulumi(run, up, "/tmp")).rejects.toThrow(/not pulumi up/);
+    await expect(runApplyPulumi(run, up, "/tmp")).rejects.toThrow();
+    for (const args of [
+      ["up", "--yes", "--target", u, "--replace", other, "--stack", "prod-us"],
+      ["up", "--yes", "--replace", u, "--stack", "prod-us"],
+      ["up", "--yes", "--target", u, "--replace", u, "--stack", "prod-us", "--skip-preview"],
+      ["up", "--target", u, "--replace", u, "--stack", "prod-us"],
+      ["up", "--yes", "--target", "rotate", "--replace", "rotate", "--stack", "prod-us"],
+      ["up", "--yes", "--target", u, "--replace", u, "--stack", "--json"],
+    ]) {
+      await expect(runGatedPulumi(run, args, "/tmp")).rejects.toThrow(/gated Pulumi stack operation only as/);
+      await expect(runGatedPlunge(run, args, "/tmp")).rejects.toThrow(/plunge stack action only as/);
+    }
+    expect(calls).toEqual([]);
+  });
+});
+
 describe("plunge stack adopt (#4562)", () => {
   test("the preview form passes runAllowedPlunge, and only runAdoptPlunge runs --yes", async () => {
     const { run, calls } = fake(() => "{}");

package/src/run.ts

@@ -492,13 +492,45 @@ export async function runAdoptPlunge(run: PulumiRunner, args: string[], cwd: str
  *
  * - `pulumi cancel --yes --stack <stack>`: releases a stuck update's lock;
  * - `pulumi state move --source <stack> --dest <stack> --yes <urn>...`: moves
- *   resources between stock stacks, never `--include-parents`.
+ *   resources between stock stacks, never `--include-parents`;
+ * - `pulumi up --yes --target <urn> --replace <urn> --stack <stack>`: a
+ *   day-2 action (#4654), the replacement of one `command:` resource, the
+ *   same URN in both places. Its preview, `preview --json --target <urn>
+ *   --replace <urn> --stack <stack>`, is a read and passes
+ *   {@link runAllowedPulumi}. `up` takes `--replace` here only:
+ *   {@link PULUMI_APPLY_COMMANDS} still refuses it.
  */
 export const PULUMI_GATED_COMMANDS: readonly string[] = [
   "pulumi cancel --yes --stack <stack>",
   "pulumi state move --source <stack> --dest <stack> --yes <urn>...",
+  "pulumi up --yes --target <urn> --replace <urn> --stack <stack>",
 ];
 
+/** A stack action's preview (#4654): `preview --json --target <urn> --replace <urn> --stack <stack>`, a read. */
+export function pulumiActionPreviewArgs(opts: { stack: string; urn: string }): string[] {
+  return ["preview", "--json", "--target", opts.urn, "--replace", opts.urn, "--stack", opts.stack];
+}
+
+/** A stack action's update (#4654): `up --yes --target <urn> --replace <urn> --stack <stack>`, under `pulumi` or `plunge`. */
+export function pulumiActionUpArgs(opts: { stack: string; urn: string }): string[] {
+  return ["up", "--yes", "--target", opts.urn, "--replace", opts.urn, "--stack", opts.stack];
+}
+
+/** Exactly {@link pulumiActionUpArgs}' form: one URN, targeted and replaced, on one stack. */
+function allowedActionUp(args: readonly string[]): boolean {
+  return (
+    args.length === 8 &&
+    args[0] === "up" &&
+    args[1] === "--yes" &&
+    args[2] === "--target" &&
+    isUrn(args[3]) &&
+    args[4] === "--replace" &&
+    args[5] === args[3] &&
+    args[6] === "--stack" &&
+    isValue(args[7])
+  );
+}
+
 /**
  * plunge's resource move (INTENTIUS/plunge#56) in its two forms. The first
  * prints the plan and writes nothing, so it passes {@link runAllowedPlunge};
@@ -507,6 +539,7 @@ export const PULUMI_GATED_COMMANDS: readonly string[] = [
 export const PLUNGE_GATED_COMMANDS: readonly string[] = [
   "plunge stack move --stack <stack> --dest <stack> <urn>... --json",
   "plunge stack move --stack <stack> --dest <stack> <urn>... --json --yes",
+  "plunge up --yes --target <urn> --replace <urn> --stack <stack>",
 ];
 
 const isUrn = (v: string | undefined): v is string => typeof v === "string" && v.startsWith("urn:pulumi:");
@@ -539,6 +572,7 @@ function allowedGatedPulumi(args: string[]): boolean {
     const urns = args.slice(7);
     return args[2] === "--source" && isValue(args[3]) && args[4] === "--dest" && isValue(args[5]) && args[6] === "--yes" && urns.length > 0 && urns.every(isUrn);
   }
+  if (args[0] === "up") return allowedActionUp(args);
   return false;
 }
 
@@ -550,9 +584,11 @@ export async function runGatedPulumi(run: PulumiRunner, args: string[], cwd: str
   return run(args, env ? { cwd, env } : { cwd });
 }
 
-/** Run the moving form of {@link PLUNGE_GATED_COMMANDS}, refusing any other argv. Only `./stack-ops.ts` calls it, after the request is spent. */
+/** Run a writing form of {@link PLUNGE_GATED_COMMANDS}, the move or a stack action's update, refusing any other argv. Only `./stack-ops.ts` calls it, after the request is spent. */
 export async function runGatedPlunge(run: PulumiRunner, args: string[], cwd: string, env?: Record<string, string>): Promise<{ stdout: string }> {
-  if (!allowedPlungeMove(args, true)) {
+  if (args[0] === "up") {
+    if (!allowedActionUp(args)) throw new Error(`chant runs a plunge stack action only as ${PLUNGE_GATED_COMMANDS[2]}, not plunge ${args.join(" ")}`);
+  } else if (!allowedPlungeMove(args, true)) {
     throw new Error(`chant moves plunge resources only as ${PLUNGE_GATED_COMMANDS[1]}, not plunge ${args.join(" ")}`);
   }
   return run(args, env ? { cwd, env } : { cwd });