@quadnix/octo 0.0.30 → 0.1.0

package/dist/services/terraform/terraform.service.js

@@ -0,0 +1,995 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { relative, resolve, sep } from 'node:path';
+import { MatchingResource, } from '../../app.type.js';
+import { Factory } from '../../decorators/factory.decorator.js';
+import { getSchemaDefaults } from '../../functions/schema/schema.js';
+import { StringUtility } from '../../utilities/string/string.utility.js';
+import { ExpressionHclNode, HclExpression, InterpolatedStringHclNode, JsonEncodeHclNode, LiteralHclNode, MapHclNode, MapHclNodeRaw, PROJECT_ROOT_VARIABLE_NAME, RefHclNode, TerraformBlock, TerraformData, TerraformOutput, TerraformResource, TerraformVariable, TypeHclNode, toHclNode, } from './terraform.type.js';
+/**
+ * Expands an author-provided spec object into attributes and blocks on `target`:
+ */
+function addTerraformResourceSpec(target, spec) {
+    for (const [key, value] of Object.entries(spec)) {
+        if (value instanceof HclExpression) {
+            target.attribute(key, value);
+        }
+        else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            addTerraformResourceSpec(target.block(key), value);
+        }
+        else if (Array.isArray(value) &&
+            value.every((v) => v !== null && typeof v === 'object' && !Array.isArray(v) && !(v instanceof HclExpression))) {
+            for (const item of value) {
+                addTerraformResourceSpec(target.block(key), item);
+            }
+        }
+        else {
+            target.attribute(key, value);
+        }
+    }
+}
+/**
+ * Full implementation of {@link OctoTerraformResourceScope}. Holds all the internal state
+ * that {@link TerraformService} reads during the wiring and render phases.
+ *
+ * The `outputs` map is the resource's answer sheet:
+ * - key is the resource's response key that other resources use for referencing.
+ * - name is the `${resourceId}-${key}` output name it is published under.
+ * - value is the terraform expression that produces the value.
+ */
+class OctoTerraformResource {
+    /**
+     * @internal
+     */
+    constructor(resourceId, resourceContext, moduleId, explicitParentResourceIds = [], providerRef, // Fully-qualified provider reference (`aws._111111111-us-east-1`).
+    externalResultExpression, // External resource marker with `data.external.<name>.result` value.
+    responseDefaults = {}) {
+        this.resourceId = resourceId;
+        this.resourceContext = resourceContext;
+        this.moduleId = moduleId;
+        this.explicitParentResourceIds = explicitParentResourceIds;
+        this.providerRef = providerRef;
+        this.externalResultExpression = externalResultExpression;
+        this.responseDefaults = responseDefaults;
+        this.outputs = new Map();
+        this.terraformResources = [];
+        // When an external script, publish the whole-result map as one output, keyed only by resource id, no output key.
+        if (externalResultExpression !== undefined) {
+            this.outputs.set(resourceId, {
+                name: StringUtility.sanitizeForIdentifier(resourceId),
+                sensitive: false,
+                value: new ExpressionHclNode(externalResultExpression),
+            });
+        }
+    }
+    addTerraformResource(type, name, spec = {}) {
+        const intraResourceDependencies = this.terraformResources.length === 0 ? [] : [this.terraformResources[this.terraformResources.length - 1].address];
+        const terraformResource = new TerraformResource(type, StringUtility.sanitizeForIdentifier(name), intraResourceDependencies);
+        if (this.providerRef && !('provider' in spec)) {
+            terraformResource.attribute('provider', new ExpressionHclNode(this.providerRef));
+        }
+        addTerraformResourceSpec(terraformResource, spec);
+        this.terraformResources.push(terraformResource);
+        return terraformResource;
+    }
+    /**
+     * @internal
+     */
+    collectRefs(into) {
+        this.terraformResources.forEach((r) => r.collectRefs(into));
+        this.outputs.forEach((o) => o.value.collectRefs(into));
+    }
+    output(outputs, options = {}) {
+        const sensitiveKeys = new Set(options.sensitiveKeys ?? []);
+        for (const [key, value] of Object.entries(outputs)) {
+            this.outputs.set(key, {
+                name: StringUtility.sanitizeForIdentifier(`${this.resourceId}-${key}`),
+                sensitive: sensitiveKeys.has(key),
+                value: toHclNode(value),
+            });
+        }
+    }
+}
+/**
+ * Everything that renders into one terragrunt module folder.
+ */
+class TerraformModule {
+    /**
+     * @internal
+     */
+    constructor(moduleId) {
+        this.moduleId = moduleId;
+        this.dataSources = [];
+        this.hasExternalResources = false; // True when folder has external resources requiring null/external configs.
+        this.needsProjectRoot = false; // True when a resource named a local file, requiring the project root variable.
+        this.providerKeys = new Set(); // Specific providers this folder's resources require.
+        this.resources = [];
+        this.variables = [];
+    }
+}
+/**
+ * Terraform providers that take no `region` argument - the hashicorp utility providers, which take
+ * no provider arguments at all. Writing one onto their block fails the plan. Regional providers
+ * (`aws`, `google`, and the rest) are not listed: they keep the `region` they have always been
+ * given, and anything unlisted that does not want one can pass `setRegionAttribute: false`.
+ */
+const REGIONLESS_PROVIDER_TYPES = new Set(['archive', 'external', 'local', 'null', 'random', 'template', 'time']);
+/**
+ * Provider types that can be told which account they are allowed to authenticate as. Only `aws`
+ * spells it `allowed_account_ids`; the equivalent everywhere else is a different word for a
+ * different thing - google scopes to a project, azure to a subscription - so nothing else is listed.
+ */
+const ACCOUNT_GUARDED_PROVIDER_TYPES = new Set(['aws']);
+/**
+ * Collects what every resource emitted through {@link TerraformModuleScope}, wires the references
+ * between module folders, and renders the terragrunt files {@link Octo.generate} writes.
+ *
+ * @internal
+ */
+export class TerraformService {
+    /**
+     * @internal
+     */
+    get step() {
+        return ' '.repeat(this.indentLength);
+    }
+    /**
+     * @internal
+     */
+    constructor(octoCommandPrefix = 'octo', indentLength = 2) {
+        this.octoCommandPrefix = octoCommandPrefix;
+        this.indentLength = indentLength;
+        this.minTerraformVersion = '1.6.0';
+        this.modules = new Map();
+        this.pendingExternalResourcesInputWiring = [];
+        this.providers = new Map(); // TF provider blocks.
+        this.requiredProviders = {}; // TF config block.
+        this.resourceRegistry = new Map();
+        this.sanitizedResourceIds = new Map(); // Sanitized id -> original id.
+    }
+    /**
+     * Sets the minimum terraform version and the `required_providers` sources/versions that render
+     * into every folder's config block (scoped to the providers each folder actually uses).
+     */
+    addTerraformConfig({ minTerraformVersion = '1.6.0', providers = {}, } = {}) {
+        this.minTerraformVersion = minTerraformVersion;
+        this.requiredProviders = { ...this.requiredProviders, ...providers };
+    }
+    /**
+     * Registers a Terraform provider block for the given provider type, account, and region.
+     *
+     * An `aws` provider is also given `allowed_account_ids = [accountId]`, so terraform refuses at plan
+     * when the credentials it resolves belong to another account. It is omitted when `accountName` is
+     * set (the repository has asked for the id not to appear in committed terraform), when `spec`
+     * already carries `allowed_account_ids`, and when `spec` sets `skip_requesting_account_id`, which
+     * stops the provider learning the account there is to check.
+     *
+     * @param providerType - The terraform provider type, e.g. `aws`, `google`.
+     * @param accountId - The account/project/subscription ID.
+     * @param regionId - The region ID.
+     * @param spec - Provider arguments beyond `alias` and `region`.
+     *   - Primitives become attributes (`key = value`).
+     *   - Plain objects become blocks (`key { }`).
+     *   - Wrap with `mapAttr()` when the provider schema expects a map attribute (`key = { }`).
+     * @param options - optional provider configurations.
+     *   - options.accountName - What to call the account in the provider alias, in place of its id.
+     *   `prod` renders `aws.prod-us-east-1` where the id renders `aws._123456789012-us-east-1`. Two
+     *   accounts may not share a name within one provider type and region, and the generated terraform
+     *   is committed, so a name is also how a repository keeps its account number out of it. It also
+     *   drops the `allowed_account_ids` guard above, which would put that id straight back.
+     *   - options.setRegionAttribute - Whether to write `region = <regionId>` onto the provider block.
+     *   Defaults to true, except for the utility providers in {@link REGIONLESS_PROVIDER_TYPES}, which
+     *   accept no arguments at all and fail the plan outright with
+     *   `An argument named "region" is not expected here`. Set it explicitly to override either way -
+     *   a regional provider this list does not know about still needs `false` passed by hand.
+     */
+    addTerraformProvider(providerType, accountId, regionId, spec = {}, { accountName, setRegionAttribute } = {}) {
+        if (!(providerType in this.requiredProviders)) {
+            throw new Error(`Provider type "${providerType}" is not configured! Call registerTerraformConfig() with a "${providerType}" entry before registering providers.`);
+        }
+        // Terraform identifiers (here, the provider alias) must start with a letter or underscore.
+        const sanitizedAlias = StringUtility.sanitizeForIdentifier(`${accountName ?? accountId}-${regionId}`);
+        const alias = /^[0-9]/.test(sanitizedAlias) ? `_${sanitizedAlias}` : sanitizedAlias;
+        const key = this.providerKey(providerType, accountId, regionId);
+        if (!this.providers.has(key)) {
+            // A name is the caller's to pick, so two accounts can collide on one where two ids cannot.
+            const taken = [...this.providers.values()].find((provider) => provider.providerType === providerType && provider.alias === alias);
+            if (taken) {
+                throw new Error(`Terraform provider alias "${alias}" is already taken by account "${taken.accountId}"! Give one of them a different accountName.`);
+            }
+            const block = new TerraformBlock(`provider "${providerType}"`);
+            block.attribute('alias', alias);
+            if (setRegionAttribute ?? !REGIONLESS_PROVIDER_TYPES.has(providerType)) {
+                block.attribute('region', regionId);
+            }
+            // Bind the provider to the account the definition names. `accountId` is otherwise only a label
+            // octo builds the alias from: terraform authenticates from the ambient credential chain, so a
+            // profile naming another account plans green and applies into it. This is the one form of the
+            // check that runs on the chain terraform applies with, and it fails at plan.
+            if (ACCOUNT_GUARDED_PROVIDER_TYPES.has(providerType) &&
+                accountName === undefined &&
+                !('allowed_account_ids' in spec) &&
+                !spec['skip_requesting_account_id']) {
+                block.attribute('allowed_account_ids', [accountId]);
+            }
+            addTerraformResourceSpec(block, spec);
+            this.providers.set(key, { accountId, alias, block, providerType, regionId });
+        }
+    }
+    /**
+     * Returns the folder record of the current sweep: one entry per folder-bearing module — a
+     * preloaded shell the sweep left empty is an emptied folder, not folder-bearing, so it drops out
+     * of the record. Call after the sweep has contributed every resource (the same point
+     * {@link renderAllModules} is valid).
+     */
+    getFolderRecords() {
+        // Provider blocks are registration-time constants; a resource reference inside one is invalid.
+        const context = {
+            resolveRef: () => {
+                throw new Error('Resource references are not supported in provider blocks!');
+            },
+            step: this.step,
+        };
+        return [...this.modules.values()]
+            .filter((module) => module.resources.length > 0)
+            .map((module) => ({
+            hasExternalResources: module.hasExternalResources,
+            moduleId: module.moduleId,
+            providers: [...module.providerKeys].sort().map((key) => {
+                const provider = this.providers.get(key);
+                return {
+                    accountId: provider.accountId,
+                    blockHcl: provider.block.render('', context),
+                    providerType: provider.providerType,
+                    regionId: provider.regionId,
+                    requiredProvider: this.requiredProviders[provider.providerType],
+                };
+            }),
+        }));
+    }
+    /**
+     * The IDs of the module folders this run rendered.
+     */
+    getModuleIds() {
+        return [...this.modules.keys()];
+    }
+    /**
+     * How each octo resource maps into terraform, which validate and commit read to match a plan
+     * entry or an output back to the resource that produced it.
+     */
+    getOctoTerraformResourceMappings() {
+        return [...this.resourceRegistry.values()].map((r) => {
+            const isExternal = r.externalResultExpression !== undefined;
+            return {
+                entireResponseOutput: isExternal ? r.outputs.get(r.resourceId).name : undefined,
+                moduleId: r.moduleId,
+                outputMappings: isExternal ? [] : [...r.outputs.entries()].map(([key, o]) => ({ key, outputName: o.name })),
+                resourceContext: r.resourceContext,
+                resourceId: r.resourceId,
+                terraformAddresses: r.terraformResources.map((t) => t.address),
+            };
+        });
+    }
+    /**
+     * Resource→resource value-reference edges, keyed by the referenced (producer) resourceId → the set
+     * of resourceIds that reference it. Edges follow `getRef` value references only — the same graph
+     * terraform cascades replacement along (force-new). `depends_on`/explicit parents are excluded:
+     * an ordering edge carries no value and does not force a dependent's replacement.
+     *
+     * Used by validate to attribute terraform's transitive replacement cascade: when octo replaces a
+     * resource, terraform recreates everything that (transitively) references it, so those changes are
+     * expected rather than unattributed.
+     */
+    getResourceReferrers() {
+        const referrers = new Map();
+        const addEdge = (referentId, referrerId) => {
+            if (referentId === referrerId) {
+                return;
+            }
+            if (!referrers.has(referentId)) {
+                referrers.set(referentId, new Set());
+            }
+            referrers.get(referentId).add(referrerId);
+        };
+        for (const resource of this.resourceRegistry.values()) {
+            const refs = [];
+            resource.collectRefs(refs);
+            for (const ref of refs) {
+                addEdge(ref.resourceId, resource.resourceId);
+            }
+            // An external resource consumes each parent's outputs as inputs — its null_resource triggers
+            // embed the parent's values, so a parent replace recreates it. That is a true value edge, even
+            // though it is recorded as an explicit parent (and its trigger refs are wired only at render
+            // time, so they are not yet in `collectRefs` here).
+            if (resource.externalResultExpression !== undefined) {
+                for (const parentResourceId of resource.explicitParentResourceIds) {
+                    addEdge(parentResourceId, resource.resourceId);
+                }
+            }
+        }
+        return referrers;
+    }
+    /**
+     * Phase 2 of rendering: prints the four files of every folder from the wiring computed in
+     * phase 1. Makes no decisions — when a {@link RefHclNode} renders, its answer is looked up in the
+     * folder's precomputed `resolvedRefs`. Cross-folder dependency cycles throw (in phase 1).
+     */
+    renderAllModules() {
+        const wiring = this.computeWiring();
+        const result = new Map();
+        for (const module of this.modules.values()) {
+            const moduleWiring = wiring.get(module.moduleId);
+            const context = {
+                resolveRef: (ref) => moduleWiring.resolvedRefs.get(`${ref.resourceId}.${ref.key}`),
+                step: this.step,
+            };
+            // main.tf: terraform config, provider blocks, data sources, resources.
+            const requiredProviders = {};
+            for (const key of module.providerKeys) {
+                const providerType = this.providers.get(key).providerType;
+                requiredProviders[providerType] = this.requiredProviders[providerType];
+            }
+            if (module.hasExternalResources) {
+                requiredProviders['null'] = this.requiredProviders['null'] ?? { source: 'hashicorp/null' };
+                requiredProviders['external'] = this.requiredProviders['external'] ?? { source: 'hashicorp/external' };
+            }
+            const mainTf = [
+                this.renderConfigBlock(requiredProviders, context),
+                ...[...module.providerKeys].sort().map((key) => this.providers.get(key).block.render('', context)),
+                ...module.dataSources.map((d) => d.render(context)),
+                ...module.resources.map((r) => r.terraformResources.map((t) => t.render(context, moduleWiring.parentDependsOn.get(r) ?? [])).join('\n\n')),
+            ]
+                .filter(Boolean)
+                .join('\n\n');
+            // variables.tf: auto variables from cross-module refs, then user variables. An external
+            // producer's variable carries its entire response object (consumed as `var.<name>.<key>`), so it
+            // must be typed `map(string)` — terraform's external-data contract — otherwise an un-typed variable
+            // coerces the object to a JSON string and `var.<name>.<key>` fails at plan/apply. Per-key scalar
+            // variables stay un-typed.
+            const variablesTf = [
+                ...(module.needsProjectRoot
+                    ? [`variable "${PROJECT_ROOT_VARIABLE_NAME}" {\n${this.step}type = string\n}`]
+                    : []),
+                ...[...moduleWiring.autoVariables.entries()]
+                    .sort(([a], [b]) => a.localeCompare(b))
+                    .map(([name, v]) => v.objectKeys ? `variable "${name}" {\n${this.step}type = map(string)\n}` : `variable "${name}" {}`),
+                ...module.variables.map((v) => v.render(context)),
+            ]
+                .filter(Boolean)
+                .join('\n\n');
+            // outputs.tf: every resource's declared outputs.
+            const outputsTf = module.resources
+                .map((r) => [...r.outputs.values()]
+                .map((o) => new TerraformOutput(o.name, o.value, o.sensitive).render(context))
+                .join('\n\n'))
+                .filter(Boolean)
+                .join('\n\n');
+            const terragruntHcl = this.renderTerragrunt(moduleWiring);
+            result.set(module.moduleId, {
+                mainTf: mainTf + '\n',
+                outputsTf: outputsTf ? outputsTf + '\n' : '',
+                terragruntHcl: terragruntHcl + '\n',
+                variablesTf: variablesTf ? variablesTf + '\n' : '',
+            });
+        }
+        return result;
+    }
+    /**
+     * Prints the four files of an **empty** folder from a recorded folder: a `main.tf` with the
+     * config block rebuilt from the recorded `required_providers` entries (plus null/external when
+     * the folder had external resources) and the recorded provider blocks verbatim; empty
+     * variables/outputs; a remote_state-only `terragrunt.hcl`.
+     *
+     * Reads no module state;
+     * the generate mode decides which folders are emptied and which recorded folder each renders from.
+     */
+    renderEmptyModule(record) {
+        const context = {
+            resolveRef: () => {
+                throw new Error('Resource references are not supported in emptied folders!');
+            },
+            step: this.step,
+        };
+        const requiredProviders = {};
+        for (const provider of record.providers) {
+            requiredProviders[provider.providerType] = provider.requiredProvider;
+        }
+        if (record.hasExternalResources) {
+            requiredProviders['null'] = this.requiredProviders['null'] ?? { source: 'hashicorp/null' };
+            requiredProviders['external'] = this.requiredProviders['external'] ?? { source: 'hashicorp/external' };
+        }
+        const mainTf = [this.renderConfigBlock(requiredProviders, context), ...record.providers.map((p) => p.blockHcl)]
+            .filter(Boolean)
+            .join('\n\n');
+        return {
+            mainTf: mainTf + '\n',
+            outputsTf: '',
+            terragruntHcl: this.renderTerragrunt({
+                autoVariables: new Map(),
+                moduleDependencies: new Map(),
+                parentDependsOn: new Map(),
+                resolvedRefs: new Map(),
+            }) + '\n',
+            variablesTf: '',
+        };
+    }
+    /**
+     * Drops everything the last run rendered, keeping the registered providers and config.
+     */
+    reset() {
+        this.minTerraformVersion = '1.6.0';
+        this.providers.clear();
+        this.requiredProviders = {};
+        this.resetTransactionState();
+    }
+    /**
+     * Clears what a transaction's sweep contributed (modules, resources, wiring), keeping the
+     * per-process registrations (terraform config and providers) intact. Test harnesses that run
+     * multiple transactions in one process call this between them; a real octo process runs one
+     * transaction, so production code never resets.
+     */
+    resetTransactionState() {
+        this.modules.clear();
+        this.pendingExternalResourcesInputWiring.length = 0;
+        this.resourceRegistry.clear();
+        this.sanitizedResourceIds.clear();
+    }
+    /**
+     * The {@link TerraformModuleScope} handed to a resource's `toHCL()`, bound to one module folder.
+     */
+    scope(moduleId) {
+        return {
+            addOctoTerraformExternalResource: (octoResource) => this.addOctoTerraformExternalResource(moduleId, octoResource),
+            addOctoTerraformResource: (octoResource, options = {}) => this.addOctoTerraformResource(moduleId, octoResource, options),
+            addTerraformData: (type, name, spec = {}) => this.addTerraformData(moduleId, type, name, spec),
+            getProviderAliasRef: (accountId, regionId) => this.getProviderAliasRef(moduleId, accountId, regionId),
+            getRef: ((resource, key) => this.getRef(resource, key)),
+            jsonencode: (subject) => this.jsonencode(subject),
+            localPath: (filePath) => this.localPath(moduleId, filePath),
+            mapAttr: (value) => this.mapAttr(value),
+            moduleId,
+            raw: (value) => this.raw(value),
+            type: (schema) => this.type(schema),
+            variable: (name, typeExpression, options) => this.variable(moduleId, name, typeExpression, options),
+        };
+    }
+    /**
+     * Generates the `null_resource` + `data "external"` wrapper for an external resource.
+     *
+     * Only the parts that depend on no other resource are built here:
+     * - the `null_resource` shell (its triggers and `local-exec` provisioners are filled in later),
+     * - the `data "external"` read of the response octo recorded, which terraform re-runs on every plan
+     *   and every apply, and defers to apply time only while the `null_resource` is planned to change,
+     * - the single whole-result output (`data.external.<name>.result`) that carries the entire response.
+     *
+     * The external resource is never enumerated per response key: its response shape is unknown at
+     * generation time (the action has not run) and is, by the `data "external"` protocol, a flat map of
+     * strings. Refs to it (`getRef`) resolve by indexing this one expression; commit reads the whole map back.
+     *
+     * The parent-input wiring (triggers + create/destroy commands) reads every parent's outputs, which
+     * only all exist once registration is complete. It is therefore deferred to
+     * {@link wireExternalResourceInputs} (run at the start of {@link computeWiring}). This deferral is
+     * what lets the generate sweep contribute resources in any order, rather than parents-first.
+     */
+    addOctoTerraformExternalResource(moduleId, octoResource) {
+        const resourceId = octoResource.resourceId;
+        const name = StringUtility.sanitizeForIdentifier(resourceId);
+        const parents = (octoResource.parents || []).map((p) => p instanceof MatchingResource ? p.getActual() : p);
+        const octoTerraformResource = this.addOctoTerraformResource(moduleId, octoResource, {
+            explicitParents: parents,
+            externalResultExpression: `data.external.${name}.result`,
+        });
+        this.module(moduleId).hasExternalResources = true;
+        // The null_resource shell. Its triggers and provisioner are added by wireExternalResourceInputs(),
+        // once every parent's outputs are known.
+        const nullResource = octoTerraformResource.addTerraformResource('null_resource', name);
+        const dataExternal = this.addTerraformData(moduleId, 'external', name, {
+            program: [...this.octoCommandPrefix.split(' '), 'get-response', `--resourceId=${resourceId}`],
+        });
+        dataExternal.attribute('depends_on', new ExpressionHclNode(`[null_resource.${name}]`));
+        this.pendingExternalResourcesInputWiring.push({ nullResource, octoResource, resourceId });
+        return octoTerraformResource;
+    }
+    /**
+     * @internal
+     */
+    addOctoTerraformResource(moduleId, octoResource, options = {}) {
+        const explicitParentResourceIds = (options.explicitParents || []).map((p) => p instanceof MatchingResource ? p.getSchemaInstanceInResourceAction().resourceId : p.resourceId);
+        // Distinct resource ids must stay distinct after sanitization, or else the generated output names,
+        // identifiers, and variable names would silently collide. Environment-variable sanitization
+        // merges strictly more characters than identifier sanitization, so this one check covers both.
+        const sanitizedResourceId = StringUtility.sanitizeForEnvironmentVariable(octoResource.resourceId);
+        const existingResourceId = this.sanitizedResourceIds.get(sanitizedResourceId);
+        if (existingResourceId !== undefined) {
+            if (existingResourceId === octoResource.resourceId) {
+                throw new Error(`Resource id "${octoResource.resourceId}" is already registered!`);
+            }
+            throw new Error(`Resource id "${octoResource.resourceId}" collides with resource id "${existingResourceId}" after sanitization!`);
+        }
+        this.sanitizedResourceIds.set(sanitizedResourceId, octoResource.resourceId);
+        const module = this.module(moduleId);
+        let providerRef;
+        if (options.provider) {
+            const { alias, key, providerType } = this.findProvider(options.provider.accountId, options.provider.regionId);
+            providerRef = `${providerType}.${alias}`;
+            module.providerKeys.add(key);
+        }
+        // Seed mock outputs from the producer schema's declared response defaults — never the live
+        // response — so a regenerate after a commit cannot inline real (possibly secret) applied values.
+        // Test resources carry a non-constructable NODE_SCHEMA; they fall back to synthetic placeholders.
+        const schemaClass = octoResource.constructor
+            .NODE_SCHEMA;
+        const responseDefaults = typeof schemaClass === 'function' ? (getSchemaDefaults(schemaClass).response ?? {}) : {};
+        const newResource = new OctoTerraformResource(octoResource.resourceId, octoResource.getContext(), moduleId, explicitParentResourceIds, providerRef, options.externalResultExpression, responseDefaults);
+        module.resources.push(newResource);
+        this.resourceRegistry.set(octoResource.resourceId, newResource);
+        return newResource;
+    }
+    /**
+     * @internal
+     */
+    addTerraformData(moduleId, type, name, spec = {}) {
+        const dataSource = new TerraformData(type, StringUtility.sanitizeForIdentifier(name));
+        addTerraformResourceSpec(dataSource, spec);
+        this.module(moduleId).dataSources.push(dataSource);
+        return dataSource;
+    }
+    /**
+     * Phase 1 of rendering: resolve every {@link RefHclNode} and compute each folder's wiring.
+     *
+     * For every folder: collect all refs made from it, then resolve each one —
+     * - producer in the same folder → the inline terraform expression,
+     * - producer in another folder → a `var.*` name, plus three recorded consequences: declare the
+     *   variable, depend on the producer's folder, wire the input in terragrunt.hcl.
+     *
+     * Explicit parents resolve similarly: same folder → `depends_on` addresses; other folder → a
+     * terragrunt dependency. All ref errors and cross-folder cycles surface here — phase 2 cannot
+     * fail.
+     */
+    computeWiring() {
+        // Resolve deferred external-resource input wiring before collecting refs, so the triggers and
+        // commands it produces are part of this pass.
+        this.wireExternalResourceInputs();
+        const wiring = new Map();
+        const wiringOf = (moduleId) => {
+            if (!wiring.has(moduleId)) {
+                wiring.set(moduleId, {
+                    autoVariables: new Map(),
+                    moduleDependencies: new Map(),
+                    parentDependsOn: new Map(),
+                    resolvedRefs: new Map(),
+                });
+            }
+            return wiring.get(moduleId);
+        };
+        const addModuleDependency = (moduleWiring, producerModuleId, reason) => {
+            if (!moduleWiring.moduleDependencies.has(producerModuleId)) {
+                moduleWiring.moduleDependencies.set(producerModuleId, new Set());
+            }
+            moduleWiring.moduleDependencies.get(producerModuleId).add(reason);
+        };
+        // Producer output expressions render without a consumer context; a ref inside an output
+        // expression would require recursive resolution and is not supported.
+        const renderInlineContext = {
+            resolveRef: () => {
+                throw new Error('Nested resource references are not supported in output expressions!');
+            },
+            step: this.step,
+        };
+        for (const module of this.modules.values()) {
+            const moduleWiring = wiringOf(module.moduleId);
+            // Collect every reference made from this module.
+            const refs = [];
+            module.resources.forEach((r) => r.collectRefs(refs));
+            module.dataSources.forEach((d) => d.collectRefs(refs));
+            module.variables.forEach((v) => v.collectRefs(refs));
+            for (const ref of refs) {
+                const producer = this.resourceRegistry.get(ref.resourceId);
+                if (!producer) {
+                    throw new Error(`Resource "${ref.resourceId}" not found in Octo Terraform!`);
+                }
+                if (producer.externalResultExpression !== undefined) {
+                    if (producer.moduleId === module.moduleId) {
+                        moduleWiring.resolvedRefs.set(`${ref.resourceId}.${ref.key}`, ref.entireResponse
+                            ? producer.externalResultExpression
+                            : `${producer.externalResultExpression}.${ref.key}`);
+                    }
+                    else {
+                        const variableName = StringUtility.sanitizeForEnvironmentVariable(ref.resourceId);
+                        const entireResponseOutput = producer.outputs.get(producer.resourceId);
+                        // The variable holds the producer's entire response object; collect the keys consumed
+                        // across all refs so the mock can be shaped as an object (see `objectKeys`).
+                        const objectKeys = moduleWiring.autoVariables.get(variableName)?.objectKeys ?? new Set();
+                        if (!ref.entireResponse) {
+                            objectKeys.add(ref.key);
+                        }
+                        moduleWiring.autoVariables.set(variableName, {
+                            objectKeys,
+                            outputName: entireResponseOutput.name,
+                            producerModuleId: producer.moduleId,
+                            producerResourceId: producer.resourceId,
+                        });
+                        addModuleDependency(moduleWiring, producer.moduleId, `ref "${ref.resourceId}.${ref.key}"`);
+                        moduleWiring.resolvedRefs.set(`${ref.resourceId}.${ref.key}`, ref.entireResponse ? `var.${variableName}` : `var.${variableName}.${ref.key}`);
+                    }
+                    continue;
+                }
+                const output = producer.outputs.get(ref.key);
+                if (!output) {
+                    throw new Error(`Ref "${ref.key}" not registered for resource "${ref.resourceId}" in Octo Terraform!`);
+                }
+                if (producer.moduleId === module.moduleId) {
+                    moduleWiring.resolvedRefs.set(`${ref.resourceId}.${ref.key}`, output.value.render('', renderInlineContext));
+                }
+                else {
+                    const variableName = StringUtility.sanitizeForEnvironmentVariable(`${ref.resourceId}_${ref.key}`);
+                    const existingVariable = moduleWiring.autoVariables.get(variableName);
+                    if (existingVariable && existingVariable.outputName !== output.name) {
+                        throw new Error(`Variable "${variableName}" maps to both outputs "${existingVariable.outputName}" and ` +
+                            `"${output.name}"! Rename one of the resources or response keys.`);
+                    }
+                    moduleWiring.autoVariables.set(variableName, {
+                        outputName: output.name,
+                        producerModuleId: producer.moduleId,
+                        producerResourceId: producer.resourceId,
+                        responseKey: ref.key,
+                    });
+                    addModuleDependency(moduleWiring, producer.moduleId, `ref "${ref.resourceId}.${ref.key}"`);
+                    moduleWiring.resolvedRefs.set(`${ref.resourceId}.${ref.key}`, `var.${variableName}`);
+                }
+            }
+            // Explicit parents: same module → depends_on; cross module → terragrunt ordering.
+            for (const resource of module.resources) {
+                const addresses = [];
+                for (const parentResourceId of resource.explicitParentResourceIds) {
+                    const parent = this.resourceRegistry.get(parentResourceId);
+                    if (!parent) {
+                        throw new Error(`Explicit parent "${parentResourceId}" of resource "${resource.resourceId}" is not registered in Terraform!`);
+                    }
+                    if (parent.moduleId === module.moduleId) {
+                        addresses.push(...parent.terraformResources.map((t) => t.address));
+                    }
+                    else {
+                        addModuleDependency(moduleWiring, parent.moduleId, `parent "${parentResourceId}" of "${resource.resourceId}"`);
+                    }
+                }
+                moduleWiring.parentDependsOn.set(resource, addresses);
+            }
+        }
+        this.detectModuleCycles(wiring);
+        return wiring;
+    }
+    /**
+     * Depth-first search over folder dependencies; throws on the first cycle, naming its path and
+     * the refs/explicit parents forming each edge.
+     */
+    detectModuleCycles(wiring) {
+        const visited = new Set();
+        const inStack = new Set();
+        const visit = (moduleId, path) => {
+            if (inStack.has(moduleId)) {
+                const cycleStart = path.indexOf(moduleId);
+                const cycle = [...path.slice(cycleStart), moduleId];
+                const edges = cycle.slice(0, -1).map((from, i) => {
+                    const to = cycle[i + 1];
+                    const reasons = [...(wiring.get(from)?.moduleDependencies.get(to) ?? [])];
+                    return `"${from}" -> "${to}" via ${reasons.join(', ')}`;
+                });
+                throw new Error(`Found cross-module dependency cycle: ${cycle.join(' -> ')}! Edges: ${edges.join('; ')}.`);
+            }
+            if (visited.has(moduleId)) {
+                return;
+            }
+            inStack.add(moduleId);
+            for (const dependency of wiring.get(moduleId)?.moduleDependencies.keys() ?? []) {
+                visit(dependency, [...path, moduleId]);
+            }
+            inStack.delete(moduleId);
+            visited.add(moduleId);
+        };
+        for (const moduleId of wiring.keys()) {
+            visit(moduleId, []);
+        }
+    }
+    /**
+     * Derives the registered provider for a deployment target using only `accountId` (+ `regionId`).
+     * The provider type was decided during provider registration.
+     *
+     * Without a `regionId` (global resources), any provider of the account matches — the first
+     * registered wins, since the alias only routes the region.
+     */
+    findProvider(accountId, regionId) {
+        const matches = [...this.providers.entries()].filter(([, p]) => p.accountId === accountId && (regionId === undefined || p.regionId === regionId));
+        const target = regionId === undefined ? `account "${accountId}"` : `account "${accountId}" and region "${regionId}"`;
+        if (matches.length === 0) {
+            throw new Error(`No provider registered for ${target}!`);
+        }
+        // A resource names its provider by account and region only, never by provider type, so that pair
+        // has to identify one provider. Deliberate: outside aws the account id is expected to be what tells
+        // them apart, which keeps the pair unique in practice, and threading a provider type through
+        // every resource binding costs more than the ambiguity is worth. Hence a hint rather than a fix.
+        const providerTypes = new Set(matches.map(([, p]) => p.providerType));
+        if (regionId !== undefined && providerTypes.size > 1) {
+            throw new Error(`Multiple providers registered for ${target}! Cannot derive a unique provider. ` +
+                `Give each provider type its own accountId, since a resource selects its provider by ` +
+                `account and region alone. Registered here: ${[...providerTypes].sort().join(', ')}.`);
+        }
+        const [key, provider] = matches[0];
+        return { alias: provider.alias, key, providerType: provider.providerType };
+    }
+    /**
+     * @internal
+     */
+    getProviderAliasRef(moduleId, accountId, regionId) {
+        const { alias, key, providerType } = this.findProvider(accountId, regionId);
+        this.module(moduleId).providerKeys.add(key);
+        return new ExpressionHclNode(`${providerType}.${alias}`);
+    }
+    /**
+     * @internal
+     */
+    getRef(resource, key) {
+        const resourceId = resource instanceof MatchingResource
+            ? resource.getSchemaInstanceInResourceAction().resourceId
+            : resource.resourceId;
+        return new RefHclNode(resourceId, key);
+    }
+    /**
+     * @internal
+     */
+    jsonencode(subject) {
+        return new JsonEncodeHclNode(subject);
+    }
+    /**
+     * Renders a local file path as `"${var.OCTO_PROJECT_ROOT}/<path from the project root>"`, and
+     * marks this folder as needing that variable declared.
+     *
+     * Separators are normalized to `/`, so a folder generated on Windows reads the same as one
+     * generated anywhere else.
+     */
+    localPath(moduleId, filePath) {
+        this.module(moduleId).needsProjectRoot = true;
+        const pathFromProjectRoot = relative(process.cwd(), resolve(filePath)).split(sep).join('/');
+        return `"\${var.${PROJECT_ROOT_VARIABLE_NAME}}/${pathFromProjectRoot}"`;
+    }
+    /**
+     * @internal
+     */
+    mapAttr(value) {
+        return new MapHclNode(Object.entries(value).map(([k, v]) => [k, toHclNode(v)]));
+    }
+    /**
+     * @internal
+     */
+    module(moduleId) {
+        if (!this.modules.has(moduleId)) {
+            this.modules.set(moduleId, new TerraformModule(moduleId));
+        }
+        return this.modules.get(moduleId);
+    }
+    /**
+     * @internal
+     */
+    providerKey(providerType, accountId, regionId) {
+        return `${providerType}:${accountId}:${regionId}`;
+    }
+    /**
+     * @internal
+     */
+    raw(value) {
+        return new ExpressionHclNode(String(value));
+    }
+    /**
+     * Prints one folder's `terraform { required_version, required_providers }` config block.
+     */
+    renderConfigBlock(requiredProviders, context) {
+        const configBlock = new TerraformBlock('terraform');
+        configBlock.attribute('required_version', `>= ${this.minTerraformVersion}`);
+        const providerTypes = Object.keys(requiredProviders).sort();
+        if (providerTypes.length > 0) {
+            const requiredProvidersBlock = configBlock.block('required_providers');
+            for (const providerType of providerTypes) {
+                const entry = requiredProviders[providerType];
+                const lines = [`source = "${entry.source}"`];
+                if (entry.minVersion) {
+                    lines.push(`version = ">= ${entry.minVersion}"`);
+                }
+                requiredProvidersBlock.attribute(providerType, new MapHclNodeRaw(lines));
+            }
+        }
+        return configBlock.render('', context);
+    }
+    /**
+     * Prints one folder's `terragrunt.hcl`: a `dependency` block per producer folder (with
+     * `mock_outputs`, shallow-merged over any applied state, so `run-all plan` works both before the
+     * first apply and when intent renames a producer resource), and the `inputs` map wiring each auto
+     * variable to the producer's output.
+     */
+    renderTerragrunt(moduleWiring) {
+        const step = this.step;
+        const sections = [];
+        // Pin the (local) backend state to a stable absolute path in the module folder. Terragrunt
+        // copies each module into a per-invocation `.terragrunt-cache` working directory; without this,
+        // local state lands inside that throwaway copy, so a later `terragrunt output` (run from a fresh
+        // copy) cannot see the state a prior `terragrunt apply` wrote. Generating a `backend.tf` that
+        // points at `${get_terragrunt_dir()}/terraform.tfstate` keeps the state in one fixed place that
+        // every terragrunt command shares. Users who want a remote backend override this block.
+        sections.push([
+            'remote_state {',
+            `${step}backend = "local"`,
+            `${step}generate = {`,
+            `${step}${step}path      = "backend.tf"`,
+            `${step}${step}if_exists = "overwrite_terragrunt"`,
+            `${step}}`,
+            `${step}config = {`,
+            `${step}${step}path = "\${get_terragrunt_dir()}/terraform.tfstate"`,
+            `${step}}`,
+            '}',
+        ].join('\n'));
+        // Dependency blocks, with mock outputs so `run-all plan` works before first apply.
+        for (const producerModuleId of [...moduleWiring.moduleDependencies.keys()].sort()) {
+            const dependencyName = StringUtility.sanitizeForIdentifier(producerModuleId);
+            // Map each consumed output name to its mock shape: a flat string for per-key scalar outputs,
+            // or an object (keyed by the accessed fields) for an external producer's entire-response output.
+            const mockOutputs = new Map();
+            for (const v of moduleWiring.autoVariables.values()) {
+                if (v.producerModuleId !== producerModuleId) {
+                    continue;
+                }
+                if (v.objectKeys) {
+                    const responseKeys = mockOutputs.get(v.outputName)?.responseKeys ?? new Set();
+                    for (const key of v.objectKeys) {
+                        responseKeys.add(key);
+                    }
+                    mockOutputs.set(v.outputName, { producerResourceId: v.producerResourceId, responseKeys });
+                }
+                else if (!mockOutputs.has(v.outputName)) {
+                    mockOutputs.set(v.outputName, { producerResourceId: v.producerResourceId, responseKey: v.responseKey });
+                }
+            }
+            // Prefer the producer schema's declared default value (an author-written, non-secret
+            // placeholder, e.g. a syntactically valid ARN) over a synthetic placeholder, falling back to
+            // `mock-*` when the schema declares no default for that response key.
+            const mockValue = (producerResourceId, responseKey, fallback) => {
+                const value = this.resourceRegistry.get(producerResourceId)?.responseDefaults[responseKey];
+                return typeof value === 'string' && value.length > 0 ? value : fallback;
+            };
+            const lines = [`dependency "${dependencyName}" {`, `${step}config_path = "../${producerModuleId}"`];
+            if (mockOutputs.size > 0) {
+                lines.push('');
+                lines.push(`${step}mock_outputs = {`);
+                for (const outputName of [...mockOutputs.keys()].sort()) {
+                    const { producerResourceId, responseKey, responseKeys } = mockOutputs.get(outputName);
+                    if (responseKeys) {
+                        const fields = [...responseKeys]
+                            .sort()
+                            .map((key) => `${key} = "${mockValue(producerResourceId, key, `mock-${outputName}-${key}`)}"`);
+                        lines.push(`${step}${step}"${outputName}" = { ${fields.join(', ')} }`);
+                    }
+                    else {
+                        lines.push(`${step}${step}"${outputName}" = "${mockValue(producerResourceId, responseKey, `mock-${outputName}`)}"`);
+                    }
+                }
+                lines.push(`${step}}`);
+                lines.push(`${step}mock_outputs_allowed_terraform_commands = ["init", "plan", "show", "validate"]`);
+                lines.push(`${step}mock_outputs_merge_strategy_with_state = "shallow"`);
+            }
+            lines.push('}');
+            sections.push(lines.join('\n'));
+        }
+        // Inputs wiring.
+        const inputEntries = [...moduleWiring.autoVariables.entries()].sort(([a], [b]) => a.localeCompare(b));
+        if (inputEntries.length > 0) {
+            const lines = ['inputs = {'];
+            for (const [variableName, { outputName, producerModuleId }] of inputEntries) {
+                lines.push(`${step}${variableName} = dependency.${StringUtility.sanitizeForIdentifier(producerModuleId)}.outputs["${outputName}"]`);
+            }
+            lines.push('}');
+            sections.push(lines.join('\n'));
+        }
+        return sections.join('\n\n');
+    }
+    /**
+     * @internal
+     */
+    type(schema) {
+        return new TypeHclNode(schema);
+    }
+    /**
+     * @internal
+     */
+    variable(moduleId, name, typeExpression, options) {
+        const resolvedType = typeof typeExpression === 'string' && !['any', 'bool', 'number', 'string'].includes(typeExpression)
+            ? new ExpressionHclNode(typeExpression)
+            : new TypeHclNode(typeExpression);
+        const variable = new TerraformVariable(name, resolvedType, options);
+        this.module(moduleId).variables.push(variable);
+        return variable;
+    }
+    /**
+     * Resolves the deferred parent-input wiring for every external resource: for each parent, expands
+     * its declared outputs into `--input` arguments on the `local-exec` create/destroy commands and
+     * into individual triggers (so the `when = destroy` provisioner can reach the raw values via
+     * `self.triggers`). Runs once all resources are registered, so it is independent of the order in
+     * which resources were contributed. Idempotent: clears the queue, so a repeat call is a no-op.
+     */
+    wireExternalResourceInputs() {
+        for (const { nullResource, octoResource, resourceId } of this.pendingExternalResourcesInputWiring) {
+            const parents = (octoResource.parents || []).map((p) => p instanceof MatchingResource ? p.getActual() : p);
+            // A native parent contributes one input per output key; an external parent its whole result as a single input.
+            const inputs = [];
+            for (const parent of parents) {
+                const parentOctoResource = this.resourceRegistry.get(parent.resourceId);
+                if (!parentOctoResource) {
+                    throw new Error(`Parent resource "${parent.resourceId}" of external resource "${resourceId}" is not registered with Terraform!`);
+                }
+                if (parentOctoResource.externalResultExpression !== undefined) {
+                    inputs.push({
+                        argKey: parent.resourceId,
+                        ref: new RefHclNode(parent.resourceId, '', true),
+                        triggerKey: StringUtility.sanitizeForEnvironmentVariable(`input_${parent.resourceId}`),
+                    });
+                }
+                else {
+                    for (const key of parentOctoResource.outputs.keys()) {
+                        inputs.push({
+                            argKey: `${parent.resourceId}.${key}`,
+                            ref: new RefHclNode(parent.resourceId, key),
+                            triggerKey: StringUtility.sanitizeForEnvironmentVariable(`input_${parent.resourceId}_${key}`),
+                        });
+                    }
+                }
+            }
+            const createCommand = [
+                `${this.octoCommandPrefix} run-action --resourceId=${resourceId}`,
+            ];
+            const destroyCommand = [
+                `${this.octoCommandPrefix} run-action --resourceId=${resourceId}`,
+            ];
+            for (const input of inputs) {
+                createCommand.push(` --input ${input.argKey}=`, input.ref);
+                destroyCommand.push(` --input ${input.argKey}=\${self.triggers.${input.triggerKey}}`);
+            }
+            const triggers = [
+                [
+                    'octo_properties_hash',
+                    new LiteralHclNode(StringUtility.deterministicHash(octoResource.getExternalTriggerProperties())),
+                ],
+                ...inputs.map((i) => [i.triggerKey, new InterpolatedStringHclNode([i.ref])]),
+            ];
+            nullResource.attribute('triggers', new MapHclNode(triggers));
+            const createProvisioner = nullResource.block('provisioner "local-exec"');
+            createProvisioner.attribute('command', new InterpolatedStringHclNode(createCommand));
+            const destroyProvisioner = nullResource.block('provisioner "local-exec"');
+            destroyProvisioner.attribute('when', new ExpressionHclNode('destroy'));
+            destroyProvisioner.attribute('command', new InterpolatedStringHclNode(destroyCommand));
+        }
+        this.pendingExternalResourcesInputWiring.length = 0;
+    }
+}
+/**
+ * @internal
+ */
+let TerraformServiceFactory = class TerraformServiceFactory {
+    /**
+     * @internal
+     */
+    static async create({ octoCommandPrefix = 'octo', terraformFileIndentLength = 2, } = {}, forceNew = false) {
+        if (!this.instance) {
+            this.instance = new TerraformService(octoCommandPrefix, terraformFileIndentLength);
+        }
+        if (forceNew) {
+            this.instance.reset();
+        }
+        return this.instance;
+    }
+};
+TerraformServiceFactory = __decorate([
+    Factory(TerraformService)
+], TerraformServiceFactory);
+export { TerraformServiceFactory };
+//# sourceMappingURL=terraform.service.js.map