@intentius/terragucci 0.4.4 → 0.4.5

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 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"];
@@ -14,6 +15,8 @@ export declare const APPROVALS: readonly ["ledger", "pr-review", "sealed"];
 /** Every stage runs on the forge's CI. */
 export declare const RUNTIMES: readonly ["forge"];
 export declare const DEPENDENTS: readonly ["follow", "plan"];
+/** What a pull request does with the dependents of a changed unit when terragrunt.dependents is unset. */
+export declare const DEFAULT_DEPENDENTS: Dependents;
 export declare const POLICY_ENGINES: readonly ["conftest", "opa"];
 export declare const POLICY_INPUTS: readonly ["plan", "hcp"];
 /**
@@ -109,6 +112,14 @@ export interface ApplySettings {
      * unset. 5 to 60.
      */
     resume?: number;
+    /**
+     * Roots that apply from a branch other than the default: branch name to
+     * root globs. A push to a named branch applies only the roots its globs
+     * match, in waves behind the same gate; a push to the default branch, and
+     * the apply a comment starts from a merge into it, skip every root a glob
+     * here matches. Plain roots only, with `when: merge`.
+     */
+    branches?: Record<string, string[]>;
 }
 /**
  * Policy as code, off unless set. `tf-plan` runs the engine over each planned
@@ -145,22 +156,45 @@ export interface PolicySettings {
 export interface OidcSettings {
     plan_role?: string;
     apply_role?: string;
+    /**
+     * AWS roles by root glob (plain roots): a root takes the pair of the first
+     * glob it matches, so each environment's roots plan and apply with roles
+     * that reach that environment's state alone. A root no glob matches takes
+     * `plan_role` and `apply_role`. In a Terragrunt repo, `terragrunt.credentials`
+     * does this.
+     */
+    roles?: Record<string, RolePair>;
     /** The AWS token's audience. Default `sts.amazonaws.com`. */
     audience?: string;
     /** GCP Workload Identity Federation: the provider's resource name and a service account per stage. */
     gcp?: {
         workload_identity_provider: string;
         plan_service_account: string;
-        apply_service_account: string; /** Default `https://sts.googleapis.com/v1/token`; a regional endpoint such as `https://sts.europe-west3.rep.googleapis.com/v1/token`. */
+        apply_service_account: string;
+        /** Default `https://sts.googleapis.com/v1/token`; a regional endpoint such as `https://sts.europe-west3.rep.googleapis.com/v1/token`. */
         token_url?: string;
+        /**
+         * Service accounts by root glob (plain roots): a root's binary, and what
+         * reads its state, impersonate the pair of the first glob it matches, so
+         * each environment's roots reach that environment's state alone. A root no
+         * glob matches takes plan_service_account and apply_service_account.
+         */
+        roles?: Record<string, RolePair>;
     };
     /** An Entra app registration or managed identity per stage, with a federated credential for the forge. */
     azure?: {
         tenant_id: string;
         subscription_id: string;
         plan_client_id: string;
-        apply_client_id: string; /** The token's audience. Default `api://AzureADTokenExchange`; `api://AzureADTokenExchangeUSGov` for Azure US Government, `api://AzureADTokenExchangeChina` for Azure China. */
+        apply_client_id: string;
+        /** The token's audience. Default `api://AzureADTokenExchange`; `api://AzureADTokenExchangeUSGov` for Azure US Government, `api://AzureADTokenExchangeChina` for Azure China. */
         audience?: string;
+        /**
+         * Client ids by root glob (plain roots), as `gcp.roles` gives service
+         * accounts; each client needs a federated credential for the forge. A root
+         * no glob matches takes plan_client_id and apply_client_id.
+         */
+        roles?: Record<string, RolePair>;
     };
 }
 /** A plan role and an apply role, for the units under one path. */
@@ -179,7 +213,7 @@ export interface TerragruntSettings {
     exclude?: string[];
     /** How many units one `run --all` runs at once. Default: from the state backend. */
     parallelism?: number;
-    /** Units that depend on a changed unit: `follow` plans them in later waves, `plan` also previews them at pull-request time. */
+    /** Units that depend on a changed unit: `plan` (the default) previews them at pull-request time as well as planning them in later waves, `follow` only plans them in later waves. */
     dependents?: Dependents;
     /**
      * Plan and apply roles by unit path glob, assumed over OIDC through a
@@ -187,6 +221,11 @@ export interface TerragruntSettings {
      */
     credentials?: Record<string, RolePair>;
 }
+/** Atmos settings. Atmos mode is detected (`atmos.yaml` at the repo root); this block only tunes it. */
+export interface AtmosSettings {
+    /** The Atmos release every job installs. Default: the one this terragucci release pins. */
+    version?: string;
+}
 /**
  * Pipeline events and the responses each takes. The first mode is the
  * default and needs no model. `drift: attribute` also names who changed each drifted attribute (a known-writes
@@ -268,6 +307,16 @@ export interface AgentCommentSettings {
     timeout?: number;
 }
 export declare const AGENT_COMMENT_KEYS: readonly ["command", "key_secret", "max_turns", "timeout"];
+/**
+ * `agent.drift`: when the drift job opens the drift issue, a job runs a coding
+ * agent on the default branch with the drift report, and a second job opens a
+ * pull request with what it changed, with `agent.token_env`'s token. The
+ * agent's job holds no forge token and no cloud role. Its settings are
+ * `agent.comment`'s (AgentCommentSettings); `true` takes every default.
+ */
+export declare const AGENT_DRIFT_KEYS: readonly ["command", "key_secret", "max_turns", "timeout"];
+/** Why `agent.drift` and `respond.drift: pull-request` do not go together. */
+export declare const AGENT_DRIFT_RESPOND = "agent.drift opens the drift pull request itself, so the codified one would be a second; set respond.drift to attribute or off";
 /**
  * `review`: a model reviews each pull request's intent against its plan
  * (review-agent.ts), off unless `agent` is true. It posts a note and never
@@ -311,10 +360,14 @@ export interface ProjectSettings {
     apply?: ApplySettings;
     /** When a pull request takes its root locks; see LOCKS. */
     locks?: Locks;
-    /** `canary`: globs for the wave that applies first. `jobs`: the most jobs one wave's roots spread across (plain roots, GitHub and Forgejo). */
+    /**
+     * `canary`: globs for the wave that applies first. `jobs`: the most jobs one wave's roots or units spread across (GitHub and Forgejo).
+     * `after`: plain roots only, for a root or glob the roots or globs it applies after, beside the order its `terraform_remote_state` reads give.
+     */
     waves?: {
         canary?: string[];
         jobs?: number;
+        after?: Record<string, string[]>;
     };
     /** A cron schedule for tf-drift, or false. */
     drift?: string | false;
@@ -397,6 +450,21 @@ export interface ProjectSettings {
     token_env?: string;
     /** Environment variables every job gets. Values only, never secrets. */
     env?: Record<string, string>;
+    /**
+     * The runner each generated job runs on: a label, a list of labels the
+     * runner must all carry, or on GitHub a runner group; or a map of
+     * `default`, `plan`, `apply` and `drift` to one of those. Rendered as
+     * `runs-on` on GitHub and Forgejo and as `tags` on GitLab. Unset, the jobs
+     * run where they always have.
+     */
+    runner?: RunnerSettings;
+    /**
+     * The names of CI secrets and variables the jobs that plan, apply and check
+     * drift get as environment variables of the same name, such as
+     * TF_VAR_db_password: never their values. GitHub and Forgejo; GitLab hands
+     * every job its CI/CD variables already, so there the key changes nothing.
+     */
+    pass?: PassSettings;
     /**
      * The secret holding `OTEL_EXPORTER_OTLP_HEADERS`, such as a collector's API
      * key, and `trace_url`: a link to a run's trace with `{trace_id}` in it
@@ -418,6 +486,8 @@ export interface ProjectSettings {
     parallelism?: number;
     /** Terragrunt settings, for a repo terragucci finds Terragrunt in. */
     terragrunt?: TerragruntSettings;
+    /** Atmos settings, for a repo with an `atmos.yaml` at its root. */
+    atmos?: AtmosSettings;
     /** Opt-in policy checks over each plan; see PolicySettings. */
     policy?: PolicySettings;
     /**
@@ -429,13 +499,15 @@ export interface ProjectSettings {
     /** The response to each pipeline event; see RESPONSES. */
     respond?: Partial<Record<RespondEvent, string>>;
     /**
-     * The agent integration behind `agent.comment`. Its token can comment and
-     * push to a pull request's branch; its role, when named, is read-only.
+     * The agent integration behind `agent.comment` and `agent.drift`. Its token
+     * can comment, push a branch and open a pull request; the agent itself never
+     * holds it.
      */
     agent?: {
         via: (typeof AGENT_VIA)[number];
         token_env: string;
         comment?: boolean | AgentCommentSettings;
+        drift?: boolean | AgentCommentSettings;
     };
     /** The AI review of a pull request's intent against its plan; see ReviewSettings. Off when absent. */
     review?: ReviewSettings;
@@ -445,7 +517,40 @@ export interface ProjectSettings {
     audit_region?: string;
     /** Dashboards and alert rules written next to the pipeline. Off unless set. */
     dashboards?: boolean | DashboardSettings;
+    /**
+     * Jobs of your own that `init` and `reconcile` write into the generated
+     * pipeline as they are: a map of job name to the job, in the forge's own
+     * syntax, or the path of a YAML file in the repo that holds that map.
+     */
+    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;
+}
+/**
+ * Ephemeral environments: each open pull request gets its own copy of the
+ * roots `roots` matches, applied from its head under the state key with
+ * `-pr-<n>` added (ephemeral.ts). Closing the pull request, or `ttl` passing
+ * since its last apply, destroys the copy through a planned destroy that the
+ * audit trail lists. A Terragrunt unit's copy takes the suffix through its
+ * remote_state key, which reads TERRAGUCCI_EPHEMERAL_SUFFIX; with synth the
+ * command writes the roots in the copy's checkout first.
+ */
+export interface EphemeralSettings {
+    /** Root globs. */
+    roots: string[];
+    /** How long a copy lives after the last apply that changed it: `<n>m`, `<n>h` or `<n>d`. Default 24h. */
+    ttl?: string;
+    /** Minutes between the sweep's runs, which destroy the copies whose TTL passed or whose pull request closed. 5 to 60; default 30. */
+    sweep?: number;
 }
+/** `ephemeral.ttl` when unset. */
+export declare const EPHEMERAL_TTL = "24h";
+/** `ephemeral.sweep` when unset. */
+export declare const EPHEMERAL_SWEEP = 30;
+/** A TTL in milliseconds: `<n>m`, `<n>h` or `<n>d`; undefined when it is none of them. */
+export declare function ttlMs(ttl: string): number | undefined;
+/** Why ephemeral environments are refused on GitLab with gitlab.token: protected. */
+export declare const EPHEMERAL_NOT_PROTECTED = "a merge request pipeline applies the copy and records it on chant/lifecycle with the project token, and with gitlab.token: protected no merge request pipeline holds it; leave ephemeral unset or the token unprotected";
 /** The whole file: one repo's settings, or `defaults` and `projects` for many repos. */
 export interface TerragucciConfig extends ProjectSettings {
     defaults?: ProjectSettings;
@@ -453,6 +558,32 @@ export interface TerragucciConfig extends ProjectSettings {
 }
 /** The response a project takes to an event: its setting, or the event's default. */
 export declare function responseTo(settings: ProjectSettings, event: RespondEvent): string;
+/** One runner: a label, every label of a list, or a GitHub runner group with any labels its runners must also carry. */
+export type RunnerSpec = string | string[] | {
+    group: string;
+    labels?: string[];
+};
+/** `runner`: one runner for every job, or one per stage over a default. */
+export type RunnerSettings = RunnerSpec | Partial<Record<RunnerStage | "default", RunnerSpec>>;
+/** The stages `runner` can name apart; every other job runs on `default`. */
+export declare const JOB_STAGES: readonly ["plan", "apply", "drift"];
+export type RunnerStage = (typeof JOB_STAGES)[number];
+/** `pass`: secret and variable names handed to the jobs as environment variables. */
+export interface PassSettings {
+    secrets?: string[];
+    vars?: string[];
+}
+/** Whether `runner` is a map of stage to runner, rather than one runner. */
+export declare function runnerByStage(v: RunnerSettings): v is Partial<Record<RunnerStage | "default", RunnerSpec>>;
+export declare const JOB_LABEL: RegExp;
+export declare const JOB_STAGE_KEYS: string[];
+/** The problems with `runner`, for `forge` when it is known. */
+export declare function runnerProblems(v: unknown, where: string, forge?: unknown): string[];
+/** Names `pass` refuses: the forges refuse a secret under these prefixes, and terragucci sets the rest in the jobs itself. */
+export declare const PASS_RESERVED_PREFIXES: string[];
+export declare const PASS_RESERVED: string[];
+/** The problems with `pass`: lists of secret and variable names, each a name a job's environment takes, none listed twice or set by `env` too. */
+export declare function passProblems(v: unknown, where: string, env?: unknown): string[];
 /** `cost: true`, or the secret holding the estimator's key and the command to run instead of Infracost. */
 export type CostSettings = true | {
     key_secret?: string;
@@ -481,7 +612,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"];
+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 class ConfigError extends Error {
     /** Every problem found, when the error is a validation failure. */
     readonly problems?: string[];
@@ -492,6 +623,24 @@ export declare function checkMode(mode: string): "dry-run" | "apply";
 export declare const CONFIG_NAMES: string[];
 /** The config file in `dir`, or undefined. Two of them is an error. */
 export declare function findConfig(dir: string): string | undefined;
+export declare const SETTING_KEYS: Set<string>;
+export declare const TERRAGRUNT_KEYS: string[];
+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 OIDC_KEYS: string[];
+export declare const TELEMETRY_KEYS: string[];
+export declare const TOKEN_PROTECTION_KEYS: string[];
+export declare const COST_KEYS: string[];
+export declare const PASS_KEYS: string[];
+export declare const AGENT_KEYS: string[];
+export declare const MODULES_KEYS: Set<string>;
+export declare const REGISTRY_KEYS: string[];
+/** A registry namespace or module name, as the Terraform module registry protocol allows them. */
+export declare const REGISTRY_NAME: RegExp;
+/** A registry module's system (its target provider): lower-case letters and digits. */
+export declare const REGISTRY_SYSTEM: RegExp;
 /** A publisher in another repo whose releases `modules.require: attested` checks. */
 export interface TrustedModuleSource {
     /** How the roots' module sources begin: an `oci://` prefix, or the publisher's git URL with or without `git::`. */
@@ -512,23 +661,37 @@ export interface ModulesSettings {
     require?: "attested";
     /** Publishers in other repos whose releases `require` checks. */
     trusted?: TrustedModuleSource[];
+    /** Run the binary's `test` on each module before a release of it publishes; a module with no tests, or one that fails them, is refused. */
+    test?: boolean;
+    /** Write each release as the Terraform module registry protocol, as static files a bucket or a Pages site serves. */
+    registry?: RegistrySettings;
+}
+/** `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>`. */
+    bucket?: string;
+    /** Or a directory in the repo, for a Pages site to serve. */
+    dir?: string;
+    /** The bucket's API address, for an S3-compatible store. */
+    endpoint?: string;
+    /** Where the files go in the bucket. The prefix is served as the host's root. */
+    prefix?: string;
+    /** The https address, with no path, that serves the files; its host is the one module sources name. */
+    url: string;
+    /** The namespace a module is published under, unless `namespaces` maps its path. */
+    namespace: string;
+    /** A tag prefix (a path in the repo, such as `platform/`) to the namespace its modules go under. The longest match wins. */
+    namespaces?: Record<string, string>;
+    /** The system (target provider) in each module's address. Default `generic`. */
+    system?: string;
+    /** What a version's download points at: a tarball beside it (the default), its git tag, or its OCI artifact. */
+    download?: "tarball" | "git-tags" | "oci";
 }
 /** Why a control repo's projects take no `rollouts` job: each project's pipeline sees only its own roots. */
-/** Why `waves.jobs` is refused on GitLab: a split wave's shares hold one apply lock between them on GitHub and Forgejo, and GitLab's apply jobs take a resource group one job at a time. */
-export declare const WAVE_JOBS_NOT_GITLAB = "a wave splits across jobs on GitHub and Forgejo; GitLab runs one apply job at a time in its resource group, so leave waves.jobs unset there";
 export declare const WAVE_JOBS_NOT_PR_APPLY = "apply.when: pull-request applies every wave in the one job a comment starts, so a wave has no jobs to spread across; leave waves.jobs unset";
-export declare const WAVE_JOBS_NOT_TERRAGRUNT = "a Terragrunt wave applies its units with one run --all in one job; waves.jobs splits a wave of plain roots, so leave it unset";
+/** Why a control repo's projects take no `rollouts` job: each project's pipeline sees only its own roots. */
 export declare const ROLLOUTS_SINGLE_REPO = "a control repo's rollout plans its waves across every project, and a project's pipeline sees only its own roots; leave rollouts unset and run terragucci respond rollout --mode apply on a schedule in the control repo";
-/**
- * What `synth` rules out, each because it would edit the roots the synth
- * command writes. Those files are output, not in git: a change to them is
- * lost at the next synth, and their source is the app's code (a CDK Terrain
- * app's TypeScript), which terragucci does not edit.
- */
-export declare const SYNTH_DRIFT_PR_SHORT = "synth writes the roots, so a live value belongs in the app that writes them, which terragucci does not edit";
-export declare const SYNTH_DRIFT_PR = "the drift pull request writes each live value into a root's own files, and with synth the command writes those files and git does not hold them, so the value belongs in the app that writes them, which terragucci does not edit; set respond.drift to attribute, which names who changed each value in the drift issue, or to off";
-export declare const SYNTH_ROLLOUTS = "a rollout moves a pin in each root's files or its lock file, and with synth the command writes those files and git does not hold them, so the pin is in the app that writes them; move it there";
-/** The problems `synth` finds in one project's settings: a drift schedule whose response is the pull request, and a rollouts schedule. */
+/** The problems `synth` finds in one project's settings: a drift schedule whose response is the pull request, a rollouts schedule, and generate. */
 export declare function synthProblems(s: ProjectSettings, where: string): string[];
 /** Why `comments` is GitLab's alone: the other forges start a job for each comment. */
 export declare const COMMENTS_GITLAB_ONLY = "comments is for GitLab, which starts no pipeline for a merge request note; GitHub and Forgejo start the comment jobs from the comment itself, so leave comments unset";
@@ -550,10 +713,30 @@ export declare const PR_APPLY_NEEDS_ON_GITLAB: {
  * job posts it.
  */
 export declare const PROTECTED_TOKEN_NEEDS_COMMENTS = "protected needs comments: <cron>: a merge request's pipeline then holds no token that may post the plan note, so the comments schedule's job posts it";
-/** The problems with a GitLab project's `apply.when: pull-request` and `gitlab.token: protected`, when it has any. */
+/**
+ * Why `agent.comment` and `review` need `comments:` on GitLab: a merge
+ * request note starts no pipeline, and a merge request's own pipeline runs
+ * its own pipeline file, so the comments schedule's job starts the agent's and
+ * the review's pipelines on the default branch.
+ */
+export declare const NEEDS_COMMENTS_ON_GITLAB: {
+    agent: string;
+    review: string;
+};
+/** The problems with a GitLab project's `apply.when: pull-request`, `gitlab.token: protected`, `agent.comment` and `review`, when it has any. */
 export declare function gitlabPrApplyProblems(s: Record<string, unknown>, where: string): string[];
 /** Why GitLab has no plan-time locks: no merge request event runs a pipeline from the default branch. */
 export declare const NO_GITLAB_PLAN_LOCKS = "plan is not supported on GitLab, where no merge request event runs a job from the default branch that could hold the lock; leave locks unset, and with apply.when: pull-request a merge request locks its roots on `/terragucci apply` or `/terragucci lock`";
+/** A job name `own_jobs` takes: one every forge's YAML reads as a plain key. */
+export declare const OWN_JOB_NAME: RegExp;
+/** The problems with `own_jobs`: a map of job name to job, or the path of a YAML file in the repo that holds one. */
+export declare function ownJobsProblems(v: unknown, where: string): string[];
+export declare const EPHEMERAL_KEYS: string[];
+export declare const APPLY_KEYS: string[];
+/** 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`. */
+export declare const BRANCHES_NOT_PR_APPLY = "apply.when: pull-request applies an open pull request into the default branch, and a push applies nothing, so no branch could apply its roots; leave apply.branches unset";
 /** Where a shared policy is fetched from: the git URL and the ref. */
 export interface PolicySource {
     url: string;
@@ -567,6 +750,14 @@ export interface PolicySource {
  * Undefined when it is not that shape.
  */
 export declare function parsePolicySource(source: string): PolicySource | undefined;
+export declare const SECRET_NAME: RegExp;
+export declare const DECIDE_KEYS: string[];
+export declare const DURATION: RegExp;
+export declare const ATMOS_KEYS: string[];
+/** Why a config with both an atmos and a terragrunt block is refused. */
+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;
 /** 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/terragucci",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "The whole Terraform lifecycle, handled: one config file, generated pipelines for GitHub, GitLab and Forgejo.",
   "license": "Apache-2.0",
   "type": "module",
@@ -18,7 +18,8 @@
       "types": "./dist/types.d.ts"
     },
     "./report.schema.json": "./dist/report.schema.json",
-    "./notify.schema.json": "./dist/notify.schema.json"
+    "./notify.schema.json": "./dist/notify.schema.json",
+    "./terragucci.schema.json": "./dist/terragucci.schema.json"
   },
   "files": [
     "dist",
@@ -51,6 +52,7 @@
     "@intentius/chant-lexicon-github": "0.109.0",
     "@intentius/chant-lexicon-gitlab": "0.109.0",
     "@intentius/chant-lexicon-terraform": "0.109.0",
-    "@intentius/tsad-reference": "2.1.0"
+    "@intentius/tsad-reference": "2.1.0",
+    "@modelcontextprotocol/sdk": "1.30.1"
   }
 }