@intentius/chant-lexicon-prometheus 0.106.4 → 0.108.0

package/dist/op/activity-contracts.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Activity contracts for this lexicon's `op/activities` (#3369).
+ *
+ * Resolved by convention at
+ * `@intentius/chant-lexicon-prometheus/op/activity-contracts`:
+ * `loadActivityContracts` merges them into the map OPS012 checks each step's
+ * args against and OPS013 checks each step-output reference against. Every
+ * activity here has one; `rulesLoadedObserve`'s return schema is what lets a
+ * `ConvergeOp({ observe: rulesLoadedObserve(...) })` pass OPS013, and
+ * `alertmanagerSilence`'s is what a later step reads `.out.silenceId` from.
+ *
+ * Each `args` schema mirrors the `*Args` interface in `./activities/`,
+ * without the `_`-prefixed test seams, and is a `z.strictObject`, so a
+ * misspelled key fails the build.
+ */
+export declare const promtoolCheckRulesContract: import("@intentius/chant/op").ActivityContract<{
+    rules: string | string[];
+    bin?: string | undefined;
+}, {
+    files: string[];
+    ok: boolean;
+    output: string;
+}>;
+export declare const promtoolTestRulesContract: import("@intentius/chant/op").ActivityContract<{
+    rules: string;
+    tests?: string | string[] | undefined;
+    testYaml?: string | string[] | undefined;
+    bin?: string | undefined;
+}, {
+    files: string[];
+    ok: boolean;
+    output: string;
+    tests: number;
+}>;
+export declare const amtoolCheckConfigContract: import("@intentius/chant/op").ActivityContract<{
+    config: string;
+    bin?: string | undefined;
+}, {
+    files: string[];
+    ok: boolean;
+    output: string;
+}>;
+export declare const amtoolRoutesTestContract: import("@intentius/chant/op").ActivityContract<{
+    config: string;
+    labels: Record<string, string>;
+    expect: string | string[];
+    bin?: string | undefined;
+}, {
+    config: string;
+    labels: Record<string, string>;
+    receivers: string[];
+    ok: boolean;
+}>;
+export declare const alertmanagerSilenceContract: import("@intentius/chant/op").ActivityContract<{
+    record?: string | undefined;
+    recordDir?: string | undefined;
+    url?: string | undefined;
+    matchers: string[] | Record<string, string>;
+    duration: string;
+    comment?: string | undefined;
+    createdBy?: string | undefined;
+}, {
+    silenceId: string;
+    url: string;
+    startsAt: string;
+    endsAt: string;
+    record: string;
+}>;
+export declare const alertmanagerUnsilenceContract: import("@intentius/chant/op").ActivityContract<{
+    record?: string | undefined;
+    recordDir?: string | undefined;
+    url?: string | undefined;
+    silenceId?: string | undefined;
+}, {
+    expired: string[];
+    failed: {
+        silenceId: string;
+        detail: string;
+    }[];
+}>;
+export declare const rulesLoadedObserveContract: import("@intentius/chant/op").ActivityContract<{
+    url?: string | undefined;
+    groups?: string[] | undefined;
+    rules?: string | string[] | undefined;
+    timeoutMs?: number | undefined;
+}, {
+    resources: {
+        name: string;
+        status: "drifted" | "in-sync" | "unknown";
+        detail: string;
+    }[];
+}>;
+export declare const ruleAuditContract: import("@intentius/chant/op").ActivityContract<{
+    url?: string | undefined;
+    pendingFor?: string | undefined;
+    firingFor?: string | undefined;
+    selectorBudget?: number | undefined;
+    lookback?: string | undefined;
+    mode?: "issue" | "report" | undefined;
+    issueTitle?: string | undefined;
+}, {
+    mode: "issue" | "report";
+    findings: {
+        kind: "firing-too-long" | "pending-too-long" | "rule-error" | "selector-no-series";
+        subject: string;
+        detail: string;
+    }[];
+    queried: number;
+    unchecked: number;
+    summary: string;
+    issueUrl?: string | undefined;
+}>;
+//# sourceMappingURL=activity-contracts.d.ts.map

package/dist/op/activity-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../src/op/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH,eAAO,MAAM,0BAA0B;;;;;;;EAItC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;EAIrC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;EAIrC,CAAC;AAEF,eAAO,MAAM,wBAAwB;;;;;;;;;;EAIpC,CAAC;AAIF,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;EAWvC,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;EAIzC,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;;;;;;;EAItC,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;EAqB7B,CAAC"}

package/dist/op/audit-op.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `RuleAuditOp`: what a live Prometheus says about its rules, as an Op with
+ * an optional schedule (#3369). One `ruleAudit` step reports groups with
+ * health errors, alerts pending or firing past a threshold, and selectors
+ * no live target emits (one query per selector, within a budget).
+ * `onFinding` is `report` (the default) or `issue`, which keeps one open
+ * issue current.
+ *
+ * @example
+ * ```typescript
+ * export const { op } = RuleAuditOp({ name: "rule-audit", url: "http://prometheus:9090", schedule: "0 * * * *" });
+ * ```
+ */
+import { type OpResource } from "@intentius/chant/op";
+import type { RuleAuditMode } from "./activities/rule-audit.js";
+export interface RuleAuditOpConfig {
+    /** Op name (kebab-case). */
+    name: string;
+    /** Prometheus's base URL. Default `$PROMETHEUS_URL`, else `http://localhost:9090`. */
+    url?: string;
+    /** Cron expression; omit for one-shot `chant run`. */
+    schedule?: string;
+    /** @default "report" */
+    onFinding?: RuleAuditMode;
+    /** @default "1h" */
+    pendingFor?: string;
+    /** @default "24h" */
+    firingFor?: string;
+    /** @default 50 */
+    selectorBudget?: number;
+    /** @default "1h" */
+    lookback?: string;
+}
+export interface RuleAuditOpResources {
+    op: InstanceType<typeof OpResource>;
+}
+export declare function RuleAuditOp(config: RuleAuditOpConfig): RuleAuditOpResources;
+//# sourceMappingURL=audit-op.d.ts.map

package/dist/op/audit-op.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-op.d.ts","sourceRoot":"","sources":["../../src/op/audit-op.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,oBAAoB;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;CACrC;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,oBAAoB,CAY3E"}

package/dist/op/builders.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Typed step builders for this lexicon's Op activities (#3369), following
+ * the helm and fly builders: each one's options ARE the activity's own
+ * `*Args` interface (minus its `_`-prefixed test seams), every field also
+ * takes a `StepOutputRef`, and `profile` and `id` go to the step.
+ *
+ * `promtoolCheckRules`, `promtoolTestRules` and `amtoolCheckConfig` share
+ * their names with the plain functions in `../tools.ts`, which the package
+ * root already exports, so those three builders are reached here, at
+ * `@intentius/chant-lexicon-prometheus/op/builders`. The root exports the
+ * rest.
+ */
+import { type ActivityStep, type NamedActivityStep, type WithStepRefs } from "@intentius/chant/op";
+import type { AmtoolCheckConfigArgs, AmtoolRoutesTestArgs, PromtoolCheckRulesArgs, PromtoolTestRulesArgs } from "./activities/promtool.js";
+import type { AlertmanagerSilenceArgs, AlertmanagerUnsilenceArgs } from "./activities/silence.js";
+import type { RulesLoadedObserveArgs } from "./activities/rules-loaded.js";
+import type { RuleAuditArgs } from "./activities/rule-audit.js";
+import { type SloTestInput } from "./slo-rule-tests.js";
+type StepOpts = {
+    profile?: ActivityStep["profile"];
+    id?: string;
+};
+type Authored<T> = Omit<T, `_${string}`>;
+/** `promtool check rules` over built rule files. Defaults to the `fastIdempotent` profile. */
+export declare const promtoolCheckRules: (args: WithStepRefs<Authored<PromtoolCheckRulesArgs>> & StepOpts) => NamedActivityStep;
+/**
+ * `promtool test rules` over a built rule file. `slos` generates the tests
+ * from `Slo` declarations at build time (`sloRuleTests`): each burn-rate
+ * pair fires at its rate and not below it. Defaults to the `fastIdempotent`
+ * profile.
+ */
+export declare const promtoolTestRules: (args: WithStepRefs<Authored<PromtoolTestRulesArgs>> & StepOpts & {
+    slos?: SloTestInput[];
+}) => NamedActivityStep;
+/** `amtool check-config` over a built Alertmanager config. Defaults to the `fastIdempotent` profile. */
+export declare const amtoolCheckConfig: (args: WithStepRefs<Authored<AmtoolCheckConfigArgs>> & StepOpts) => NamedActivityStep;
+/** `amtool config routes test`: `labels` route to `expect`. Defaults to the `fastIdempotent` profile. */
+export declare const amtoolRoutesTest: (args: WithStepRefs<Authored<AmtoolRoutesTestArgs>> & StepOpts) => NamedActivityStep;
+/**
+ * Silence alerts through Alertmanager's API for `duration`, recording the
+ * silence id under `record` so `alertmanagerUnsilence` can expire it from
+ * a final phase or an `onFailure` phase. Defaults to the `atMostOnce`
+ * profile: a retry after a lost answer would create a second silence.
+ */
+export declare const alertmanagerSilence: (args: WithStepRefs<Authored<AlertmanagerSilenceArgs>> & StepOpts) => NamedActivityStep;
+/** Expire the silences `record` holds (or `silenceId`). Defaults to the `fastIdempotent` profile. */
+export declare const alertmanagerUnsilence: (args?: WithStepRefs<Authored<AlertmanagerUnsilenceArgs>> & StepOpts) => NamedActivityStep;
+/**
+ * Observe declared rule groups for a `ConvergeOp({ observe })`: one resource
+ * per group, drifted when Prometheus has not loaded it or a rule in it has
+ * `health: "err"`. Defaults to the `fastIdempotent` profile.
+ */
+export declare const rulesLoadedObserve: (args: WithStepRefs<Authored<RulesLoadedObserveArgs>> & StepOpts) => NamedActivityStep;
+/** Audit a live Prometheus's rules, alerts and selectors (the step of `RuleAuditOp`). Defaults to the `fastIdempotent` profile. */
+export declare const ruleAudit: (args?: WithStepRefs<Authored<RuleAuditArgs>> & StepOpts) => NamedActivityStep;
+export {};
+//# sourceMappingURL=builders.d.ts.map

package/dist/op/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAA8B,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC/H,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAC/F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEnE,KAAK,QAAQ,GAAG;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACnE,KAAK,QAAQ,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,IAAI,MAAM,EAAE,CAAC,CAAC;AASzC,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,uEAP2B,iBAO4C,CAAC;AAEvG;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,SACtB,YAAY,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC,GAAG,QAAQ,GAAG;IAAE,IAAI,CAAC,EAAE,YAAY,EAAE,CAAA;CAAE,KACzF,iBAMF,CAAC;AAEF,wGAAwG;AACxG,eAAO,MAAM,iBAAiB,sEA1B4B,iBA0ByC,CAAC;AAEpG,yGAAyG;AACzG,eAAO,MAAM,gBAAgB,qEA7B6B,iBA6BsC,CAAC;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,wEArC0B,iBAqC2C,CAAC;AAEtG,qGAAqG;AACrG,eAAO,MAAM,qBAAqB,UAAU,YAAY,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC,GAAG,QAAQ,KAAQ,iBAC9B,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,uEAhD2B,iBAgD4C,CAAC;AAEvG,mIAAmI;AACnI,eAAO,MAAM,SAAS,UAAU,YAAY,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,GAAG,QAAQ,KAAQ,iBAC9B,CAAC"}

package/dist/op/slo-rule-tests.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `promtool test rules` input generated from `Slo` declarations (#3369),
+ * lifted from `composites/slo-burn.test.ts`.
+ *
+ * For each burn-rate pair an `Slo` builds, two synthetic scenarios over a
+ * good and a bad request counter: healthy for the pair's long window, then
+ * burning the error budget at 1.25 times the pair's factor (it must fire)
+ * and at 0.9 times it (it must not). The small evaluator in `rule-eval.ts`
+ * runs the SLO's rules over each scenario and says which alerts fire at a
+ * few evaluation times around the expected onset; those become the
+ * `alert_rule_test` expectations, so `promtool test rules` holds Prometheus
+ * to the same answer.
+ *
+ * The SLI expressions are the author's, so the generator cannot invent the
+ * series they read: `good` and `bad` name one series each (`metric{labels}`),
+ * counters such that the SLI counts `good` as good events and `bad` as bad
+ * ones. The evaluator throws on PromQL it does not implement, which then
+ * fails here, at authoring time, rather than in promtool.
+ *
+ * Pairs whose long window is a day or more step in five minutes, the rest in
+ * one, and promtool's `evaluation_interval` is per file, so the result is
+ * one test file per step size.
+ */
+import { type SloInstance } from "../composites/slo.js";
+export interface SloTestInput {
+    /** The `Slo(...)` result. */
+    slo: SloInstance;
+    /** The good-events counter, e.g. `requests_total{code="200"}`. */
+    good: string;
+    /** The bad-events counter, e.g. `requests_total{code="500"}`. */
+    bad: string;
+    /** Events per minute. Default 1000. */
+    rate?: number;
+}
+/** `metric{a="1",b="2"}` as a label set with `__name__`. */
+export declare function seriesLabels(series: string): Record<string, string>;
+/** Counter samples as promtool's `a+bxn` segments. */
+export declare function seriesValues(values: number[]): string;
+/**
+ * The `promtool test rules` files for these SLOs, one per step size, each
+ * naming `rules.yml` (where `promtoolTestRules` writes the rule file).
+ */
+export declare function sloRuleTests(inputs: SloTestInput[]): string[];
+//# sourceMappingURL=slo-rule-tests.d.ts.map

package/dist/op/slo-rule-tests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slo-rule-tests.d.ts","sourceRoot":"","sources":["../../src/op/slo-rule-tests.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAgC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQnF,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,GAAG,EAAE,WAAW,CAAC;IACjB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AASD,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiBnE;AAED,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAgBrD;AA6DD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,EAAE,CAmB7D"}

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AA+B9D;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAyH9B,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAgC9D;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAwI9B,CAAC"}

package/dist/rules/prom-helpers.ts

@@ -5,9 +5,9 @@
  *
  * Documents are recognized by shape, not by which lexicon emitted them, so a
  * rule file that reaches the output some other way (a hand-written YAML
- * sidecar) is checked too. `PrometheusRule` manifests are not read here;
- * their groups are the same `RuleGroup`s and are checked where they are
- * declared.
+ * sidecar) is checked too. `PrometheusRule` manifests are not read here:
+ * `chant build` hands each lexicon's checks only that lexicon's output, so the
+ * k8s lexicon's WK8606 runs `prometheusRuleDiagnostics` (below) over them.
  */
 
 import type { PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
@@ -135,3 +135,38 @@ export function routingDiagnostics(ctx: PostSynthContext): PostSynthDiagnostic[]
   const files = ruleFiles.map((r) => r.config);
   return alertmanager.flatMap(({ source, config }) => validateSeverityRouting(files, config).map((i) => toDiagnostic(i, source)));
 }
+
+/**
+ * The rule-file checks (PROM101-PROM107, PROM211, PROM213-PROM219) over the
+ * groups of every `PrometheusRule` in the build, whichever lexicon emitted
+ * it. `spec.groups` is a rule file's `groups`, so `validateRuleFile` reads it
+ * as is. Findings keep their PROM ids and name the PrometheusRule's namespace
+ * and name. PROM212 (runbook URLs) stays opt-in and is not run here.
+ */
+export function prometheusRuleDiagnostics(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const out: PostSynthDiagnostic[] = [];
+  for (const output of ctx.outputs.values()) {
+    const text = typeof output === "string" ? output : (output as SerializerResult).primary;
+    if (!text) continue;
+    let docs: unknown[];
+    try {
+      docs = loadAll(text);
+    } catch {
+      continue;
+    }
+    for (const raw of docs) {
+      const doc = raw as Record<string, any> | null;
+      if (!doc || typeof doc !== "object" || doc.kind !== "PrometheusRule") continue;
+      if (typeof doc.apiVersion !== "string" || !doc.apiVersion.startsWith("monitoring.coreos.com/")) continue;
+      const groups = doc.spec?.groups;
+      if (!Array.isArray(groups)) continue;
+      const name = String(doc.metadata?.name ?? "");
+      const source = `PrometheusRule ${doc.metadata?.namespace ? `${doc.metadata.namespace}/` : ""}${name}`;
+      for (const issue of validateRuleFile({ groups } as RuleFileConfig)) {
+        if (issue.code === "PROM212") continue;
+        out.push({ ...toDiagnostic(issue, source), ...(issue.subject ? {} : { entity: name }) });
+      }
+    }
+  }
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-prometheus",
-  "version": "0.106.4",
+  "version": "0.108.0",
   "description": "Prometheus lexicon for chant — typed recording and alerting rule groups and Alertmanager routing, serialized to a rule file and alertmanager.yml",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -41,6 +41,21 @@
       "types": "./dist/*.d.ts",
       "default": "./src/*.ts"
     },
+    "./api": {
+      "development": "./src/api/index.ts",
+      "types": "./dist/api/index.d.ts",
+      "default": "./src/api/index.ts"
+    },
+    "./op/activities": {
+      "development": "./src/op/activities/index.ts",
+      "types": "./dist/op/activities/index.d.ts",
+      "default": "./src/op/activities/index.ts"
+    },
+    "./op/activity-contracts": {
+      "development": "./src/op/activity-contracts.ts",
+      "types": "./dist/op/activity-contracts.d.ts",
+      "default": "./src/op/activity-contracts.ts"
+    },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
@@ -63,7 +78,8 @@
     "@lezer/highlight": "^1.2.4",
     "@lezer/lr": "^1.4.10",
     "@prometheus-io/lezer-promql": "0.315.0",
-    "js-yaml": "^4.3.1"
+    "js-yaml": "^4.3.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -72,7 +88,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.106.4",
+    "@intentius/chant": "^0.108.0",
     "typescript": "^5.9.3"
   }
 }

package/src/api/alertmanager.ts

@@ -0,0 +1,122 @@
+/**
+ * The Alertmanager config APIs (#3371).
+ *
+ * | Kind | Config | Health |
+ * |---|---|---|
+ * | `alertmanager` | `/api/v2/status` `config.original` | the same answer: `cluster.status`, `versionInfo.version` |
+ * | `mimir`, `cortex` | `/api/v1/alerts` (YAML: `alertmanager_config`, `template_files`) | `<prefix>/api/v2/status`, best effort |
+ *
+ * A plain Alertmanager's `config.original` is not the file it loaded. It is
+ * the loaded config marshalled again (`Config.String()` in Alertmanager's
+ * `config/config.go`): secrets read `<secret>`, the global defaults are
+ * written out, and every receiver carries the settings it inherited from
+ * `global:`. ../import/alertmanager-live.ts takes those back out. Mimir and
+ * Cortex return the config as the tenant uploaded it.
+ *
+ * `setConfig` is for the ruler apply target (#3372): `POST /api/v1/alerts`,
+ * which Mimir and Cortex serve with `-alertmanager.enable-api`. A plain
+ * Alertmanager has no config write API.
+ */
+
+import { dump } from "js-yaml";
+import { loadPrometheusYaml } from "../import/parser";
+import type { AlertmanagerTarget } from "../config";
+import { PromApiError, type PromClient } from "./client";
+
+/** What `/api/v2/status` says about the Alertmanager itself. */
+export interface AlertmanagerHealth {
+  /** `ready`, `settling` or `disabled` (no clustering). */
+  cluster?: string;
+  peers?: number;
+  version?: string;
+}
+
+/** A live Alertmanager config, as text, with where it came from. */
+export interface LiveAlertmanagerConfig {
+  /** The config YAML. */
+  text: string;
+  /** Where it was read. */
+  address: string;
+  /** True when it is Alertmanager's own re-marshalled form (`/api/v2/status`), with defaults written out and secrets masked. */
+  remarshalled: boolean;
+  /** Mimir and Cortex: the notification templates uploaded with it, by file name. */
+  templateFiles?: Record<string, string>;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** A bound Alertmanager: the transport and the target it reaches. */
+export class AlertmanagerApi {
+  constructor(
+    readonly client: PromClient,
+    readonly target: AlertmanagerTarget,
+  ) {}
+
+  /** Where `/api/v2/status` is served. */
+  get statusPath(): string {
+    return this.target.kind === "alertmanager" ? "/api/v2/status" : `${this.target.alertmanagerPrefix}/api/v2/status`;
+  }
+
+  /** The status answer, read once per client; undefined on 404. */
+  private status(): Promise<Record<string, unknown> | undefined> {
+    return this.client.once("status", () => this.client.getJson<Record<string, unknown>>(this.statusPath));
+  }
+
+  /** The loaded config; undefined when there is none (Mimir answers 404 for a tenant with no config). */
+  async readConfig(): Promise<LiveAlertmanagerConfig | undefined> {
+    return this.client.once("config", async () => {
+      if (this.target.kind === "alertmanager") {
+        const status = await this.status();
+        if (status === undefined) return undefined;
+        const original = isObject(status.config) ? status.config.original : undefined;
+        if (typeof original !== "string") throw new PromApiError(502, "GET", this.statusPath, "the status has no config.original");
+        return { text: original, address: this.statusPath, remarshalled: true };
+      }
+      const path = "/api/v1/alerts";
+      const text = await this.client.getText(path);
+      if (text === undefined) return undefined;
+      const doc = loadPrometheusYaml(text);
+      if (!isObject(doc) || typeof doc.alertmanager_config !== "string") {
+        throw new PromApiError(502, "GET", path, "the answer has no alertmanager_config");
+      }
+      const templateFiles = isObject(doc.template_files)
+        ? Object.fromEntries(Object.entries(doc.template_files).map(([k, v]) => [k, String(v)]))
+        : undefined;
+      return {
+        text: doc.alertmanager_config,
+        address: path,
+        remarshalled: false,
+        ...(templateFiles && Object.keys(templateFiles).length > 0 ? { templateFiles } : {}),
+      };
+    });
+  }
+
+  /** Cluster status and version. Never throws: a failed read is no health, since health is an attribute, not presence. */
+  async health(): Promise<AlertmanagerHealth | undefined> {
+    let status: Record<string, unknown> | undefined;
+    try {
+      status = await this.status();
+    } catch {
+      return undefined;
+    }
+    if (!status) return undefined;
+    const cluster = isObject(status.cluster) ? status.cluster : {};
+    const version = isObject(status.versionInfo) ? status.versionInfo.version : undefined;
+    return {
+      ...(typeof cluster.status === "string" ? { cluster: cluster.status } : {}),
+      ...(Array.isArray(cluster.peers) ? { peers: cluster.peers.length } : {}),
+      ...(typeof version === "string" ? { version } : {}),
+    };
+  }
+
+  /** Upload a config (Mimir and Cortex, `POST /api/v1/alerts`, 201). */
+  async setConfig(config: string, templateFiles: Record<string, string> = {}): Promise<void> {
+    if (this.target.kind === "alertmanager") {
+      throw new Error(`a plain Alertmanager (${this.target.source}) has no config API; it reads alertmanager.yml from disk`);
+    }
+    const body = dump({ template_files: templateFiles, alertmanager_config: config }, { lineWidth: -1, noRefs: true });
+    await this.client.send("POST", "/api/v1/alerts", { text: body, contentType: "application/yaml" });
+  }
+}