@intentius/chant-lexicon-pulumi 0.0.0-stage → 0.124.55

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @intentius/chant-lexicon-pulumi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pulumi lexicon for [chant](https://intentius.io/chant/). It adds your Pulumi program to a chant workspace as it is, on stock Pulumi or on [plunge](https://github.com/INTENTIUS/plunge), a Pulumi fork that keeps chant's ownership markers on each resource. It declares no resource types. It supplies the `pulumi` workspace member kind and reads a Pulumi program four ways:
+
+| Read | Source | Module |
+|---|---|---|
+| the member's graph | the `pulumi stack export` the last `pulumi-up` apply wrote to `refs/chant/snapshots`, else the one checked in as `stack-export.json` | `src/workspace-member.ts`, `src/stack-export-snapshot.ts` |
+| its change-set part | `pulumi preview --json` | `src/change-set.ts` |
+| its drift records | `pulumi refresh --preview-only --json --target <urn>`, one resource at a time | `src/drift-record.ts`, `src/drift-read.ts` |
+| its stack outputs, for another member's parameters | `pulumi stack output --json --show-secrets=false` (applied) and `pulumi preview --json` (planned) | `src/stack-outputs.ts`, `src/member-outputs.ts` |
+| engine facts, for a member on plunge | `plunge graph --json --stack <stack>` (`describeResources`), or the checked-in `engine-graph.json` (the graph read) | `src/describe-resources.ts`, `src/engine-graph.ts` |
+
+The graph read never runs `pulumi`. The change set and drift run `preview` and `refresh --preview-only`, and the outputs read adds `stack output --json --show-secrets=false`. A member on plunge runs `plunge preview`, `plunge stack output --json --show-secrets=false` and `plunge drift --resource <urn> --stream`. For its engine facts it runs one of exactly four argv: `plunge graph --json`, `plunge graph --json --stack <stack>`, `plunge graph --json --versions` and `plunge graph --json --stack <stack> --versions` ([#4529](https://github.com/INTENTIUS/chant/issues/4529)). An outputs or secrets flag on `plunge graph` is refused. That is the whole list, as ruled on [#4476](https://github.com/INTENTIUS/chant/issues/4476) (2026-10-25), which widened the [#4450](https://github.com/INTENTIUS/chant/issues/4450) ruling's `preview` and `refresh --preview-only` to keep the outputs read and the plunge commands. Nothing else runs on a read (`runAllowedPulumi` and `runAllowedPlunge` refuse any other argv, and a preview with `--show-secrets` or `--import-file`), so no read changes a stack. With `CHANT_PULUMI_APPLIED_OUTPUTS=export`, the outputs read runs nothing either.
+
+## Applies: the `pulumi-up` capability
+
+A stack can be a component step, `{ kind: "pulumi-up", dir, stack }`, that plans in a pull request and applies on merge like a `terraform-apply` root ([#4541](https://github.com/INTENTIUS/chant/issues/4541), `src/pulumi-up.ts`). The ruling on INTENTIUS/plywood#1 widened #4450 and #4476 for it alone, from an apply job holding the apply identity. Its `up` goes through `runApplyPulumi` or `runApplyPlunge`, each of which takes one fixed argv (`PULUMI_APPLY_COMMANDS` in `src/run.ts`):
+
+| Engine | Argv |
+|---|---|
+| plunge | `plunge preview --json --show-sames --stack <s> --save-plan <file>`, then `plunge up --plan <file> --yes --json --stack <s>` |
+| stock Pulumi | `pulumi preview --json --show-sames --stack <s>`, then `pulumi up --yes --json --stack <s>` |
+
+Both forms may add `--config-file <file>`, then `--target <urn>` for each target, then `--policy-pack <dir>` with an optional `--policy-pack-config <file>`, in that order. Any other flag on `up` is refused.
+
+A step pinned to its own engine release sets `engineVersion` (and `engineRoot` when its image keeps engines elsewhere than `/opt/chant`). Every run of that step, preview, `up`, stack output and export, then uses `<engineRoot>/<engine>-<engineVersion>/<engine>`, the path `pulumiInstallLine` and `plungeInstallLine` install to ([#4592](https://github.com/INTENTIUS/chant/issues/4592), `src/ci-setup.ts`). The argv is checked against the same forms, and a step without `engineVersion` runs the binary on PATH.
+
+The CI install lines take a version, download the release's Linux archive and its checksums file, and fail unless the archive matches its line there. For the default releases (Pulumi 3.272.0, plunge 0.1.0) the line must also hold the sha256 the lexicon records per architecture. Each release goes under its own versioned directory and is linked into `/usr/local/bin`, and a line skips the download when that directory already holds the binary, or for Pulumi when the `pulumi` on PATH is that version.
+
+The preview streams its engine events (`PULUMI_ENABLE_STREAMING_JSON_PREVIEW=true`, `src/engine-events.ts`), so one run gives the change set and CrossGuard's findings. A mandatory violation denies the plan. On plunge the saved plan's stamp refuses a plan whose records moved (plunge exit 40, chant's moved code 4). On stock Pulumi the apply previews again, then compares the steps in `up`'s event stream with the approved shape (`src/plan-shape.ts`), and a step outside it fails the apply. A member on the resource lock grain, the default on plunge, leaves `same` and `read` steps out of its digest. The step's `config` is written into a scratch copy of `Pulumi.<stack>.yaml` and passed with `--config-file`, never `--config`, which writes the working tree's file. A release cut records the stack's directory (`releaseInputs`), unless its backend is a file path relative to that directory. Under a release, a promote or rollback previews and applies the recorded copy, after `pulumi install` (or `plunge install`) in the copy when its runtime needs one (`src/release-copy.ts`); a Node copy with no recorded lockfile is refused by name.
+
+After `up`, the capability runs `stack export --stack <s>`, replaces every secret with `[secret]`, drops the secrets provider's state, and writes the export through chant's index store as `<env>/<stack>__pulumi-export` ([#4546](https://github.com/INTENTIUS/chant/issues/4546), `refs/chant/snapshots` by default). The graph, the preview's prior state and the drift read take that export first, so a stack chant applies needs no checked-in `stack-export.json`. A failed export leaves the apply standing and says why in the step's `exportSnapshot` output.
+
+A program that reads another stack through `StackReference` orders its stack after that one ([#4547](https://github.com/INTENTIUS/chant/issues/4547), `src/stack-references.ts`). The capability's `declaredReads` reads each step's export for `pulumi:pulumi:StackReference` resources, matches each `name` to the other `pulumi-up` step with that `Pulumi.yaml` name and stack, and reports a read of each output the export recorded that is not secret. Core writes those reads into the step's `stackReferences` input and adds a `dependsOn`, so the waves put the referenced stack first, a failed upstream holds the reader, and a reader waits while the upstream's plan cannot say a value it reads. A reference to a stack no step applies adds no edge, and the plan's artifact names it under `stackReferences.outside`.
+
+## Adoption: `PulumiAdoptOp`
+
+`PulumiAdoptOp` (`src/composites/pulumi-adopt-op.ts`, [#4562](https://github.com/INTENTIUS/chant/issues/4562)) adopts stock stacks onto plunge's per-resource records, the pulumi twin of `TerraformAdoptOp`. Its phases are Check (the shared bucket check on the backend's bucket), Export (`pulumi stack export --stack <s>` into a scratch file), then per stack Preview (`plunge stack adopt --json`), a gate bound to the preview's digest, and Adopt (`plunge stack adopt --json --yes`, through `runAdoptPlunge`). `from: { backend }` or `from: { file }` adopts an export with `--file`, the route from Pulumi Cloud. Gates and the run are recorded on the workspace ledger.
+
+## Gated stack operations
+
+`src/stack-ops.ts` ([#4578](https://github.com/INTENTIUS/chant/issues/4578)) runs three stack operations, each only after its gated request (#4551) is approved on the workspace ledger by someone other than the requester, under the op `pulumi-stack-ops`. The first call records the request and returns the `chant approve` command; the same call after the approval spends it, runs once, and records how it ended.
+
+| Function | Request | What runs after approval |
+|---|---|---|
+| `gatedStackExport` | `stack-export` of `<stack>` | `pulumi stack export --stack <s>` (or plunge's), written mode 600 to a file outside every git working tree; refused in CI |
+| `gatedStackCancel` | `stack-cancel` of `<stack>` with its lock id | `pulumi cancel --yes --stack <s>`, once the lock is still the approved one (read from a `file://` backend's lock directory); refused on plunge, which has no stack lock |
+| `gatedStackMove` | `stack-move` of `move:<source>:<dest>` with the URNs | `pulumi state move --source <s> --dest <d> --yes <urn>...`, or `plunge stack move --stack <s> --dest <d> <urn>... --json --yes` after plunge's plan; both stacks preview first, and the move runs only when the previews change nothing but the moved resources |
+
+`pulumiStackLockIds({ dir, stack })` ([#4615](https://github.com/INTENTIUS/chant/issues/4615)) reads the lock ids a stack holds now, the same read `gatedStackCancel` checks with, so a product can offer the id to approve. It answers `checked: false` on a backend other than `file://`, and no ids for a plunge stack.
+
+The writes go through `runGatedPulumi` and `runGatedPlunge` in `src/run.ts`, whose fixed forms (`PULUMI_GATED_COMMANDS`, `PLUNGE_GATED_COMMANDS`) are the only ones allowed.
+
+## Drift: `chant workspace drift`
+
+`chant workspace drift --member <pulumi member> [--resource <urn>] [--stream]` runs `chant lifecycle drift` in the member's reader project, which calls this lexicon's `readDrift`. A stock member is read with one `pulumi refresh --preview-only --json --target <urn>` per resource in its checked-in `stack-export.json`. A member on plunge is read with `plunge drift --resource <urn> --stream` per resource. `--resource` reads one URN. The only read is `refresh`.
+
+A member runs on plunge when its config says `engine: "plunge"`, or when `Pulumi.yaml` names a backend URL starting with `plunge` (`plunge+file://...`, `plunge://...`). Only `Pulumi.yaml` is read, never `PULUMI_BACKEND_URL` or login state.
+
+## Engine facts for a member on plunge
+
+plunge keeps a record per resource, and `plunge graph --json` prints the stack's graph from those records in the engine graph document chant#4520 designed. It makes no provider call and prints no output value. chant reads it two ways ([#4529](https://github.com/INTENTIUS/chant/issues/4529)):
+
+- `describeResources` runs `plunge graph --json --stack <stack>` once per member, with the stack the other reads use. Each node becomes a resource keyed like the member graph's node, with plunge's facts on `ResourceMetadata.facts`. Every resource has `ownership: "unknown"` and no marker, so no change set or teardown decides from it.
+- The graph read takes a checked-in `engine-graph.json` beside `stack-export.json`. Its facts go on the nodes (`nodes[].facts`) and its `property` edges join the graph with `grain: "property"`. The export's `dependencies` and `parent` edges carry `grain: "instance"`.
+
+plunge's markers say `source: "record"`: what its record says it wrote, not a read of the object. A stock member gets neither read, and chant runs nothing new for it. Record versions (`--versions`) cost one listing per record, so `describeResources` leaves them off.
+
+## Outputs into another member's parameters
+
+A chant member reads a Pulumi member's outputs with core's `member-outputs` verb (chant#4455):
+
+```ts
+import { memberOutputsComponent } from "@intentius/chant/components/verbs/member-outputs";
+
+export const aws = memberOutputsComponent("aws");
+export const records: Component = {
+  name: "records",
+  dependsOn: ["aws"],
+  deploy: [phase("Apply", [cfnDeploy({ template: "dist/dns.json", inputs: { awsEndpoint: stackOutput("aws", "awsEndpoint") } })])],
+};
+```
+
+The consumer lists `pulumi` among its lexicons, which brings `pulumiCapabilityPlugin` and its source, `pulumiOutputSource`, for members of kind `pulumi`.
+
+- Applied values come from `pulumi stack output --json --show-secrets=false` in the member's directory. With `CHANT_PULUMI_APPLIED_OUTPUTS=export`, chant runs nothing and reads them from the checked-in `stack-export.json`.
+- Planned values come from `pulumi preview --json --show-sames`. A real preview carries no outputs on the stack's `pulumi:pulumi:Stack` step (recorded, #4475), so a preview with nothing to apply gives the checked-in export's outputs and one with changes leaves every output unknown. An output a stack step does carry is read, and one holding Pulumi's unknown sentinel is unknown. The consumer is planned without an unknown output, gets a hole on `aws#outputs` naming it, and is held back on merge until the member applied, then planned again.
+- The plan digest is the member part's `pulumi-preview` digest, so a preview that moves after review moves the consumer's digest.
+- While the preview still has changes, `run` refuses and the consumer is blocked behind the member.
+- Secret outputs are left out of both reads. chant never carries or prints their values.
+- A member on plunge runs the same commands under `plunge`.
+- Both commands run against the member's selected stack.
+
+```bash
+npm install --save-dev @intentius/chant @intentius/chant-lexicon-pulumi
+```
+
+## License
+
+See the main project LICENSE file.

package/dist/adopt.d.ts

@@ -0,0 +1,68 @@
+import type { BucketTarget } from "@intentius/chant/bucket-check";
+/** `AdoptView.status`. */
+export type PlungeAdoptStatus = "would-adopt" | "adopted" | "already-adopted" | "refused";
+export interface PlungeAdoptRefusal {
+    code: string;
+    urn?: string;
+    reason: string;
+}
+export interface PlungeAdoptResource {
+    urn: string;
+    type: string;
+    id: string;
+    /** `marker`, `record`, `pending` or `already-adopted`. */
+    fate: string;
+    adoptedAs?: string;
+    marked?: boolean;
+    reason?: string;
+}
+/** The parts of plunge's `AdoptView` chant reads. */
+export interface PlungeAdoptView {
+    stack: string;
+    status: PlungeAdoptStatus;
+    checkpoint: {
+        source?: string;
+        digest?: string;
+    };
+    resources: PlungeAdoptResource[];
+    refusals: PlungeAdoptRefusal[];
+}
+/** The adopt document, or undefined when `text` is not one. */
+export declare function parsePlungeAdoptView(text: string | undefined): PlungeAdoptView | undefined;
+/** The gate's digest over an adopt document (see the module comment). */
+export declare function pulumiAdoptDigest(view: PlungeAdoptView): string;
+/** Counts by fate. */
+export declare function adoptFates(view: PlungeAdoptView): Record<string, number>;
+/** The stack's backend URL and where it came from, first that answers: the step's, `plywood.yml`'s, `PULUMI_BACKEND_URL`, `Pulumi.yaml`'s. */
+export declare function pulumiStackBackend(dir: string, opts?: {
+    configured?: string;
+    env?: Record<string, string | undefined>;
+}): {
+    url: string;
+    source: string;
+} | undefined;
+/** The stock backend at the same root: the URL without plunge's `plunge+` prefix. */
+export declare function stockBackendUrl(url: string): string;
+/** What the bucket check reads for a backend, or why it does not run. */
+export type AdoptBucketTarget = {
+    target: BucketTarget;
+    namespaces: string[];
+    waived: string[];
+} | {
+    skip: string;
+} | {
+    refuse: string;
+};
+/**
+ * The bucket behind a DIY backend URL, for the shared check (#4558). An
+ * `s3://` URL gives the bucket, its `region` (else `AWS_REGION`), its
+ * `endpoint` with static keys from the environment, and the path as the
+ * namespace a lifecycle rule must cover; `gs://` gives the bucket. A
+ * `file://` backend has no bucket, and the check is skipped with that
+ * reason. An `azblob://` URL does not name the subscription and resource
+ * group the check reads, so it is refused unless the step names the bucket
+ * itself. `allow_insecure` on the URL and `PLUNGE_ALLOW_INSECURE` are read as
+ * plunge reads them.
+ */
+export declare function adoptBucketTarget(url: string, env?: Record<string, string | undefined>): AdoptBucketTarget;
+//# sourceMappingURL=adopt.d.ts.map

package/dist/adopt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.d.ts","sourceRoot":"","sources":["../src/adopt.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAMlE,0BAA0B;AAC1B,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAE1F,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAMD,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CA+B1F;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAK/D;AAED,sBAAsB;AACtB,wBAAgB,UAAU,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIxE;AAED,8IAA8I;AAC9I,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAAO,GAC3E;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAgB7C;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,yEAAyE;AACzE,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvB;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,iBAAiB,CAkDvH"}

package/dist/adopt.js

@@ -0,0 +1,162 @@
+/**
+ * Adopting a stock Pulumi stack onto plunge's per-resource records (#4562):
+ * the pieces `PulumiAdoptOp` (`./composites/pulumi-adopt-op.ts`) and its
+ * activities (`./op/activities/pulumi-adopt.ts`) share.
+ *
+ * - {@link parsePlungeAdoptView}: the document `plunge stack adopt --json`
+ *   prints (plunge `pkg/backend/plunge` `AdoptView`, its site's
+ *   reference/adopt-json page): `status` is `would-adopt`, `adopted`,
+ *   `already-adopted` or `refused`, with each resource's fate and every
+ *   refusal.
+ * - {@link pulumiAdoptDigest}: what the Op's gate binds. It covers the
+ *   stack, the checkpoint's digest and source, and each resource's URN,
+ *   type, ID and fate, and leaves `status` out, so the preview an approver
+ *   saw and the `--yes` run that follows digest the same when nothing moved.
+ * - {@link pulumiStackBackend} and {@link adoptBucketTarget}: the stack's
+ *   backend URL, and the bucket the shared check (#4558) reads from it.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+import { parseYAML } from "@intentius/chant/yaml";
+import { readPlywoodEngine } from "./member-engine.js";
+import { isObject } from "./values.js";
+const STATUSES = new Set(["would-adopt", "adopted", "already-adopted", "refused"]);
+const str = (v) => (typeof v === "string" ? v : undefined);
+/** The adopt document, or undefined when `text` is not one. */
+export function parsePlungeAdoptView(text) {
+    if (!text)
+        return undefined;
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isObject(doc) || typeof doc.status !== "string" || !STATUSES.has(doc.status))
+        return undefined;
+    const checkpoint = isObject(doc.checkpoint) ? doc.checkpoint : {};
+    const resources = (Array.isArray(doc.resources) ? doc.resources : []).filter(isObject).map((r) => ({
+        urn: str(r.urn) ?? "",
+        type: str(r.type) ?? "",
+        id: str(r.id) ?? "",
+        fate: str(r.fate) ?? "",
+        ...(str(r.adoptedAs) ? { adoptedAs: str(r.adoptedAs) } : {}),
+        ...(typeof r.marked === "boolean" ? { marked: r.marked } : {}),
+        ...(str(r.reason) ? { reason: str(r.reason) } : {}),
+    }));
+    const refusals = (Array.isArray(doc.refusals) ? doc.refusals : []).filter(isObject).map((r) => ({ code: str(r.code) ?? "", ...(str(r.urn) ? { urn: str(r.urn) } : {}), reason: str(r.reason) ?? "" }));
+    return {
+        stack: str(doc.stack) ?? "",
+        status: doc.status,
+        checkpoint: { ...(str(checkpoint.source) ? { source: str(checkpoint.source) } : {}), ...(str(checkpoint.digest) ? { digest: str(checkpoint.digest) } : {}) },
+        resources,
+        refusals,
+    };
+}
+/** The gate's digest over an adopt document (see the module comment). */
+export function pulumiAdoptDigest(view) {
+    const resources = view.resources
+        .map((r) => ({ urn: r.urn, type: r.type, id: r.id, fate: r.fate === "already-adopted" ? (r.adoptedAs ?? r.fate) : r.fate }))
+        .sort((a, b) => (a.urn < b.urn ? -1 : a.urn > b.urn ? 1 : 0));
+    return computePlanDigest("plunge-adopt", { stack: view.stack, checkpoint: view.checkpoint.digest ?? null, resources });
+}
+/** Counts by fate. */
+export function adoptFates(view) {
+    const out = {};
+    for (const r of view.resources)
+        out[r.fate] = (out[r.fate] ?? 0) + 1;
+    return out;
+}
+/** The stack's backend URL and where it came from, first that answers: the step's, `plywood.yml`'s, `PULUMI_BACKEND_URL`, `Pulumi.yaml`'s. */
+export function pulumiStackBackend(dir, opts = {}) {
+    if (opts.configured)
+        return { url: opts.configured, source: "the step's backend" };
+    const plywood = readPlywoodEngine(dir);
+    if (plywood?.backend)
+        return { url: plywood.backend, source: plywood.file };
+    const env = (opts.env ?? process.env).PULUMI_BACKEND_URL;
+    if (env)
+        return { url: env, source: "PULUMI_BACKEND_URL" };
+    const file = join(dir, "Pulumi.yaml");
+    if (existsSync(file)) {
+        try {
+            const url = parseYAML(readFileSync(file, "utf-8")).backend?.url;
+            if (typeof url === "string")
+                return { url, source: "Pulumi.yaml" };
+        }
+        catch {
+            // No backend named.
+        }
+    }
+    return undefined;
+}
+/** The stock backend at the same root: the URL without plunge's `plunge+` prefix. */
+export function stockBackendUrl(url) {
+    return url.replace(/^plunge\+/, "");
+}
+/**
+ * The bucket behind a DIY backend URL, for the shared check (#4558). An
+ * `s3://` URL gives the bucket, its `region` (else `AWS_REGION`), its
+ * `endpoint` with static keys from the environment, and the path as the
+ * namespace a lifecycle rule must cover; `gs://` gives the bucket. A
+ * `file://` backend has no bucket, and the check is skipped with that
+ * reason. An `azblob://` URL does not name the subscription and resource
+ * group the check reads, so it is refused unless the step names the bucket
+ * itself. `allow_insecure` on the URL and `PLUNGE_ALLOW_INSECURE` are read as
+ * plunge reads them.
+ */
+export function adoptBucketTarget(url, env = process.env) {
+    const stock = stockBackendUrl(url);
+    let u;
+    try {
+        u = new URL(stock);
+    }
+    catch {
+        return { refuse: `the backend ${url} is not a URL the bucket check can read` };
+    }
+    const waived = [
+        ...(u.searchParams.get("allow_insecure") ?? "").split(","),
+        ...(env.PLUNGE_ALLOW_INSECURE ?? "").split(","),
+    ]
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const prefix = u.pathname.replace(/^\/+/, "");
+    const namespaces = prefix ? [prefix.endsWith("/") ? prefix : `${prefix}/`] : [];
+    switch (u.protocol) {
+        case "file:":
+            return { skip: `the backend ${url} is a local file path, which has no bucket to check` };
+        case "s3:": {
+            const region = u.searchParams.get("region") ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION;
+            if (!region)
+                return { refuse: `the backend ${url} names no region and AWS_REGION is not set, so the bucket check cannot read ${u.hostname}` };
+            const endpoint = u.searchParams.get("endpoint") ?? undefined;
+            if (endpoint && !(env.AWS_ACCESS_KEY_ID && env.AWS_SECRET_ACCESS_KEY)) {
+                return { refuse: `the backend ${url} names the endpoint ${endpoint}, and the bucket check reads an endpoint only with static keys (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)` };
+            }
+            const target = {
+                store: "s3",
+                bucket: u.hostname,
+                region,
+                ...(endpoint
+                    ? {
+                        endpoint: /^[a-z]+:\/\//.test(endpoint) ? endpoint : `https://${endpoint}`,
+                        credentials: {
+                            accessKeyId: env.AWS_ACCESS_KEY_ID,
+                            secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+                            ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}),
+                        },
+                    }
+                    : {}),
+            };
+            return { target, namespaces, waived };
+        }
+        case "gs:":
+            return { target: { store: "gcs", bucket: u.hostname }, namespaces, waived };
+        case "azblob:":
+            return { refuse: `the backend ${url} does not name the storage account's subscription and resource group; set the step's bucket to the azblob target` };
+        default:
+            return { refuse: `the backend ${url} is not a bucket plunge stores records in (s3, gs, azblob or file)` };
+    }
+}

package/dist/capability-plugin.d.ts

@@ -0,0 +1,6 @@
+import { type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+export declare const PULUMI_VERB_FAMILIES: {
+    readonly apply: readonly ["pulumi-up"];
+};
+export declare const pulumiCapabilityPlugin: CapabilityPlugin;
+//# sourceMappingURL=capability-plugin.d.ts.map

package/dist/capability-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-plugin.d.ts","sourceRoot":"","sources":["../src/capability-plugin.ts"],"names":[],"mappings":"AAUA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAKzG,eAAO,MAAM,oBAAoB;aAC/B,KAAK,YAAG,WAAW;CACX,CAAC;AAEX,eAAO,MAAM,sBAAsB,EAAE,gBAcpC,CAAC"}

package/dist/capability-plugin.js

@@ -0,0 +1,21 @@
+import { ownPackageVersion } from "@intentius/chant/components/capability-plugin";
+import { pulumiStackOutputSource } from "./member-outputs.js";
+import { pulumiUpCapability } from "./pulumi-up.js";
+export const PULUMI_VERB_FAMILIES = {
+    apply: ["pulumi-up"],
+};
+export const pulumiCapabilityPlugin = {
+    name: "pulumi",
+    get version() {
+        return ownPackageVersion(import.meta.url);
+    },
+    capabilities() {
+        return [pulumiUpCapability];
+    },
+    families() {
+        return PULUMI_VERB_FAMILIES;
+    },
+    engineOutputSources() {
+        return [pulumiStackOutputSource];
+    },
+};

package/dist/change-set.d.ts

@@ -0,0 +1,182 @@
+/**
+ * The change-set adapter for a Pulumi member (#4453): `pulumi preview --json`
+ * into an `@intentius/chant/change-set` part, planner `pulumi`.
+ *
+ * ## Steps to entries
+ *
+ * The preview prints one step per resource the program registered, `same`
+ * included, and a replace as two or three steps on one URN
+ * (`create-replacement`, `replace`, `delete-replaced`). The adapter keeps one
+ * entry per URN, at the URN, so `node` comes from the one URN rule
+ * (`@intentius/chant/pulumi-urn`, #4456):
+ *
+ * | step op | action | disruption |
+ * |---|---|---|
+ * | `create` | create | |
+ * | `update` | update | in-place |
+ * | `delete` | delete | destroy |
+ * | `replace`, `create-replacement`, `delete-replaced` | replace | replace, or destroy when the delete comes first (`deleteBeforeReplace`) |
+ * | `same` | no-op | |
+ * | `read`, `read-replacement`, `refresh` | read | |
+ * | `import` | no-op, importing | |
+ * | `import-replacement` | replace, importing | replace |
+ * | `discard`, `remove-pending-replace` | forget | |
+ *
+ * An op the table does not hold is a hole on the member, never a guess.
+ *
+ * Attributes are top-level inputs, as the change set wants them. A create
+ * writes every input. An update or replace writes the keys `detailedDiff`
+ * and `diffReasons` name, and every input whose new value holds an unknown.
+ * `replaceReasons` and a `detailedDiff` kind ending in `-replace` mark
+ * `forcesReplacement`. An input that holds Pulumi's unknown sentinel is
+ * `unknown: true` with no `after`: a resource that reads an output of one
+ * being created shows its dependent input as unknown. A value that holds a
+ * secret is `sensitive: true` with neither side.
+ *
+ * ## What preview cannot list: `mayAppear`
+ *
+ * A program may register resources inside an `apply()`. At preview an
+ * `apply()` whose input is unknown does not run, so what it would register
+ * is never in the steps. Dropping it would make the set look smaller than
+ * the apply, so the adapter marks it `mayAppear` instead, on two signals:
+ *
+ * 1. A component (a step whose state is `custom: false`, not the root stack)
+ *    whose subtree in the preview holds an unknown, in any input or output,
+ *    or a create or replace, whose outputs are unknown until apply. Its code
+ *    may be waiting on that value to register children. It gets one entry
+ *    at `pulumiMayAppearAddress(<component urn>)`, action `create`, type
+ *    `unknown`, no attributes, on the component's node.
+ * 2. With the last deployment's `pulumi stack export` (`prior`): a resource
+ *    the export holds and the preview has no step for gets an `update`
+ *    entry with disruption `unknown`, since a full preview lists every
+ *    registered resource and only an `apply()` that did not run leaves one
+ *    out. A `delete` step for a resource under a component signal 1 marks
+ *    keeps its `delete` and gets `mayAppear`, since the `apply()` may
+ *    register it again. A preview narrowed with `--target` (`targeted`)
+ *    lists only its targets, and a failed one stops part way, so signal 2's
+ *    first half is off for both.
+ *
+ * A resource registered inside an `apply()` directly under the stack, with
+ * no export that holds it, has no component to stand under and is not
+ * detected. When the export does hold it and its input is unknown, the
+ * preview prints a `delete` for it, which reads as a plain delete. Those are
+ * the two cases left out.
+ *
+ * ## The digest
+ *
+ * {@link pulumiPreviewDigest}: `computePlanDigest("pulumi-preview", …)` over
+ * each step's op, URN, provider, id, inputs before and after, `diffReasons`,
+ * `replaceReasons` and `detailedDiff`, sorted by URN and op. It leaves out
+ * `config`, `duration`, `diagnostics` and `changeSummary`, and the states'
+ * outputs, which at preview are the last deployment's or unknown. For a
+ * member on the resource lock grain the `pulumi-up` capability passes
+ * `changedOnly` (#4541, ruling B), which leaves `same` and `read` steps out.
+ *
+ * The fixtures under `testdata/pulumi-preview` are recorded from pulumi
+ * 3.272.0 against the plunge corpus's aws-ts program on floci (#4475). What
+ * the recording showed: `preview --json` lists no unchanged resource unless
+ * `--show-sames` is passed, which chant's argv does, since signal 2 reads a
+ * missing resource as one an `apply()` may register; a replace is one
+ * `replace` step at preview, not three; the stack's step carries no planned
+ * outputs; a secret is the blinded string `"[secret]"`; and a resource
+ * registered inside an `apply()` directly under the stack whose input is
+ * unknown (the corpus's `vpc-id` parameter, named after a VPC being
+ * replaced) is printed as a `delete`, which this adapter keeps as a plain
+ * delete since nothing tells it apart from a removed resource.
+ *
+ * ## The import graph
+ *
+ * Like the terraform lexicon's `change-set`, this imports chant's
+ * `change-set` types, `lifecycle/plan-digest`, `pulumi-urn` and `./values`,
+ * so it bundles without TypeScript, node's process modules or zod (#3421).
+ */
+import type { ChangeSetAction, ChangeSetDisruption, ChangeSetPart } from "@intentius/chant/change-set";
+import { type Json } from "./values.js";
+/** One resource state on a preview step, `apitype.ResourceV3`, as far as the adapter reads it. */
+export interface PulumiStepState {
+    urn?: string;
+    custom?: boolean;
+    delete?: boolean;
+    id?: string;
+    type?: string;
+    parent?: string;
+    inputs?: Json;
+    outputs?: Json;
+}
+/** One step of `pulumi preview --json` or `pulumi refresh --preview-only --json`. */
+export interface PulumiStep {
+    op?: string;
+    urn?: string;
+    provider?: string;
+    oldState?: PulumiStepState;
+    newState?: PulumiStepState;
+    diffReasons?: string[];
+    replaceReasons?: string[];
+    detailedDiff?: Record<string, {
+        kind?: string;
+        inputDiff?: boolean;
+    }> | null;
+}
+/** The steps of a preview or refresh document, or undefined when it has none. */
+export declare function pulumiSteps(doc: unknown): PulumiStep[] | undefined;
+/** One resource of a `pulumi stack export`, as far as the adapter reads it. */
+export interface PulumiExportedResource {
+    urn: string;
+    type: string;
+    custom?: boolean;
+    id?: string;
+    parent?: string;
+}
+/** The resources of a `pulumi stack export` document (`deployment.resources`). Not one: an empty list. */
+export declare function pulumiExportResources(doc: unknown): PulumiExportedResource[];
+/** Step ops that change nothing: what {@link PulumiPreviewDigestOptions.changedOnly} leaves out of the digest. */
+export declare const PULUMI_UNCHANGED_OPS: ReadonlySet<string>;
+export interface PulumiPreviewDigestOptions {
+    /**
+     * Leave `same` and `read` steps out (#4541, ruling B): set for a member on
+     * the resource lock grain, so a pull request that lands on other resources
+     * of the stack does not move this one's digest. plunge's plan stamp still
+     * refuses a moved record among the steps that change.
+     */
+    changedOnly?: boolean;
+}
+/**
+ * The member's plan digest: `computePlanDigest("pulumi-preview", …)` over
+ * what each step proposes, sorted by URN and op, so two renderings of one
+ * preview agree. See the module comment for what it leaves out. With
+ * `changedOnly`, `same` and `read` steps are left out too, under the label
+ * `pulumi-preview-changed`, so the two digests never collide.
+ */
+export declare function pulumiPreviewDigest(preview: unknown, opts?: PulumiPreviewDigestOptions): string;
+/** The action and disruption one URN's steps mean, or undefined for an op the change set has no action for. */
+export declare function pulumiStepsAction(steps: PulumiStep[]): {
+    action: ChangeSetAction;
+    disruption?: ChangeSetDisruption;
+    importing?: true;
+} | undefined;
+export interface PulumiPreviewPartInput {
+    /** The workspace member's name, which names its graph nodes (`<member>/<key>`). */
+    member: string;
+    /** `pulumi preview --json`, parsed. */
+    preview: unknown;
+    /** The stack the preview ran against, recorded as `scope`. */
+    stack?: string;
+    /**
+     * The last deployment, as `pulumi stack export` prints it: the member's
+     * checked-in `stack-export.json`. With it, a resource the preview leaves
+     * out is a `mayAppear` entry rather than silence.
+     */
+    prior?: unknown;
+    /** The preview was narrowed with `--target`, so it lists only its targets. */
+    targeted?: boolean;
+    /** The preview failed: the member is failed with this error, and keeps whatever steps it printed. */
+    error?: string;
+    /** Digest options (#4541, ruling B): `changedOnly` for a member on the resource lock grain. */
+    digest?: PulumiPreviewDigestOptions;
+}
+/**
+ * A Pulumi member's part, from its `pulumi preview --json`. Throws when the
+ * document has no `steps` and no `error` says why.
+ */
+export declare function pulumiPreviewPart(input: PulumiPreviewPartInput): ChangeSetPart;
+//# sourceMappingURL=change-set.d.ts.map

package/dist/change-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../src/change-set.ts"],"names":[],"mappings":"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"}