@intentius/terragucci 0.2.0 → 0.3.0

package/dist/types.d.ts

@@ -1,10 +1,15 @@
-export declare const BINARIES: readonly ["terraform", "tofu", "choudoufu", "cdktn"];
+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 RUNTIMES: readonly ["forge", "fountain"];
+/** Every stage runs on the forge's CI. */
+export declare const RUNTIMES: readonly ["forge"];
 export declare const DEPENDENTS: readonly ["follow", "plan"];
 export declare const POLICY_ENGINES: readonly ["conftest", "opa"];
 export declare const POLICY_INPUTS: readonly ["plan", "hcp"];
+/** When a change applies: after it merges (default), or from its open pull request before it merges. */
+export declare const APPLY_WHEN: readonly ["merge", "pull-request"];
+/** With `apply.when: pull-request`, who merges once every wave applied: a person (default), or terragucci. */
+export declare const APPLY_MERGE: readonly ["manual", "auto"];
 export type Binary = (typeof BINARIES)[number];
 export type ForgeName = (typeof FORGES)[number];
 export type Gate = (typeof GATES)[number];
@@ -12,6 +17,23 @@ export type Runtime = (typeof RUNTIMES)[number];
 export type Dependents = (typeof DEPENDENTS)[number];
 export type PolicyEngine = (typeof POLICY_ENGINES)[number];
 export type PolicyInput = (typeof POLICY_INPUTS)[number];
+export type ApplyWhen = (typeof APPLY_WHEN)[number];
+export type ApplyMerge = (typeof APPLY_MERGE)[number];
+/**
+ * `apply:`: when a change applies. `when: merge` (the default) applies the
+ * default branch after a merge. `when: pull-request` applies an open pull
+ * request's head on `/terragucci apply`, under the same waves and gates, and
+ * the push after the merge plans and reports drift without applying.
+ * `merge: auto` merges the pull request once every wave applied, in a job of
+ * its own, with the token in the secret `merge_token_env` names when it is
+ * set (required on Forgejo, whose job token cannot push to the default
+ * branch). Plain roots on GitHub and Forgejo only (NO_GITLAB_PR_APPLY).
+ */
+export interface ApplySettings {
+    when?: ApplyWhen;
+    merge?: ApplyMerge;
+    merge_token_env?: string;
+}
 /**
  * Policy as code, off unless set. `tf-plan` runs the engine over each planned
  * root's plan JSON and fails the root on a denial. No response, agent or
@@ -41,14 +63,16 @@ export interface OidcSettings {
     gcp?: {
         workload_identity_provider: string;
         plan_service_account: string;
-        apply_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`. */
+        token_url?: string;
     };
     /** 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;
+        apply_client_id: string; /** The token's audience. Default `api://AzureADTokenExchange`; `api://AzureADTokenExchangeUSGov` for Azure US Government, `api://AzureADTokenExchangeChina` for Azure China. */
+        audience?: string;
     };
 }
 /** A plan role and an apply role, for the units under one path. */
@@ -77,27 +101,24 @@ export interface TerragruntSettings {
 }
 /**
  * Pipeline events and the responses each takes. The first mode is the
- * default and needs no model; `agent` adds an agent's comment or proposal on
- * top of the deterministic response, and is never the default. `drift:
- * attribute` also names who changed each drifted attribute (a known-writes
+ * default and needs no model. `drift: attribute` also names who changed each drifted attribute (a known-writes
  * table, then the audit log, then a typed decision when `decide:` is set).
  */
 export declare const RESPONSES: {
-    readonly plan: readonly ["summary", "agent"];
+    readonly plan: readonly ["summary"];
     readonly "wave-refused": readonly ["diff", "off"];
-    readonly "apply-failed": readonly ["triage", "agent", "off"];
-    readonly drift: readonly ["pull-request", "attribute", "agent", "off"];
+    readonly "apply-failed": readonly ["triage", "off"];
+    readonly drift: readonly ["pull-request", "attribute", "off"];
     readonly tips: readonly ["pull-request", "off"];
     readonly fmt: readonly ["commit", "off"];
-    readonly publish: readonly ["notes", "agent", "off"];
+    readonly publish: readonly ["notes", "off"];
     readonly rollout: readonly ["next-wave", "off"];
-    readonly question: readonly ["off", "agent"];
     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:`. */
     readonly description: readonly ["off", "check"];
 };
 export type RespondEvent = keyof typeof RESPONSES;
-export declare const AGENT_VIA: readonly ["forge", "fountain"];
+export declare const AGENT_VIA: readonly ["forge"];
 /** The services `decide:` can name; each speaks the Jev request and response shape. */
 export declare const DECIDE_BACKENDS: readonly ["laya", "von", "decider", "jev"];
 export type DecideBackend = (typeof DECIDE_BACKENDS)[number];
@@ -144,8 +165,8 @@ export declare const DASHBOARD_DURATION_KEYS: readonly ["drift_age", "wave_wait"
  * `agent.comment`: the `/terragucci agent <ask>` pull request comment, off
  * unless set. The comment starts a job that runs a coding agent on the pull
  * request's head branch and pushes what it changes with `agent.token_env`'s
- * token. The job gets no cloud credentials: no `oidc` role and not
- * `agent.role`. `true` takes every default.
+ * token. The job gets no cloud credentials: no `oidc` role. `true` takes every
+ * default.
  */
 export interface AgentCommentSettings {
     /** The agent's command line, run in the checkout with the prompt on stdin. Default: Claude Code in print mode with file tools only (AGENT_COMMAND in agent-comment.ts). */
@@ -172,6 +193,8 @@ export interface ProjectSettings {
     url?: string;
     /** When a wave waits for an approval. */
     gate?: Gate;
+    /** When a change applies; see ApplySettings. */
+    apply?: ApplySettings;
     waves?: {
         canary?: string[];
     };
@@ -182,12 +205,15 @@ export interface ProjectSettings {
      * A bucket for plan reports. `url` is the address that serves the bucket's
      * objects to a browser (a static site, a CDN, the store's public endpoint);
      * with it, the note, the index and the dashboards link the bucket's copy.
+     * `role` is an AWS role the job assumes with its OIDC token to write the
+     * reports, apart from the job's own role.
      */
     reports?: {
         bucket: string;
         endpoint?: string;
         prefix?: string;
         url?: string;
+        role?: string;
     };
     /** The environment variable holding the forge token. */
     token_env?: string;
@@ -213,8 +239,6 @@ export interface ProjectSettings {
      * write one. The two must differ, on every cloud set.
      */
     oidc?: OidcSettings;
-    /** Whether removing the project from a control repo removes its generated files. */
-    owned?: boolean;
     /** How many roots of one dependency layer plan at once. Default: from the state backend. */
     parallelism?: number;
     /** Terragrunt settings, for a repo terragucci finds Terragrunt in. */
@@ -224,13 +248,12 @@ export interface ProjectSettings {
     /** The response to each pipeline event; see RESPONSES. */
     respond?: Partial<Record<RespondEvent, string>>;
     /**
-     * Where an agent response runs, for any event set to `agent`. Its token can
-     * comment and open pull requests; its role, when named, is read-only.
+     * 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.
      */
     agent?: {
         via: (typeof AGENT_VIA)[number];
         token_env: string;
-        role?: string;
         comment?: boolean | AgentCommentSettings;
     };
     /** The typed-decision service; see DecideSettings. Off when absent. A project's `decide` replaces the defaults' whole. */
@@ -253,7 +276,6 @@ export interface ResolvedSettings extends ProjectSettings {
     drift: string | false;
     runtime: Runtime;
     tips: boolean;
-    owned: boolean;
     env: Record<string, string>;
 }
 export declare const BUILT_IN: ResolvedSettings;
@@ -267,6 +289,14 @@ 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;
+/**
+ * Why GitLab has no apply before merge. GitLab builds a merge request's
+ * pipeline from the merge request's own `.gitlab-ci.yml`, so a job that
+ * applies it would run the checks before the apply (approval, locks, the
+ * pipeline file) inside a pipeline the merge request controls, and the apply
+ * role would have to trust every branch of the project.
+ */
+export declare const NO_GITLAB_PR_APPLY = "pull-request is not supported on GitLab, where a merge request's pipeline is defined by the merge request itself, so nothing it runs can be trusted with the apply role; leave apply.when unset, and the change applies after it merges";
 /** 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.2.0",
+  "version": "0.3.0",
   "description": "The whole Terraform lifecycle, handled: one config file, generated pipelines for GitHub, GitLab and Forgejo.",
   "license": "Apache-2.0",
   "type": "module",
@@ -45,11 +45,11 @@
   },
   "devDependencies": {
     "@cdktn/hcl2json": "0.24.0",
-    "@intentius/chant": "0.106.4",
-    "@intentius/chant-lexicon-forgejo": "0.106.4",
-    "@intentius/chant-lexicon-github": "0.106.4",
-    "@intentius/chant-lexicon-gitlab": "0.106.4",
-    "@intentius/chant-lexicon-terraform": "0.106.4",
+    "@intentius/chant": "0.107.1",
+    "@intentius/chant-lexicon-forgejo": "0.107.1",
+    "@intentius/chant-lexicon-github": "0.107.1",
+    "@intentius/chant-lexicon-gitlab": "0.107.1",
+    "@intentius/chant-lexicon-terraform": "0.107.1",
     "@intentius/tsad-reference": "2.1.0"
   }
 }