@intentius/terragucci 0.4.43 → 0.4.44

package/dist/terragucci.schema.json

@@ -252,9 +252,37 @@
       "description": "The command that writes the roots before any job reads them."
     },
     "image": {
-      "type": "string",
-      "pattern": "^[^\\s]+$",
-      "description": "The image every job runs in, built FROM terragucci's."
+      "anyOf": [
+        {
+          "type": "string",
+          "pattern": "^[^\\s]+$"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "pattern": "^[^\\s]+$"
+            },
+            "mirror": {
+              "anyOf": [
+                {
+                  "const": true
+                },
+                {
+                  "type": "string",
+                  "pattern": "^/"
+                }
+              ]
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "name"
+          ]
+        }
+      ],
+      "description": "The image every job runs in, built FROM terragucci's; as a map, its name and the provider mirror it carries."
     },
     "notify": {
       "type": "object",
@@ -360,6 +388,48 @@
       ],
       "description": "A cron schedule for the job that opens each rollout's next wave, or false."
     },
+    "control": {
+      "type": "object",
+      "properties": {
+        "repo": {
+          "type": "string",
+          "pattern": "^[^/\\s]+(/[^/\\s]+){2,}$"
+        },
+        "op": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._\\/-]{0,127}$"
+        },
+        "forge": {
+          "enum": [
+            "github",
+            "gitlab",
+            "forgejo"
+          ]
+        },
+        "member": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._\\/-]{0,127}$"
+        },
+        "token_env": {
+          "type": "string",
+          "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+        },
+        "read_token_env": {
+          "type": "string",
+          "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+        },
+        "ref": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._\\/-]{0,127}$"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "repo",
+        "op"
+      ],
+      "description": "The control repo to tell after the default branch's apply succeeds; it runs this repo's dependents."
+    },
     "gitlab": {
       "type": "object",
       "properties": {
@@ -1052,6 +1122,15 @@
               "allow_unattended"
             ]
           }
+        },
+        "agents": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^\\S+$"
+          },
+          "description": "Forge app or bot identities that are agents; a change proposed through one has input.actor.kind agent."
         }
       },
       "additionalProperties": false,
@@ -1189,6 +1268,10 @@
                   "type": "integer",
                   "minimum": 1
                 },
+                "max_cost_usd": {
+                  "type": "number",
+                  "exclusiveMinimum": 0
+                },
                 "timeout": {
                   "type": "integer",
                   "minimum": 1
@@ -1218,6 +1301,10 @@
                   "type": "integer",
                   "minimum": 1
                 },
+                "max_cost_usd": {
+                  "type": "number",
+                  "exclusiveMinimum": 0
+                },
                 "timeout": {
                   "type": "integer",
                   "minimum": 1
@@ -1998,9 +2085,37 @@
           "description": "The command that writes the roots before any job reads them."
         },
         "image": {
-          "type": "string",
-          "pattern": "^[^\\s]+$",
-          "description": "The image every job runs in, built FROM terragucci's."
+          "anyOf": [
+            {
+              "type": "string",
+              "pattern": "^[^\\s]+$"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "pattern": "^[^\\s]+$"
+                },
+                "mirror": {
+                  "anyOf": [
+                    {
+                      "const": true
+                    },
+                    {
+                      "type": "string",
+                      "pattern": "^/"
+                    }
+                  ]
+                }
+              },
+              "additionalProperties": false,
+              "required": [
+                "name"
+              ]
+            }
+          ],
+          "description": "The image every job runs in, built FROM terragucci's; as a map, its name and the provider mirror it carries."
         },
         "notify": {
           "type": "object",
@@ -2098,6 +2213,48 @@
           "const": false,
           "description": "A single repo's key; a control repo runs terragucci respond rollout itself."
         },
+        "control": {
+          "type": "object",
+          "properties": {
+            "repo": {
+              "type": "string",
+              "pattern": "^[^/\\s]+(/[^/\\s]+){2,}$"
+            },
+            "op": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._\\/-]{0,127}$"
+            },
+            "forge": {
+              "enum": [
+                "github",
+                "gitlab",
+                "forgejo"
+              ]
+            },
+            "member": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._\\/-]{0,127}$"
+            },
+            "token_env": {
+              "type": "string",
+              "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+            },
+            "read_token_env": {
+              "type": "string",
+              "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+            },
+            "ref": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9._\\/-]{0,127}$"
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "repo",
+            "op"
+          ],
+          "description": "The control repo to tell after the default branch's apply succeeds; it runs this repo's dependents."
+        },
         "gitlab": {
           "type": "object",
           "properties": {
@@ -2790,6 +2947,15 @@
                   "allow_unattended"
                 ]
               }
+            },
+            "agents": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string",
+                "pattern": "^\\S+$"
+              },
+              "description": "Forge app or bot identities that are agents; a change proposed through one has input.actor.kind agent."
             }
           },
           "additionalProperties": false,
@@ -2927,6 +3093,10 @@
                       "type": "integer",
                       "minimum": 1
                     },
+                    "max_cost_usd": {
+                      "type": "number",
+                      "exclusiveMinimum": 0
+                    },
                     "timeout": {
                       "type": "integer",
                       "minimum": 1
@@ -2956,6 +3126,10 @@
                       "type": "integer",
                       "minimum": 1
                     },
+                    "max_cost_usd": {
+                      "type": "number",
+                      "exclusiveMinimum": 0
+                    },
                     "timeout": {
                       "type": "integer",
                       "minimum": 1

package/dist/types.d.ts

@@ -196,6 +196,13 @@ export interface PolicySettings {
      * counts.
      */
     override?: (string | OverrideEntry)[];
+    /**
+     * The forge app or bot identities that are agents, such as `my-agent[bot]`.
+     * A change proposed through one is an agent's: `input.actor.kind` is
+     * `agent` (./actor.ts). Read at base, like `override`. Unset, every change
+     * is a person's.
+     */
+    agents?: string[];
     /**
      * The rule outcomes the policy has: `deny` always, and `hold` and
      * `allow_unattended` when listed, read from `hold`, `hold_*`,
@@ -363,10 +370,65 @@ export interface AgentCommentSettings {
     key_secret?: string;
     /** The most turns the agent takes, as `$TG_AGENT_MAX_TURNS`. Default 30. */
     max_turns?: number;
+    /** The most the agent may spend, in US dollars, as `$TG_AGENT_MAX_COST_USD`. The agent job is stopped and nothing is pushed when the cost it reports is above it. No default: without it there is no money limit. */
+    max_cost_usd?: number;
     /** Minutes before the agent's job is stopped. Default 30. */
     timeout?: number;
 }
-export declare const AGENT_COMMENT_KEYS: readonly ["command", "key_secret", "max_turns", "timeout"];
+/**
+ * `image` as a map: the image every job runs in, and whether it is a prepared
+ * image carrying a provider mirror (`terragucci image recipe` writes one).
+ * With `mirror` set, tf-check checks the mirror covers every lock file.
+ */
+export interface ImageSettings {
+    /** The image reference, built FROM the terragucci image for the binary. */
+    name: string;
+    /** The provider mirror's directory in the image; `true` is the one the recipe writes (MIRROR_DIR). */
+    mirror?: string | true;
+}
+export declare const IMAGE_KEYS: readonly ["name", "mirror"];
+/**
+ * `control`: after a member repo's apply on the default branch succeeds, its pipeline sends a dispatch to the
+ * control repo (a repository_dispatch on GitHub, a pipeline trigger on GitLab, a workflow dispatch on Forgejo),
+ * and the control repo runs the member's dependents with `chant workspace run --dependents-of`. The token the
+ * member holds is for that one call.
+ */
+export interface ControlSettings {
+    /** The control repo, as a project key: `<host>/<owner>/<name>`. Its host says which forge's dispatch is sent. */
+    repo: string;
+    /** The control repo's forge, when its host does not say (forgeFromHost). */
+    forge?: ForgeName;
+    /** The Op the control repo runs on the member's dependents (`chant workspace run --op`). */
+    op: string;
+    /** The member's name in the control repo's workspace. Default: the repo's name. */
+    member?: string;
+    /** The secret holding the token that may dispatch to the control repo. Default `TERRAGUCCI_CONTROL_TOKEN`. */
+    token_env?: string;
+    /** The secret holding a read-only token for the control repo, which the generated tf-plan job checks it out with. Default `TERRAGUCCI_CONTROL_READ_TOKEN`; the job's own token is used when the secret is not set. Never the dispatch token. */
+    read_token_env?: string;
+    /** The branch of the control repo a GitLab pipeline or a Forgejo workflow runs on. Default `main`; GitHub's dispatch always runs the default branch. */
+    ref?: string;
+}
+export declare const CONTROL_KEYS: readonly ["repo", "op", "forge", "member", "token_env", "read_token_env", "ref"];
+/** The token a member holds for the dispatch when `control.token_env` is unset. */
+export declare const CONTROL_TOKEN_ENV = "TERRAGUCCI_CONTROL_TOKEN";
+/** The secret the plan job reads the control repo with when `control.read_token_env` is unset: read-only, and not the dispatch token. */
+export declare const CONTROL_READ_TOKEN_ENV = "TERRAGUCCI_CONTROL_READ_TOKEN";
+/** A member name or Op name as the control repo's workspace spells them; the dispatch carries both into a shell line. */
+export declare const CONTROL_NAME: RegExp;
+/** A branch name the dispatch may carry into a URL and a shell line. */
+export declare const CONTROL_REF: RegExp;
+/** The problems with `control`. */
+export declare function controlProblems(v: unknown, where: string): string[];
+/** Where `terragucci image recipe` puts the provider mirror in the image. */
+export declare const MIRROR_DIR = "/usr/share/terragucci/providers";
+/** The image reference `image` names, in either form. */
+export declare function imageName(image: string | ImageSettings | undefined): string | undefined;
+/** The provider mirror's directory in the image `image` names, when it carries one. */
+export declare function imageMirror(image: string | ImageSettings | undefined): string | undefined;
+/** The problems with `image`: a reference, or a map of `name` and `mirror`. */
+export declare function imageProblems(v: unknown, where: string): string[];
+export declare const AGENT_COMMENT_KEYS: readonly ["command", "key_secret", "max_turns", "max_cost_usd", "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
@@ -374,7 +436,7 @@ export declare const AGENT_COMMENT_KEYS: readonly ["command", "key_secret", "max
  * 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"];
+export declare const AGENT_DRIFT_KEYS: readonly ["command", "key_secret", "max_turns", "max_cost_usd", "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";
 /**
@@ -446,9 +508,10 @@ export interface ProjectSettings {
     /**
      * 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 `ci.hooks` need.
+     * the binary, plus what the `ci.hooks` need. A map names it under `name`
+     * and says, with `mirror`, that it carries a provider mirror (ImageSettings).
      */
-    image?: string;
+    image?: string | ImageSettings;
     /**
      * Notifications: the names of the secrets holding a Slack or Teams
      * incoming webhook, and a generic webhook's address with the key that
@@ -485,6 +548,11 @@ export interface ProjectSettings {
      * control repo. `respond.rollout: off` leaves the job out.
      */
     rollouts?: string | false;
+    /**
+     * The control repo to tell once the default branch's apply succeeded (ControlSettings). The pipeline gets a
+     * job that sends the control repo a dispatch, and the control repo runs this project's dependents.
+     */
+    control?: ControlSettings;
     /** GitLab only: how the project keeps its forge token; see TOKEN_PROTECTIONS. */
     gitlab?: {
         token?: GitLabToken;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/terragucci",
-  "version": "0.4.43",
+  "version": "0.4.44",
   "description": "The whole Terraform lifecycle, handled: one config file, generated pipelines for GitHub, GitLab and Forgejo.",
   "license": "Apache-2.0",
   "type": "module",
@@ -19,10 +19,12 @@
     },
     "./report.schema.json": "./dist/report.schema.json",
     "./notify.schema.json": "./dist/notify.schema.json",
-    "./terragucci.schema.json": "./dist/terragucci.schema.json"
+    "./terragucci.schema.json": "./dist/terragucci.schema.json",
+    "./workspace-kinds": "./workspace-kinds.json"
   },
   "files": [
     "dist",
+    "workspace-kinds.json",
     "README.md",
     "LICENSE"
   ],
@@ -34,7 +36,7 @@
     "build": "node ../../scripts/build-cli.mjs"
   },
   "dependencies": {
-    "@intentius/chant": "0.124.46"
+    "@intentius/chant": "0.124.50"
   },
   "peerDependencies": {
     "@intentius/tsad-reference": "2.x",
@@ -50,10 +52,10 @@
   },
   "devDependencies": {
     "@cdktn/hcl2json": "0.24.0",
-    "@intentius/chant-lexicon-forgejo": "0.124.46",
-    "@intentius/chant-lexicon-github": "0.124.46",
-    "@intentius/chant-lexicon-gitlab": "0.124.46",
-    "@intentius/chant-lexicon-terraform": "0.124.46",
+    "@intentius/chant-lexicon-forgejo": "0.124.50",
+    "@intentius/chant-lexicon-github": "0.124.50",
+    "@intentius/chant-lexicon-gitlab": "0.124.50",
+    "@intentius/chant-lexicon-terraform": "0.124.50",
     "@intentius/tsad-reference": "2.1.0",
     "@modelcontextprotocol/sdk": "1.30.1"
   }

package/workspace-kinds.json

@@ -0,0 +1,12 @@
+{
+  "schema": 1,
+  "kinds": [
+    {
+      "name": "terragucci-control",
+      "description": "a terragucci control repo: a terragucci.yml that lists projects and the defaults they share",
+      "precedence": 300,
+      "probe": { "anyFile": ["terragucci.yml", "terragucci.yaml", "terragucci.json"] },
+      "memberFile": { "path": "terragucci.yml", "schema": "dist/terragucci.schema.json" }
+    }
+  ]
+}