@intentius/chant-lexicon-pulumi 0.124.54 → 0.124.56

package/dist/composites/pulumi-adopt-op.js

@@ -0,0 +1,132 @@
+/**
+ * PulumiAdoptOp composite (#4562): adopt stock Pulumi stacks onto plunge's
+ * per-resource records, behind a gate, the pulumi twin of the terraform
+ * lexicon's `TerraformAdoptOp`. It is the step after `plywood init --engine
+ * plunge` (INTENTIUS/plywood#3); plywood supplies the words.
+ *
+ * plunge refuses a stock checkpoint with no records (`AdoptionRequiredError`)
+ * rather than recreate everything, so a stack moves to plunge by `plunge
+ * stack adopt`. Adoption writes one record per resource with the
+ * checkpoint's IDs and calls no cloud API; the next `plunge up` adds the
+ * `plunge-stack` and `plunge-urn` tags in place.
+ *
+ * Phases:
+ *
+ *   - **Check**: the shared bucket check (#4558) on each stack's backend
+ *     bucket. A setting that fails, not waived, refuses the run before
+ *     anything is exported, naming the fix. A `file://` backend is skipped.
+ *   - **Export**: each stack's stock checkpoint, `pulumi stack export
+ *     --stack <s>`, kept in a scratch file. It is the back-out copy (`pulumi
+ *     stack import --file` on a stock backend), and on the route from Pulumi
+ *     Cloud (`from: { backend }`) or from an export taken by hand (`from: {
+ *     file }`) it is what plunge adopts with `--file`.
+ *   - Then one wave per stack, in the order given: **Preview** runs `plunge
+ *     stack adopt --json` (writes nothing), the **gate** binds that preview's
+ *     `planDigest`, and **Adopt** runs `plunge stack adopt --json --yes`. A
+ *     stack whose checkpoint changed after approval previews a new digest,
+ *     and the old approval does not open the gate for it.
+ *
+ * Every gate is a fact on the workspace ledger: `chant run` records the
+ * pending gate citing the preview's digest and exits gated, `chant approve
+ * <op> <gate>` writes the resolution, and the next run walks to the Adopt
+ * step. The run itself is a run record on the same ledger (#4551), as for
+ * `TerraformAdoptOp`. There is no `gate: "never"`: adoption moves the stack's
+ * state onto another backend's records, which nobody should skip reviewing.
+ *
+ * ## Compensation
+ *
+ * Refused without a command, as `TerraformAdoptOp` refuses it. Backing out
+ * is `plunge stack export --file s.json` then `pulumi stack import --file
+ * s.json` on a stock backend, a decision about the stack and its backend
+ * rather than something chant should run on its own.
+ *
+ * @example
+ * ```typescript
+ * import { PulumiAdoptOp } from "@intentius/chant-lexicon-pulumi";
+ *
+ * export const { op } = PulumiAdoptOp({
+ *   name: "adopt-infra",
+ *   stacks: [{ member: "infra", dir: "./infra", stack: "dev" }],
+ * });
+ * ```
+ */
+import { Op, phase, gate, activity } from "@intentius/chant/op";
+import { pulumiAdopt, pulumiAdoptCheck, pulumiAdoptExport, pulumiAdoptPreview } from "../op/builders.js";
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+export function PulumiAdoptOp(config) {
+    const compensateCommand = typeof config.compensate === "object" ? config.compensate.command : undefined;
+    const compensateImage = typeof config.compensate === "object" ? config.compensate.image : undefined;
+    if (config.compensate !== undefined && config.compensate !== false && compensateCommand === undefined) {
+        throw new Error(`PulumiAdoptOp "${config.name}": compensate is enabled, but there is no automatic undo for an adoption. ` +
+            `Backing out is plunge stack export --file, then pulumi stack import --file on a stock backend, a decision ` +
+            `about the stack and its backend. Supply compensate: { command: "..." } with an undo of your own, or set ` +
+            `compensate: false.`);
+    }
+    if (!Array.isArray(config.stacks) || config.stacks.length === 0) {
+        throw new Error(`PulumiAdoptOp "${config.name}": stacks is empty; name at least one { member, dir, stack } to adopt`);
+    }
+    const seen = new Set();
+    for (const s of config.stacks) {
+        const key = `${s.member}/${s.stack}`;
+        if (seen.has(key))
+            throw new Error(`PulumiAdoptOp "${config.name}": ${key} is listed twice`);
+        seen.add(key);
+    }
+    const where = config.cwd ? { cwd: config.cwd } : {};
+    const single = config.stacks.length === 1;
+    const gateBase = config.gateName ?? `approve-${config.name}`;
+    const checks = config.stacks.map((s, i) => pulumiAdoptCheck(s.member, {
+        dir: s.dir,
+        stack: s.stack,
+        ...where,
+        ...(s.backend ? { backend: s.backend } : {}),
+        ...(s.bucket ? { bucket: s.bucket } : {}),
+        ...(s.namespaces ? { namespaces: s.namespaces } : {}),
+        ...(s.allowInsecure ? { allowInsecure: s.allowInsecure } : {}),
+        id: `check-${i}`,
+    }));
+    const exports = config.stacks.map((s, i) => pulumiAdoptExport(s.member, {
+        dir: s.dir,
+        stack: s.stack,
+        ...where,
+        ...(s.backend ? { backend: s.backend } : {}),
+        ...(s.from ? { from: s.from } : {}),
+        id: `export-${i}`,
+        profile: "longInfra",
+    }));
+    const waves = config.stacks.flatMap((s, i) => {
+        const file = s.from ? { file: exports[i].out.file } : {};
+        const preview = pulumiAdoptPreview(s.member, { dir: s.dir, stack: s.stack, ...where, ...file, id: `preview-${i}` });
+        preview.outcomeAttribute = { name: single ? "Adoptable" : `Adoptable-${slug(s.member)}-${slug(s.stack)}`, from: "resources" };
+        const adopt = pulumiAdopt(s.member, { dir: s.dir, stack: s.stack, ...where, ...file, planDigest: preview.out.planDigest, id: `adopt-${i}` });
+        adopt.outcomeAttribute = { name: single ? "Adopted" : `Adopted-${slug(s.member)}-${slug(s.stack)}`, from: "resources" };
+        const label = single ? "" : ` ${s.member}/${s.stack}`;
+        return [
+            phase(`Preview${label}`, [preview]),
+            phase(`Gate${label}`, [
+                gate(single ? gateBase : `${gateBase}-${slug(s.member)}-${slug(s.stack)}`, {
+                    plan: preview.out.planDigest,
+                    ...(config.gateTimeout ? { timeout: config.gateTimeout } : {}),
+                    description: config.gateDescription ??
+                        `Approve adopting the Pulumi stack ${s.member}/${s.stack} onto plunge's per-resource records. The ` +
+                            `preview's adopt document is what is approved: each resource gets a record with the checkpoint's ID, ` +
+                            `no cloud object changes now, and the next plunge up writes the plunge-stack and plunge-urn tags.`,
+                }),
+            ]),
+            phase(`Adopt${label}`, [adopt]),
+        ];
+    });
+    const op = Op({
+        name: config.name,
+        overview: `Adopt ${single ? `the Pulumi stack ${config.stacks[0].member}/${config.stacks[0].stack}` : `${config.stacks.length} Pulumi stacks`} onto plunge's per-resource records`,
+        labels: {
+            Adopt: "true",
+            Surface: "pulumi-adopt",
+        },
+        phases: [phase("Check", checks), phase("Export", exports), ...waves],
+        ...(compensateCommand
+            ? { onFailure: [phase("Rollback", [activity("shellCmd", { cmd: compensateCommand, ...(compensateImage ? { image: compensateImage } : {}) })])] }
+            : {}),
+    });
+    return { op };
+}

package/dist/engine-events.d.ts

@@ -0,0 +1,222 @@
+/**
+ * The engine event stream of `pulumi up --json`, and of `pulumi preview
+ * --json` run with `PULUMI_ENABLE_STREAMING_JSON_PREVIEW=true` (#4541,
+ * ruling C): one `apitype.EngineEvent` per line, the same shape for stock
+ * Pulumi and plunge (`sdk/go/common/apitype/events.go`).
+ *
+ * The printed preview document drops policy events
+ * (`pkg/backend/display/json.go` `ShowPreviewDigest`), so the pulumi-up
+ * capability previews with the stream instead, and reads both the change set
+ * and CrossGuard's verdict from one engine run:
+ *
+ * - {@link pulumiStreamPreview}: the stream turned back into the document
+ *   `pulumiPreviewPart` and `pulumiPreviewDigest` read (`./change-set.ts`).
+ *   Steps come from `resourcePreEvent`, filtered as the printed document
+ *   filters them (`shouldShow`: a non-logical replacement step is left out,
+ *   and `same` steps are kept, since chant always passes `--show-sames`).
+ *   Each state is normalized to the printed form: a blinded secret envelope
+ *   becomes `"[secret]"`, an empty `inputs` or `outputs` map and an empty
+ *   `id` are left out, and `detailedDiff`'s `diffKind` is read as `kind`.
+ *   The digest of the result equals the digest of the printed document for
+ *   the same preview (checked against `testdata/pulumi-stream`).
+ * - {@link pulumiPolicyEvents} and {@link pulumiPolicyFindings}: the
+ *   `policyEvent` lines, as `@intentius/chant/gate-policy` findings. A
+ *   `mandatory` violation denies; `advisory` ones are warnings; `disabled`
+ *   ones are dropped.
+ * - {@link pulumiStreamSummary}: the `summaryEvent`, and plunge's
+ *   per-resource timings (INTENTIUS/plunge#55) when the steps carry them.
+ * - {@link pulumiStreamTimings}: those timings alone, by URN. plunge puts
+ *   `metadata.plungeTimings` on each `resOutputsEvent` and
+ *   `resOpFailedEvent` of `up --json`: one entry per provider call (`kind:
+ *   "provider"`, `call` one of check, diff, create, read, update, delete)
+ *   and per write or delete of the resource's record (`kind: "record"`),
+ *   each with `startedAt` and `durationMs`, and `failed` when it failed.
+ *   Every call is on exactly one event, and a replacement's create and
+ *   delete steps split a URN's calls over two events, so the reader joins
+ *   them. Stock Pulumi prints no such field, and the reader then finds none.
+ *
+ * During `up`, the engine may first preview: those `resourcePreEvent`s carry
+ * `planning: true`. {@link pulumiAppliedSteps} keeps only the steps the update
+ * ran, which is what the stock apply compares with the approved shape
+ * (ruling A).
+ *
+ * Like `./change-set.ts`, this module imports only `./values` and types, so it
+ * bundles without node's process modules.
+ */
+import type { GatePolicyFindings } from "@intentius/chant/gate-policy";
+import type { PulumiStep } from "./change-set.js";
+import { type Json } from "./values.js";
+/** The env var that makes `preview --json` stream engine events instead of printing one document (`sdk/go/common/env/env.go`). */
+export declare const PULUMI_STREAMING_PREVIEW_ENV = "PULUMI_ENABLE_STREAMING_JSON_PREVIEW";
+/** One line of the stream, as far as this module reads it. */
+export interface PulumiEngineEvent {
+    sequence?: number;
+    timestamp?: number;
+    resourcePreEvent?: {
+        metadata?: PulumiEventStep;
+        planning?: boolean;
+    };
+    resOutputsEvent?: {
+        metadata?: PulumiEventStep;
+        planning?: boolean;
+    };
+    resOpFailedEvent?: {
+        metadata?: PulumiEventStep;
+        status?: number;
+        steps?: number;
+    };
+    policyEvent?: PulumiPolicyEvent;
+    summaryEvent?: PulumiSummaryEvent;
+    diagnosticEvent?: {
+        urn?: string;
+        message?: string;
+        severity?: string;
+        ephemeral?: boolean;
+    };
+    preludeEvent?: {
+        config?: Record<string, string>;
+    };
+    cancelEvent?: Record<string, never>;
+    errorEvent?: {
+        error?: string;
+    };
+}
+/** `apitype.StepEventMetadata`. */
+export interface PulumiEventStep {
+    op?: string;
+    urn?: string;
+    type?: string;
+    old?: PulumiEventState | null;
+    new?: PulumiEventState | null;
+    keys?: string[];
+    diffs?: string[];
+    detailedDiff?: Record<string, {
+        diffKind?: string;
+        inputDiff?: boolean;
+    }> | null;
+    logical?: boolean;
+    provider?: string;
+    /** plunge's per-resource timings (INTENTIUS/plunge#55), when the fork prints them. Read with {@link plungeTimingOf}. */
+    plungeTimings?: unknown[];
+}
+/** What a plunge timing times: a provider call, or a write of the resource's own record. */
+export type PlungeTimingKind = "provider" | "record";
+/** The calls plunge times (INTENTIUS/plunge#55), by kind. */
+export declare const PLUNGE_TIMING_CALLS: Readonly<Record<PlungeTimingKind, readonly string[]>>;
+/** One entry of `metadata.plungeTimings` (INTENTIUS/plunge#55). */
+export interface PlungeTiming {
+    kind: PlungeTimingKind;
+    /** For `provider`: check, diff, create, read, update or delete. For `record`: write or delete. */
+    call: string;
+    /** RFC 3339, to the nanosecond. */
+    startedAt: string;
+    /** Fractional milliseconds. */
+    durationMs: number;
+    /** Set when the call failed. A conditional record write that lost to another run counts as failed. */
+    failed?: boolean;
+}
+/**
+ * `value` as a {@link PlungeTiming}, or undefined when it is not one. A
+ * `call` outside the kind's list is kept, so a newer plunge's calls still
+ * read; an entry with no kind, no start or a negative duration is dropped.
+ */
+export declare function plungeTimingOf(value: unknown): PlungeTiming | undefined;
+/** `apitype.StepEventStateMetadata`. */
+export interface PulumiEventState {
+    type?: string;
+    urn?: string;
+    custom?: boolean;
+    delete?: boolean;
+    id?: string;
+    parent?: string;
+    provider?: string;
+    inputs?: Json | null;
+    outputs?: Json | null;
+}
+/** `apitype.PolicyEvent`. */
+export interface PulumiPolicyEvent {
+    resourceUrn?: string;
+    message?: string;
+    policyName?: string;
+    policyPackName?: string;
+    policyPackVersion?: string;
+    /** `advisory`, `mandatory`, `remediate` or `disabled`. */
+    enforcementLevel?: string;
+    severity?: string;
+}
+/** `apitype.SummaryEvent`. */
+export interface PulumiSummaryEvent {
+    maybeCorrupt?: boolean;
+    durationSeconds?: number;
+    resourceChanges?: Record<string, number>;
+    isPreview?: boolean;
+    result?: string;
+    PolicyPacks?: Record<string, string>;
+}
+/** Every line of `stream` that parses as a JSON object. Other lines (a banner, a progress line) are skipped. */
+export declare function pulumiEngineEvents(stream: string): PulumiEngineEvent[];
+/** One event step as a printed preview step (`getPreviewMetadataStep`). */
+export declare function pulumiStepOfEvent(m: PulumiEventStep): PulumiStep;
+/**
+ * A streamed preview as the document `pulumi preview --json` prints without
+ * the env var: `steps`, `diagnostics` and, from the summary, `changeSummary`.
+ * What `pulumiPreviewPart` and `pulumiPreviewDigest` read.
+ */
+export declare function pulumiStreamPreview(stream: string | readonly PulumiEngineEvent[]): {
+    steps: PulumiStep[];
+    diagnostics: Array<{
+        urn?: string;
+        message: string;
+        severity: string;
+    }>;
+    changeSummary?: Record<string, number>;
+};
+/** The steps an `up` ran: its `resourcePreEvent`s outside any preview phase (`planning` unset). */
+export declare function pulumiAppliedSteps(stream: string | readonly PulumiEngineEvent[]): PulumiStep[];
+/** The URNs whose operation failed during an `up` (`resOpFailedEvent`), sorted. */
+export declare function pulumiFailedUrns(stream: string | readonly PulumiEngineEvent[]): string[];
+/** The URNs an `up` finished an operation on (`resOutputsEvent` outside a preview phase, `same` left out), sorted. */
+export declare function pulumiLandedUrns(stream: string | readonly PulumiEngineEvent[]): string[];
+/** A CrossGuard violation the stream reported. */
+export interface PulumiPolicyViolation {
+    pack: string;
+    packVersion?: string;
+    policy: string;
+    enforcementLevel: string;
+    message: string;
+    urn?: string;
+    severity?: string;
+}
+/** The `policyEvent` lines of a stream, `disabled` ones left out. */
+export declare function pulumiPolicyEvents(stream: string | readonly PulumiEngineEvent[]): PulumiPolicyViolation[];
+/** The rule id a CrossGuard policy is named by in chant's gate and overrides: `crossguard.<pack>.<policy>`. */
+export declare function crossGuardRule(v: Pick<PulumiPolicyViolation, "pack" | "policy">): string;
+/**
+ * CrossGuard's violations as gate findings (`@intentius/chant/gate-policy`):
+ * a `mandatory` one denies the plan, an `advisory` (or `remediate`) one is
+ * a warning. CrossGuard has no hold.
+ */
+export declare function pulumiPolicyFindings(violations: readonly PulumiPolicyViolation[]): GatePolicyFindings;
+/** What an `up` reported at its end, for the step's output. */
+export interface PulumiApplySummary {
+    /** Counts by op, `same` included, as the engine reports them. */
+    resourceChanges: Record<string, number>;
+    durationSeconds?: number;
+    /** `succeeded`, `failed` or `cancelled`, when the engine says. */
+    result?: string;
+    maybeCorrupt?: boolean;
+    /** plunge's per-resource timings (INTENTIUS/plunge#55), by URN, in stream order, when the steps carry them. */
+    timings?: Record<string, PlungeTiming[]>;
+}
+/**
+ * plunge's per-resource timings in `up --json` (INTENTIUS/plunge#55), by URN:
+ * every valid entry of `metadata.plungeTimings` on each `resOutputsEvent`
+ * and `resOpFailedEvent`, joined across a URN's events in stream order. A
+ * stock Pulumi stream gives `{}`.
+ */
+export declare function pulumiStreamTimings(stream: string | readonly PulumiEngineEvent[]): Record<string, PlungeTiming[]>;
+/** The stream's `summaryEvent`, with plunge's timings when present. Undefined when the stream has no summary. */
+export declare function pulumiStreamSummary(stream: string | readonly PulumiEngineEvent[]): PulumiApplySummary | undefined;
+/** The first error a stream reported (an error diagnostic or an `errorEvent`), if any. */
+export declare function pulumiStreamError(stream: string | readonly PulumiEngineEvent[]): string | undefined;
+//# sourceMappingURL=engine-events.d.ts.map

package/dist/engine-events.d.ts.map

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

package/dist/engine-events.js

@@ -0,0 +1,280 @@
+/**
+ * The engine event stream of `pulumi up --json`, and of `pulumi preview
+ * --json` run with `PULUMI_ENABLE_STREAMING_JSON_PREVIEW=true` (#4541,
+ * ruling C): one `apitype.EngineEvent` per line, the same shape for stock
+ * Pulumi and plunge (`sdk/go/common/apitype/events.go`).
+ *
+ * The printed preview document drops policy events
+ * (`pkg/backend/display/json.go` `ShowPreviewDigest`), so the pulumi-up
+ * capability previews with the stream instead, and reads both the change set
+ * and CrossGuard's verdict from one engine run:
+ *
+ * - {@link pulumiStreamPreview}: the stream turned back into the document
+ *   `pulumiPreviewPart` and `pulumiPreviewDigest` read (`./change-set.ts`).
+ *   Steps come from `resourcePreEvent`, filtered as the printed document
+ *   filters them (`shouldShow`: a non-logical replacement step is left out,
+ *   and `same` steps are kept, since chant always passes `--show-sames`).
+ *   Each state is normalized to the printed form: a blinded secret envelope
+ *   becomes `"[secret]"`, an empty `inputs` or `outputs` map and an empty
+ *   `id` are left out, and `detailedDiff`'s `diffKind` is read as `kind`.
+ *   The digest of the result equals the digest of the printed document for
+ *   the same preview (checked against `testdata/pulumi-stream`).
+ * - {@link pulumiPolicyEvents} and {@link pulumiPolicyFindings}: the
+ *   `policyEvent` lines, as `@intentius/chant/gate-policy` findings. A
+ *   `mandatory` violation denies; `advisory` ones are warnings; `disabled`
+ *   ones are dropped.
+ * - {@link pulumiStreamSummary}: the `summaryEvent`, and plunge's
+ *   per-resource timings (INTENTIUS/plunge#55) when the steps carry them.
+ * - {@link pulumiStreamTimings}: those timings alone, by URN. plunge puts
+ *   `metadata.plungeTimings` on each `resOutputsEvent` and
+ *   `resOpFailedEvent` of `up --json`: one entry per provider call (`kind:
+ *   "provider"`, `call` one of check, diff, create, read, update, delete)
+ *   and per write or delete of the resource's record (`kind: "record"`),
+ *   each with `startedAt` and `durationMs`, and `failed` when it failed.
+ *   Every call is on exactly one event, and a replacement's create and
+ *   delete steps split a URN's calls over two events, so the reader joins
+ *   them. Stock Pulumi prints no such field, and the reader then finds none.
+ *
+ * During `up`, the engine may first preview: those `resourcePreEvent`s carry
+ * `planning: true`. {@link pulumiAppliedSteps} keeps only the steps the update
+ * ran, which is what the stock apply compares with the approved shape
+ * (ruling A).
+ *
+ * Like `./change-set.ts`, this module imports only `./values` and types, so it
+ * bundles without node's process modules.
+ */
+import { isObject, PULUMI_BLINDED_SECRET, PULUMI_SECRET_SIG, PULUMI_SIG_KEY } from "./values.js";
+/** The env var that makes `preview --json` stream engine events instead of printing one document (`sdk/go/common/env/env.go`). */
+export const PULUMI_STREAMING_PREVIEW_ENV = "PULUMI_ENABLE_STREAMING_JSON_PREVIEW";
+/** The calls plunge times (INTENTIUS/plunge#55), by kind. */
+export const PLUNGE_TIMING_CALLS = {
+    provider: ["check", "diff", "create", "read", "update", "delete"],
+    record: ["write", "delete"],
+};
+/**
+ * `value` as a {@link PlungeTiming}, or undefined when it is not one. A
+ * `call` outside the kind's list is kept, so a newer plunge's calls still
+ * read; an entry with no kind, no start or a negative duration is dropped.
+ */
+export function plungeTimingOf(value) {
+    if (!isObject(value))
+        return undefined;
+    const v = value;
+    if (v.kind !== "provider" && v.kind !== "record")
+        return undefined;
+    if (typeof v.call !== "string" || v.call === "")
+        return undefined;
+    if (typeof v.startedAt !== "string" || !Number.isFinite(Date.parse(v.startedAt)))
+        return undefined;
+    if (typeof v.durationMs !== "number" || !Number.isFinite(v.durationMs) || v.durationMs < 0)
+        return undefined;
+    return { kind: v.kind, call: v.call, startedAt: v.startedAt, durationMs: v.durationMs, ...(v.failed === true ? { failed: true } : {}) };
+}
+/** Every line of `stream` that parses as a JSON object. Other lines (a banner, a progress line) are skipped. */
+export function pulumiEngineEvents(stream) {
+    const out = [];
+    for (const line of stream.split("\n")) {
+        const text = line.trim();
+        if (!text.startsWith("{"))
+            continue;
+        try {
+            const v = JSON.parse(text);
+            if (isObject(v))
+                out.push(v);
+        }
+        catch {
+            // A line that is not one event: the stream's events are one per line.
+        }
+    }
+    return out;
+}
+/** Ops that are part of a replacement (`deploy.IsReplacementStep`). */
+const REPLACEMENT_OPS = new Set(["replace", "create-replacement", "delete-replaced", "read-replacement", "discard-replaced", "import-replacement"]);
+/** The printed document's filter (`shouldShow`), with `--show-sames` on: a non-logical replacement step is left out. */
+function shown(m) {
+    return !(m.logical !== true && REPLACEMENT_OPS.has(m.op ?? ""));
+}
+/** A value with every blinded secret envelope read as the printed document's `"[secret]"`. */
+function blinded(v) {
+    if (Array.isArray(v))
+        return v.map(blinded);
+    if (!isObject(v))
+        return v;
+    if (v[PULUMI_SIG_KEY] === PULUMI_SECRET_SIG)
+        return PULUMI_BLINDED_SECRET;
+    return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, blinded(x)]));
+}
+/** A step state in the printed document's form (`apitype.ResourceV3`, empty fields omitted). */
+function stateOf(s) {
+    if (!s || typeof s !== "object" || Array.isArray(s))
+        return undefined;
+    const map = (m) => (isObject(m) && Object.keys(m).length > 0 ? blinded(m) : undefined);
+    const inputs = map(s.inputs);
+    const outputs = map(s.outputs);
+    return {
+        ...(s.urn ? { urn: s.urn } : {}),
+        ...(typeof s.custom === "boolean" ? { custom: s.custom } : {}),
+        ...(s.delete ? { delete: true } : {}),
+        ...(s.id ? { id: s.id } : {}),
+        ...(s.type ? { type: s.type } : {}),
+        ...(s.parent ? { parent: s.parent } : {}),
+        ...(inputs ? { inputs } : {}),
+        ...(outputs ? { outputs } : {}),
+    };
+}
+/** One event step as a printed preview step (`getPreviewMetadataStep`). */
+export function pulumiStepOfEvent(m) {
+    const oldState = stateOf(m.old);
+    const newState = stateOf(m.new);
+    const detailedDiff = isObject(m.detailedDiff)
+        ? Object.fromEntries(Object.entries(m.detailedDiff).map(([k, d]) => [k, { ...(typeof d?.diffKind === "string" ? { kind: d.diffKind } : {}), ...(typeof d?.inputDiff === "boolean" ? { inputDiff: d.inputDiff } : {}) }]))
+        : undefined;
+    return {
+        ...(m.op ? { op: m.op } : {}),
+        ...(m.urn ? { urn: m.urn } : {}),
+        ...(m.provider ? { provider: m.provider } : {}),
+        ...(oldState ? { oldState } : {}),
+        ...(newState ? { newState } : {}),
+        ...(m.diffs?.length ? { diffReasons: [...m.diffs] } : {}),
+        ...(m.keys?.length ? { replaceReasons: [...m.keys] } : {}),
+        ...(detailedDiff ? { detailedDiff } : {}),
+    };
+}
+function stepsOf(events, keep) {
+    const out = [];
+    for (const e of events) {
+        const pre = e.resourcePreEvent;
+        if (!pre || !isObject(pre.metadata) || typeof pre.metadata.urn !== "string")
+            continue;
+        if (!keep(pre) || !shown(pre.metadata))
+            continue;
+        out.push(pulumiStepOfEvent(pre.metadata));
+    }
+    return out;
+}
+/** The diagnostics a stream printed, as the printed document lists them (ephemeral and debug ones left out). */
+function diagnosticsOf(events) {
+    return events
+        .map((e) => e.diagnosticEvent)
+        .filter((d) => isObject(d) && d.ephemeral !== true && d.severity !== "debug" && typeof d.message === "string")
+        .map((d) => ({ ...(d.urn ? { urn: d.urn } : {}), message: d.message, severity: d.severity ?? "info" }));
+}
+/**
+ * A streamed preview as the document `pulumi preview --json` prints without
+ * the env var: `steps`, `diagnostics` and, from the summary, `changeSummary`.
+ * What `pulumiPreviewPart` and `pulumiPreviewDigest` read.
+ */
+export function pulumiStreamPreview(stream) {
+    const events = typeof stream === "string" ? pulumiEngineEvents(stream) : stream;
+    const summary = events.map((e) => e.summaryEvent).find((x) => isObject(x));
+    return {
+        steps: stepsOf(events, () => true),
+        diagnostics: diagnosticsOf(events),
+        ...(summary?.resourceChanges ? { changeSummary: summary.resourceChanges } : {}),
+    };
+}
+/** The steps an `up` ran: its `resourcePreEvent`s outside any preview phase (`planning` unset). */
+export function pulumiAppliedSteps(stream) {
+    const events = typeof stream === "string" ? pulumiEngineEvents(stream) : stream;
+    return stepsOf(events, (e) => e.planning !== true);
+}
+/** The URNs whose operation failed during an `up` (`resOpFailedEvent`), sorted. */
+export function pulumiFailedUrns(stream) {
+    const events = typeof stream === "string" ? pulumiEngineEvents(stream) : stream;
+    const urns = events.map((e) => e.resOpFailedEvent?.metadata?.urn).filter((u) => typeof u === "string");
+    return [...new Set(urns)].sort();
+}
+/** The URNs an `up` finished an operation on (`resOutputsEvent` outside a preview phase, `same` left out), sorted. */
+export function pulumiLandedUrns(stream) {
+    const events = typeof stream === "string" ? pulumiEngineEvents(stream) : stream;
+    const urns = events
+        .map((e) => e.resOutputsEvent)
+        .filter((o) => isObject(o) && o.planning !== true && o.metadata?.op !== "same")
+        .map((o) => o.metadata?.urn)
+        .filter((u) => typeof u === "string");
+    return [...new Set(urns)].sort();
+}
+/** The `policyEvent` lines of a stream, `disabled` ones left out. */
+export function pulumiPolicyEvents(stream) {
+    const events = typeof stream === "string" ? pulumiEngineEvents(stream) : stream;
+    const out = [];
+    for (const e of events) {
+        const p = e.policyEvent;
+        if (!p || typeof p !== "object" || p.enforcementLevel === "disabled")
+            continue;
+        out.push({
+            pack: p.policyPackName ?? "",
+            ...(p.policyPackVersion ? { packVersion: p.policyPackVersion } : {}),
+            policy: p.policyName ?? "",
+            enforcementLevel: p.enforcementLevel ?? "advisory",
+            message: (p.message ?? "").trim(),
+            ...(p.resourceUrn ? { urn: p.resourceUrn } : {}),
+            ...(p.severity ? { severity: p.severity } : {}),
+        });
+    }
+    return out;
+}
+/** The rule id a CrossGuard policy is named by in chant's gate and overrides: `crossguard.<pack>.<policy>`. */
+export function crossGuardRule(v) {
+    return `crossguard.${v.pack}.${v.policy}`;
+}
+/**
+ * CrossGuard's violations as gate findings (`@intentius/chant/gate-policy`):
+ * a `mandatory` one denies the plan, an `advisory` (or `remediate`) one is
+ * a warning. CrossGuard has no hold.
+ */
+export function pulumiPolicyFindings(violations) {
+    const where = (v) => (v.urn ? ` (${v.urn})` : "");
+    return {
+        denials: violations.filter((v) => v.enforcementLevel === "mandatory").map((v) => ({ rule: crossGuardRule(v), message: `${v.message}${where(v)}` })),
+        holds: [],
+        warnings: violations.filter((v) => v.enforcementLevel !== "mandatory").map((v) => `${crossGuardRule(v)}: ${v.message}${where(v)}`),
+    };
+}
+/**
+ * plunge's per-resource timings in `up --json` (INTENTIUS/plunge#55), by URN:
+ * every valid entry of `metadata.plungeTimings` on each `resOutputsEvent`
+ * and `resOpFailedEvent`, joined across a URN's events in stream order. A
+ * stock Pulumi stream gives `{}`.
+ */
+export function pulumiStreamTimings(stream) {
+    var _a;
+    const events = typeof stream === "string" ? pulumiEngineEvents(stream) : stream;
+    const timings = {};
+    for (const e of events) {
+        for (const m of [e.resOutputsEvent?.metadata, e.resOpFailedEvent?.metadata]) {
+            if (!m?.urn || !Array.isArray(m.plungeTimings))
+                continue;
+            const read = m.plungeTimings.map(plungeTimingOf).filter((t) => t !== undefined);
+            if (read.length > 0)
+                (timings[_a = m.urn] ?? (timings[_a] = [])).push(...read);
+        }
+    }
+    return timings;
+}
+/** The stream's `summaryEvent`, with plunge's timings when present. Undefined when the stream has no summary. */
+export function pulumiStreamSummary(stream) {
+    const events = typeof stream === "string" ? pulumiEngineEvents(stream) : stream;
+    const s = events.map((e) => e.summaryEvent).find((x) => isObject(x));
+    const timings = pulumiStreamTimings(events);
+    if (!s)
+        return undefined;
+    return {
+        resourceChanges: isObject(s.resourceChanges) ? s.resourceChanges : {},
+        ...(typeof s.durationSeconds === "number" ? { durationSeconds: s.durationSeconds } : {}),
+        ...(typeof s.result === "string" && s.result ? { result: s.result } : {}),
+        ...(s.maybeCorrupt ? { maybeCorrupt: true } : {}),
+        ...(Object.keys(timings).length > 0 ? { timings } : {}),
+    };
+}
+/** The first error a stream reported (an error diagnostic or an `errorEvent`), if any. */
+export function pulumiStreamError(stream) {
+    const events = typeof stream === "string" ? pulumiEngineEvents(stream) : stream;
+    for (const e of events) {
+        if (typeof e.errorEvent?.error === "string" && e.errorEvent.error.trim())
+            return e.errorEvent.error.trim();
+        if (e.diagnosticEvent?.severity === "error" && typeof e.diagnosticEvent.message === "string")
+            return e.diagnosticEvent.message.trim();
+    }
+    return undefined;
+}