@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

package/dist/state/s3.d.ts

@@ -1,68 +1,21 @@
-import { type StoreFetch } from "./object-store.js";
-export interface S3Credentials {
-    accessKeyId: string;
-    secretAccessKey: string;
-    sessionToken?: string;
-}
-/** A role to assume with the job's OIDC token, the way the AWS SDKs read `AWS_ROLE_ARN` and `AWS_WEB_IDENTITY_TOKEN_FILE`. */
-export interface S3WebIdentity {
-    roleArn: string;
-    tokenFile: string;
-    sessionName: string;
-    /** STS's address, https://host[:port], no path. */
-    endpoint: string;
-}
-export interface S3Location {
-    bucket: string;
-    /** https://host[:port], no path. Default: AWS's regional endpoint. */
-    endpoint?: string;
-    region: string;
-}
-export type S3Target = S3Location & (S3Credentials | {
-    webIdentity: S3WebIdentity;
-});
+/**
+ * The S3 client a state's lock and write use: chant core's (#4554,
+ * `@intentius/chant/object-store`), which signs with chant's one AWS
+ * signer. Get, put, put only when absent, head and delete one object; with
+ * no static keys, a role is assumed with the job's OIDC token through STS
+ * AssumeRoleWithWebIdentity.
+ */
+import { type S3Target } from "@intentius/chant/object-store";
+export { assumeRoleWithWebIdentity, S3Client, sign, type S3Credentials, type S3Location, type S3Target, type S3WebIdentity } from "@intentius/chant/object-store";
 /**
  * The target for `bucket` from the AWS environment variables. Credentials,
  * first match wins: static keys in `AWS_ACCESS_KEY_ID` and
  * `AWS_SECRET_ACCESS_KEY`; `AWS_ROLE_ARN` assumed with the token in
- * `AWS_WEB_IDENTITY_TOKEN_FILE`.
+ * `AWS_WEB_IDENTITY_TOKEN_FILE`, in a session named `chant-state` unless
+ * AWS_ROLE_SESSION_NAME names one.
  */
 export declare function s3FromEnv(where: {
     bucket: string;
     endpoint?: string;
 }, env?: NodeJS.ProcessEnv): S3Target;
-/** STS AssumeRoleWithWebIdentity. The request carries the token and is not signed. */
-export declare function assumeRoleWithWebIdentity(w: S3WebIdentity, fetchFn: StoreFetch, readToken?: (file: string) => string): Promise<S3Credentials & {
-    expiration?: Date;
-}>;
-/** Signature Version 4 headers for a request; its query string, if any, is signed in canonical order. `extra` headers are signed too. */
-export declare function sign(t: Pick<S3Location, "region"> & S3Credentials, method: string, rawUrl: string, extra: Record<string, string>, payload: string, now: Date, service?: string): Record<string, string>;
-export declare class S3Client {
-    readonly target: S3Target;
-    private readonly fetchFn;
-    private creds?;
-    constructor(target: S3Target, fetchFn?: StoreFetch);
-    private where;
-    /** Static keys as given; a web identity's keys once per client, again a minute before they expire. */
-    private signer;
-    private request;
-    /** Write an object, unconditionally. */
-    put(key: string, body: string, contentType: string): Promise<void>;
-    /** The object's text, or undefined when there is none. */
-    get(key: string): Promise<string | undefined>;
-    /** The object's metadata and never its body: whether it exists, its ETag and its version id. */
-    head(key: string): Promise<{
-        exists: boolean;
-        etag?: string;
-        versionId?: string;
-    }>;
-    /**
-     * Write an object only when there is none (If-None-Match: *): true when
-     * this write made it, false when one was there. A store that refuses the
-     * condition fails the write: a lock is never taken unconditionally.
-     */
-    putIfAbsent(key: string, body: string, contentType: string): Promise<boolean>;
-    /** Delete an object. One that is not there is deleted already. */
-    remove(key: string): Promise<void>;
-}
 //# sourceMappingURL=s3.d.ts.map

package/dist/state/s3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/state/s3.ts"],"names":[],"mappings":"AAaA,OAAO,EAA+D,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE9G,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,8HAA8H;AAC9H,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,CAAC,aAAa,GAAG;IAAE,WAAW,EAAE,aAAa,CAAA;CAAE,CAAC,CAAC;AAErF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,QAAQ,CAoBtH;AAED,sFAAsF;AACtF,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAwC,GAAG,OAAO,CAAC,aAAa,GAAG;IAAE,UAAU,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC,CAqB5M;AAKD,yIAAyI;AACzI,wBAAgB,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,GAAG,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,SAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBrM;AAKD,qBAAa,QAAQ;IAGP,QAAQ,CAAC,MAAM,EAAE,QAAQ;IAAE,OAAO,CAAC,QAAQ,CAAC,OAAO;IAF/D,OAAO,CAAC,KAAK,CAAC,CAAiD;IAE/D,YAAqB,MAAM,EAAE,QAAQ,EAAmB,OAAO,GAAE,UAAyB,EAAI;IAE9F,OAAO,CAAC,KAAK;IAIb,sGAAsG;YACxF,MAAM;YAcN,OAAO;IAMrB,wCAAwC;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE;IAED,0DAA0D;IACpD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAKlD;IAED,gGAAgG;IAC1F,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAOvF;IAED;;;;OAIG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMlF;IAED,kEAAkE;IAC5D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;CACF"}
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/state/s3.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAA8B,KAAK,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAE1F,OAAO,EAAE,yBAAyB,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAElK;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,QAAQ,CAEtH"}

package/dist/state/s3.js

@@ -1,170 +1,19 @@
 /**
- * The little of S3 a state's lock and write need: get, put, put only when
- * absent, head and delete one object, signed with AWS Signature Version 4
- * from `node:crypto`. Any S3-compatible store answers it (S3, MinIO, floci).
- * With no static keys, a role is assumed with the job's OIDC token through
- * STS AssumeRoleWithWebIdentity. `fetch` is injectable so the signing is
- * tested against recorded requests.
- *
- * Lifted from terragucci's `report/s3.ts` (c493e0e), without presigning,
- * version listing and the re-plan's traded credentials.
+ * The S3 client a state's lock and write use: chant core's (#4554,
+ * `@intentius/chant/object-store`), which signs with chant's one AWS
+ * signer. Get, put, put only when absent, head and delete one object; with
+ * no static keys, a role is assumed with the job's OIDC token through STS
+ * AssumeRoleWithWebIdentity.
  */
-import { createHash, createHmac } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { defaultFetch, encodePath, encodeStrict, StoreError, xmlText } from "./object-store.js";
+import { s3FromEnv as coreS3FromEnv } from "@intentius/chant/object-store";
+export { assumeRoleWithWebIdentity, S3Client, sign } from "@intentius/chant/object-store";
 /**
  * The target for `bucket` from the AWS environment variables. Credentials,
  * first match wins: static keys in `AWS_ACCESS_KEY_ID` and
  * `AWS_SECRET_ACCESS_KEY`; `AWS_ROLE_ARN` assumed with the token in
- * `AWS_WEB_IDENTITY_TOKEN_FILE`.
+ * `AWS_WEB_IDENTITY_TOKEN_FILE`, in a session named `chant-state` unless
+ * AWS_ROLE_SESSION_NAME names one.
  */
 export function s3FromEnv(where, env = process.env) {
-    const endpoint = where.endpoint ?? env.AWS_ENDPOINT_URL_S3 ?? env.AWS_ENDPOINT_URL;
-    const region = env.AWS_REGION || env.AWS_DEFAULT_REGION || "us-east-1";
-    const at = { bucket: where.bucket, ...(endpoint ? { endpoint: endpoint.replace(/\/+$/, "") } : {}), region };
-    const accessKeyId = env.AWS_ACCESS_KEY_ID;
-    const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
-    if (accessKeyId && secretAccessKey)
-        return { ...at, accessKeyId, secretAccessKey, ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}) };
-    const tokenFile = env.AWS_WEB_IDENTITY_TOKEN_FILE;
-    if (env.AWS_ROLE_ARN && tokenFile) {
-        return {
-            ...at,
-            webIdentity: {
-                roleArn: env.AWS_ROLE_ARN,
-                tokenFile,
-                sessionName: env.AWS_ROLE_SESSION_NAME || "chant-state",
-                endpoint: (env.AWS_ENDPOINT_URL_STS || env.AWS_ENDPOINT_URL || `https://sts.${region}.amazonaws.com`).replace(/\/+$/, ""),
-            },
-        };
-    }
-    throw new StoreError("set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE");
-}
-/** STS AssumeRoleWithWebIdentity. The request carries the token and is not signed. */
-export async function assumeRoleWithWebIdentity(w, fetchFn, readToken = (f) => readFileSync(f, "utf-8")) {
-    let token;
-    try {
-        token = readToken(w.tokenFile).trim();
-    }
-    catch (e) {
-        throw new StoreError(`cannot read the OIDC token in ${w.tokenFile}: ${e.message}`);
-    }
-    if (!token)
-        throw new StoreError(`the OIDC token file ${w.tokenFile} is empty`);
-    const body = new URLSearchParams({ Action: "AssumeRoleWithWebIdentity", Version: "2011-06-15", RoleArn: w.roleArn, RoleSessionName: w.sessionName, WebIdentityToken: token }).toString();
-    const res = await fetchFn(`${w.endpoint}/`, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded; charset=utf-8", accept: "application/xml" }, body });
-    const xml = await res.text();
-    if (!res.ok) {
-        const why = [xmlText(xml, "Code"), xmlText(xml, "Message")].filter(Boolean).join(": ") || xml.slice(0, 300);
-        throw new StoreError(`AssumeRoleWithWebIdentity for ${w.roleArn}: ${res.status} ${why}`);
-    }
-    const accessKeyId = xmlText(xml, "AccessKeyId");
-    const secretAccessKey = xmlText(xml, "SecretAccessKey");
-    const sessionToken = xmlText(xml, "SessionToken");
-    if (!accessKeyId || !secretAccessKey || !sessionToken)
-        throw new StoreError(`AssumeRoleWithWebIdentity for ${w.roleArn} answered without credentials`);
-    const expires = xmlText(xml, "Expiration");
-    return { accessKeyId, secretAccessKey, sessionToken, ...(expires && !Number.isNaN(Date.parse(expires)) ? { expiration: new Date(expires) } : {}) };
-}
-const sha256 = (b) => createHash("sha256").update(b).digest("hex");
-const hmac = (key, s) => createHmac("sha256", key).update(s).digest();
-/** Signature Version 4 headers for a request; its query string, if any, is signed in canonical order. `extra` headers are signed too. */
-export function sign(t, method, rawUrl, extra, payload, now, service = "s3") {
-    const url = new URL(rawUrl);
-    const amzDate = now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
-    const day = amzDate.slice(0, 8);
-    const headers = {
-        host: url.host,
-        "x-amz-content-sha256": payload,
-        "x-amz-date": amzDate,
-        ...Object.fromEntries(Object.entries(extra).map(([k, v]) => [k.toLowerCase(), v])),
-        ...(t.sessionToken ? { "x-amz-security-token": t.sessionToken } : {}),
-    };
-    const names = Object.keys(headers).sort();
-    const query = [...url.searchParams].map(([k, v]) => `${encodeStrict(k)}=${encodeStrict(v)}`).sort().join("&");
-    const canonical = [method, url.pathname, query, ...names.map((n) => `${n}:${headers[n].trim()}`), "", names.join(";"), payload].join("\n");
-    const scope = `${day}/${t.region}/${service}/aws4_request`;
-    const toSign = ["AWS4-HMAC-SHA256", amzDate, scope, sha256(canonical)].join("\n");
-    const key4 = hmac(hmac(hmac(hmac(`AWS4${t.secretAccessKey}`, day), t.region), service), "aws4_request");
-    const signature = createHmac("sha256", key4).update(toSign).digest("hex");
-    const { host: _host, ...sent } = headers;
-    return { ...sent, authorization: `AWS4-HMAC-SHA256 Credential=${t.accessKeyId}/${scope}, SignedHeaders=${names.join(";")}, Signature=${signature}` };
-}
-/** The address of `key` in the bucket: path-style on a custom endpoint, virtual-hosted on AWS. */
-const objectUrl = (t, key) => `${t.endpoint ? `${t.endpoint}/${t.bucket}` : `https://${t.bucket}.s3.${t.region}.amazonaws.com`}/${encodePath(key)}`;
-export class S3Client {
-    constructor(target, fetchFn = defaultFetch) {
-        this.target = target;
-        this.fetchFn = fetchFn;
-    }
-    where(key) {
-        return `s3://${this.target.bucket}/${key}`;
-    }
-    /** Static keys as given; a web identity's keys once per client, again a minute before they expire. */
-    async signer() {
-        const t = this.target;
-        if (!("webIdentity" in t))
-            return t;
-        const assume = () => (this.creds = assumeRoleWithWebIdentity(t.webIdentity, this.fetchFn).catch((e) => {
-            this.creds = undefined;
-            throw e;
-        }));
-        let held = await (this.creds ?? assume());
-        if (held.expiration && held.expiration.getTime() - Date.now() < 60000)
-            held = await assume();
-        const { accessKeyId, secretAccessKey, sessionToken } = held;
-        return { bucket: t.bucket, ...(t.endpoint ? { endpoint: t.endpoint } : {}), region: t.region, accessKeyId, secretAccessKey, ...(sessionToken ? { sessionToken } : {}) };
-    }
-    async request(method, key, body, extra = {}) {
-        const t = await this.signer();
-        const url = objectUrl(t, key);
-        return this.fetchFn(url, { method, headers: sign(t, method, url, extra, sha256(body), new Date()), ...(method === "PUT" ? { body } : {}) });
-    }
-    /** Write an object, unconditionally. */
-    async put(key, body, contentType) {
-        const res = await this.request("PUT", key, body, { "content-type": contentType });
-        if (!res.ok)
-            throw new StoreError(`PUT ${this.where(key)}: ${res.status} ${(await res.text()).slice(0, 300)}`);
-    }
-    /** The object's text, or undefined when there is none. */
-    async get(key) {
-        const res = await this.request("GET", key, "");
-        if (res.status === 404)
-            return undefined;
-        if (!res.ok)
-            throw new StoreError(`GET ${this.where(key)}: ${res.status} ${(await res.text()).slice(0, 300)}`);
-        return res.text();
-    }
-    /** The object's metadata and never its body: whether it exists, its ETag and its version id. */
-    async head(key) {
-        const res = await this.request("HEAD", key, "");
-        if (res.status === 404)
-            return { exists: false };
-        if (!res.ok)
-            throw new StoreError(`HEAD ${this.where(key)}: ${res.status}`);
-        const etag = res.headers?.get("etag") ?? undefined;
-        const version = res.headers?.get("x-amz-version-id") ?? undefined;
-        return { exists: true, ...(etag ? { etag } : {}), ...(version && version !== "null" ? { versionId: version } : {}) };
-    }
-    /**
-     * Write an object only when there is none (If-None-Match: *): true when
-     * this write made it, false when one was there. A store that refuses the
-     * condition fails the write: a lock is never taken unconditionally.
-     */
-    async putIfAbsent(key, body, contentType) {
-        const res = await this.request("PUT", key, body, { "content-type": contentType, "if-none-match": "*" });
-        if (res.status === 412 || res.status === 409)
-            return false;
-        if (res.status === 501)
-            throw new StoreError(`PUT ${this.where(key)}: the store does not take a conditional write (501)`);
-        if (!res.ok)
-            throw new StoreError(`PUT ${this.where(key)}: ${res.status} ${(await res.text()).slice(0, 300)}`);
-        return true;
-    }
-    /** Delete an object. One that is not there is deleted already. */
-    async remove(key) {
-        const res = await this.request("DELETE", key, "");
-        if (!res.ok && res.status !== 404)
-            throw new StoreError(`DELETE ${this.where(key)}: ${res.status} ${(await res.text()).slice(0, 300)}`);
-    }
+    return coreS3FromEnv({ ...where, sessionName: "chant-state", setting: "the state bucket" }, env);
 }

package/dist/state/store.js

@@ -52,7 +52,7 @@ function s3Store(o, fetchFn) {
         lock: (info) => client.putIfAbsent(lockKey, info, JSON_TYPE),
         unlock: () => client.remove(lockKey),
         readBeside: (suffix) => client.get(`${o.key}${suffix}`),
-        writeBeside: (suffix, body) => client.put(`${o.key}${suffix}`, body, JSON_TYPE),
+        writeBeside: async (suffix, body) => void (await client.put(`${o.key}${suffix}`, body, JSON_TYPE)),
         removeBeside: (suffix) => client.remove(`${o.key}${suffix}`),
         besideLocation: (suffix) => `s3://${o.bucket}/${o.key}${suffix}`,
         adopt: () => { },
@@ -75,7 +75,7 @@ function gcsStore(o, fetchFn) {
         lock: (info) => client.putIfAbsent(o.lock, info, JSON_TYPE),
         unlock: () => client.remove(o.lock),
         readBeside: (suffix) => client.get(`${o.key}${suffix}`),
-        writeBeside: (suffix, body) => client.put(`${o.key}${suffix}`, body, JSON_TYPE),
+        writeBeside: async (suffix, body) => void (await client.put(`${o.key}${suffix}`, body, JSON_TYPE)),
         removeBeside: (suffix) => client.remove(`${o.key}${suffix}`),
         besideLocation: (suffix) => `gs://${o.bucket}/${o.key}${suffix}`,
         adopt: () => { },

package/dist/state-ops.d.ts

@@ -0,0 +1,255 @@
+import type { Capability } from "@intentius/chant/components/capability";
+import type { ChangeSetPart } from "@intentius/chant/change-set";
+import { finishGatedRequest, readGatedRequests, requestGate, spendGatedRequest, type GatedRequest, type GatedRequestRules, type RequestGateInput, type RequestGateResult } from "@intentius/chant/lifecycle/gated-request";
+import { type BinaryExec } from "./state/exec.js";
+/** The ops the gated requests of this module wait at, one per kind, as terragucci named them. */
+export declare const STATE_OPS: {
+    readonly unlock: "tf-unlock";
+    readonly migrate: "tf-migrate";
+    readonly export: "tf-state-export";
+};
+/** The request kinds of #4551's design. */
+export declare const STATE_OP_KINDS: {
+    readonly unlock: "unlock";
+    readonly migrate: "migrate";
+    readonly export: "state-export";
+};
+/** A binary run that exited non-zero, with the tail of its output. */
+export declare class StateOpError extends Error {
+    readonly root: string;
+    readonly command: string;
+    readonly code: number;
+    readonly tail: string;
+    constructor(root: string, command: string, code: number, tail: string);
+}
+/** A gated operation stopped for a person: its request waits for an approval. The command that ran it exits 3. */
+export declare class StateOpWaitingError extends Error {
+    readonly op: string;
+    readonly subject: string;
+    readonly digest: string;
+    readonly command: string;
+    readonly exitCode: 3;
+    constructor(op: string, subject: string, digest: string, command: string);
+}
+/** Where and how the binary runs for one root. */
+export interface RootRun {
+    /** The root's name, as messages and records name it. */
+    root: string;
+    binary: string;
+    /** The root's directory. */
+    dir: string;
+    env?: NodeJS.ProcessEnv;
+    exec?: BinaryExec;
+}
+/** `init -input=false -no-color`, with `-reconfigure` and `-backend-config` pairs when given. */
+export declare function initRoot(r: RootRun & {
+    backendConfig?: Record<string, string>;
+    reconfigure?: boolean;
+}): Promise<void>;
+/**
+ * Release the state lock with this ID: `force-unlock -force -no-color <id>`.
+ * Run it under {@link gatedStateOp}; the binary releases whichever lock has
+ * the ID, so the approval binds the ID and the lock's location.
+ */
+export declare function forceUnlockState(r: RootRun & {
+    id: string;
+}): Promise<void>;
+/**
+ * Write a state file with `state push`. `lock: false` passes `-lock=false`,
+ * for a caller that holds the state's lock itself; `force` passes `-force`,
+ * for a push over an empty state of another lineage the caller checked.
+ */
+export declare function pushStateFile(r: RootRun & {
+    file: string;
+    lock?: boolean;
+    force?: boolean;
+}): Promise<void>;
+/** A plan read back: its JSON, and the binary's summary line. */
+export interface PlanRead {
+    planFile: string;
+    json: unknown;
+    summary: string;
+}
+/**
+ * Plan a root against its state and read the plan: the check a migration
+ * makes before and after it writes. `lock: false` passes `-lock=false`, for a
+ * caller that holds the lock itself.
+ */
+export declare function planStateCheck(r: RootRun & {
+    planFile: string;
+    lock?: boolean;
+}): Promise<PlanRead>;
+/** A copy's plan: the plan read back, and its change-set part with the member's plan digest. */
+export interface CopyPlanRead extends PlanRead {
+    part: ChangeSetPart;
+    planDigest: string;
+}
+/**
+ * Initialise a root under its copy's backend settings and plan it, a destroy
+ * with `destroy`. `backendConfig` is what makes it the copy (a state key with
+ * the copy's suffix), so it is required and never empty: without it the plan
+ * would be of the root's own state. Pass `init: false` for a root another
+ * tool initialised (a Terragrunt unit prepared with the suffix set).
+ */
+export declare function planCopy(r: RootRun & {
+    backendConfig: Record<string, string>;
+    planFile: string;
+    destroy?: boolean;
+    lockTimeout?: string | false;
+    init?: boolean;
+}): Promise<CopyPlanRead>;
+/** Apply a saved plan, and nothing else: `apply -input=false -no-color <plan>`. */
+export declare function applyPlanFile(r: RootRun & {
+    planFile: string;
+    lockTimeout?: string | false;
+}): Promise<void>;
+/** The gated-request ledger, injectable for tests. Default chant's on `chant/lifecycle`. */
+export interface GatedRequestLedger {
+    requestGate: typeof requestGate;
+    spendGatedRequest: typeof spendGatedRequest;
+    finishGatedRequest: typeof finishGatedRequest;
+    readGatedRequests: typeof readGatedRequests;
+}
+/**
+ * The time a request was first asked, so asking again binds the same
+ * digest: chant's digest covers `at`, and a run that asked anew each time
+ * would never meet the approval of the last one. The newest standing,
+ * unspent request with the same kind, subject, requester and fields gives
+ * its `at`; with none, `now`.
+ */
+export declare function requestedAt(op: string, request: Omit<GatedRequest, "at">, options?: {
+    now?: string;
+    cwd?: string;
+    ledger?: Pick<GatedRequestLedger, "readGatedRequests">;
+}): Promise<string>;
+/** The digest `requestGate` puts in `fields.proof` for an attachment. */
+export declare const attachmentDigest: (attachment: string) => string;
+export interface GatedStateOpInput {
+    op: string;
+    /** The request, less `at`, which {@link requestedAt} fills. */
+    request: Omit<GatedRequest, "at"> & {
+        at?: string;
+    };
+    rules: GatedRequestRules;
+    description?: string;
+    expiry?: string;
+    base?: string;
+    /** A document the request carries, such as a migration's proof; its digest joins the request. */
+    attachment?: string;
+    cwd?: string;
+    now?: string;
+    runId?: string;
+    commit?: string;
+    ledger?: GatedRequestLedger;
+    gates?: RequestGateInput["gates"];
+    /**
+     * A last check just before the spend, for a fact that can change while the
+     * request waited (a run that may hold the lock came back). A string refuses
+     * the operation with that reason, and the approval is not spent.
+     */
+    beforeSpend?: () => Promise<string | undefined>;
+}
+/** How a gated operation ended. */
+export type GatedStateOpResult<T> = Exclude<RequestGateResult, {
+    status: "approved";
+}> | {
+    status: "held";
+    digest: string;
+    request: GatedRequest;
+    reason: string;
+} | {
+    status: "done";
+    digest: string;
+    request: GatedRequest;
+    approvedBy: string;
+    output: T;
+    recorded: boolean;
+} | {
+    status: "failed";
+    digest: string;
+    request: GatedRequest;
+    approvedBy: string;
+    error: Error;
+    recorded: boolean;
+};
+/**
+ * Run `act` once its request is approved: ask (or read) the request, spend
+ * the approval, act, and record how it ended. `act` returns its output and
+ * the flat facts that go on the finished line. A spend that cannot be pushed
+ * throws before `act` runs, so no approval acts twice. A finished line that
+ * cannot be written is reported as `recorded: false`; the act already ran.
+ */
+export declare function gatedStateOp<T>(input: GatedStateOpInput, act: (approved: {
+    digest: string;
+    request: GatedRequest;
+    approvedBy: string;
+}) => Promise<{
+    output: T;
+    detail?: Record<string, string | number | boolean>;
+}>): Promise<GatedStateOpResult<T>>;
+/** The digest a request binds, for a caller that prints it before it asks. */
+export declare const stateOpDigest: (op: string, request: GatedRequest) => string;
+/** The step input the gated capabilities share: the root and the request's rules. */
+interface GatedRootInput {
+    root: string;
+    /** The project's directory, where the ledger is and roots are found. Default the process's. */
+    cwd?: string;
+    /** The root's directory. Default `root` under the project. */
+    dir?: string;
+    binary?: string;
+    /** Who asks. Default the CI actor, else the user. */
+    by?: string;
+    /** Which approvals count. Default the ledger's. */
+    approval?: GatedRequestRules["mode"];
+}
+/** `terraform-state-unlock`: release one lock, by ID, under a gated request. */
+export interface StateUnlockStepInput extends GatedRootInput {
+    id: string;
+    /** Where the lock is, as the record names it: the lock file, the lock object, the lease's blob. */
+    location: string;
+}
+/** `terraform-state-push`: write state files to their roots under one gated request whose attachment is the proof. */
+export interface StatePushStepInput extends GatedRootInput {
+    files: Array<{
+        root: string;
+        dir?: string;
+        file: string;
+        lock?: boolean;
+        force?: boolean;
+    }>;
+    /** The proof the approval binds: what the push writes and why it is safe. */
+    proof: string;
+}
+/** `terraform-copy`: plan and apply a root's copy under its own backend settings. */
+export interface CopyStepInput {
+    root: string;
+    cwd?: string;
+    dir?: string;
+    binary?: string;
+    backendConfig: Record<string, string>;
+    destroy?: boolean;
+    lockTimeout?: string | false;
+}
+export declare const terraformStateUnlockCapability: Capability<StateUnlockStepInput, {
+    root: string;
+    id: string;
+}>;
+export declare const terraformStatePushCapability: Capability<StatePushStepInput, {
+    roots: string[];
+}>;
+export declare const terraformCopyCapability: Capability<CopyStepInput, {
+    root: string;
+    planDigest: string;
+}>;
+/** The state operations' capabilities, for the plugin's registry. */
+export declare const terraformStateOpCapabilities: readonly [Capability<StateUnlockStepInput, {
+    root: string;
+    id: string;
+}>, Capability<StatePushStepInput, {
+    roots: string[];
+}>, Capability<CopyStepInput, {
+    root: string;
+    planDigest: string;
+}>];
+export {};
+//# sourceMappingURL=state-ops.d.ts.map

package/dist/state-ops.d.ts.map

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