@intentius/terragucci 0.4.1 → 0.4.3

package/dist/types.d.ts

@@ -78,6 +78,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 +175,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:`. */
@@ -261,12 +268,44 @@ export interface ProjectSettings {
     };
     /** A cron schedule for tf-drift, or false. */
     drift?: string | false;
+    /**
+     * The command that writes the roots before any job reads them, such as
+     * CDK Terrain's `npx cdktn synth`. Run from the repo's root, in the check,
+     * plan, apply and drift jobs, on their own checkout.
+     */
+    synth?: 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).
+     */
+    notify?: {
+        slack?: string;
+        teams?: string;
+        webhook?: string;
+        webhook_key?: string;
+    };
+    /**
+     * Cost estimates per root in the plan note: Infracost on the customer's
+     * own key (`key_secret`, default INFRACOST_API_KEY), or a `command` that
+     * prints Infracost's JSON (report/cost.ts).
+     */
+    cost?: CostSettings;
     /**
      * GitLab only: the cron of the comments schedule, or false. The pipeline
      * gets a `comments` job that reads new merge request notes on that
      * 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;
@@ -301,10 +340,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
@@ -342,6 +378,13 @@ 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;
+/** `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;
+    command?: string;
+};
+/** 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";
 /** Settings with terragucci's defaults filled in. Detection fills `roots`, `binary` and `forge` later. */
 export interface ResolvedSettings extends ProjectSettings {
     gate: Gate;
@@ -351,6 +394,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", "drift", "cost", "tips", "runtime", "telemetry", "respond", "decide", "audit_region", "modules", "terragrunt", "token_env"];
 export declare class ConfigError extends Error {
     /** Every problem found, when the error is a validation failure. */
     readonly problems?: string[];
@@ -361,6 +416,29 @@ 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. */
+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";
 /** 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.1",
+  "version": "0.4.3",
   "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",