@intentius/terragucci 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,292 @@
+export declare const BINARIES: readonly ["terraform", "tofu", "choudoufu", "cdktn"];
+export declare const FORGES: readonly ["github", "gitlab", "forgejo"];
+export declare const GATES: readonly ["always", "on-destroy", "never"];
+export declare const RUNTIMES: readonly ["forge", "fountain"];
+export declare const DEPENDENTS: readonly ["follow", "plan"];
+export declare const POLICY_ENGINES: readonly ["conftest", "opa"];
+export declare const POLICY_INPUTS: readonly ["plan", "hcp"];
+export type Binary = (typeof BINARIES)[number];
+export type ForgeName = (typeof FORGES)[number];
+export type Gate = (typeof GATES)[number];
+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];
+/**
+ * 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
+ * comment can waive it.
+ */
+export interface PolicySettings {
+    /** The engine. Default `conftest`, which terragucci installs on demand when it is not on the path. */
+    engine?: PolicyEngine;
+    /** The directory of Rego policy, relative to the repo root. Default `policy`. */
+    path?: string;
+    /** The Rego package whose `deny`, `violation`, `deny_*` and `warn` rules count. conftest default: every namespace. opa default: `main`, or every package under `terraform.policies` with `input: hcp`. */
+    namespace?: string;
+    /** What `input` holds: `plan`, the bare plan JSON (default); `hcp`, `{plan, run}` as HCP Terraform's OPA policies read it. */
+    input?: PolicyInput;
+}
+/**
+ * The jobs' cloud identities over the forge's OIDC token. `plan_role` and
+ * `apply_role` are AWS roles; `gcp` and `azure` set those clouds, beside AWS
+ * or instead of it.
+ */
+export interface OidcSettings {
+    plan_role?: string;
+    apply_role?: string;
+    /** The AWS token's audience. Default `sts.amazonaws.com`. */
+    audience?: string;
+    /** GCP Workload Identity Federation: the provider's resource name and a service account per stage. */
+    gcp?: {
+        workload_identity_provider: string;
+        plan_service_account: string;
+        apply_service_account: 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;
+    };
+}
+/** A plan role and an apply role, for the units under one path. */
+export interface RolePair {
+    plan: string;
+    apply: string;
+}
+/**
+ * Terragrunt settings. Terragrunt mode is detected (`root.hcl`,
+ * `terragrunt.hcl` or `terragrunt.stack.hcl`); this block only tunes it.
+ */
+export interface TerragruntSettings {
+    /** The Terragrunt release the pipeline installs. Default: the one terragucci's image carries. */
+    version?: string;
+    /** Unit globs discovery leaves out, beside `catalog/**` and the module cache. */
+    exclude?: string[];
+    /** How many units one `run --all` runs at once. Default: from the state backend. */
+    parallelism?: number;
+    /** Units that depend on a changed unit: `follow` plans them in later waves, `plan` also previews them at pull-request time. */
+    dependents?: Dependents;
+    /**
+     * Plan and apply roles by unit path glob, assumed over OIDC through a
+     * generated auth-provider-cmd. A unit that sets its own `iam_role` keeps it.
+     */
+    credentials?: Record<string, RolePair>;
+}
+/**
+ * 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
+ * table, then the audit log, then a typed decision when `decide:` is set).
+ */
+export declare const RESPONSES: {
+    readonly plan: readonly ["summary", "agent"];
+    readonly "wave-refused": readonly ["diff", "off"];
+    readonly "apply-failed": readonly ["triage", "agent", "off"];
+    readonly drift: readonly ["pull-request", "attribute", "agent", "off"];
+    readonly tips: readonly ["pull-request", "off"];
+    readonly fmt: readonly ["commit", "off"];
+    readonly publish: readonly ["notes", "agent", "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"];
+/** 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];
+export declare const QUESTION_TYPES: readonly ["noul", "choice", "score"];
+export type QuestionType = (typeof QUESTION_TYPES)[number];
+/**
+ * `decide:`: the typed-decision service the opt-in uses ask (terragucci#28).
+ * With no `decide:`, every use runs its deterministic response.
+ */
+export interface DecideSettings {
+    /** Which service answers: laya (the terragucci-decide image), von, decider or jev. */
+    backend: DecideBackend;
+    /** The service's base URL; `/v1/systemone` is appended. Required except for jev, which defaults to TypeSafe's. */
+    url?: string;
+    /** The pinned model version. Required except for laya, which defaults to the version terragucci-decide serves. */
+    model?: string;
+    /** The environment variable holding the service's bearer token. Required for jev. */
+    token_env?: string;
+    /** The probability an answer needs before a use acts on it, per question type, between 0 and 1. */
+    thresholds?: Partial<Record<QuestionType, number>>;
+}
+/** `dashboards:` in terragucci.yml, as a map. `true` takes every default. */
+export interface DashboardSettings {
+    /** Where the files go, relative to the repo. Default `observability/terragucci`. */
+    dir?: string;
+    /** The uid of the Grafana datasource that reads the Prometheus holding the metrics. Default `prometheus`. */
+    prometheus?: string;
+    /** The uid of the Grafana datasource that reads Tempo. Default `tempo`. */
+    tempo?: string;
+    /** The Grafana folder the dashboards and Grafana-managed rules go in. Default `terragucci`. */
+    folder?: string;
+    /** Where Grafana's container finds the dashboard files. Default `/var/lib/grafana/dashboards/terragucci`. */
+    path?: string;
+    /** Alert when a project's drift is older than this. Default `1d`. */
+    drift_age?: string;
+    /** Alert when a wave has waited for its approval longer than this. Default `4h`. */
+    wave_wait?: string;
+    /** Alert when a project's drift run has not run for this long. Default `2d`. */
+    schedule?: string;
+}
+export declare const DASHBOARD_KEYS: readonly ["dir", "prometheus", "tempo", "folder", "path", "drift_age", "wave_wait", "schedule"];
+export declare const DASHBOARD_DURATION_KEYS: readonly ["drift_age", "wave_wait", "schedule"];
+/**
+ * `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.
+ */
+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). */
+    command?: string;
+    /** The secret holding the model's API key, mapped into the agent's step alone. Default `ANTHROPIC_API_KEY`. */
+    key_secret?: string;
+    /** The most turns the agent takes, as `$TG_AGENT_MAX_TURNS`. Default 30. */
+    max_turns?: 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"];
+/** 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 forge, for a host terragucci cannot name. */
+    forge?: ForgeName;
+    /** Where the project lives, for a forge not on https or the default port. */
+    url?: string;
+    /** When a wave waits for an approval. */
+    gate?: Gate;
+    waves?: {
+        canary?: string[];
+    };
+    /** A cron schedule for tf-drift, or false. */
+    drift?: string | false;
+    runtime?: Runtime;
+    /**
+     * 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.
+     */
+    reports?: {
+        bucket: string;
+        endpoint?: string;
+        prefix?: string;
+        url?: string;
+    };
+    /** The environment variable holding the forge token. */
+    token_env?: string;
+    /** Environment variables every job gets. Values only, never secrets. */
+    env?: Record<string, string>;
+    /**
+     * The secret holding `OTEL_EXPORTER_OTLP_HEADERS`, such as a collector's API
+     * key, and `trace_url`: a link to a run's trace with `{trace_id}` in it
+     * (Grafana's Explore, Tempo, Jaeger), which the report links.
+     */
+    telemetry?: {
+        headers_secret?: string;
+        trace_url?: string;
+    };
+    tips?: boolean;
+    modules?: {
+        path?: string;
+        publish?: string | string[];
+    };
+    /**
+     * 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
+     * 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. */
+    terragrunt?: TerragruntSettings;
+    /** Opt-in policy checks over each plan; see PolicySettings. */
+    policy?: PolicySettings;
+    /** 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.
+     */
+    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. */
+    decide?: DecideSettings;
+    /** The AWS region whose CloudTrail drift attribution reads. Default: the region the aws CLI already uses. */
+    audit_region?: string;
+    /** Dashboards and alert rules written next to the pipeline. Off unless set. */
+    dashboards?: boolean | DashboardSettings;
+}
+/** The whole file: one repo's settings, or `defaults` and `projects` for many repos. */
+export interface TerragucciConfig extends ProjectSettings {
+    defaults?: ProjectSettings;
+    projects?: Record<string, 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;
+/** Settings with terragucci's defaults filled in. Detection fills `roots`, `binary` and `forge` later. */
+export interface ResolvedSettings extends ProjectSettings {
+    gate: Gate;
+    drift: string | false;
+    runtime: Runtime;
+    tips: boolean;
+    owned: boolean;
+    env: Record<string, string>;
+}
+export declare const BUILT_IN: ResolvedSettings;
+export declare class ConfigError extends Error {
+    /** Every problem found, when the error is a validation failure. */
+    readonly problems?: string[];
+    constructor(message: string, problems?: string[]);
+}
+/** A `--mode` value: dry-run or apply. */
+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;
+/** 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";
+/** The TypeScript folder ships separately; only a `.ts` config needs it. */
+export declare const TSAD_INSTALL = "npm i -D @intentius/tsad-reference";
+/** Load and validate a config file. A `.ts` file is folded unless `mode` says otherwise. */
+export declare function loadConfig(path: string, mode?: ConfigMode): Promise<TerragucciConfig>;
+export interface ProjectKey {
+    key: string;
+    host: string;
+    /** Everything after the host: owner/name, or a GitLab group path and name. */
+    path: string;
+    owner: string;
+    name: string;
+}
+/** Split `<host>/<path>`. The host is the first segment; the path needs an owner and a name. */
+export declare function parseProjectKey(key: string): ProjectKey;
+/** The forge a host belongs to, when the host says so. */
+export declare function forgeFromHost(host: string): ForgeName | undefined;
+/** One repo's settings: built-in defaults, then the file's own keys. */
+export declare function resolveRepo(config: TerragucciConfig): ResolvedSettings;
+/** A control repo's project: built-in defaults, then `defaults`, then the project's own keys. */
+export declare function resolveProject(config: TerragucciConfig, key: string): ResolvedSettings;

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@intentius/terragucci",
+  "version": "0.2.0",
+  "description": "The whole Terraform lifecycle, handled: one config file, generated pipelines for GitHub, GitLab and Forgejo.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/INTENTIUS/terragucci.git",
+    "directory": "packages/terragucci"
+  },
+  "homepage": "https://intentius.io/terragucci/",
+  "bin": {
+    "terragucci": "dist/terragucci.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts"
+    },
+    "./report.schema.json": "./dist/report.schema.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "types": "./dist/types.d.ts",
+  "scripts": {
+    "build": "node ../../scripts/build-cli.mjs"
+  },
+  "peerDependencies": {
+    "@intentius/tsad-reference": "2.x",
+    "@cdktn/hcl2json": "0.x"
+  },
+  "peerDependenciesMeta": {
+    "@intentius/tsad-reference": {
+      "optional": true
+    },
+    "@cdktn/hcl2json": {
+      "optional": true
+    }
+  },
+  "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/tsad-reference": "2.1.0"
+  }
+}