@intentius/terragucci 0.4.2 → 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
@@ -78,6 +103,12 @@ export interface ApplySettings {
     merge?: ApplyMerge;
     merge_token_env?: string;
     requires?: ApplyRequire[];
+    /**
+     * Minutes between runs of the resume job, which applies a waiting wave once
+     * an approval of its digest is on chant/lifecycle (resume.ts). Off when
+     * unset. 5 to 60.
+     */
+    resume?: number;
 }
 /**
  * Policy as code, off unless set. `tf-plan` runs the engine over each planned
@@ -169,6 +200,7 @@ export declare const RESPONSES: {
     readonly tips: readonly ["pull-request", "off"];
     readonly fmt: readonly ["commit", "off"];
     readonly publish: readonly ["notes", "off"];
+    /** next-wave: with `rollouts:` set, init writes a job that runs `respond rollout` on that schedule, so a merged and applied wave's next one opens within one interval. off leaves the job out. */
     readonly rollout: readonly ["next-wave", "off"];
     readonly "version-bump": readonly ["off", "suggest"];
     /** terragucci#30: a typed decision flags a pull request whose description leaves out what its plan destroys or replaces. Needs `decide:`. */
@@ -236,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. */
@@ -256,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;
@@ -268,13 +325,33 @@ export interface ProjectSettings {
      */
     synth?: string;
     /**
-     * Chat notifications: the names of the secrets holding a Slack or Teams
-     * incoming webhook. An apply job whose wave waits, is refused or fails
-     * posts to each (notify.ts).
+     * 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), 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
@@ -288,6 +365,14 @@ export interface ProjectSettings {
      * schedule (comment-gitlab.ts), since GitLab starts no pipeline for a note.
      */
     comments?: string | false;
+    /**
+     * A cron schedule, or false: init writes a job that runs `terragucci respond
+     * rollout --mode apply` on it, which opens the next wave of every rollout in
+     * flight once the last one merged and applied. A single repo's key: a
+     * control repo's rollout spans its projects, so it is continued from the
+     * control repo. `respond.rollout: off` leaves the job out.
+     */
+    rollouts?: string | false;
     /** GitLab only: how the project keeps its forge token; see TOKEN_PROTECTIONS. */
     gitlab?: {
         token?: GitLabToken;
@@ -322,10 +407,7 @@ export interface ProjectSettings {
         trace_url?: string;
     };
     tips?: boolean;
-    modules?: {
-        path?: string;
-        publish?: string | string[];
-    };
+    modules?: ModulesSettings;
     /**
      * Cloud identities the pipeline takes over OIDC, so no long-lived keys sit in CI.
      * Plan runs pull-request code and gets the read-only identity; apply gets the
@@ -338,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>>;
     /**
@@ -349,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. */
@@ -367,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";
@@ -379,6 +470,18 @@ export interface ResolvedSettings extends ProjectSettings {
     env: Record<string, string>;
 }
 export declare const BUILT_IN: ResolvedSettings;
+/**
+ * The keys a project's jobs read from the project's own terragucci.yml: the
+ * plan and apply stages, `respond`, `approve` and `check-policy` read them
+ * there, and no pipeline flag carries them. A control repo's `reconcile`
+ * writes each one its settings give the project, other than the built-in
+ * value, into that file (init.ts). Every other key reaches a project through
+ * the pipeline init writes (flags, the job's environment, its steps and
+ * files, such as `apply.resume` and `notify.webhook`). `url` is the project's
+ * 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 class ConfigError extends Error {
     /** Every problem found, when the error is a validation failure. */
     readonly problems?: string[];
@@ -389,6 +492,44 @@ 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;
+/** 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::`. */
+    source: string;
+    /** The publisher's cosign public key, a path in this repo. */
+    key: string;
+    /** The git repository whose `chant/lifecycle` branch holds the publisher's release ledger. */
+    ledger: string;
+}
+export interface ModulesSettings {
+    path?: string;
+    publish?: string | string[];
+    /** Sign each release, write its provenance and SBOM, and record it in the release ledger. `true` reads the key at cosign.pub. */
+    attest?: boolean | {
+        key?: string;
+    };
+    /** `attested`: tf-check and tf-plan refuse a root that pins a release of a checked source unless it verifies. */
+    require?: "attested";
+    /** Publishers in other repos whose releases `require` checks. */
+    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.2",
+  "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",
@@ -17,7 +17,8 @@
     ".": {
       "types": "./dist/types.d.ts"
     },
-    "./report.schema.json": "./dist/report.schema.json"
+    "./report.schema.json": "./dist/report.schema.json",
+    "./notify.schema.json": "./dist/notify.schema.json"
   },
   "files": [
     "dist",