@quadnix/octo 0.0.29 → 0.1.0

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,21 @@
+/**
+ * @internal
+ */
+export declare class StringUtility {
+    /**
+     * Produces a short deterministic hash of a value, with object keys sorted recursively,
+     * so the hash does not change when key insertion order does.
+     */
+    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,39 @@
+import { createHash } from 'node:crypto';
+/**
+ * @internal
+ */
+export class StringUtility {
+    /**
+     * Produces a short deterministic hash of a value, with object keys sorted recursively,
+     * so the hash does not change when key insertion order does.
+     */
+    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;;GAEG;AACH,MAAM,OAAO,aAAa;IACxB;;;OAGG;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,227 @@
+import { type ExecFileOptionsWithStringEncoding } from 'node:child_process';
+import type { TerraformOutputs } from '../../modes/commit.mode.js';
+import type { TerraformPlan } from '../../modes/validate.mode.js';
+interface TerraformRawResult {
+    readonly args: string[];
+    readonly exitCode: number;
+    readonly stderr: string;
+    readonly stdout: string;
+}
+/**
+ * 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 {
+    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 and the per-command timeout. `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.
+     */
+    constructor(options?: {
+        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 onOutput Called with each chunk terragrunt writes, as it writes it. An apply can run for
+     * tens of minutes, and the buffered result only arrives at the end - without this the caller has
+     * nothing to show for the whole run. The chunks are also still accumulated into the result.
+     */
+    apply(terragruntDir: string, { onOutput }?: {
+        onOutput?: (chunk: string, stream: 'stderr' | 'stdout') => void;
+    }): 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 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 raw output is returned.
+     */
+    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 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 raw output is returned.
+     */
+    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>;
+    /**
+     * @param onOutput Receives each chunk as the child writes it. `execFile` keeps accumulating into
+     * its own buffers regardless, so the resolved result is unchanged whether or not this is passed.
+     */
+    protected execFileAsync(file: string, args: string[], options: ExecFileOptionsWithStringEncoding, onOutput?: (chunk: 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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, runs `body`, and
+     * checks it back in.
+     *
+     * 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.
+     */
+    private withTerraformState;
+}
+/**
+ * @internal
+ */
+export declare class TerraformUtilityFactory {
+    private static instance;
+    /**
+     * @internal
+     */
+    static create(options?: ConstructorParameters<typeof TerraformUtility>[0], forceNew?: boolean): Promise<TerraformUtility>;
+}
+export {};