@quadnix/octo 0.0.30 → 0.1.0

package/dist/services/terraform/terraform.service.d.ts

@@ -0,0 +1,426 @@
+import { MatchingResource, type ResourceSchema, type TerraformFolderOutput, type UnknownResource } from '../../app.type.js';
+import type { BaseResourceSchema } from '../../resources/resource.schema.js';
+import { HclExpression, TerraformData, type TerraformLiteralType, TerraformResource, TerraformVariable } from './terraform.type.js';
+/**
+ * Mapping of an octo resource to terraform. It is used during:
+ * - Validation: (octo diff <-> TF plan comparison).
+ * - Commit (tfstate outputs -> response population).
+ */
+interface OctoTerraformResourceMapping {
+    /**
+     * Set for external resources only: the single output carrying the entire response map.
+     */
+    entireResponseOutput?: string;
+    /**
+     * The terragrunt folder this octo resource lives in (one folder per octo module).
+     */
+    moduleId: string;
+    /**
+     * Per response key, and the name of the output it is published under.
+     * Empty array for external resources (see {@link entireResponseOutput}).
+     */
+    outputMappings: {
+        key: string;
+        outputName: string;
+    }[];
+    /**
+     * The octo resource context, used during validate to match a TF plan entry back to its octo resource.
+     */
+    resourceContext: string;
+    /**
+     * The octo resource's unique id, used to look it up in the registry.
+     */
+    resourceId: string;
+    /**
+     * The addresses of every TerraformResource block generated for this octo resource.
+     * Used during validate to check the TF plan covers them all.
+     */
+    terraformAddresses: string[];
+}
+/**
+ * One octo resource's slice of the terraform module being generated.
+ *
+ * Obtained from {@link TerraformModuleScope.addOctoTerraformResource}. Everything you emit through it
+ * is attributed to that octo resource, which is how Octo later maps a terraform plan entry, and a
+ * terraform output, back to the resource it belongs to.
+ *
+ * @group Resources
+ *
+ * @see {@link ATerraformResource} for where this is used.
+ */
+export interface OctoTerraformResourceScope<TResponse extends BaseResourceSchema['response'] = BaseResourceSchema['response']> {
+    /**
+     * Emits one `resource "<type>" "<name>"` block for this octo resource.
+     * Multiple calls chain via `depends_on` in call order.
+     * The provider alias is applied automatically when the resource was registered with a provider context.
+     */
+    addTerraformResource(type: string, name: string, spec?: Record<string, unknown>): TerraformResource;
+    /**
+     * Declares the outputs for this resource — one entry per response key.
+     * Every response key must be declared; the commit phase reads exactly these outputs to
+     * reconstruct the full response.
+     */
+    output(outputs: Record<keyof TResponse & string, unknown>, options?: {
+        sensitiveKeys?: (keyof TResponse & string)[];
+    }): void;
+}
+interface TerraformModuleFiles {
+    mainTf: string;
+    outputsTf: string;
+    terragruntHcl: string;
+    variablesTf: string;
+}
+/**
+ * The terraform module folder a resource writes itself into.
+ *
+ * Octo hands one to {@link ATerraformResource.toHCL}, scoped to the folder that resource belongs to.
+ * It is a small HCL builder: register the octo resource, emit blocks on the scope it returns, and
+ * reference other resources through {@link TerraformModuleScope.getRef} rather than by writing
+ * addresses by hand - only `getRef` knows whether the producer lands in this folder or another one.
+ *
+ * @group Resources
+ *
+ * @see {@link ATerraformResource} for where this is used.
+ */
+export interface TerraformModuleScope {
+    /**
+     * Wraps an octo resource whose lifecycle runs outside Terraform (e.g. a script or SDK call).
+     * Generates a `null_resource` + `data "external"` pair that calls `octo run-action`
+     * at apply time and exposes the result as outputs.
+     */
+    addOctoTerraformExternalResource<T extends UnknownResource>(octoResource: T): OctoTerraformResourceScope<ResourceSchema<T>['response']>;
+    /**
+     * Registers an octo resource as a native Terraform resource. Returns an
+     * {@link OctoTerraformResourceScope} on which you call `addTerraformResource()` to emit
+     * HCL blocks and `output()` to declare what other resources can reference.
+     *
+     * - Pass `options.explicitParents` for dependencies that aren't captured by attribute references alone.
+     * - Pass `options.provider` to pin the resource to a specific account/region provider.
+     */
+    addOctoTerraformResource<T extends UnknownResource>(octoResource: T, options?: {
+        explicitParents?: (UnknownResource | MatchingResource<BaseResourceSchema>)[];
+        provider?: TerraformProviderContext;
+    }): OctoTerraformResourceScope<ResourceSchema<T>['response']>;
+    /**
+     * Emits a `data "<type>" "<name>"` block. Use for read-only data sources that look
+     * up existing infrastructure (e.g. `aws_ami`, `aws_caller_identity`).
+     */
+    addTerraformData(type: string, name: string, spec?: Record<string, unknown>): TerraformData;
+    /**
+     * Returns the `<providerType>.<alias>` expression for a registered provider.
+     * Pass the result as the `provider` attribute when a resource must target a
+     * specific account/region different from the module's default.
+     */
+    getProviderAliasRef(accountId: string, regionId?: string): HclExpression;
+    /**
+     * Returns a reference to another resource's output that resolves correctly at
+     * render time: an inline TF expression when the producer is in the same module,
+     * or a `var.*` wired through terragrunt when it is in a different module.
+     */
+    getRef<T extends UnknownResource>(resource: T, key: keyof ResourceSchema<T>['response'] & string): HclExpression;
+    getRef<S extends BaseResourceSchema>(resource: MatchingResource<S>, key: keyof S['response'] & string): HclExpression;
+    /**
+     * Wraps a value in a `jsonencode(...)` call.
+     */
+    jsonencode(subject: object | unknown[]): HclExpression;
+    /**
+     * Returns the HCL for a file on the developer's disk, as a quoted string ready to pass to
+     * {@link TerraformModuleScope.raw} or to a terraform function such as `filemd5`.
+     *
+     * The path renders relative to the octo project root and is joined to `var.OCTO_PROJECT_ROOT` at
+     * plan time, so the generated folder holds the same text whichever machine wrote it. Terragrunt
+     * runs terraform from a copy of the folder, so a plain relative path would not resolve.
+     */
+    localPath(filePath: string): string;
+    /**
+     * Use `mapAttr()` when the provider schema defines a **map/object attribute** (`key = { }`).
+     * Use a plain JS object in the resource spec when the schema expects a **block** (`key { }`).
+     * The distinction matters: blocks have no `=`. Check the provider docs for each argument.
+     */
+    mapAttr(value: Record<string, unknown>): HclExpression;
+    /**
+     * The ID of the octo module this folder was generated for.
+     */
+    readonly moduleId: string;
+    /**
+     * Emits a value verbatim as a terraform expression (no quoting).
+     */
+    raw(value: unknown): HclExpression;
+    /**
+     * Returns a terraform `type(...)` expression for use in `variable` declarations.
+     */
+    type(schema: unknown): HclExpression;
+    /**
+     * Declares a user-supplied input variable for this module. Use when a value must
+     * be provided at apply time rather than derived from another resource's output.
+     */
+    variable(name: string, typeExpression: unknown, options: {
+        default: TerraformLiteralType;
+        sensitive: boolean;
+    }): TerraformVariable;
+}
+/**
+ * Every terraform resource requires a deployment target - which provider, account, and region to make the call to.
+ * This deployment target is automatically derived using accountId and regionId,
+ * rather than developers hard-coding the provider alias.
+ */
+interface TerraformProviderContext {
+    accountId: string;
+    regionId?: string;
+}
+/**
+ * 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 declare class TerraformService {
+    private readonly octoCommandPrefix;
+    private readonly indentLength;
+    private minTerraformVersion;
+    private readonly modules;
+    private readonly pendingExternalResourcesInputWiring;
+    private readonly providers;
+    private requiredProviders;
+    private readonly resourceRegistry;
+    private readonly sanitizedResourceIds;
+    /**
+     * @internal
+     */
+    private get step();
+    /**
+     * @internal
+     */
+    constructor(octoCommandPrefix?: string, indentLength?: number);
+    /**
+     * 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, providers, }?: {
+        minTerraformVersion?: string;
+        providers?: Record<string, {
+            minVersion?: string;
+            source: string;
+        }>;
+    }): void;
+    /**
+     * 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: string, accountId: string, regionId: string, spec?: Record<string, unknown>, { accountName, setRegionAttribute }?: {
+        accountName?: string;
+        setRegionAttribute?: boolean;
+    }): void;
+    /**
+     * 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(): TerraformFolderOutput[];
+    /**
+     * The IDs of the module folders this run rendered.
+     */
+    getModuleIds(): string[];
+    /**
+     * 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(): OctoTerraformResourceMapping[];
+    /**
+     * 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(): Map<string, Set<string>>;
+    /**
+     * 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(): Map<string, TerraformModuleFiles>;
+    /**
+     * 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: TerraformFolderOutput): TerraformModuleFiles;
+    /**
+     * Drops everything the last run rendered, keeping the registered providers and config.
+     */
+    reset(): void;
+    /**
+     * 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(): void;
+    /**
+     * The {@link TerraformModuleScope} handed to a resource's `toHCL()`, bound to one module folder.
+     */
+    scope(moduleId: string): TerraformModuleScope;
+    /**
+     * 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.
+     */
+    private addOctoTerraformExternalResource;
+    /**
+     * @internal
+     */
+    private addOctoTerraformResource;
+    /**
+     * @internal
+     */
+    private addTerraformData;
+    /**
+     * 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.
+     */
+    private computeWiring;
+    /**
+     * Depth-first search over folder dependencies; throws on the first cycle, naming its path and
+     * the refs/explicit parents forming each edge.
+     */
+    private detectModuleCycles;
+    /**
+     * 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.
+     */
+    private findProvider;
+    /**
+     * @internal
+     */
+    private getProviderAliasRef;
+    /**
+     * @internal
+     */
+    private getRef;
+    /**
+     * @internal
+     */
+    private jsonencode;
+    /**
+     * 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.
+     */
+    private localPath;
+    /**
+     * @internal
+     */
+    private mapAttr;
+    /**
+     * @internal
+     */
+    private module;
+    /**
+     * @internal
+     */
+    private providerKey;
+    /**
+     * @internal
+     */
+    private raw;
+    /**
+     * Prints one folder's `terraform { required_version, required_providers }` config block.
+     */
+    private renderConfigBlock;
+    /**
+     * 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.
+     */
+    private renderTerragrunt;
+    /**
+     * @internal
+     */
+    private type;
+    /**
+     * @internal
+     */
+    private 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.
+     */
+    private wireExternalResourceInputs;
+}
+/**
+ * @internal
+ */
+export declare class TerraformServiceFactory {
+    private static instance;
+    /**
+     * @internal
+     */
+    static create({ octoCommandPrefix, terraformFileIndentLength, }?: {
+        octoCommandPrefix?: string;
+        terraformFileIndentLength?: number;
+    }, forceNew?: boolean): Promise<TerraformService>;
+}
+export {};