@intentius/chant-lexicon-pulumi 0.124.54 → 0.124.56

package/dist/check-step.js

@@ -0,0 +1,270 @@
+/**
+ * The pulumi lexicon's steps in chant's check stage (#4633). `chant ci
+ * check` runs them after the `ci.hooks.check` hooks, for each workspace
+ * member of kind `pulumi` (`LexiconPlugin.checkSteps`,
+ * `@intentius/chant/components/check-steps`), so a product's check
+ * (`plywood check`) gets them through chant with nothing of its own:
+ *
+ * - `pulumi-install`: `pulumi install` (`plunge install` for a member on
+ *   plunge, `./member-engine.ts`) in the member's directory, which fetches
+ *   the program's dependencies and plugins the way `Pulumi.yaml` says;
+ * - `stack-config`: each stack's `Pulumi.<stack>.yaml` checked against the
+ *   project's config schema in `Pulumi.yaml`, with no command run (a key
+ *   with a type and no default must be set, a value must read as its type,
+ *   and a `secret: true` key must be encrypted). The stacks are the ones the
+ *   project lists by their files, plus the member's declared stack;
+ * - `pulumi-about`: `pulumi about --json`, which reports the engine, its
+ *   plugins and the backend for the report.
+ *
+ * The argv go through `runCheckPulumi` (`./run.ts`), which refuses any
+ * other. The environment is the check job's ({@link CheckStepsContext.env}):
+ * no forge token, no OIDC request variables, no cloud credential, so neither
+ * command can write a stack. A failure names the member and stack, and the
+ * check exits with chant's `failed` code.
+ *
+ * The runner is injectable, so the tests run no binary.
+ */
+import { execFile } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { parseYAML } from "@intentius/chant/yaml";
+import { pulumiMemberEngine } from "./member-engine.js";
+import { engineEnv, pulumiRunFailure, runCheckPulumi } from "./run.js";
+const execFileAsync = promisify(execFile);
+/** The lexicon name the report carries. */
+const LEXICON = "pulumi";
+/** A runner for `bin` with exactly `env` (the check job's), never the process's whole environment. */
+export function checkRunner(bin, env) {
+    return (args, opts) => execFileAsync(bin, args, { cwd: opts.cwd, maxBuffer: 64 * 1024 * 1024, env: engineEnv({ ...env, ...opts.env }) });
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** The key in its full form: a bare name belongs to the project. */
+function fullKey(project, key) {
+    return key.includes(":") ? key : `${project}:${key}`;
+}
+/** Read `Pulumi.yaml`'s schema from its parsed document. A short-form entry (`key: value`) is a value with no type. */
+export function pulumiProjectSchema(doc) {
+    const d = isRecord(doc) ? doc : {};
+    const project = typeof d.name === "string" ? d.name : "";
+    const config = isRecord(d.config) ? d.config : {};
+    const keys = [];
+    for (const [name, entry] of Object.entries(config)) {
+        const key = fullKey(project, name);
+        const schema = isRecord(entry) && ("type" in entry || "default" in entry || "value" in entry || "secret" in entry || "description" in entry || "items" in entry);
+        if (!schema) {
+            keys.push({ key, secret: false, hasDefault: true });
+            continue;
+        }
+        const e = entry;
+        keys.push({
+            key,
+            ...(typeof e.type === "string" ? { type: e.type } : {}),
+            ...(isRecord(e.items) && typeof e.items.type === "string" ? { items: { type: e.items.type } } : {}),
+            secret: e.secret === true,
+            hasDefault: "default" in e || "value" in e,
+        });
+    }
+    return { project, keys, stackConfigDir: typeof d.stackConfigDir === "string" && d.stackConfigDir.length > 0 ? d.stackConfigDir : "." };
+}
+const isSecure = (v) => isRecord(v) && typeof v.secure === "string";
+/** Whether a scalar stack value reads as `type`. Values are strings once Pulumi reads them, so `"3"` is an integer. */
+function readsAs(type, value) {
+    switch (type) {
+        case "string":
+            return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+        case "integer":
+            return (typeof value === "number" && Number.isInteger(value)) || (typeof value === "string" && /^-?[0-9]+$/.test(value.trim()));
+        case "boolean":
+            return typeof value === "boolean" || value === "true" || value === "false";
+        case "array":
+            return Array.isArray(value);
+        default:
+            return true;
+    }
+}
+/**
+ * What is wrong with one stack's config (`config:` of its
+ * `Pulumi.<stack>.yaml`, parsed) against the project's schema, as lines
+ * naming the stack and key. Empty when it passes. Keys of other namespaces
+ * (a provider's `aws:region`) are not checked: the project declares no type
+ * for them.
+ */
+export function pulumiStackConfigProblems(schema, stack, stackDoc) {
+    const raw = isRecord(stackDoc) && isRecord(stackDoc.config) ? stackDoc.config : {};
+    const values = new Map();
+    for (const [k, v] of Object.entries(raw))
+        values.set(fullKey(schema.project, k), v);
+    const problems = [];
+    for (const k of schema.keys) {
+        if (!k.type && !k.secret)
+            continue;
+        if (!values.has(k.key)) {
+            if (k.type && !k.hasDefault)
+                problems.push(`stack ${stack} is missing the configuration value ${k.key} (type ${k.type}, no default)`);
+            continue;
+        }
+        const value = values.get(k.key);
+        if (k.secret && !isSecure(value)) {
+            problems.push(`stack ${stack} sets ${k.key} in plain text, and the project declares it secret; set it with pulumi config set --secret`);
+            continue;
+        }
+        if (isSecure(value) || !k.type)
+            continue;
+        if (!readsAs(k.type, value)) {
+            problems.push(`stack ${stack} sets ${k.key} to ${JSON.stringify(value)}, which is not of type ${k.type}`);
+            continue;
+        }
+        if (k.type === "array" && k.items?.type && Array.isArray(value)) {
+            const bad = value.findIndex((item) => !isSecure(item) && !readsAs(k.items.type, item));
+            if (bad >= 0)
+                problems.push(`stack ${stack} sets ${k.key}[${bad}] to ${JSON.stringify(value[bad])}, which is not of type ${k.items.type}`);
+        }
+    }
+    return problems;
+}
+/** The project's file in `dir`, `Pulumi.yaml` or `Pulumi.yml`. */
+function projectFile(dir) {
+    return ["Pulumi.yaml", "Pulumi.yml"].map((f) => join(dir, f)).find((f) => existsSync(f));
+}
+/** The stacks the project lists by their `Pulumi.<stack>.yaml` files in `dir`, sorted. */
+export function listedStacks(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .map((f) => /^Pulumi\.(.+)\.ya?ml$/.exec(f)?.[1])
+        .filter((s) => s !== undefined)
+        .sort();
+}
+/** The stack file for `stack` in `dir`, if there is one. */
+function stackFile(dir, stack) {
+    return [`Pulumi.${stack}.yaml`, `Pulumi.${stack}.yml`].map((f) => join(dir, f)).find((f) => existsSync(f));
+}
+/** Read `pulumi about --json`'s document. Undefined when it is not JSON. */
+export function pulumiAboutDetail(engine, stdout) {
+    if (!stdout)
+        return undefined;
+    let doc;
+    try {
+        doc = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(doc))
+        return undefined;
+    const cli = isRecord(doc.cli) ? doc.cli : {};
+    const plugins = Array.isArray(doc.plugins)
+        ? doc.plugins.filter(isRecord).map((p) => ({ name: String(p.name ?? ""), ...(typeof p.version === "string" ? { version: p.version } : {}) })).filter((p) => p.name)
+        : [];
+    const b = isRecord(doc.backend) ? doc.backend : undefined;
+    const backend = b
+        ? { ...(typeof b.name === "string" ? { name: b.name } : {}), ...(typeof b.url === "string" ? { url: b.url } : {}), ...(typeof b.user === "string" ? { user: b.user } : {}) }
+        : undefined;
+    return { engine, ...(typeof cli.version === "string" ? { version: cli.version } : {}), plugins, ...(backend ? { backend } : {}) };
+}
+// ── The steps ───────────────────────────────────────────────────────
+/** The last lines of what a failed run printed, for its reason. */
+function tail(text) {
+    const lines = (text ?? "").trim().split("\n").filter(Boolean);
+    return lines.slice(-3).join(" | ");
+}
+/** The steps for one member, in order: install, each stack's config, about. */
+export async function pulumiMemberCheck(member, ctx, opts = {}) {
+    const fields = member.fields ?? {};
+    const declaredEngine = fields.engine === "pulumi" || fields.engine === "plunge" ? fields.engine : undefined;
+    const declaredStack = typeof fields.stack === "string" && fields.stack.length > 0 ? fields.stack : undefined;
+    const { engine } = pulumiMemberEngine(member.dir, declaredEngine, { env: ctx.env });
+    const run = (opts.runner ?? checkRunner)(engine, ctx.env);
+    const out = [];
+    const base = { lexicon: LEXICON, member: member.name };
+    const file = projectFile(member.dir);
+    if (!file) {
+        out.push({ ...base, step: "pulumi-install", exit: 1, outcome: "failed", reason: `member ${member.name} has no Pulumi.yaml in ${member.dir}` });
+        return out;
+    }
+    // pulumi install
+    let installed = true;
+    try {
+        await runCheckPulumi(run, ["install"], member.dir);
+        out.push({ ...base, step: "pulumi-install", exit: 0, outcome: "passed" });
+    }
+    catch (err) {
+        installed = false;
+        const f = pulumiRunFailure(err);
+        const why = f.missingBinary ? `${engine} is not installed in the check job` : tail(f.stderr) || tail(f.stdout) || f.message;
+        out.push({ ...base, step: "pulumi-install", exit: f.exitCode ?? 1, outcome: "failed", reason: `${engine} install failed for member ${member.name}: ${why}` });
+    }
+    // Stack config, run by nothing but this module.
+    let schema;
+    try {
+        schema = pulumiProjectSchema(parseYAML(readFileSync(file, "utf-8")));
+    }
+    catch (err) {
+        out.push({ ...base, step: "stack-config", exit: 1, outcome: "failed", reason: `member ${member.name}: ${file} does not read as YAML (${err instanceof Error ? err.message : String(err)})` });
+    }
+    if (schema) {
+        const stackDir = join(member.dir, schema.stackConfigDir);
+        const stacks = [...new Set([...listedStacks(stackDir), ...(declaredStack ? [declaredStack] : [])])].sort();
+        if (stacks.length === 0)
+            out.push({ ...base, step: "stack-config", exit: 0, outcome: "skipped", reason: `member ${member.name} lists no stack (no Pulumi.<stack>.yaml in ${stackDir})` });
+        for (const stack of stacks) {
+            const at = stackFile(stackDir, stack);
+            let doc = {};
+            if (at) {
+                try {
+                    doc = parseYAML(readFileSync(at, "utf-8"));
+                }
+                catch (err) {
+                    out.push({ ...base, step: "stack-config", stack, exit: 1, outcome: "failed", reason: `member ${member.name}, stack ${stack}: ${at} does not read as YAML (${err instanceof Error ? err.message : String(err)})` });
+                    continue;
+                }
+            }
+            const problems = pulumiStackConfigProblems(schema, stack, doc);
+            out.push(problems.length === 0
+                ? { ...base, step: "stack-config", stack, exit: 0, outcome: "passed" }
+                : { ...base, step: "stack-config", stack, exit: 1, outcome: "failed", reason: `member ${member.name}: ${problems.join("; ")}`, detail: { problems } });
+        }
+    }
+    // pulumi about --json
+    if (!installed) {
+        out.push({ ...base, step: "pulumi-about", exit: 0, outcome: "skipped", reason: `member ${member.name}: ${engine} install failed, so about did not run` });
+        return out;
+    }
+    const aboutArgs = declaredStack ? ["about", "--json", "--stack", declaredStack] : ["about", "--json"];
+    const stackPart = declaredStack ? { stack: declaredStack } : {};
+    try {
+        const { stdout } = await runCheckPulumi(run, aboutArgs, member.dir);
+        const detail = pulumiAboutDetail(engine, stdout);
+        out.push(detail
+            ? { ...base, step: "pulumi-about", ...stackPart, exit: 0, outcome: "passed", detail }
+            : { ...base, step: "pulumi-about", ...stackPart, exit: 1, outcome: "failed", reason: `${engine} about --json for member ${member.name} printed no JSON` });
+    }
+    catch (err) {
+        const f = pulumiRunFailure(err);
+        // about exits non-zero when one of its reads fails (no backend login in a check job), and still prints what it read.
+        const detail = pulumiAboutDetail(engine, f.stdout);
+        if (detail) {
+            ctx.log(`pulumi check: ${engine} about for ${member.name} exited ${f.exitCode ?? 1} and reported: ${tail(f.stderr) || "no reason"}`);
+            out.push({ ...base, step: "pulumi-about", ...stackPart, exit: f.exitCode ?? 1, outcome: "passed", detail });
+        }
+        else {
+            const why = f.missingBinary ? `${engine} is not installed in the check job` : tail(f.stderr) || f.message;
+            out.push({ ...base, step: "pulumi-about", ...stackPart, exit: f.exitCode ?? 1, outcome: "failed", reason: `${engine} about failed for member ${member.name}${declaredStack ? `, stack ${declaredStack}` : ""}: ${why}` });
+        }
+    }
+    return out;
+}
+/** The pulumi lexicon's check steps, for `LexiconPlugin.checkSteps`. */
+export function pulumiCheckSteps(opts = {}) {
+    return {
+        lexicon: LEXICON,
+        kinds: ["pulumi"],
+        async run(ctx) {
+            const out = [];
+            for (const member of ctx.members)
+                out.push(...(await pulumiMemberCheck(member, ctx, opts)));
+            return out;
+        },
+    };
+}

package/dist/ci-setup.d.ts

@@ -0,0 +1,53 @@
+export type CiEngine = "pulumi" | "plunge";
+/** The Pulumi release the default lines install: the plunge corpus's, which plunge 0.1.0 is built from. */
+export declare 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 declare const PLUNGE_CI_VERSION = "0.1.0";
+/** Where the lines install each release by default. */
+export declare const CI_ENGINE_ROOT = "/opt/chant";
+/** The archive's architecture word, as both projects name their Linux builds. */
+export type CiArch = "x64" | "arm64";
+export declare const CI_ARCHES: readonly CiArch[];
+/**
+ * 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 declare const PINNED_SHA256: Readonly<Record<string, string>>;
+/** What a caller may set on an install line. */
+export interface CiInstallOptions {
+    /** Where the versioned directories live. Default {@link CI_ENGINE_ROOT}. */
+    root?: string;
+    /** Recorded sums by architecture, in place of {@link PINNED_SHA256}'s for this release. */
+    sha256?: Partial<Record<CiArch, string>>;
+}
+/** One release's download: the base URL, the archive per architecture, and its checksums file. */
+export interface CiRelease {
+    base: string;
+    archive(arch: CiArch): string;
+    checksums: string;
+}
+/** The release of `engine` at `version`. A version is a plain semver, so it is safe on a shell line. */
+export declare function ciRelease(engine: CiEngine, version: string): CiRelease;
+/** Where one release of one engine lives after its line runs. */
+export declare function ciEngineDir(engine: CiEngine, version: string, root?: string): string;
+/** The recorded sums for `version`, by architecture: the caller's, else {@link PINNED_SHA256}'s. */
+export declare function recordedSums(engine: CiEngine, version: string, given?: Partial<Record<CiArch, string>>): Partial<Record<CiArch, string>>;
+/**
+ * Pulumi at `version` under `<root>/pulumi-<version>/`, checked against the
+ * release checksums. Skips when the `pulumi` on PATH is that version.
+ */
+export declare function pulumiInstallLine(version?: string, options?: CiInstallOptions): string;
+/**
+ * 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 declare function plungeInstallLine(version?: string, options?: CiInstallOptions): string;
+/** The lines for the project at `dir`. */
+export declare function pulumiCiSetup(ctx: {
+    dir: string;
+}): string[];
+//# sourceMappingURL=ci-setup.d.ts.map

package/dist/ci-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-setup.d.ts","sourceRoot":"","sources":["../src/ci-setup.ts"],"names":[],"mappings":"AA6BA,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3C,2GAA2G;AAC3G,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C,mIAAmI;AACnI,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,uDAAuD;AACvD,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C,iFAAiF;AACjF,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;AACrC,eAAO,MAAM,SAAS,EAAE,SAAS,MAAM,EAAqB,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAK1D,CAAC;AAEF,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC1C;AAED,kGAAkG;AAClG,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,wGAAwG;AACxG,wBAAgB,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CActE;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,SAAiB,GAAG,MAAM,CAG5F;AAED,oGAAoG;AACpG,wBAAgB,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAUxI;AA0CD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAoB,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAIrG;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAoB,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAErG;AAED,0CAA0C;AAC1C,wBAAgB,aAAa,CAAC,GAAG,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,EAAE,CAE5D"}

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"}