@intentius/terragucci 0.4.3 → 0.4.4

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import { type GenerateSettings } from "./generate-config";
 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"];
@@ -57,6 +58,30 @@ export type ApplyWhen = (typeof APPLY_WHEN)[number];
 export type Locks = (typeof LOCKS)[number];
 export type ApplyMerge = (typeof APPLY_MERGE)[number];
 export type ApplyRequire = (typeof APPLY_REQUIRES)[number];
+/** The stages a step runs before or after (`steps:`). `drift` is the drift job's refresh-only plan. */
+export declare const STEP_STAGES: readonly ["init", "plan", "apply", "drift"];
+export type StepStage = (typeof STEP_STAGES)[number];
+/** What a step's non-zero exit does: fail the root (the default), or hold its wave for an approval. */
+export declare const STEP_FAILURES: readonly ["fail", "approve"];
+export type StepFailure = (typeof STEP_FAILURES)[number];
+export declare const STEP_KEYS: readonly ["name", "run", "before", "after", "roots", "on_failure"];
+/**
+ * One entry of `steps:`. `run` is a shell command, run in the root's
+ * directory. Exactly one of `before` and `after` names the stage. `roots`
+ * are globs of the roots it runs for (every root when unset).
+ * `on_failure: approve` turns a non-zero exit into a hold: the root's wave
+ * waits for an approval of its set digest, whatever `gate` says. Only a step
+ * that runs before the gate is decided can hold it: one before or after
+ * init or plan.
+ */
+export interface StepSettings {
+    run: string;
+    name?: string;
+    before?: StepStage;
+    after?: StepStage;
+    roots?: string[];
+    on_failure?: StepFailure;
+}
 /**
  * `apply:`: when a change applies. `when: merge` (the default) applies the
  * default branch after a merge. `when: pull-request` applies an open pull
@@ -243,14 +268,37 @@ export interface AgentCommentSettings {
     timeout?: number;
 }
 export declare const AGENT_COMMENT_KEYS: readonly ["command", "key_secret", "max_turns", "timeout"];
+/**
+ * `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
+ * approves; a `tf-apply` wave's policy reads its risk as `input.review`.
+ */
+export interface ReviewSettings {
+    /** Turns the review on. */
+    agent?: boolean;
+    /** The command line, run with the prompt on stdin; it prints the review. Default: Claude Code in print mode with no tools (REVIEW_COMMAND in review-agent.ts). */
+    command?: string;
+    /** The secret holding the model's API key, mapped into the review command's step alone. Default `ANTHROPIC_API_KEY`. */
+    key_secret?: string;
+    /** The instructions file, read from the default branch. Default `.terragucci/review.md`. */
+    instructions?: string;
+    /** Minutes before the review job is stopped. Default 10. */
+    timeout?: number;
+}
+export declare const REVIEW_KEYS: readonly ["agent", "command", "key_secret", "instructions", "timeout"];
 /** The settings one project (or one repo) can carry. Every key is optional. */
 export interface ProjectSettings {
     /** Globs of root directories. Detected when absent. */
     roots?: string[];
     /** The binary the pipeline runs. Detected when absent. */
     binary?: Binary;
-    /** The binary's version. Read from the roots' `required_version` when it pins one. */
-    version?: string;
+    /**
+     * The binary's version. Read from the roots' `required_version` when it pins one. As a map of root
+     * glob to release, the version each root it matches runs (tofu and terraform, plain roots only).
+     */
+    version?: string | Record<string, string>;
+    /** Each plain root's backend, provider and version files, which `terragucci generate` writes; see generate.ts. */
+    generate?: GenerateSettings;
     /** The forge, for a host terragucci cannot name. */
     forge?: ForgeName;
     /** Where the project lives, for a forge not on https or the default port. */
@@ -263,8 +311,10 @@ 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). */
     waves?: {
         canary?: string[];
+        jobs?: number;
     };
     /** A cron schedule for tf-drift, or false. */
     drift?: string | false;
@@ -274,17 +324,34 @@ export interface ProjectSettings {
      * plan, apply and drift jobs, on their own checkout.
      */
     synth?: string;
+    /**
+     * Commands run before and after a root's init, plan, apply and drift, in
+     * the stage's own job, on its checkout, with its environment less the forge
+     * tokens. Read from terragucci.yml at base, never from the change under
+     * review (./steps.ts).
+     */
+    steps?: StepSettings[];
+    /**
+     * The image every job runs in, in place of terragucci's: one built FROM
+     * the terragucci image for the binary, so the job still has terragucci and
+     * the binary, plus what the steps need.
+     */
+    image?: string;
     /**
      * Notifications: the names of the secrets holding a Slack or Teams
      * incoming webhook, and a generic webhook's address with the key that
      * signs its body. An apply job whose wave waits, is refused or fails posts
-     * to each (notify.ts).
+     * to each (notify.ts), and the drift job posts drift to Slack and Teams.
+     * `relay` names the customer's relay (relay.ts): a waiting wave's Slack
+     * message gets Approve and Decline buttons, its Teams card the reply
+     * `@<relay> approve wave-<k> <digest>`.
      */
     notify?: {
         slack?: string;
         teams?: string;
         webhook?: string;
         webhook_key?: string;
+        relay?: string;
     };
     /**
      * Cost estimates per root in the plan note: Infracost on the customer's
@@ -353,6 +420,12 @@ export interface ProjectSettings {
     terragrunt?: TerragruntSettings;
     /** Opt-in policy checks over each plan; see PolicySettings. */
     policy?: PolicySettings;
+    /**
+     * `atlantis plan` and `atlantis apply` comments read as `/terragucci plan`
+     * and `/terragucci apply`. Off by default. The alias changes the words
+     * only: the same checks decide (comment.ts).
+     */
+    atlantis_comments?: boolean;
     /** The response to each pipeline event; see RESPONSES. */
     respond?: Partial<Record<RespondEvent, string>>;
     /**
@@ -364,6 +437,8 @@ export interface ProjectSettings {
         token_env: string;
         comment?: boolean | AgentCommentSettings;
     };
+    /** The AI review of a pull request's intent against its plan; see ReviewSettings. Off when absent. */
+    review?: ReviewSettings;
     /** The typed-decision service; see DecideSettings. Off when absent. A project's `decide` replaces the defaults' whole. */
     decide?: DecideSettings;
     /** The AWS region whose CloudTrail drift attribution reads. Default: the region the aws CLI already uses. */
@@ -382,6 +457,7 @@ export declare function responseTo(settings: ProjectSettings, event: RespondEven
 export type CostSettings = true | {
     key_secret?: string;
     command?: string;
+    approve_above?: number;
 };
 /** The secret Infracost's key is read from when `cost.key_secret` is unset; the job gets it as this variable too. */
 export declare const COST_KEY_SECRET = "INFRACOST_API_KEY";
@@ -405,7 +481,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", "drift", "cost", "tips", "runtime", "telemetry", "respond", "decide", "audit_region", "modules", "terragrunt", "token_env"];
+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 class ConfigError extends Error {
     /** Every problem found, when the error is a validation failure. */
     readonly problems?: string[];
@@ -438,7 +514,22 @@ export interface ModulesSettings {
     trusted?: TrustedModuleSource[];
 }
 /** 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";
 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. */
+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";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/terragucci",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "The whole Terraform lifecycle, handled: one config file, generated pipelines for GitHub, GitLab and Forgejo.",
   "license": "Apache-2.0",
   "type": "module",