@intentius/terragucci 0.4.7 → 0.4.9

package/dist/types.d.ts

@@ -2,7 +2,15 @@ import { type GenerateSettings } from "./generate-config";
 export { ROOTS_NOT_ATMOS, ROOTS_NOT_TERRAGRUNT, SYNTH_DRIFT_PR, SYNTH_DRIFT_PR_SHORT, SYNTH_GENERATE, SYNTH_ROLLOUTS } from "./refusals";
 export declare const BINARIES: readonly ["terraform", "tofu", "choudoufu"];
 export declare const FORGES: readonly ["github", "gitlab", "forgejo"];
-export declare const GATES: readonly ["always", "on-destroy", "never"];
+export declare const GATES: readonly ["always", "on-destructive", "never"];
+/** Older spellings of a gate policy, still accepted from terragucci.yml and --gate: `on-destroy` is `on-destructive`. */
+export declare const GATE_ALIASES: {
+    readonly "on-destroy": "on-destructive";
+};
+/** Every gate name terragucci accepts: the policies and their older spellings. */
+export declare const GATE_NAMES: readonly GateName[];
+/** The policy a gate name means, or undefined when it names none. */
+export declare function normalizeGate(v: unknown): Gate | undefined;
 /**
  * What counts as the approval of a waiting wave (`approval:`). `ledger` (the
  * default): any `chant approve` of the wave's set digest on chant/lifecycle,
@@ -43,6 +51,8 @@ export declare const APPLY_REQUIRES: readonly ["approved", "mergeable", "undiver
 export type Binary = (typeof BINARIES)[number];
 export type ForgeName = (typeof FORGES)[number];
 export type Gate = (typeof GATES)[number];
+/** A gate as terragucci.yml or --gate may spell it: a policy, or an older name for one. */
+export type GateName = Gate | keyof typeof GATE_ALIASES;
 export type Approval = (typeof APPROVALS)[number];
 /**
  * `gitlab.token`: how a GitLab project keeps its forge token. `unprotected`
@@ -120,6 +130,14 @@ export interface ApplySettings {
      * here matches. Plain roots only, with `when: merge`.
      */
     branches?: Record<string, string[]>;
+    /**
+     * The workspace decision point every wave gate asks instead of waiting for
+     * `terragucci approve` (chant's "A gate that asks a decision point"). The
+     * point declares `gate.planDigest`, so each plan is its own question, and
+     * its deciders and quorum decide. Read at base, like `approval:`, which
+     * stays `ledger`.
+     */
+    point?: string;
 }
 /**
  * Policy as code, off unless set. `tf-plan` runs the engine over each planned
@@ -164,8 +182,12 @@ export interface OidcSettings {
      * does this.
      */
     roles?: Record<string, RolePair>;
-    /** The AWS token's audience. Default `sts.amazonaws.com`. */
-    audience?: string;
+    /**
+     * The AWS token's audience. Default `sts.amazonaws.com`. A map gives each
+     * stage its own (`plan`, `apply`, `drift`); a stage it leaves out keeps the
+     * default.
+     */
+    audience?: string | Partial<Record<AudienceStage, string>>;
     /** GCP Workload Identity Federation: the provider's resource name and a service account per stage. */
     gcp?: {
         workload_identity_provider: string;
@@ -352,8 +374,8 @@ export interface ProjectSettings {
     forge?: ForgeName;
     /** Where the project lives, for a forge not on https or the default port. */
     url?: string;
-    /** When a wave waits for an approval. */
-    gate?: Gate;
+    /** When a wave waits for an approval. A loaded config holds the policy's current name: on-destroy reads as on-destructive. */
+    gate?: GateName;
     /** What counts as a waiting wave's approval; see APPROVALS. Read from the config at base, never the applied commit's own. */
     approval?: Approval;
     /** When a change applies; see ApplySettings. */
@@ -490,6 +512,8 @@ export interface ProjectSettings {
     atmos?: AtmosSettings;
     /** Opt-in policy checks over each plan; see PolicySettings. */
     policy?: PolicySettings;
+    /** The module and provider sources a root may use, checked before init; see SourcesSettings. Off when absent. */
+    sources?: SourcesSettings;
     /**
      * `atlantis plan` and `atlantis apply` comments read as `/terragucci plan`
      * and `/terragucci apply`. Off by default. The alias changes the words
@@ -525,6 +549,54 @@ export interface ProjectSettings {
     own_jobs?: string | Record<string, Record<string, unknown>>;
     /** Roots each pull request gets a copy of, under a state key of its own, destroyed on close or once its TTL passes; see EphemeralSettings. */
     ephemeral?: EphemeralSettings;
+    /**
+     * Named environments: each names its roots by glob and sets the keys that
+     * vary for them (./environments.ts). A root in no environment takes the
+     * top-level values. Read at base, like `gate`. A control repo's `defaults`
+     * and project blocks merge them per environment name.
+     */
+    environments?: Record<string, EnvironmentSettings>;
+}
+/** An environment's name: lower-case letters, digits, `-` and `_`. */
+export declare const ENVIRONMENT_NAME: RegExp;
+/** The keys an environment takes. */
+export declare const ENVIRONMENT_KEYS: readonly ["roots", "gate", "oidc", "runner", "parallelism", "forge_environment"];
+/** The keys of an environment's `oidc`. */
+export declare const ENVIRONMENT_OIDC_KEYS: readonly ["plan_role", "apply_role", "audience", "gcp", "azure"];
+/**
+ * One environment of `environments:`. `roots` are root globs; a root matches
+ * at most one environment. Each other key, when set, replaces the top-level
+ * key's value for the environment's roots.
+ */
+export interface EnvironmentSettings {
+    roots: string[];
+    /** The gate of a wave that holds the environment's roots. A wave of roots in several environments takes the strictest of their gates. */
+    gate?: GateName;
+    /** The environment's identities: its roots plan and apply with them, as `oidc.roles` gives a root glob a pair. */
+    oidc?: EnvironmentOidc;
+    /** The runner the environment's apply jobs run on: a runner, or `{ apply: <runner> }`. A plan job plans every environment's roots, so it keeps the top-level runner. */
+    runner?: RunnerSpec | {
+        apply?: RunnerSpec;
+    };
+    /** How many of the environment's roots of one dependency layer plan at once. */
+    parallelism?: number;
+    /** The forge environment its apply jobs run in, on GitHub and GitLab. Default: the environment's name. Forgejo has none. */
+    forge_environment?: string;
+}
+/** An environment's identities: an AWS role pair, and a GCP service account pair or an Azure client pair under the project's `oidc.gcp` or `oidc.azure`. */
+export interface EnvironmentOidc {
+    plan_role?: string;
+    apply_role?: string;
+    /** The AWS token audience of the environment's apply jobs, over `oidc.audience`. */
+    audience?: string;
+    gcp?: {
+        plan_service_account: string;
+        apply_service_account: string;
+    };
+    azure?: {
+        plan_client_id: string;
+        apply_client_id: string;
+    };
 }
 /**
  * Ephemeral environments: each open pull request gets its own copy of the
@@ -612,7 +684,7 @@ export declare const BUILT_IN: ResolvedSettings;
  * own clone URL and `rollouts` belongs to a single repo, so `defaults`
  * refuses both.
  */
-export declare const PROJECT_FILE_KEYS: readonly ["policy", "reports", "approval", "gate", "roots", "waves", "parallelism", "synth", "steps", "drift", "cost", "tips", "runtime", "telemetry", "respond", "review", "decide", "audit_region", "modules", "terragrunt", "token_env", "generate", "ephemeral"];
+export declare const PROJECT_FILE_KEYS: readonly ["policy", "sources", "reports", "approval", "gate", "roots", "waves", "parallelism", "synth", "steps", "drift", "cost", "tips", "runtime", "telemetry", "respond", "review", "decide", "audit_region", "modules", "terragrunt", "token_env", "generate", "ephemeral", "environments"];
 export declare class ConfigError extends Error {
     /** Every problem found, when the error is a validation failure. */
     readonly problems?: string[];
@@ -629,7 +701,13 @@ export declare const RELEASE_VERSION: RegExp;
 /** The settings of `notify`, `policy`, `oidc`, `telemetry`, `gitlab`, `cost`, `pass` and `agent`. */
 export declare const NOTIFY_KEYS: string[];
 export declare const POLICY_KEYS: string[];
+export declare const SOURCES_KEYS: string[];
+/** One `sources` entry: a glob with no whitespace, commas, semicolons or quotes. */
+export declare const SOURCE_GLOB = "^[^\\s,;'\"]+$";
 export declare const OIDC_KEYS: string[];
+/** The stages `oidc.audience` takes as a map: the jobs that plan a change, the jobs that apply (confirm among them), and drift. */
+export declare const AUDIENCE_STAGES: readonly ["plan", "apply", "drift"];
+export type AudienceStage = (typeof AUDIENCE_STAGES)[number];
 export declare const TELEMETRY_KEYS: string[];
 export declare const TOKEN_PROTECTION_KEYS: string[];
 export declare const COST_KEYS: string[];
@@ -666,6 +744,18 @@ export interface ModulesSettings {
     /** Write each release as the Terraform module registry protocol, as static files a bucket or a Pages site serves. */
     registry?: RegistrySettings;
 }
+/**
+ * `sources`: the module and provider sources a root may use (./sources.ts).
+ * A list that is set refuses every source of its kind that no glob in it
+ * matches, before `init` downloads anything; a list that is not set checks
+ * nothing of its kind. Read at base, as `policy` is.
+ */
+export interface SourcesSettings {
+    /** Globs of module sources, as written and without their `?` query, such as `./**` for local paths. */
+    modules?: string[];
+    /** Globs of provider addresses, such as `hashicorp/*` or `registry.example.com/acme/*`. */
+    providers?: string[];
+}
 /** `modules.registry`: the module registry protocol as static files. */
 export interface RegistrySettings {
     /** The bucket the files go to: `s3://<bucket>`, `gs://<bucket>` or `az://<account>/<container>`. */
@@ -733,6 +823,8 @@ export declare const OWN_JOB_NAME: RegExp;
 export declare function ownJobsProblems(v: unknown, where: string): string[];
 export declare const EPHEMERAL_KEYS: string[];
 export declare const APPLY_KEYS: string[];
+/** A decision point's name, as chant's points file declares it. */
+export declare const POINT_NAME: RegExp;
 /** A branch name `apply.branches` may name: what a forge's rule and the job's shell both take as it is. */
 export declare const APPLY_BRANCH: RegExp;
 /** Why `apply.branches` is refused with `apply.when: pull-request`. */
@@ -758,6 +850,32 @@ export declare const ATMOS_KEYS: string[];
 export declare const ATMOS_NOT_TERRAGRUNT = "terragucci runs an Atmos repo or a Terragrunt repo, not both; keep the block of the one this repo is";
 /** The GCP Workload Identity Federation provider's resource name. */
 export declare const WIF_PROVIDER: RegExp;
+/** The apply group of the roots in no environment, or that no glob gives an identity (./groups.ts). */
+export declare const DEFAULT_GROUP = "default";
+/** Names an apply group cannot take: the rest group's, and chant's own job names (decide, share-<i>). */
+export declare const reservedGroupName: (name: string) => boolean;
+/** Why an environment's `runner.plan` is refused: a plan job plans the roots of every environment. */
+export declare const ENVIRONMENT_PLAN_RUNNER = "a plan job plans the roots of every environment, so an environment's runner is its apply jobs' alone; set runner: { apply: <runner> }, and runner.plan at the top level";
+/** A forge environment's name, as GitHub and GitLab both take it. */
+export declare const FORGE_ENVIRONMENT_NAME: RegExp;
+/** Why an environment cannot take a name the apply jobs use for their own. */
+export declare const ENVIRONMENT_RESERVED = "names the apply jobs use for their own (default holds the roots in no environment; decide and share-<n> are a wave's own jobs)";
+/** Why `environments` refuses `apply.when: pull-request`: a comment's one job applies every environment's roots. */
+export declare const ENVIRONMENTS_PR_APPLY = "with environments each environment's roots apply in jobs of their own, with their own identities, and apply.when: pull-request applies every wave in the one job a comment starts; leave apply.when at merge";
+/** Why `environments` refuses `apply.resume` on GitHub and Forgejo: the resume job applies every wave in one job. */
+export declare const ENVIRONMENTS_RESUME = "with environments each environment's roots apply in jobs of their own, and on GitHub and Forgejo the resume job applies every wave in one job; leave apply.resume unset and re-run the waiting wave's job once it is approved";
+/** Why `environments` refuses `ephemeral`: a pull request's copies apply in one job with the apply identities. */
+export declare const ENVIRONMENTS_EPHEMERAL = "with environments each environment's roots apply in jobs of their own, and an ephemeral copy applies in the pull request's one job; leave ephemeral unset";
+/** Why an environment's `forge_environment` is refused on Forgejo. */
+export declare const FORGE_ENVIRONMENT_NOT_FORGEJO = "Forgejo Actions has no deployment environments, so a job cannot run in one; leave forge_environment out of each environment";
+/**
+ * What a whole set of environments needs from the settings around it: a
+ * root glob in each, and the project's `oidc.gcp` or `oidc.azure` for an
+ * environment that names a GCP or Azure pair, since the provider, the tenant
+ * and the token come from there. A repo's own file is checked whole in
+ * checkSettings; a control repo's project once its defaults are merged in.
+ */
+export declare function environmentNeeds(s: ProjectSettings, where: string): string[];
 /** Check a parsed config and return it typed, or throw with every problem listed. */
 export declare function validateConfig(raw: unknown, where: string): TerragucciConfig;
 export type ConfigMode = "fold" | "run" | "check";
@@ -781,3 +899,5 @@ export declare function forgeFromHost(host: string): ForgeName | undefined;
 export declare function resolveRepo(config: TerragucciConfig): ResolvedSettings;
 /** A control repo's project: built-in defaults, then `defaults`, then the project's own keys. */
 export declare function resolveProject(config: TerragucciConfig, key: string): ResolvedSettings;
+/** `environments` merged per environment name: an environment both name takes `over`'s keys over `base`'s. */
+export declare function mergeEnvironments(base: Record<string, EnvironmentSettings> | undefined, over: Record<string, EnvironmentSettings> | undefined): Record<string, EnvironmentSettings> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/terragucci",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "The whole Terraform lifecycle, handled: one config file, generated pipelines for GitHub, GitLab and Forgejo.",
   "license": "Apache-2.0",
   "type": "module",
@@ -34,7 +34,7 @@
     "build": "node ../../scripts/build-cli.mjs"
   },
   "dependencies": {
-    "@intentius/chant": "0.109.0"
+    "@intentius/chant": "0.124.24"
   },
   "peerDependencies": {
     "@intentius/tsad-reference": "2.x",
@@ -50,10 +50,10 @@
   },
   "devDependencies": {
     "@cdktn/hcl2json": "0.24.0",
-    "@intentius/chant-lexicon-forgejo": "0.109.0",
-    "@intentius/chant-lexicon-github": "0.109.0",
-    "@intentius/chant-lexicon-gitlab": "0.109.0",
-    "@intentius/chant-lexicon-terraform": "0.109.0",
+    "@intentius/chant-lexicon-forgejo": "0.124.24",
+    "@intentius/chant-lexicon-github": "0.124.24",
+    "@intentius/chant-lexicon-gitlab": "0.124.24",
+    "@intentius/chant-lexicon-terraform": "0.124.24",
     "@intentius/tsad-reference": "2.1.0",
     "@modelcontextprotocol/sdk": "1.30.1"
   }