@intentius/chant-lexicon-grafana 0.98.0 → 0.100.0

package/src/schema-validate.ts

@@ -1,17 +1,36 @@
 /**
  * Validate built Grafana JSON against the vendored schemas at
- * `GRAFANA_SCHEMA_PIN`, offline.
+ * `GRAFANA_SCHEMA_PIN`, with the correction overlay applied, offline.
  *
  * The dashboard is checked against the dashboard schema as it stands. Panel
  * options, `fieldConfig.defaults.custom` and each query are checked against
  * their plugin's schema with every `required` list removed, because Grafana
- * fills in options a panel leaves out: what still fails is a key the schema
- * doesn't have or a value it doesn't allow.
+ * fills in options a panel leaves out.
+ *
+ * Two kinds of problem come back. A value the schema does not allow (a
+ * wrong type, an enum value it does not list, a required field missing) is
+ * an error. A key the pinned schema does not know is a warning: Grafana
+ * adds fields every minor release and keeps what it does not understand, so
+ * an unknown key is more often a newer Grafana than a mistake. To tell the
+ * two apart each value is validated twice, once with every object opened
+ * (`additionalProperties: false` dropped; what fails is an error) and once
+ * as pinned (what fails only for an unknown key is a warning).
+ *
+ * An export shared externally embeds its library panels in `__elements`;
+ * each element's `model` is checked the same way as a panel on the grid.
+ *
+ * `oneOf` is read as `anyOf` throughout. The CUE these schemas come from
+ * has disjunctions, which accept a value matching any branch; cog writes
+ * them as `oneOf`, which rejects a value matching two, and loosely
+ * discriminated unions (a table's `cellOptions: { type: "auto" }` matches
+ * several variants) match more than one.
  */
 
-import Ajv, { type ValidateFunction, type ErrorObject } from "ajv";
+import { createRequire } from "module";
+import type AjvClass from "ajv";
+import type { ValidateFunction, ErrorObject } from "ajv";
 import type { SchemaName } from "./pin";
-import { loadSchema } from "./spec/schemas";
+import { SCHEMA_JSON } from "./spec/schemas.gen";
 import { panelDefinitionFor } from "./panels";
 import { queryDefinitionFor } from "./query";
 
@@ -19,35 +38,94 @@ export interface SchemaProblem {
   /** JSON pointer into the dashboard. */
   path: string;
   message: string;
+  /** `error` for a value the schema does not allow, `warning` for a key it does not know. */
+  severity: "error" | "warning";
 }
 
-let ajv: Ajv | undefined;
-function getAjv(): Ajv {
-  ajv ??= new Ajv({ strict: false, allErrors: true, validateFormats: false });
+let ajv: AjvClass | undefined;
+let ajvError: string | undefined;
+
+/**
+ * ajv, loaded on first use.
+ *
+ * Every `chant build`, `chant lint` and `chant list` loads the plugin, and the
+ * plugin's post-synth barrel reaches this module, so a top-level import would
+ * put ajv on every run that has grafana installed, validating or not.
+ * `check()` is synchronous, so `await import()` is not available;
+ * `createRequire` is (the same as the cedar lexicon's wasm, and ajv is
+ * CommonJS). Where it cannot load (a bundle with no `node_modules` beside
+ * it), {@link schemaValidationUnavailable} says why and GRAF107 reports that
+ * instead of throwing.
+ */
+function getAjv(): AjvClass | undefined {
+  if (ajv || ajvError) return ajv;
+  try {
+    const mod = createRequire(import.meta.url)("ajv") as { default?: typeof AjvClass } & typeof AjvClass;
+    const Ajv = mod.default ?? mod;
+    ajv = new Ajv({ strict: false, allErrors: true, validateFormats: false });
+  } catch (err) {
+    ajvError = (err instanceof Error ? err.message : String(err)).split("\n")[0];
+  }
   return ajv;
 }
 
+/** Why schema validation cannot run here (ajv did not load), or undefined when it can. */
+export function schemaValidationUnavailable(): string | undefined {
+  getAjv();
+  return ajvError === undefined ? undefined : `ajv could not be loaded: ${ajvError}`;
+}
+
+function requireAjv(): AjvClass {
+  const a = getAjv();
+  if (!a) throw new Error(`grafana schema validation: ${schemaValidationUnavailable()}`);
+  return a;
+}
+
+const parsed = new Map<SchemaName, Record<string, unknown>>();
+
+/**
+ * One schema as validation uses it: the vendored file with its overlay
+ * applied, from the generated `spec/schemas.gen.ts` (no filesystem read, so
+ * it works bundled), parsed on first use.
+ */
+export function bundledSchema(name: SchemaName): Record<string, unknown> {
+  let schema = parsed.get(name);
+  if (!schema) {
+    schema = JSON.parse(SCHEMA_JSON[name]) as Record<string, unknown>;
+    parsed.set(name, schema);
+  }
+  return schema;
+}
+
 const compiled = new Map<string, ValidateFunction>();
 
-function stripRequired(node: unknown): unknown {
-  if (Array.isArray(node)) return node.map(stripRequired);
+interface Mode {
+  /** Drop every `required` list (panel options and queries: Grafana fills them in). */
+  lenient: boolean;
+  /** Drop every `additionalProperties: false`, so unknown keys pass. */
+  open: boolean;
+}
+
+function prepare(node: unknown, mode: Mode): unknown {
+  if (Array.isArray(node)) return node.map((n) => prepare(n, mode));
   if (node && typeof node === "object") {
     const out: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(node)) {
-      if (k === "required" && Array.isArray(v)) continue;
-      out[k] = stripRequired(v);
+      if (mode.lenient && k === "required" && Array.isArray(v)) continue;
+      if (mode.open && k === "additionalProperties" && v === false) continue;
+      out[k === "oneOf" && Array.isArray(v) ? "anyOf" : k] = prepare(v, mode);
     }
     return out;
   }
   return node;
 }
 
-/** A validator for one definition of one vendored schema (the root `$ref` when `def` is left out). */
-function validatorFor(name: SchemaName, def: string | undefined, lenient: boolean): ValidateFunction | undefined {
-  const key = `${name}#${def ?? ""}#${lenient}`;
+/** A validator for one definition of one schema (the root `$ref` when `def` is left out). */
+function validatorFor(name: SchemaName, def: string | undefined, mode: Mode): ValidateFunction | undefined {
+  const key = `${name}#${def ?? ""}#${mode.lenient}#${mode.open}`;
   const hit = compiled.get(key);
   if (hit) return hit;
-  const schema = loadSchema(name);
+  const schema = bundledSchema(name);
   const definitions = (schema.definitions ?? {}) as Record<string, unknown>;
   const ref = def ? `#/definitions/${def}` : (schema.$ref as string | undefined);
   if (!ref) return undefined;
@@ -55,31 +133,48 @@ function validatorFor(name: SchemaName, def: string | undefined, lenient: boolea
   const root: Record<string, unknown> = {
     $schema: schema.$schema,
     $ref: ref,
-    definitions: lenient ? stripRequired(definitions) : definitions,
+    definitions: prepare(definitions, mode),
   };
-  const fn = getAjv().compile(root);
+  const fn = requireAjv().compile(root);
   compiled.set(key, fn);
   return fn;
 }
 
-function problems(errors: ErrorObject[] | null | undefined, prefix: string): SchemaProblem[] {
+function describe(e: ErrorObject): string {
+  const extra =
+    e.keyword === "enum" ? `: ${(e.params as { allowedValues: unknown[] }).allowedValues.map((v) => JSON.stringify(v)).join(", ")}` : "";
+  return `${e.message ?? "is invalid"}${extra}`;
+}
+
+/**
+ * Everything wrong with one value against one definition: errors from the
+ * opened schema, then unknown keys from the pinned one.
+ */
+function check(value: unknown, name: SchemaName, def: string | undefined, lenient: boolean, prefix: string): SchemaProblem[] {
+  const open = validatorFor(name, def, { lenient, open: true });
+  const closed = validatorFor(name, def, { lenient, open: false });
+  if (!open || !closed) return [];
   const seen = new Set<string>();
   const out: SchemaProblem[] = [];
-  for (const e of errors ?? []) {
-    // oneOf/anyOf wrappers repeat what their branches already said.
-    if (e.keyword === "oneOf" || e.keyword === "anyOf" || e.keyword === "if") continue;
-    const extra =
-      e.keyword === "additionalProperties"
-        ? ` ("${(e.params as { additionalProperty: string }).additionalProperty}")`
-        : e.keyword === "enum"
-          ? `: ${(e.params as { allowedValues: unknown[] }).allowedValues.map((v) => JSON.stringify(v)).join(", ")}`
-          : "";
-    const path = `${prefix}${e.instancePath}` || "/";
-    const message = `${e.message ?? "is invalid"}${extra}`;
+  const push = (path: string, message: string, severity: SchemaProblem["severity"]) => {
     const k = `${path} ${message}`;
-    if (seen.has(k)) continue;
+    if (seen.has(k)) return;
     seen.add(k);
-    out.push({ path, message });
+    out.push({ path, message, severity });
+  };
+  if (!open(value)) {
+    for (const e of open.errors ?? []) {
+      // anyOf/if wrappers repeat what their branches already said.
+      if (e.keyword === "oneOf" || e.keyword === "anyOf" || e.keyword === "if") continue;
+      push(`${prefix}${e.instancePath}` || "/", describe(e), "error");
+    }
+  }
+  if (!closed(value)) {
+    for (const e of closed.errors ?? []) {
+      if (e.keyword !== "additionalProperties") continue;
+      const key = (e.params as { additionalProperty: string }).additionalProperty;
+      push(`${prefix}${e.instancePath}` || "/", `unknown key "${key}" (not in the pinned schema)`, "warning");
+    }
   }
   return out;
 }
@@ -98,46 +193,93 @@ function panelsOf(dashboard: Json): Array<{ panel: Json; path: string }> {
   return out;
 }
 
-/** Everything in one dashboard that the pinned schemas reject. */
+/** A panel (not a row) against the dashboard's Panel definition and its plugin's options, custom field config and queries. */
+function checkPanel(panel: Json, path: string): SchemaProblem[] {
+  const out = check(panel, "dashboard", "Panel", false, path);
+  const def = typeof panel.type === "string" ? panelDefinitionFor(panel.type) : undefined;
+  if (def?.schema) {
+    if (panel.options !== undefined) out.push(...check(panel.options, def.schema, "Options", true, `${path}/options`));
+    const custom = (panel.fieldConfig as { defaults?: { custom?: unknown } } | undefined)?.defaults?.custom;
+    if (custom !== undefined) out.push(...check(custom, def.schema, "FieldConfig", true, `${path}/fieldConfig/defaults/custom`));
+  }
+  const panelType = (panel.datasource as { type?: string } | undefined)?.type;
+  const targets = Array.isArray(panel.targets) ? (panel.targets as Json[]) : [];
+  targets.forEach((t, k) => {
+    const type = (t?.datasource as { type?: string } | undefined)?.type ?? panelType;
+    const qdef = type ? queryDefinitionFor(type) : undefined;
+    if (!qdef?.schema) return;
+    out.push(...check(t, qdef.schema, undefined, true, `${path}/targets/${k}`));
+  });
+  return out;
+}
+
+/** `LibraryElementKind.Panel` (public/app/features/library-panels/types.ts:8-10 at v13.2.2, its only member). */
+const LIBRARY_PANEL_KIND = 1;
+
+/**
+ * The library panel models an external export embeds in `__elements`. The
+ * envelope check covers each element's own fields (uid, name, kind, model
+ * present); the model is a whole panel, checked like one.
+ */
+function libraryPanelModels(dashboard: Json): Array<{ panel: Json; path: string }> {
+  const elements = dashboard.__elements;
+  if (!elements || typeof elements !== "object" || Array.isArray(elements)) return [];
+  const out: Array<{ panel: Json; path: string }> = [];
+  for (const [key, el] of Object.entries(elements as Record<string, unknown>)) {
+    if (!el || typeof el !== "object") continue;
+    const { kind, model } = el as { kind?: unknown; model?: unknown };
+    if (kind !== undefined && kind !== LIBRARY_PANEL_KIND) continue;
+    if (!model || typeof model !== "object" || Array.isArray(model)) continue;
+    out.push({ panel: model as Json, path: `/__elements/${key.replace(/~/g, "~0").replace(/\//g, "~1")}/model` });
+  }
+  return out;
+}
+
+/** Everything in one dashboard that the pinned schemas reject or do not know. */
 export function validateDashboardSchema(dashboard: Json): SchemaProblem[] {
   const out: SchemaProblem[] = [];
   // The envelope and each panel are checked separately: the schema's
   // `oneOf [Panel, RowPanel]` would otherwise report every panel error twice,
   // once per branch.
-  const whole = validatorFor("dashboard", undefined, false)!;
   const envelope = Array.isArray(dashboard.panels) ? { ...dashboard, panels: [] } : dashboard;
-  if (!whole(envelope)) out.push(...problems(whole.errors, ""));
-  const panelSchema = validatorFor("dashboard", "Panel", false)!;
-  const rowSchema = validatorFor("dashboard", "RowPanel", false)!;
+  out.push(...check(envelope, "dashboard", undefined, false, ""));
 
   for (const { panel, path } of panelsOf(dashboard)) {
     if (!panel || typeof panel !== "object") {
-      out.push({ path, message: "must be object" });
+      out.push({ path, message: "must be object", severity: "error" });
       continue;
     }
     if (panel.type === "row") {
       const header = Array.isArray(panel.panels) ? { ...panel, panels: [] } : panel;
-      if (!rowSchema(header)) out.push(...problems(rowSchema.errors, path));
+      out.push(...check(header, "dashboard", "RowPanel", false, path));
       continue;
     }
-    if (!panelSchema(panel)) out.push(...problems(panelSchema.errors, path));
-    const def = typeof panel.type === "string" ? panelDefinitionFor(panel.type) : undefined;
-    if (def?.schema) {
-      const options = validatorFor(def.schema, "Options", true);
-      if (options && panel.options !== undefined && !options(panel.options)) out.push(...problems(options.errors, `${path}/options`));
-      const custom = (panel.fieldConfig as { defaults?: { custom?: unknown } } | undefined)?.defaults?.custom;
-      const fc = validatorFor(def.schema, "FieldConfig", true);
-      if (fc && custom !== undefined && !fc(custom)) out.push(...problems(fc.errors, `${path}/fieldConfig/defaults/custom`));
-    }
-    const panelType = (panel.datasource as { type?: string } | undefined)?.type;
-    const targets = Array.isArray(panel.targets) ? (panel.targets as Json[]) : [];
-    targets.forEach((t, k) => {
-      const type = (t?.datasource as { type?: string } | undefined)?.type ?? panelType;
-      const qdef = type ? queryDefinitionFor(type) : undefined;
-      if (!qdef?.schema) return;
-      const v = validatorFor(qdef.schema, undefined, true);
-      if (v && !v(t)) out.push(...problems(v.errors, `${path}/targets/${k}`));
-    });
+    out.push(...checkPanel(panel, path));
   }
+  for (const { panel, path } of libraryPanelModels(dashboard)) out.push(...checkPanel(panel, path));
   return out;
 }
+
+/** The `expr` schema definition for each server-side expression type. */
+const EXPRESSION_DEFINITIONS: Record<string, string> = {
+  math: "TypeMath",
+  reduce: "TypeReduce",
+  resample: "TypeResample",
+  classic_conditions: "TypeClassicConditions",
+  threshold: "TypeThreshold",
+  sql: "TypeSql",
+};
+
+/**
+ * Check one server-side expression model (an alert rule's `data[].model`
+ * whose datasource is `__expr__`) against the pinned `expr` schema, as
+ * written: its `type` picks the definition, and every required field must
+ * be there, since Grafana fills none in.
+ */
+export function validateExpressionSchema(model: Json, prefix = ""): SchemaProblem[] {
+  const def = typeof model.type === "string" ? EXPRESSION_DEFINITIONS[model.type] : undefined;
+  if (!def) {
+    return [{ path: `${prefix}/type`, message: `is ${JSON.stringify(model.type)}, not one of ${Object.keys(EXPRESSION_DEFINITIONS).join(", ")}`, severity: "error" }];
+  }
+  return check(model, "expr", def, false, prefix);
+}

package/src/schema.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, test } from "vitest";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { GRAFANA_SCHEMA_PIN, SCHEMA_NAMES, schemaUrl } from "./pin";
+import { GRAFANA_SCHEMA_PIN, SCHEMA_NAMES, VENDORED_SCHEMA_NAMES, schemaUrl } from "./pin";
 import { digestMismatches, loadSchema } from "./spec/schemas";
 import { schemaModules } from "./codegen/generate";
 import { schemaModule, tsType } from "./codegen/schema-types";
@@ -13,7 +13,9 @@ const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
 describe("the schema pin", () => {
   test("names a commit and a digest for every vendored schema", () => {
     expect(GRAFANA_SCHEMA_PIN.commit).toMatch(/^[0-9a-f]{40}$/);
-    expect(Object.keys(GRAFANA_SCHEMA_PIN.files).sort()).toEqual([...SCHEMA_NAMES].sort());
+    expect(Object.keys(GRAFANA_SCHEMA_PIN.files).sort()).toEqual([...VENDORED_SCHEMA_NAMES].sort());
+    // Types come from the classic schemas only; dashboardv2 is vendored for the importer (#2947).
+    expect(VENDORED_SCHEMA_NAMES.filter((n) => !(SCHEMA_NAMES as readonly string[]).includes(n))).toEqual(["dashboardv2"]);
     expect(schemaUrl("stat")).toBe(`https://raw.githubusercontent.com/grafana/grafana-foundation-sdk/${GRAFANA_SCHEMA_PIN.commit}/jsonschema/stat.jsonschema.json`);
   });
 

package/src/serializer.test.ts

@@ -7,7 +7,7 @@ import { load } from "js-yaml";
 import type { Declarable } from "@intentius/chant/declarable";
 import type { SerializerResult } from "@intentius/chant/serializer";
 import { grafanaSerializer } from "./serializer";
-import { Datasource } from "./datasource";
+import { Datasource, ExternalDatasource } from "./datasource";
 import { Dashboard, DashboardProvider } from "./dashboard";
 import { StatPanel, TimeSeriesPanel } from "./panels";
 import { PromQuery } from "./query";
@@ -150,6 +150,18 @@ describe("grafana serializer", () => {
     expect(JSON.parse(out.primary).files).toEqual(Object.keys(out.files!).sort());
   });
 
+  test("an ExternalDatasource is referenced by uid, in panels and in another datasource's settings, and not provisioned", () => {
+    const loki = new ExternalDatasource({ type: "loki", uid: "loki-prod", name: "Loki (prod)" });
+    const tempo = new Datasource({ name: "Tempo", type: "tempo", jsonData: { tracesToLogsV2: { datasourceUid: loki } } });
+    const logs = new StatPanel({ datasource: loki });
+    const out = run({ loki, tempo, d: new Dashboard({ title: "D", panels: [logs] }) });
+    expect(JSON.parse(out.files!["dashboards/d.json"]).panels[0].datasource).toEqual({ type: "loki", uid: "loki-prod" });
+    const ds = load(out.files![DATASOURCES_FILE]) as { datasources: Array<{ name: string; jsonData?: unknown }> };
+    expect(ds.datasources.map((d) => d.name)).toEqual(["Tempo"]);
+    expect(ds.datasources[0].jsonData).toEqual({ tracesToLogsV2: { datasourceUid: "loki-prod" } });
+    expect(JSON.parse(out.primary).externalDatasources).toEqual([{ type: "loki", uid: "loki-prod", name: "Loki (prod)" }]);
+  });
+
   test("round trip: the emitted text parses back to the declared values", () => {
     const panel = new TimeSeriesPanel({ title: "Rate", datasource: prometheus, targets: [up], interval: "30s" });
     const out = run({ d: new Dashboard({ title: "Round trip", description: "desc", tags: ["a", "b"], panels: [panel] }) });

package/src/serializer.ts

@@ -9,13 +9,21 @@
  * - `provisioning/datasources/chant.yaml`: every declared datasource.
  * - `provisioning/dashboards/chant.yaml`: the provider that loads the
  *   dashboard files, a default one unless a `DashboardProvider` is declared.
+ * - `provisioning/alerting/chant.yaml`: rule groups, contact points, the
+ *   notification policy tree, mute timings and templates, when the build
+ *   declares any (see `alerting-build.ts`).
  *
  * Mount `provisioning/` at `/etc/grafana/provisioning` and `dashboards/` at
  * the provider's path (`/var/lib/grafana/dashboards` by default).
  *
- * The primary output is a small JSON index of what was built. Grafana's
- * files have no metadata channel chant could use without changing what
- * Grafana imports, so no ownership marker is stamped.
+ * The primary output is a small JSON index of what was built. The dashboard
+ * JSON carries no ownership marker, because Grafana keeps who manages a
+ * dashboard outside it, in the resource's metadata on its
+ * `dashboard.grafana.app` API. For a file-provisioned dashboard that metadata
+ * is the `grafana.app/managerId` annotation Grafana writes, whose value is the
+ * provider name in `provisioning/dashboards/chant.yaml`: `chant` unless a
+ * `DashboardProvider` names another. That name is the marker chant stamps at
+ * synthesis, and ./ownership.ts reads it back.
  */
 
 import type { Declarable } from "@intentius/chant/declarable";

package/src/skill-defs.ts

@@ -28,4 +28,38 @@ export const grafanaSkills = createSkillsLoader(import.meta.url, [
     description: "Load chant-built Grafana dashboards and datasources into a running Grafana through its provisioning directories, in Docker or Kubernetes",
     triggers: [{ type: "context" as const, value: "grafana provisioning" }],
   },
+  {
+    file: "chant-grafana-alerting.md",
+    name: "chant-grafana-alerting",
+    description:
+      "Declare Grafana-managed alert rules, server-side expressions, contact points, notification policies and mute timings, turn an Slo into burn-rate rules, and import Grafana's alerting exports",
+    triggers: [
+      { type: "context" as const, value: "grafana alerting" },
+      { type: "context" as const, value: "grafana alert rule" },
+      { type: "context" as const, value: "contact point" },
+    ],
+    examples: [
+      {
+        title: "An SLO's burn-rate alerts as Grafana-managed rules",
+        output: 'export const checkoutBurn = SloAlertRules({ slo: checkout, datasource: prometheus, folder: "SLOs" });',
+      },
+    ],
+  },
+  {
+    file: "chant-grafana-operations.md",
+    name: "chant-grafana-operations",
+    description:
+      "Start a Grafana project from a template, bring existing dashboards into chant with chant import, find what changed in a running Grafana with chant lifecycle diff --live, export a Grafana as TypeScript, and apply a build over the HTTP API",
+    triggers: [
+      { type: "context" as const, value: "grafana drift" },
+      { type: "context" as const, value: "import grafana dashboard" },
+      { type: "context" as const, value: "grafana apply" },
+    ],
+    examples: [
+      {
+        title: "See what was edited in a running Grafana since the last build",
+        output: "chant lifecycle diff staging --live",
+      },
+    ],
+  },
 ]);

package/src/skills/chant-grafana-alerting.md

@@ -0,0 +1,49 @@
+---
+skill: chant-grafana-alerting
+description: Declare Grafana-managed alert rules, server-side expressions, contact points, notification policies and mute timings with chant, turn an Slo into burn-rate rules, and import Grafana's alerting exports
+user-invocable: true
+---
+
+# Grafana-managed alerting with chant
+
+Everything is written to `provisioning/alerting/chant.yaml`, Grafana's alerting provisioning file. Mount `dist/grafana/provisioning` at `/etc/grafana/provisioning`.
+
+## A rule
+
+```ts
+import { AlertRule, AlertRuleGroup, PromQuery, ReduceExpression, ThresholdExpression } from "@intentius/chant-lexicon-grafana";
+
+const errors = new PromQuery({ datasource: prometheus, expr: 'sum(rate(http_requests_total{code=~"5.."}[5m]))', instant: true });
+const last = new ReduceExpression({ expression: "A", reducer: "last" });
+const high = new ThresholdExpression({ expression: "B", conditions: [{ evaluator: { type: "gt", params: [5] } }] });
+const rule = new AlertRule({ title: "5xx above 5/s", uid: "checkout-5xx", data: [errors, last, high], for: "5m", labels: { severity: "page" } });
+export const checkoutAlerts = new AlertRuleGroup({ name: "checkout", folder: "Checkout", interval: "1m", rules: [rule] });
+```
+
+- refIds follow `data` order (A, B, C); expressions name inputs by refId (`"A"`, or `$A` in a `MathExpression`). `condition` defaults to the last refId.
+- Queries need a `Datasource`, `ExternalDatasource` or `{ type, uid }`; never a `DatasourceVariable`.
+- Any plugin's model: `new AlertQuery({ datasource, model: { ... } })`. A typed query with its own range: `new AlertQuery({ query, relativeTimeRange: { from: "5m" } })`.
+- Set `uid` explicitly on rules whose title may change.
+
+## Notifications
+
+- `ContactPoint({ name, receivers: [{ type: "slack", settings: { url: "$__env{SLACK_URL}" } }] })`. Secrets always as `$__env{...}` or `$__file{...}`; GRAF002 flags literals.
+- `NotificationPolicy({ receiver: oncall, routes: [{ receiver: tickets, object_matchers: [["severity", "=", "ticket"]], mute_time_intervals: [weekends] }] })`. One per organisation: it replaces the whole tree.
+- `MuteTiming({ name: "weekends", time_intervals: [{ weekdays: ["saturday", "sunday"] }] })`, `NotificationTemplate({ name, template })`.
+- Pass entities rather than names where you can; GRAF113 checks names against what the build declares.
+
+## An SLO's burn-rate alerts
+
+```ts
+export const checkoutBurn = SloAlertRules({ slo: checkout, datasource: prometheus, folder: "SLOs" });
+```
+
+One rule per window pair, reading the `Slo`'s recorded `slo:sli_error:ratio_rate<window>` series, so the `Slo`'s Prometheus rule group must be loaded. Rules carry `severity: page|ticket` for the policy tree, or pass `contactPoint`.
+
+## Import
+
+`chant import alert-rules.yaml` reads a provisioning file or Grafana's export (`/api/v1/provisioning/alert-rules/export?format=yaml`, and the contact-points, policies and mute-timings exports). Read every warning: guessed datasource types, `[REDACTED]` secrets turned into `$__env{...}`, and delete/reset lists that are not carried.
+
+## Checks
+
+GRAF108 (PromQL), GRAF111 (condition and expression refIds), GRAF112 (datasources), GRAF113 (contact points, mute timings, matchers), GRAF114 (uids, intervals as multiples of 10s, duplicates).

package/src/skills/chant-grafana-operations.md

@@ -0,0 +1,108 @@
+---
+skill: chant-grafana-operations
+description: Start a Grafana project from a template, bring existing dashboards into chant with chant import, find what changed in a running Grafana with chant lifecycle diff --live, export a Grafana as TypeScript, and apply a build over the HTTP API
+user-invocable: true
+---
+
+# Operating Grafana with chant
+
+Use this skill when a Grafana already exists: dashboards made in the UI to bring under chant, a provisioned dashboard somebody edited, or a build to push without mounting files. For writing dashboards see the chant-grafana skill; for provisioning files and ConfigMaps, chant-grafana-provisioning; for alert rules, chant-grafana-alerting.
+
+## Start a project
+
+```bash
+chant init --lexicon grafana my-dashboards                      # a Prometheus datasource and one dashboard
+chant init --lexicon grafana --template red my-dashboards       # RedDashboard over span metrics, ExternalDatasource, Folder
+chant init --lexicon grafana --template k8s-pods my-dashboards  # pod dashboard delivered as sidecar ConfigMaps (k8s + grafana)
+chant init --lexicon grafana --template slo my-dashboards       # Slo rules, SloDashboard and SloAlertRules (prometheus + grafana)
+```
+
+Every template builds clean and passes the GRAF checks as written. `k8s-pods` and `slo` ship a `chant.config.ts` naming both lexicons and a `build` script without `--lexicon`, so both outputs and both lexicons' checks run.
+
+## Import dashboards you already have
+
+Export the dashboard in Grafana (Export > Export as JSON, classic or V2 resource), then:
+
+```bash
+chant import checkout.json --output src                      # inside a project that lists grafana
+chant import checkout.json --lexicon grafana --output src    # anywhere else
+chant build src --lexicon grafana -o dist/grafana/index.json
+```
+
+The importer also reads `GET /api/dashboards/uid/<uid>` responses, `dashboard.grafana.app` v1 and v2 resources, and datasource, dashboard and alerting provisioning files. Each dashboard lands in `src/<uid>/`: `dashboard.ts`, `panels.ts`, one `row-<title>.ts` per row, `variables.ts`, and `datasources.ts` with an `ExternalDatasource` per datasource named by uid. Replace an `ExternalDatasource` with a `Datasource` of the same uid to provision it from chant too.
+
+Read every import warning. Anything the lexicon can't express is reported, never dropped. Common ones: a v2 dashboard's tabs become rows, an export made for sharing turns `${DS_*}` inputs into `DatasourceVariable`s, and two imported dashboards naming one datasource both declare it (GRAF104; delete one declaration and import it from the other file).
+
+A dashboard inside a Kubernetes ConfigMap imports with the k8s lexicon: `chant import grafana-configmaps.yaml` gives a grafana `Dashboard` as the ConfigMap's value.
+
+## Point environments at a Grafana
+
+Observe, export and apply read `grafana.profiles.<env>` in `chant.config.ts`. Credentials are named by environment variable, never written in the file:
+
+```ts
+import type { ChantConfig } from "@intentius/chant/config";
+import "@intentius/chant-lexicon-grafana";
+
+export default {
+  lexicons: ["grafana"],
+  ownership: { stack: "shop", env: "prod" },
+  grafana: {
+    profiles: {
+      staging: { url: "https://grafana.staging.example.com", token: { env: "GRAFANA_STAGING_TOKEN" } },
+      prod: { url: "https://grafana.example.com", token: { env: "GRAFANA_PROD_TOKEN" }, orgId: 2 },
+    },
+  },
+} satisfies ChantConfig;
+```
+
+With no profile, `GRAFANA_URL` plus `GRAFANA_TOKEN` (or `GRAFANA_USER` and `GRAFANA_PASSWORD`) is used. Grafana Cloud also needs `namespace: "stacks-<id>"`. A Viewer service account can observe and export. Applying needs Editor, or a custom role with `grafanaActionsFor("Apply", "Prune")`.
+
+## Find what changed in Grafana
+
+```bash
+chant lifecycle diff staging --live
+chant lifecycle diff staging --live --json              # the same report as data
+chant lifecycle diff staging --live --update-baseline   # accept what it reported
+```
+
+Paths are in your source's terms: `panels[0].panels[1].title` is the second panel of the first row. A value you declared that differs is drift. A value you never declared, such as a panel added in the UI, is listed as unclaimed and never proposed as a change. What the build fills in (panel ids, auto grid positions, refIds) and what Grafana adds on read are not reported. A dashboard Grafana 13 stores as v2 is read at v2 and diffed after conversion, so a tab added in the UI shows as drift in the rows.
+
+Ownership decides what counts as chant's. A dashboard loaded by one of the project's providers (named `chant` unless you declared another `DashboardProvider`), or carrying the `app.kubernetes.io/managed-by: chant` label the applier writes, is `owned`. Anything else is `foreign`. Datasources and dashboards on Grafana 11 are `unknown`, and `--owned` leaves them out.
+
+A `DashboardProvider` can't be observed (Grafana serves no API for provisioning files) and is reported as not observed, not missing.
+
+## Export a Grafana as TypeScript
+
+```bash
+chant import --from staging --lexicon grafana --output src
+chant import --from staging --lexicon grafana --type Grafana::Dashboard --name checkout --output src
+chant import --from staging --lexicon grafana --owned --output src
+```
+
+It writes every dashboard and datasource in the organisation, laid out like a file import. Datasource secrets come back as `"[REDACTED]"`, each with a warning. Replace them with `$__env{NAME}` or `$__file{path}`, which GRAF002 requires.
+
+## Apply over the HTTP API
+
+When the build's files can't be mounted into Grafana, or you want real folders with pinned uids, apply from an Op:
+
+```ts
+// ops/grafana.op.ts, with "build:grafana": "chant build src --lexicon grafana -o dist/grafana.json" in package.json
+import { Op, phase, build } from "@intentius/chant/op";
+import { grafanaApply } from "@intentius/chant-lexicon-grafana";
+
+export default Op({
+  name: "grafana-prod",
+  phases: [
+    phase("Build", [build(".", { script: "build:grafana" })]),
+    phase("Apply", [grafanaApply("dist/grafana.json", { environment: "prod", prune: true })]),
+  ],
+});
+```
+
+Run it with `chant run grafana-prod`, or from an agent through the MCP `op-run`, `op-status` and `op-signal` tools. The applier creates folders parents first with their uids, writes library panels found in `__elements`, and sends each dashboard with the project's labels. A dashboard whose live content already matches is `unchanged` and not written; a panel title edited in the UI is put back. `prune` deletes only dashboards and folders labelled with this project's stack and env. It never touches UI-saved or file-provisioned dashboards, library panels, or anything on Grafana 11, and does nothing when no `ownership.stack` is set. Datasources still come from the provisioning file.
+
+## A loop that keeps UI edits
+
+1. `chant lifecycle diff prod --live` shows the edit.
+2. Either change the source to match and rebuild, or `chant import --from prod --name <uid>` to pull the dashboard, then copy the changed panel over.
+3. Apply, or let provisioning reload, and diff again. It should report nothing.

package/src/skills/chant-grafana-provisioning.md

@@ -25,7 +25,7 @@ docker run -p 3000:3000 \
 
 ## Kubernetes
 
-Put the two provisioning files in one ConfigMap mounted at `/etc/grafana/provisioning/datasources` and `/etc/grafana/provisioning/dashboards` (a `subPath` each, or two ConfigMaps), and the dashboard JSON in another mounted at `/var/lib/grafana/dashboards`. `grafanaFiles(entities)` returns every file by path, so a k8s composite can build those ConfigMaps from the same declarations without a second build.
+Use `GrafanaConfigMaps({ entities, namespace })` from `@intentius/chant-lexicon-grafana/k8s` in a k8s build root. It writes one ConfigMap per dashboard labelled `grafana_dashboard: "1"`, with the folder in the `k8s-sidecar-target-directory` annotation. The datasource file goes in a ConfigMap labelled `grafana_datasource: "1"`, and the provider file in a third. The Grafana Helm chart's sidecar picks these up as they are. For a Grafana without the sidecar, spread `grafanaVolumes({ entities })`'s `volumes` and `volumeMounts` into the Deployment: provisioning goes under `/etc/grafana/provisioning`, and each dashboard folder gets a projected volume of its own. `grafanaFiles(entities)` still returns every file by path for any other layout.
 
 ## Changing where dashboards live
 
@@ -35,8 +35,8 @@ Declare a `DashboardProvider` to change the mount path, pin a folder, or allow U
 export const provider = new DashboardProvider({ name: "team", path: "/dashboards", allowUiUpdates: true });
 ```
 
-With no provider declared, chant writes one named `chant` that reads `/var/lib/grafana/dashboards` and maps subdirectories to folders.
+With no provider declared, chant writes one named `chant` that reads `/var/lib/grafana/dashboards` and maps subdirectories to folders. A provider with `folder` set puts every dashboard in that folder and ignores the dashboards' own `folder`; GRAF109 warns. Two providers on the same or nested paths load every dashboard twice, which GRAF109 reports as an error. A dashboard `folder` of `"Platform/Kubernetes"` nests on Grafana 13.1 and later.
 
 ## Checking before Grafana does
 
-`chant lint` and `chant build` run GRAF101-GRAF107 on the output, including a check against Grafana's dashboard schema at the pinned version. To check against a real Grafana, the lexicon's `import.test.ts` boots `grafana/grafana` with Docker, provisions the example and reads each dashboard back over the HTTP API.
+`chant lint` and `chant build` run the GRAF1xx checks on the output, including a check against Grafana's dashboard schema at the pinned version, a PromQL syntax check on every query sent to a Prometheus, and a check that the providers put each dashboard in its declared folder, once. To check against a real Grafana, the lexicon's `import.test.ts` boots `grafana/grafana` with Docker, provisions the example and reads each dashboard back over the HTTP API.