@quadnix/octo 0.0.30 → 0.2.0

package/dist/utilities/http/http.utility.js

@@ -0,0 +1,98 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { TransactionError } from '../../errors/index.js';
+/**
+ * The one place octo speaks HTTP.
+ *
+ * A response is handed back whatever its status, so the caller decides what a refusal means instead
+ * of catching one. Only a request that never reached a server throws.
+ *
+ * @internal
+ */
+export class HttpUtility {
+    /**
+     * Downloads `url` into `filePath`, streaming it so its size is not bounded by memory. False when the
+     * server refused it or the download was cut short, which can leave part of the file behind.
+     *
+     * @internal
+     * @throws {@link TransactionError} When the host could not be reached at all.
+     */
+    static async downloadToFile(url, filePath) {
+        const response = await this.send(url);
+        if (!response.ok || !response.body) {
+            return false;
+        }
+        try {
+            await pipeline(Readable.fromWeb(response.body), createWriteStream(filePath));
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * What a refused request said went wrong, as one line. A service that answers a list - a failed
+     * validation usually does - is read as a sentence, and a body that is not JSON as its status.
+     *
+     * @internal
+     */
+    static async readErrorMessage(response) {
+        let body;
+        try {
+            body = (await response.json());
+        }
+        catch (error) {
+            return `${response.status} ${response.statusText}`;
+        }
+        const message = Array.isArray(body.message) ? body.message.join(', ') : body.message;
+        return message || `${response.status} ${response.statusText}`;
+    }
+    /**
+     * A body may be a stream, which is sent as it is read rather than held in memory. A stream's length
+     * is unknown to fetch, so a server that needs one is given `Content-Length` in `headers`.
+     *
+     * @internal
+     * @throws {@link TransactionError} When the host could not be reached at all, which is a different
+     * thing from being refused by it and is the caller's to report differently.
+     */
+    static async send(url, { body, headers = {}, method = 'GET' } = {}) {
+        try {
+            // `duplex` is what lets the body be a stream; Node's fetch refuses one without it.
+            return await fetch(url, { body, duplex: 'half', headers, method });
+        }
+        catch (error) {
+            throw new TransactionError(`Cannot reach "${new URL(url).origin}"!`);
+        }
+    }
+    /**
+     * {@link HttpUtility.send} with a JSON body, which is every request octo makes that carries one
+     * other than an upload.
+     *
+     * @internal
+     */
+    static async sendJson(url, { body, headers = {}, method = 'GET' } = {}) {
+        return this.send(url, {
+            body: body === undefined ? undefined : JSON.stringify(body),
+            headers: { ...headers, 'Content-Type': 'application/json' },
+            method,
+        });
+    }
+    /**
+     * PUTs the file at `filePath` to `url`, streaming it so its size is not bounded by memory, with its
+     * `Content-Length`, which a presigned URL is usually signed with.
+     *
+     * @internal
+     * @throws {@link TransactionError} When the host could not be reached at all.
+     */
+    static async uploadFile(url, filePath, headers = {}) {
+        const { size } = await stat(filePath);
+        return this.send(url, {
+            body: Readable.toWeb(createReadStream(filePath)),
+            headers: { ...headers, 'Content-Length': String(size) },
+            method: 'PUT',
+        });
+    }
+}
+//# sourceMappingURL=http.utility.js.map

package/dist/utilities/http/http.utility.js.map

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

package/dist/utilities/node/node.utility.d.ts

@@ -3,5 +3,8 @@ import type { UnknownResource } from '../../app.type.js';
  * @internal
  */
 export declare class NodeUtility {
+    /**
+     * @internal
+     */
     static sortResourcesByDependency(resources: UnknownResource[]): UnknownResource[];
 }

package/dist/utilities/node/node.utility.js

@@ -3,6 +3,9 @@ import { DiffAction } from '../../functions/diff/diff.js';
  * @internal
  */
 export class NodeUtility {
+    /**
+     * @internal
+     */
     static sortResourcesByDependency(resources) {
         const sortedResources = [];
         for (const resource of resources) {

package/dist/utilities/node/node.utility.js.map

@@ -1 +1 @@
-{"version":3,"file":"node.utility.js","sourceRoot":"","sources":["../../../src/utilities/node/node.utility.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE1D;;GAEG;AACH,MAAM,OAAO,WAAW;IACtB,MAAM,CAAC,yBAAyB,CAAC,SAA4B;QAC3D,MAAM,eAAe,GAAsB,EAAE,CAAC;QAE9C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,KAAK,GAAG,CAAC,CAAC;YAEd,MAAM,YAAY,GAAG,QAAQ,CAAC,eAAe,EAAE,CAAC;YAChD,KAAK,MAAM,UAAU,IAAI,YAAY,EAAE,CAAC;gBACtC,IAAI,UAAU,CAAC,mBAAmB,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC/F,MAAM,cAAc,GAAG,UAAU,CAAC,EAAqB,CAAC;oBACxD,MAAM,WAAW,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,cAAc,CAAC,UAAU,CAAC,CAAC;oBACjG,IAAI,WAAW,KAAK,CAAC,CAAC,EAAE,CAAC;wBACvB,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,CAAC,CAAC,CAAC;oBAC3C,CAAC;gBACH,CAAC;YACH,CAAC;YAED,eAAe,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;QAC7C,CAAC;QAED,OAAO,eAAe,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"node.utility.js","sourceRoot":"","sources":["../../../src/utilities/node/node.utility.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE1D;;GAEG;AACH,MAAM,OAAO,WAAW;IACtB;;OAEG;IACH,MAAM,CAAC,yBAAyB,CAAC,SAA4B;QAC3D,MAAM,eAAe,GAAsB,EAAE,CAAC;QAE9C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,KAAK,GAAG,CAAC,CAAC;YAEd,MAAM,YAAY,GAAG,QAAQ,CAAC,eAAe,EAAE,CAAC;YAChD,KAAK,MAAM,UAAU,IAAI,YAAY,EAAE,CAAC;gBACtC,IAAI,UAAU,CAAC,mBAAmB,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC/F,MAAM,cAAc,GAAG,UAAU,CAAC,EAAqB,CAAC;oBACxD,MAAM,WAAW,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,cAAc,CAAC,UAAU,CAAC,CAAC;oBACjG,IAAI,WAAW,KAAK,CAAC,CAAC,EAAE,CAAC;wBACvB,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,CAAC,CAAC,CAAC;oBAC3C,CAAC;gBACH,CAAC;YACH,CAAC;YAED,eAAe,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;QAC7C,CAAC;QAED,OAAO,eAAe,CAAC;IACzB,CAAC;CACF"}

package/dist/utilities/object/object.utility.d.ts

@@ -2,8 +2,20 @@
  * @internal
  */
 export declare class ObjectUtility {
+    /**
+     * @internal
+     */
     static deepFreeze<T extends object>(object: T): void;
+    /**
+     * @internal
+     */
     static deepMergeInPlace(target: object, source: object): void;
+    /**
+     * @internal
+     */
     static isPlainObject(value: unknown): value is object;
+    /**
+     * @internal
+     */
     static onEveryNestedKey(object: object, callback: (parent: object, key: string, value: unknown) => void): void;
 }

package/dist/utilities/object/object.utility.js

@@ -4,12 +4,18 @@ import { ANode } from '../../functions/node/node.abstract.js';
  */
 export class ObjectUtility {
     // Source: https://stackoverflow.com/a/58496119/1834562
+    /**
+     * @internal
+     */
     static deepFreeze(object) {
         Object.freeze(object);
         Object.values(object)
             .filter((x) => !Object.isFrozen(x))
             .forEach(ObjectUtility.deepFreeze);
     }
+    /**
+     * @internal
+     */
     static deepMergeInPlace(target, source) {
         for (const key of Object.keys(source)) {
             const sourceValue = source[key];
@@ -25,9 +31,15 @@ export class ObjectUtility {
             }
         }
     }
+    /**
+     * @internal
+     */
     static isPlainObject(value) {
         return typeof value === 'object' && value !== null && !Array.isArray(value);
     }
+    /**
+     * @internal
+     */
     static onEveryNestedKey(object, callback) {
         const keys = object instanceof ANode ? Object.keys(object.synth()) : Object.keys(object);
         for (const key of keys) {

package/dist/utilities/object/object.utility.js.map

@@ -1 +1 @@
-{"version":3,"file":"object.utility.js","sourceRoot":"","sources":["../../../src/utilities/object/object.utility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,uCAAuC,CAAC;AAE9D;;GAEG;AACH,MAAM,OAAO,aAAa;IACxB,uDAAuD;IACvD,MAAM,CAAC,UAAU,CAAmB,MAAS;QAC3C,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACtB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;aAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;aAClC,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,CAAC,gBAAgB,CAAC,MAAc,EAAE,MAAc;QACpD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACtC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAChC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAEhC,IAAI,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,CAAC;gBACvE,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YAClD,CAAC;iBAAM,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;gBACpE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,WAAW,EAAE,GAAG,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CACpG,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CACzC,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,CAAC,aAAa,CAAC,KAAc;QACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,CAAC,gBAAgB,CAAC,MAAc,EAAE,QAA+D;QACrG,MAAM,IAAI,GAAG,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;gBACtD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;gBAE1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;oBAChD,aAAa,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAClD,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"object.utility.js","sourceRoot":"","sources":["../../../src/utilities/object/object.utility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,uCAAuC,CAAC;AAE9D;;GAEG;AACH,MAAM,OAAO,aAAa;IACxB,uDAAuD;IACvD;;OAEG;IACH,MAAM,CAAC,UAAU,CAAmB,MAAS;QAC3C,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACtB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;aAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;aAClC,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,MAAc,EAAE,MAAc;QACpD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACtC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAChC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAEhC,IAAI,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,CAAC;gBACvE,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YAClD,CAAC;iBAAM,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;gBACpE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,WAAW,EAAE,GAAG,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CACpG,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CACzC,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,KAAc;QACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9E,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,MAAc,EAAE,QAA+D;QACrG,MAAM,IAAI,GAAG,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;gBACtD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;gBAE1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;oBAChD,aAAa,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAClD,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/utilities/project/project.utility.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The octo project root, for code that cannot rely on the current working directory being it.
+ *
+ * An external resource's action is the case this exists for. Octo runs it in two different places:
+ * `octo commit` runs the delete action from the project root, but terraform runs the add and update
+ * actions from a terragrunt cache directory, so a path a module resolved against the project root
+ * resolves against nothing by the time the action reads it. Octo already supplies the root to every
+ * terragrunt command as `TF_VAR_OCTO_PROJECT_ROOT`, which terraform passes down to `local-exec`;
+ * this reads it back, and falls back to the working directory for the run that has no terraform in
+ * the middle.
+ *
+ * Store a project-relative path in a resource's `properties` and resolve it here. An absolute one
+ * would put the developer's directory layout into octo state, and into the properties hash that
+ * generated terraform commits as an external resource's trigger.
+ *
+ * @group Utilities
+ */
+export declare class ProjectUtility {
+    /**
+     * The absolute path of the octo project root.
+     */
+    static getProjectRoot(): string;
+    /**
+     * Resolves a project-relative path against {@link ProjectUtility.getProjectRoot}. An absolute path
+     * is returned as given.
+     */
+    static resolveFromProjectRoot(filePath: string): string;
+}

package/dist/utilities/project/project.utility.js

@@ -0,0 +1,35 @@
+import { isAbsolute, resolve } from 'node:path';
+import { PROJECT_ROOT_VARIABLE_NAME } from '../../services/terraform/terraform.type.js';
+/**
+ * The octo project root, for code that cannot rely on the current working directory being it.
+ *
+ * An external resource's action is the case this exists for. Octo runs it in two different places:
+ * `octo commit` runs the delete action from the project root, but terraform runs the add and update
+ * actions from a terragrunt cache directory, so a path a module resolved against the project root
+ * resolves against nothing by the time the action reads it. Octo already supplies the root to every
+ * terragrunt command as `TF_VAR_OCTO_PROJECT_ROOT`, which terraform passes down to `local-exec`;
+ * this reads it back, and falls back to the working directory for the run that has no terraform in
+ * the middle.
+ *
+ * Store a project-relative path in a resource's `properties` and resolve it here. An absolute one
+ * would put the developer's directory layout into octo state, and into the properties hash that
+ * generated terraform commits as an external resource's trigger.
+ *
+ * @group Utilities
+ */
+export class ProjectUtility {
+    /**
+     * The absolute path of the octo project root.
+     */
+    static getProjectRoot() {
+        return process.env[`TF_VAR_${PROJECT_ROOT_VARIABLE_NAME}`] || process.cwd();
+    }
+    /**
+     * Resolves a project-relative path against {@link ProjectUtility.getProjectRoot}. An absolute path
+     * is returned as given.
+     */
+    static resolveFromProjectRoot(filePath) {
+        return isAbsolute(filePath) ? filePath : resolve(this.getProjectRoot(), filePath);
+    }
+}
+//# sourceMappingURL=project.utility.js.map

package/dist/utilities/project/project.utility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.utility.js","sourceRoot":"","sources":["../../../src/utilities/project/project.utility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,0BAA0B,EAAE,MAAM,4CAA4C,CAAC;AAExF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,cAAc;IACzB;;OAEG;IACH,MAAM,CAAC,cAAc;QACnB,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,0BAA0B,EAAE,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC9E,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,sBAAsB,CAAC,QAAgB;QAC5C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,QAAQ,CAAC,CAAC;IACpF,CAAC;CACF"}

package/dist/utilities/string/string.utility.d.ts

@@ -0,0 +1,41 @@
+/**
+ * String helpers for module and resource authors: hashing values into stable ids, fitting names into
+ * a provider's length limit, and making names safe for terraform.
+ *
+ * @group Utilities/String
+ */
+export declare class StringUtility {
+    /**
+     * Shortens a name to at most `maxLength` characters, replacing what is cut with a digest of the whole
+     * name. Two names that differ anywhere still differ after shortening, and the same name always
+     * shortens the same way. A name already within the limit is returned as it is.
+     *
+     * Use it where a provider limits a name that is built by joining others, e.g. a distribution name and
+     * an origin id, so that cutting the tail alone could make two names collide.
+     *
+     * @example
+     * ```ts
+     * StringUtility.boundedName('my-distribution-with-a-very-long-origin-id', 20);
+     * // The first 11 characters, a dash and 8 hex characters: 20 in all.
+     * ```
+     */
+    static boundedName(name: string, maxLength: number): string;
+    /**
+     * Produces a 16-character hex hash of any value, with object keys sorted recursively, so the hash
+     * does not change when key insertion order does. Hash several parts as an array,
+     * `deterministicHash([bucketName, accessPrefix])`, which keeps `['ab', 'c']` and `['a', 'bc']` apart.
+     * Take a prefix of it where a shorter id is enough.
+     */
+    static deterministicHash(value: unknown): string;
+    /**
+     * Replaces every character that is not a letter, digit, or underscore with an underscore.
+     * Suitable for names that travel through environment variables (e.g. terraform variables,
+     * which terragrunt passes as `TF_VAR_<name>`), where dashes are not allowed.
+     */
+    static sanitizeForEnvironmentVariable(value: string): string;
+    /**
+     * Replaces every character that is not a letter, digit, underscore, or dash with an underscore.
+     * Suitable for terraform identifiers (resource names, output names), which allow dashes.
+     */
+    static sanitizeForIdentifier(value: string): string;
+}

package/dist/utilities/string/string.utility.js

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+/**
+ * String helpers for module and resource authors: hashing values into stable ids, fitting names into
+ * a provider's length limit, and making names safe for terraform.
+ *
+ * @group Utilities/String
+ */
+export class StringUtility {
+    /**
+     * Shortens a name to at most `maxLength` characters, replacing what is cut with a digest of the whole
+     * name. Two names that differ anywhere still differ after shortening, and the same name always
+     * shortens the same way. A name already within the limit is returned as it is.
+     *
+     * Use it where a provider limits a name that is built by joining others, e.g. a distribution name and
+     * an origin id, so that cutting the tail alone could make two names collide.
+     *
+     * @example
+     * ```ts
+     * StringUtility.boundedName('my-distribution-with-a-very-long-origin-id', 20);
+     * // The first 11 characters, a dash and 8 hex characters: 20 in all.
+     * ```
+     */
+    static boundedName(name, maxLength) {
+        if (name.length <= maxLength) {
+            return name;
+        }
+        const digest = StringUtility.deterministicHash(name).substring(0, 8);
+        return `${name.substring(0, maxLength - digest.length - 1)}-${digest}`;
+    }
+    /**
+     * Produces a 16-character hex hash of any value, with object keys sorted recursively, so the hash
+     * does not change when key insertion order does. Hash several parts as an array,
+     * `deterministicHash([bucketName, accessPrefix])`, which keeps `['ab', 'c']` and `['a', 'bc']` apart.
+     * Take a prefix of it where a shorter id is enough.
+     */
+    static deterministicHash(value) {
+        const stableStringify = (v) => {
+            if (v === null || typeof v !== 'object') {
+                return JSON.stringify(v);
+            }
+            if (Array.isArray(v)) {
+                return `[${v.map(stableStringify).join(',')}]`;
+            }
+            const keys = Object.keys(v).sort();
+            return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`).join(',')}}`;
+        };
+        return createHash('sha256').update(stableStringify(value)).digest('hex').substring(0, 16);
+    }
+    /**
+     * Replaces every character that is not a letter, digit, or underscore with an underscore.
+     * Suitable for names that travel through environment variables (e.g. terraform variables,
+     * which terragrunt passes as `TF_VAR_<name>`), where dashes are not allowed.
+     */
+    static sanitizeForEnvironmentVariable(value) {
+        return value.replace(/[^a-zA-Z0-9_]/g, '_');
+    }
+    /**
+     * Replaces every character that is not a letter, digit, underscore, or dash with an underscore.
+     * Suitable for terraform identifiers (resource names, output names), which allow dashes.
+     */
+    static sanitizeForIdentifier(value) {
+        return value.replace(/[^a-zA-Z0-9_-]/g, '_');
+    }
+}
+//# sourceMappingURL=string.utility.js.map

package/dist/utilities/string/string.utility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.utility.js","sourceRoot":"","sources":["../../../src/utilities/string/string.utility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACxB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,WAAW,CAAC,IAAY,EAAE,SAAiB;QAChD,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,MAAM,GAAG,aAAa,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrE,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;IACzE,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAc;QACrC,MAAM,eAAe,GAAG,CAAC,CAAU,EAAU,EAAE;YAC7C,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACxC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAC3B,CAAC;YACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrB,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YACjD,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAA4B,CAAC,CAAC,IAAI,EAAE,CAAC;YAC9D,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,eAAe,CAAE,CAA6B,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QACxH,CAAC,CAAC;QACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,8BAA8B,CAAC,KAAa;QACjD,OAAO,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAa;QACxC,OAAO,KAAK,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IAC/C,CAAC;CACF"}

package/dist/utilities/terraform/terraform.utility.d.ts

@@ -0,0 +1,276 @@
+import type { TerraformOutputs } from '../../modes/commit.mode.js';
+import type { TerraformPlan } from '../../modes/validate.mode.js';
+interface TerraformRawResult {
+    readonly args: string[];
+    readonly exitCode: number;
+}
+/**
+ * The result of planning every module folder under a terragrunt directory.
+ *
+ * A folder appears in exactly one of the two maps: in `plans` when terraform produced a plan, or in
+ * `errors` with the reason it could not. Both are keyed by the folder name, i.e. the octo `moduleId`.
+ * `errors` is what lets `validate` say why a folder could not be inspected.
+ */
+interface TerraformPlanResult {
+    errors: Map<string, string>;
+    plans: Map<string, TerraformPlan>;
+}
+/**
+ * Octo's single interface to the terraform and terragrunt binaries.
+ *
+ * {@link Octo.generate} writes module folders; this runs them, and turns their output back into the
+ * shapes the other modes expect - `plan(dir, { json: true })` feeds {@link Octo.validate}, and
+ * `output(dir, { json: true })` feeds {@link Octo.commit}. Routing every invocation through one class
+ * is what keeps flags, timeouts, and event emission consistent.
+ *
+ * Resolve it from the {@link Container} so that a run's terraform events reach the same listeners as
+ * everything else.
+ *
+ * @example
+ * ```ts
+ * const terraform = await Container.getInstance().get(TerraformUtility);
+ * const { errors, plans } = await terraform.plan('./infrastructure', { json: true });
+ * const report = await octo.validate(app, { errors, plans });
+ * ```
+ *
+ * @group Utilities/Terraform
+ */
+export declare class TerraformUtility {
+    /**
+     * The id of the last process any instance started, so ids never repeat within one octo process.
+     */
+    private static lastProcessId;
+    private onceArgs;
+    private readonly options;
+    /**
+     * The timeout the caller asked for, or undefined when they asked for none. A command that changes
+     * infrastructure is bounded only by this, never by the default.
+     */
+    private readonly requestedTimeoutInMs;
+    /**
+     * @param options Overrides for the binaries invoked, the per-command timeout, and the state
+     * check-in interval. `terragruntBinary` defaults to `terragrunt`.
+     *
+     * `timeoutInMs` defaults to 60 minutes for the commands that only read - `plan`, `output`, `show`.
+     * `apply` and `destroy` run unbounded unless it is given: a timeout there turns a slow apply into
+     * one killed part way through a mutation, and how long a stack legitimately takes is a fact about
+     * that stack rather than something a default can know. What bounds them instead is the caller -
+     * a CI job's own timeout, or a person at a terminal.
+     *
+     * `stateCheckInIntervalInMs` is how often terraform state is checked into the state provider while
+     * a command runs, 10 seconds by default. Terraform rewrites it as each resource completes.
+     */
+    constructor(options?: {
+        stateCheckInIntervalInMs?: number;
+        terraformBinary?: string;
+        terragruntBinary?: string;
+        timeoutInMs?: number;
+    });
+    /**
+     * Runs `terragrunt run --all -- apply` over every generated module folder.
+     *
+     * **This changes real infrastructure**, and runs with `-auto-approve`. Use
+     * {@link TerraformUtility.findPlannedDestroys} beforehand if a destroy needs confirming.
+     *
+     * @param terragruntDir The directory octo generated the module folders into.
+     */
+    apply(terragruntDir: string): Promise<TerraformRawResult>;
+    /**
+     * Runs `terragrunt run --all -- destroy` over every generated module folder.
+     *
+     * **This tears down real infrastructure**, and runs with `-auto-approve`.
+     */
+    destroy(terragruntDir: string): Promise<TerraformRawResult>;
+    /**
+     * Every address a set of plans will destroy, across all folders. A recreate (`create` + `delete`)
+     * counts, since the old object is still destroyed.
+     *
+     * Lets a caller refuse to apply until the destroys have been shown, which {@link apply} cannot do on
+     * its own because it runs with `-auto-approve`.
+     */
+    findPlannedDestroys(plans: Map<string, TerraformPlan>): {
+        address: string;
+        moduleId: string;
+        tfActions: string[];
+    }[];
+    /**
+     * Returns the immediate sub-directories of `terragruntDir` that look like generated module
+     * folders (they contain a `terragrunt.hcl`). Each folder name is the octo `moduleId`.
+     */
+    listModuleFolders(terragruntDir: string): Promise<string[]>;
+    /**
+     * Reads the outputs of every generated module folder.
+     *
+     * @param terragruntDir The directory octo generated the module folders into.
+     * @param options Pass `{ json: true }` to get the outputs parsed and keyed by `moduleId`, which is
+     * the shape {@link Octo.commit} takes. Without it, terragrunt's output goes out only as events.
+     */
+    output(terragruntDir: string, options: {
+        json: true;
+    }): Promise<Map<string, TerraformOutputs>>;
+    /**
+     * @internal
+     */
+    output(terragruntDir: string, options?: {
+        json?: false;
+    }): Promise<TerraformRawResult>;
+    /**
+     * Plans every generated module folder.
+     *
+     * @param terragruntDir The directory octo generated the module folders into.
+     * @param options Pass `{ json: true }` to get the plans parsed and keyed by `moduleId`, which is
+     * the shape {@link Octo.validate} takes - along with the `errors` of any folder that could not be
+     * planned. Without it, terragrunt's output goes out only as events.
+     */
+    plan(terragruntDir: string, options: {
+        json: true;
+    }): Promise<TerraformPlanResult>;
+    /**
+     * @internal
+     */
+    plan(terragruntDir: string, options?: {
+        json?: false;
+    }): Promise<TerraformRawResult>;
+    /**
+     * To append extra CLI arguments to the *next* command only. Returns `this`, so it chains.
+     */
+    setArgsOnce(args: string[]): this;
+    /**
+     * Runs `terragrunt run --all -- validate` over every generated module folder, checking the generated
+     * HCL is well-formed. Unrelated to {@link Octo.validate}, which compares plans against intent.
+     */
+    validate(terragruntDir: string): Promise<TerraformRawResult>;
+    /**
+     * Runs `file` with `args`, handing each chunk it writes to `onChunk` as it arrives. Keeps its whole
+     * stdout only when `keepStdout` asks for it, and the last {@link STDERR_TAIL_LENGTH} characters of its
+     * stderr, so a process writing for an hour holds no more memory than one writing for a second.
+     */
+    protected spawnAsync(file: string, args: string[], options: {
+        cwd?: string;
+        env: NodeJS.ProcessEnv;
+        keepStdout: boolean;
+        timeout?: number;
+    }, onChunk: (text: string, stream: 'stderr' | 'stdout') => void): Promise<{
+        stderr: string;
+        stdout: string;
+    }>;
+    /**
+     * The environment a terragrunt command runs with, carrying the terraform binary override.
+     */
+    private buildEnv;
+    /**
+     * Takes the arguments set by {@link TerraformUtility.setArgsOnce}, clearing them.
+     */
+    private consumeArgs;
+    /**
+     * Renders why one folder could not be planned.
+     *
+     * Terragrunt writes its diagnostics to stderr, which carries the `Error:` block, so that comes
+     * first. The wrapped {@link TerraformCommandError} message is the fallback for failures that
+     * produce no stderr, such as a malformed `show -json` payload failing at `JSON.parse`.
+     */
+    private describePlanFailure;
+    /**
+     * Publishes the same started/finished pair {@link runAll} does, around a body that drives
+     * terragrunt folder by folder instead.
+     *
+     * The JSON-mode `plan` and `output` take that per-folder path, and it is the slowest step of a
+     * `validate` - a full plan runs for tens of seconds - so the log must not fall silent through it.
+     */
+    private emitAround;
+    /**
+     * The `terragrunt run --all` invocation itself, wrapped in its started/finished pair.
+     */
+    private invokeRunAll;
+    /**
+     * Moves the terraform state of every move the last generate recorded out of its old module folder
+     * into its new one, with `terraform state mv`, and copies the moved resources' outputs along, since
+     * folders depending on the new one read them there. An address the old folder's state does not hold,
+     * or the new one's already holds, is skipped, which is what a move already made leaves behind.
+     * Records in `originalStates` what each state file held before its first move, `undefined` where none
+     * existed.
+     */
+    private moveStates;
+    /**
+     * Runs `terragrunt output -json` in one module folder.
+     *
+     * A folder whose output fails is reported as `undefined`, not thrown — one bad module folder must not
+     * abort every other folder's result.
+     */
+    private readOutputs;
+    /**
+     * Runs `terragrunt plan -out=<planFile>` followed by `terragrunt show -json <planFile>` in one module folder.
+     *
+     * The plan file is written to an absolute temp path, never inside a terragrunt
+     * cache — terragrunt picks a different cache sub-directory per invocation, so a relative plan file
+     * written by one command cannot be found by the next.
+     *
+     * A folder whose plan/show/parse fails is reported as an `error`, not thrown — one bad module folder must not
+     * abort every other folder's result. The failure is carried so `validate` can report it verbatim.
+     */
+    private readPlan;
+    /**
+     * The directory with every symbolic link on its path resolved, or the directory as given when it does
+     * not exist. Terragrunt drops `dependency` blocks when its working directory is reached through a
+     * symbolic link, as macOS's temporary directory is.
+     */
+    private resolveRealPath;
+    /**
+     * Writes back what each state file held before {@link TerraformUtility.moveStates}, deleting one that
+     * did not exist.
+     */
+    private restoreStates;
+    /**
+     * Runs one terragrunt command in a single module folder (`cwd` = that folder).
+     */
+    private run;
+    /**
+     * Runs `terragrunt run --all -- <command>` across every module folder under `terragruntDir`, with
+     * the terraform state of every folder checked out around it.
+     */
+    private runAll;
+    /**
+     * Runs `binary` with `args` in `dir`. Its stdout is returned only when it is asked for JSON, which is
+     * the output octo reads; every other process's output goes out only as events.
+     */
+    private runIn;
+    /**
+     * Runs one process. Every terraform and terragrunt process octo starts goes through here, and goes out
+     * as events: a {@link TerraformProcessStartedEvent}, a {@link TerraformProcessOutputEvent} for each
+     * chunk it writes, and a {@link TerraformProcessExitedEvent}, all named after `command`.
+     *
+     * @throws {@link TerraformCommandError} When the process cannot start or exits non-zero.
+     */
+    private runProcess;
+    /**
+     * Wraps whatever a failed spawn threw into a {@link TerraformCommandError}.
+     */
+    private toTerraformCommandError;
+    /**
+     * Checks every module folder's terraform state out of Octo's state provider, moves the state of every
+     * resource generate moved between folders, runs `body`, and checks the state back in.
+     *
+     * Only a command that changes infrastructure (`keepMoves`) checks the moves in. Any other runs on them
+     * and puts back what the state files held before, so a move nobody applied never reaches the provider.
+     *
+     * The check-in runs on the way out of a failure as much as a success, because what terraform has
+     * already built is real whether or not the command that built it returned cleanly. A timer checks
+     * in through the command as well, bounding what a killed runner loses.
+     *
+     * A failed command keeps its own error when the check-in after it fails too; the check-in's error
+     * is printed on stderr. The folder's state is ahead of the provider's then, and the next run keeps
+     * it and checks it in.
+     */
+    private withTerraformState;
+}
+/**
+ * @internal
+ */
+export declare class TerraformUtilityFactory {
+    private static instance;
+    /**
+     * @internal
+     */
+    static create(options?: ConstructorParameters<typeof TerraformUtility>[0], forceNew?: boolean): Promise<TerraformUtility>;
+}
+export {};