@intentius/chant-lexicon-pulumi 0.124.54 → 0.124.55

package/dist/ci-setup.js

@@ -0,0 +1,146 @@
+/**
+ * The engine install lines a Pulumi project's pull request pipeline runs in
+ * chant's default image (#4550, `LexiconPlugin.ciSetup`): Pulumi, or plunge
+ * when the member's engine is plunge (`pulumiMemberEngine`, #4559).
+ *
+ * Each line installs one release (#4592), modelled on plywood#12's
+ * (INTENTIUS/plywood 9b24b50847, packages/plywood/src/images.ts):
+ *
+ * - it takes a version, by default {@link PULUMI_CI_VERSION} or
+ *   {@link PLUNGE_CI_VERSION};
+ * - it downloads the Linux archive for the job's architecture and the
+ *   release's own checksums file (Pulumi's `pulumi-<ver>-checksums.txt`,
+ *   plunge's `plunge-v<ver>-checksums.txt`), and fails unless the archive's
+ *   line is there and matches the archive (`sha256sum -c`);
+ * - for a release with a recorded sum ({@link PINNED_SHA256}, or the
+ *   caller's `sha256`), the line must also hold that sum, so a tampered
+ *   checksums file fails as a tampered archive does;
+ * - it unpacks under a versioned path, `/opt/chant/<engine>-<version>/`,
+ *   with the language hosts beside the binary, and links the binary into
+ *   /usr/local/bin;
+ * - it skips the download when that directory already holds the binary,
+ *   and for Pulumi also when the `pulumi` on PATH is that version, so an
+ *   image that carries the engine pays nothing.
+ *
+ * A product with images of its own (plywood keeps its engines under
+ * /opt/plywood) passes `root`, so the lines find what its image carries.
+ */
+import { pulumiMemberEngine } from "./member-engine.js";
+/** The Pulumi release the default lines install: the plunge corpus's, which plunge 0.1.0 is built from. */
+export const PULUMI_CI_VERSION = "3.272.0";
+/** The plunge release the default lines install (INTENTIUS/plunge, tag plunge-v<ver>), not the Pulumi version it is built from. */
+export const PLUNGE_CI_VERSION = "0.1.0";
+/** Where the lines install each release by default. */
+export const CI_ENGINE_ROOT = "/opt/chant";
+export const CI_ARCHES = ["x64", "arm64"];
+/**
+ * The sha256 of each recorded Linux archive, copied from its release's
+ * checksums file (the same sums plywood#12 records). A checksums file that
+ * lists another sum for one of these fails the install. Add a release's
+ * two lines when moving a default version.
+ */
+export const PINNED_SHA256 = {
+    "pulumi-v3.272.0-linux-x64.tar.gz": "58d545f2b98761051922008ebd381ecef95484d7f7a5ff7faa15d7a780ea84f6",
+    "pulumi-v3.272.0-linux-arm64.tar.gz": "4f0741901b8982c4326b702dabf483c63d2cf77c88ac42dd752b72541284a534",
+    "plunge-v0.1.0-linux-x64.tar.gz": "22b89da39ab7dc11268c7b625fec3d99c0793c9c47bf8d031fa94e6967ee8187",
+    "plunge-v0.1.0-linux-arm64.tar.gz": "6855611b8cf8381d73f5ddf0b5c0a0d83bdc2a5bd8c50d415e52bb05a4574f83",
+};
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const ROOT = /^\/[A-Za-z0-9._/-]*$/;
+/** The release of `engine` at `version`. A version is a plain semver, so it is safe on a shell line. */
+export function ciRelease(engine, version) {
+    if (!VERSION.test(version))
+        throw new Error(`${engine} version ${JSON.stringify(version)} is not a release version such as 3.272.0`);
+    if (engine === "pulumi") {
+        return {
+            base: `https://github.com/pulumi/pulumi/releases/download/v${version}`,
+            archive: (arch) => `pulumi-v${version}-linux-${arch}.tar.gz`,
+            checksums: `pulumi-${version}-checksums.txt`,
+        };
+    }
+    return {
+        base: `https://github.com/INTENTIUS/plunge/releases/download/plunge-v${version}`,
+        archive: (arch) => `plunge-v${version}-linux-${arch}.tar.gz`,
+        checksums: `plunge-v${version}-checksums.txt`,
+    };
+}
+/** Where one release of one engine lives after its line runs. */
+export function ciEngineDir(engine, version, root = CI_ENGINE_ROOT) {
+    if (!ROOT.test(root))
+        throw new Error(`an engine root is an absolute path of letters, digits and ._/-, not ${JSON.stringify(root)}`);
+    return `${root.replace(/\/+$/, "")}/${engine}-${version}`;
+}
+/** The recorded sums for `version`, by architecture: the caller's, else {@link PINNED_SHA256}'s. */
+export function recordedSums(engine, version, given) {
+    const r = ciRelease(engine, version);
+    const out = {};
+    for (const arch of CI_ARCHES) {
+        const sum = given ? given[arch] : PINNED_SHA256[r.archive(arch)];
+        if (sum === undefined)
+            continue;
+        if (!SHA256.test(sum))
+            throw new Error(`the recorded sha256 for ${r.archive(arch)} is not 64 hex digits`);
+        out[arch] = sum;
+    }
+    return out;
+}
+/** The job's architecture as x64 or arm64. */
+const JOB_ARCH = `"$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/')"`;
+/**
+ * Shell that downloads one release into `dir` and checks it against the
+ * release's checksums file and, when recorded, the sum per architecture.
+ * Both archives unpack a top directory named after the engine, which
+ * `--strip-components=1` drops.
+ */
+function fetchScript(engine, version, dir, sums) {
+    const r = ciRelease(engine, version);
+    const recorded = CI_ARCHES.filter((a) => sums[a]);
+    const pinCase = recorded.length > 0 ? `case "$a" in ${recorded.map((a) => `${a}) want=${sums[a]} ;;`).join(" ")} *) want= ;; esac` : "want=";
+    const file = r.archive("x64").replace("-x64.", "-$a.");
+    return [
+        `a=${JOB_ARCH}`,
+        `f="${file}"`,
+        `t="$(mktemp -d)"`,
+        `curl -fsSLo "$t/$f" "${r.base}/$f"`,
+        `curl -fsSLo "$t/sums" "${r.base}/${r.checksums}"`,
+        // The archive's line, with any ./ or * before the name taken off.
+        `line="$(sed -n "s#^\\([0-9a-f]\\{64\\}\\)  *[*.]*/*$f\\$#\\1#p" "$t/sums")"`,
+        `{ [ -n "$line" ] || { echo "${engine} ${version}: $f is not in ${r.checksums}" >&2; exit 1; }; }`,
+        pinCase,
+        `{ [ -z "$want" ] || [ "$line" = "$want" ] || { echo "${engine} ${version}: ${r.checksums} lists $line for $f; chant records $want" >&2; exit 1; }; }`,
+        `echo "$line  $t/$f" | sha256sum -c - >/dev/null`,
+        `mkdir -p "${dir}"`,
+        `tar -xzf "$t/$f" -C "${dir}" --strip-components=1`,
+    ].join(" && ");
+}
+/** The line for one engine: skip when present, else fetch and check, then link into /usr/local/bin. */
+function installLine(engine, version, options, present) {
+    const dir = ciEngineDir(engine, version, options.root);
+    const install = `(set -e; ${fetchScript(engine, version, dir, recordedSums(engine, version, options.sha256))})`;
+    const link = `ln -sf "${dir}/${engine}" /usr/local/bin/${engine}`;
+    const inDir = `[ -x "${dir}/${engine}" ]`;
+    return present ? `${present} || { { ${inDir} || ${install}; } && ${link}; }` : `{ ${inDir} || ${install}; } && ${link}`;
+}
+/**
+ * Pulumi at `version` under `<root>/pulumi-<version>/`, checked against the
+ * release checksums. Skips when the `pulumi` on PATH is that version.
+ */
+export function pulumiInstallLine(version = PULUMI_CI_VERSION, options = {}) {
+    ciRelease("pulumi", version);
+    const present = `{ command -v pulumi >/dev/null 2>&1 && [ "$(pulumi version 2>/dev/null)" = "v${version}" ]; }`;
+    return installLine("pulumi", version, options, present);
+}
+/**
+ * plunge at `version` under `<root>/plunge-<version>/`, its language hosts
+ * beside it, checked against the release checksums. plunge reports the
+ * Pulumi version it is built from, not its own release, so only the
+ * versioned directory tells an installed release apart.
+ */
+export function plungeInstallLine(version = PLUNGE_CI_VERSION, options = {}) {
+    return installLine("plunge", version, options);
+}
+/** The lines for the project at `dir`. */
+export function pulumiCiSetup(ctx) {
+    return [pulumiMemberEngine(ctx.dir).engine === "plunge" ? plungeInstallLine() : pulumiInstallLine()];
+}

package/dist/composites/pulumi-adopt-op.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 { OpResource } from "@intentius/chant/op";
+/** One stack to adopt. */
+export interface PulumiAdoptStack {
+    /** The member's name. */
+    member: string;
+    /** The stack's directory, where `Pulumi.yaml` is, relative to the project root. */
+    dir: string;
+    /** The stack to adopt. */
+    stack: string;
+    /** The plunge backend URL (`plunge+s3://...`). Default: `plywood.yml`'s, `PULUMI_BACKEND_URL`, `Pulumi.yaml`'s. */
+    backend?: string;
+    /**
+     * Where the checkpoint comes from, when it is not the stock stack at the
+     * same root: `backend`, another backend to export from (Pulumi Cloud), or
+     * `file`, an export already taken. Either way plunge adopts it with
+     * `--file`.
+     */
+    from?: {
+        backend: string;
+    } | {
+        file: string;
+    };
+    /** The bucket to check, as `@intentius/chant/bucket-check` takes it, when the URL does not name it fully (azblob). */
+    bucket?: Record<string, unknown>;
+    /** Key prefixes a lifecycle rule must cover. Default: the backend URL's path. */
+    namespaces?: string[];
+    /** Bucket settings waived, as plunge's `allow_insecure`. An unwaivable one stays refused. */
+    allowInsecure?: string[];
+}
+export interface PulumiAdoptOpConfig {
+    /** Op name (kebab-case). */
+    name: string;
+    /** The stacks to adopt, one wave each, in this order. */
+    stacks: PulumiAdoptStack[];
+    /** Directory relative `dir`s resolve against. Default: the running process's cwd. */
+    cwd?: string;
+    /** The gate's name with one stack; with several, each gate is `<gateName>-<member>-<stack>`. Default: `approve-<name>`. */
+    gateName?: string;
+    /** How long a recorded pending gate stays valid, as a duration string. Default: core's own (48h). */
+    gateTimeout?: string;
+    /** Override the gate description shown to the approver. */
+    gateDescription?: string;
+    /** Rollback on a failed adoption, run as an `onFailure` phase. Refused without a command. */
+    compensate?: boolean | {
+        command?: string;
+        image?: string;
+    };
+}
+export interface PulumiAdoptOpResources {
+    /** Op resource: Check, Export, then Preview, gate and Adopt per stack. */
+    op: InstanceType<typeof OpResource>;
+}
+export declare function PulumiAdoptOp(config: PulumiAdoptOpConfig): PulumiAdoptOpResources;
+//# sourceMappingURL=pulumi-adopt-op.d.ts.map

package/dist/composites/pulumi-adopt-op.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pulumi-adopt-op.d.ts","sourceRoot":"","sources":["../../src/composites/pulumi-adopt-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,EAA6B,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAG5E,0BAA0B;AAC1B,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,mHAAmH;IACnH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,sHAAsH;IACtH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,6FAA6F;IAC7F,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2HAA2H;IAC3H,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6FAA6F;IAC7F,UAAU,CAAC,EAAE,OAAO,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAED,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAID,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,sBAAsB,CAsFjF"}

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,cAAc,CAAC;AAChE,OAAO,EAAsE,KAAK,IAAI,EAAE,MAAM,UAAU,CAAC;AAEzG,kIAAkI;AAClI,eAAO,MAAM,4BAA4B,yCAAyC,CAAC;AAEnF,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,eAAe,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACtE,eAAe,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,eAAe,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE,gBAAgB,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,eAAe,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,eAAe,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC7F,YAAY,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACpC,UAAU,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjC;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC9B,GAAG,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wHAAwH;IACxH,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;CAC3B;AAED,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAErD,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC,CAGrF,CAAC;AAEF,mEAAmE;AACnE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,kGAAkG;IAClG,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,sGAAsG;IACtG,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAQvE;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACvB;AAED,6BAA6B;AAC7B,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,8BAA8B;AAC9B,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,gHAAgH;AAChH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAatE;AAoCD,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,eAAe,GAAG,UAAU,CAkBhE;AAqBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,GAAG;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,WAAW,EAAE,KAAK,CAAC;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAQ3N;AAED,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,GAAG,UAAU,EAAE,CAG9F;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAIxF;AAED,sHAAsH;AACtH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAQxF;AAED,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,GAAG,qBAAqB,EAAE,CAiBzG;AAED,+GAA+G;AAC/G,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,GAAG,QAAQ,CAAC,GAAG,MAAM,CAExF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,GAAG,kBAAkB,CAOrG;AAED,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAWjH;AAED,iHAAiH;AACjH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,GAAG,kBAAkB,GAAG,SAAS,CAYjH;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE,GAAG,MAAM,GAAG,SAAS,CAOnG"}