@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/api/fake-grafana-writes.ts

@@ -0,0 +1,201 @@
+/**
+ * A Grafana that remembers writes, in memory, for the applier's tests
+ * (#2948). The read-only fake (./fake-grafana.ts) serves a fixed state for
+ * observe and export; this one serves the routes the applier writes to and
+ * keeps what it was sent, so a second apply sees the first one's result.
+ *
+ * It behaves as Grafana 12.4.11 and 13.2.2 did when the applier was checked
+ * against them (../op/activities/grafana-apply.e2e.test.ts): `POST` to an
+ * existing name is a 409, `PUT` needs no `resourceVersion`, a stored
+ * dashboard gets the built-in annotation and Grafana's defaults
+ * (`storedDashboard`), a folder with anything in it cannot be deleted over
+ * `/apis`, and a library element update needs its `version`. With
+ * `api: "legacy"` it is a Grafana 11: no `/apis` groups, dashboards over
+ * `/api/dashboards/db` and `/api/dashboards/uid`, folders over `/api/folders`.
+ */
+
+import type { GrafanaHttp, GrafanaResponse } from "./client";
+import { storedDashboard } from "./fake-grafana";
+
+type Json = Record<string, unknown>;
+
+function isObject(v: unknown): v is Json {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+export interface StoredResource {
+  spec: Json;
+  labels: Record<string, string>;
+  annotations: Record<string, string>;
+}
+
+export interface WritableGrafanaState {
+  /** `v1` (13.x), `v1beta1` (12.4), or `legacy` (11.x). */
+  api: "v1" | "v1beta1" | "legacy";
+  dashboards: Record<string, StoredResource>;
+  /** Folders by uid; `spec.title` is the title and the `grafana.app/folder` annotation the parent. */
+  folders: Record<string, StoredResource>;
+  libraryElements: Record<string, Json>;
+  namespace?: string;
+  /** Answer every request with this status (a refused token: 401). */
+  status?: number;
+}
+
+export function emptyGrafana(api: WritableGrafanaState["api"]): WritableGrafanaState {
+  return { api, dashboards: {}, folders: {}, libraryElements: {} };
+}
+
+/** What Grafana fills in on a dashboard it stores, beyond `storedDashboard`. */
+const DASHBOARD_DEFAULTS: Json = { editable: true, fiscalYearStartMonth: 0, graphTooltip: 0, links: [], templating: { list: [] }, timepicker: {}, timezone: "", weekStart: "" };
+
+function store(spec: Json): Json {
+  return { ...DASHBOARD_DEFAULTS, ...storedDashboard(spec) };
+}
+
+const ok = (json: unknown, status = 200): GrafanaResponse => ({ status, json });
+const notFound: GrafanaResponse = { status: 404, json: { message: "not found" } };
+
+/**
+ * A {@link GrafanaHttp} over `state`, which it changes as it is written to.
+ * Every request is recorded in `calls` as `METHOD path`.
+ */
+export function writableGrafana(state: WritableGrafanaState, calls: string[] = []): GrafanaHttp {
+  const ns = state.namespace ?? "default";
+  const apis = state.api !== "legacy";
+  const dashRoute = new RegExp(`^/apis/dashboard\\.grafana\\.app/${state.api}/namespaces/${ns}/dashboards(?:/([^/]+))?$`);
+  const folderRoute = new RegExp(`^/apis/folder\\.grafana\\.app/${state.api}/namespaces/${ns}/folders(?:/([^/]+))?$`);
+
+  const resource = (kind: string, group: string, uid: string, r: StoredResource): Json => ({
+    apiVersion: `${group}/${state.api}`,
+    kind,
+    metadata: { name: uid, namespace: ns, resourceVersion: "1", labels: { "grafana.app/deprecatedInternalID": "1", ...r.labels }, annotations: r.annotations },
+    spec: r.spec,
+    ...(kind === "Dashboard" ? { status: { conversion: { failed: false, storedVersion: "v0alpha1" } } } : {}),
+  });
+  const metadataOf = (body: unknown): { name: string; labels: Record<string, string>; annotations: Record<string, string> } => {
+    const m = isObject(body) && isObject(body.metadata) ? body.metadata : {};
+    const strings = (v: unknown) => (isObject(v) ? (Object.fromEntries(Object.entries(v).filter(([, x]) => typeof x === "string")) as Record<string, string>) : {});
+    const labels = strings(m.labels);
+    delete labels["grafana.app/deprecatedInternalID"];
+    return { name: typeof m.name === "string" ? m.name : "", labels, annotations: strings(m.annotations) };
+  };
+  const parentOf = (r: StoredResource) => r.annotations["grafana.app/folder"] ?? "";
+  const counts = (uid: string) => ({
+    dashboards: Object.values(state.dashboards).filter((d) => parentOf(d) === uid).length,
+    folders: Object.values(state.folders).filter((f) => parentOf(f) === uid).length,
+    librarypanels: Object.values(state.libraryElements).filter((e) => e.folderUid === uid).length,
+    alertrules: 0,
+  });
+
+  return async (method, path, body) => {
+    calls.push(`${method} ${path}`);
+    if (state.status !== undefined) return { status: state.status, json: { message: "refused" } };
+    const [route] = path.split("?");
+
+    if (route === "/apis/dashboard.grafana.app") {
+      if (!apis) return notFound;
+      const versions = state.api === "v1" ? ["v2", "v0alpha1", "v1", "v1beta1"] : ["v1beta1", "v0alpha1", "v2beta1"];
+      return ok({ kind: "APIGroup", versions: versions.map((version) => ({ version })) });
+    }
+    if (route === "/apis/folder.grafana.app") {
+      if (!apis) return notFound;
+      return ok({ kind: "APIGroup", versions: (state.api === "v1" ? ["v1", "v1beta1"] : ["v1beta1"]).map((version) => ({ version })) });
+    }
+
+    for (const [re, kind, group, table] of [
+      [dashRoute, "Dashboard", "dashboard.grafana.app", state.dashboards],
+      [folderRoute, "Folder", "folder.grafana.app", state.folders],
+    ] as const) {
+      const m = apis ? re.exec(route) : null;
+      if (!m) continue;
+      const uid = m[1] ? decodeURIComponent(m[1]) : undefined;
+      if (!uid) {
+        if (method === "GET") return ok({ items: Object.entries(table).map(([u, r]) => resource(kind, group, u, r)), metadata: {} });
+        if (method === "POST") {
+          const meta = metadataOf(body);
+          if (table[meta.name]) return { status: 409, json: { message: "already exists" } };
+          const spec = isObject(body) && isObject(body.spec) ? body.spec : {};
+          table[meta.name] = { spec: kind === "Dashboard" ? store(spec) : spec, labels: meta.labels, annotations: meta.annotations };
+          return ok(resource(kind, group, meta.name, table[meta.name]), 201);
+        }
+        return { status: 405, json: {} };
+      }
+      const r = table[uid];
+      if (method === "GET") return r ? ok(resource(kind, group, uid, r)) : notFound;
+      if (method === "PUT") {
+        const meta = metadataOf(body);
+        const spec = isObject(body) && isObject(body.spec) ? body.spec : {};
+        table[uid] = { spec: kind === "Dashboard" ? store(spec) : spec, labels: meta.labels, annotations: meta.annotations };
+        return ok(resource(kind, group, uid, table[uid]), r ? 200 : 201);
+      }
+      if (method === "DELETE") {
+        if (!r) return notFound;
+        if (kind === "Folder" && Object.values(counts(uid)).some((n) => n > 0)) return { status: 400, json: { message: "Folder cannot be deleted: folder is not empty" } };
+        delete table[uid];
+        return ok({ status: "Success" });
+      }
+    }
+
+    const counted = /^\/api\/folders\/([^/]+)\/counts$/.exec(route);
+    if (counted) return state.folders[decodeURIComponent(counted[1])] ? ok(counts(decodeURIComponent(counted[1]))) : notFound;
+
+    // Legacy dashboards and folders (Grafana 11; 12.4 and 13.2 still serve them).
+    const legacyDash = /^\/api\/dashboards\/uid\/([^/]+)$/.exec(route);
+    if (legacyDash && method === "GET") {
+      const uid = decodeURIComponent(legacyDash[1]);
+      const d = state.dashboards[uid];
+      if (!d) return notFound;
+      return ok({ dashboard: { ...d.spec, uid, id: 7, version: 3 }, meta: { folderUid: parentOf(d), provisioned: false } });
+    }
+    if (route === "/api/dashboards/db" && method === "POST" && isObject(body) && isObject(body.dashboard)) {
+      const { uid, id: _id, version: _v, ...spec } = body.dashboard;
+      const folderUid = typeof body.folderUid === "string" ? body.folderUid : "";
+      const prior = state.dashboards[String(uid)];
+      state.dashboards[String(uid)] = { spec, labels: prior?.labels ?? {}, annotations: folderUid ? { "grafana.app/folder": folderUid } : {} };
+      return ok({ status: "success", uid, version: 1 });
+    }
+    if (route === "/api/search") return ok(Object.keys(state.dashboards).map((uid) => ({ uid, type: "dash-db" })));
+    const legacyFolder = /^\/api\/folders\/([^/]+)(\/move)?$/.exec(route);
+    if (legacyFolder) {
+      const uid = decodeURIComponent(legacyFolder[1]);
+      const f = state.folders[uid];
+      if (!f) return notFound;
+      if (legacyFolder[2] && method === "POST" && isObject(body)) {
+        f.annotations = typeof body.parentUid === "string" && body.parentUid ? { "grafana.app/folder": body.parentUid } : {};
+        return ok({ uid });
+      }
+      if (method === "GET") return ok({ uid, title: f.spec.title, version: 1, ...(parentOf(f) ? { parentUid: parentOf(f) } : {}) });
+      if (method === "PUT" && isObject(body)) {
+        f.spec = { title: body.title };
+        return ok({ uid, title: body.title });
+      }
+    }
+    if (route === "/api/folders" && method === "POST" && isObject(body)) {
+      const uid = String(body.uid);
+      if (state.folders[uid]) return { status: 409, json: { message: "a folder with that uid already exists" } };
+      state.folders[uid] = { spec: { title: body.title }, labels: {}, annotations: typeof body.parentUid === "string" && body.parentUid ? { "grafana.app/folder": body.parentUid } : {} };
+      return ok({ uid, title: body.title });
+    }
+
+    // Library elements: the same on every version.
+    if (route === "/api/library-elements" && method === "POST" && isObject(body)) {
+      const uid = String(body.uid);
+      if (state.libraryElements[uid]) return { status: 400, json: { message: "library element with that name or UID already exists" } };
+      state.libraryElements[uid] = { uid, name: body.name, kind: body.kind, model: body.model, folderUid: body.folderUid ?? "", version: 1 };
+      return ok({ result: state.libraryElements[uid] });
+    }
+    const lib = /^\/api\/library-elements\/([^/]+)$/.exec(route);
+    if (lib) {
+      const uid = decodeURIComponent(lib[1]);
+      const el = state.libraryElements[uid];
+      if (!el) return notFound;
+      if (method === "GET") return ok({ result: el });
+      if (method === "PATCH" && isObject(body)) {
+        if (body.version !== el.version) return { status: 400, json: { message: "bad request data" } };
+        state.libraryElements[uid] = { ...el, name: body.name, model: body.model, folderUid: body.folderUid ?? "", version: (el.version as number) + 1 };
+        return ok({ result: state.libraryElements[uid] });
+      }
+    }
+    return notFound;
+  };
+}

package/src/api/fake-grafana.ts

@@ -0,0 +1,186 @@
+/**
+ * A Grafana API in memory, for the observe and export tests (#2946).
+ *
+ * Serves the routes the readers use, from a state the test sets up, in the
+ * shapes Grafana 12.4.11 and 13.2.2 return (checked against both with the
+ * e2e in ../observe.e2e.test.ts): the API group discovery, dashboard
+ * resources under `/apis`, the legacy `/api/dashboards/uid` and
+ * `/api/search`, folders, and datasources. `storedDashboard` does to a built
+ * dashboard what Grafana does when it stores one.
+ */
+
+import type { GrafanaHttp, GrafanaResponse } from "./client";
+
+type Json = Record<string, unknown>;
+
+export interface FakeDashboard {
+  /** The classic JSON, as it would be stored (see {@link storedDashboard}). */
+  spec: Json;
+  labels?: Record<string, string>;
+  annotations?: Record<string, string>;
+  /** The version it is stored at: `v0alpha1` for a classic dashboard, `v2beta1` for one saved as v2. */
+  storedVersion?: string;
+  /**
+   * For a dashboard stored as v2, its v2 spec, served at the v2 versions the
+   * server has (`spec` is then the classic read's down-conversion). Without
+   * it the v2 routes answer 404.
+   */
+  v2?: Json;
+  folderUid?: string;
+}
+
+export interface FakeGrafanaState {
+  /** `v1` (13.x), `v1beta1` (12.x), or `legacy` for a server with no `/apis/dashboard.grafana.app` (11.x). */
+  api: "v1" | "v1beta1" | "legacy";
+  dashboards: Record<string, FakeDashboard>;
+  datasources?: Record<string, Json>;
+  folders?: Record<string, string>;
+  /** Answer every request with this status (a refused token: 401). */
+  status?: number;
+  namespace?: string;
+}
+
+const BUILTIN_ANNOTATION = {
+  builtIn: 1,
+  datasource: { type: "grafana", uid: "-- Grafana --" },
+  enable: true,
+  hide: true,
+  iconColor: "rgba(0, 211, 255, 1)",
+  name: "Annotations & Alerts",
+  type: "dashboard",
+};
+
+function isObject(v: unknown): v is Json {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function dropNulls(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(dropNulls);
+  if (isObject(v)) return Object.fromEntries(Object.entries(v).filter(([, x]) => x !== null).map(([k, x]) => [k, dropNulls(x)]));
+  return v;
+}
+
+function storePanel(p: Json): Json {
+  const out: Json = { ...p };
+  if (isObject(out.options) && Object.keys(out.options).length === 0) delete out.options;
+  const fc = out.fieldConfig;
+  if (isObject(fc) && isObject(fc.defaults) && Object.keys(fc.defaults).length === 0 && Array.isArray(fc.overrides) && fc.overrides.length === 0) delete out.fieldConfig;
+  if (Array.isArray(out.panels)) out.panels = out.panels.map((c) => (isObject(c) ? storePanel(c) : c));
+  return out;
+}
+
+/**
+ * A built dashboard as Grafana hands it back through `/apis` (measured on
+ * 12.4.11 and 13.2.2): the built-in annotation added, empty `options` and
+ * `fieldConfig` dropped, `null` values dropped, and the uid moved to the
+ * resource's name. The legacy route (`/api/dashboards/uid`) serves the
+ * built JSON plus `id` and `version`; the fake serves this model on both,
+ * which is the harder case for the legacy path.
+ */
+export function storedDashboard(built: Json): Json {
+  const out = dropNulls(built) as Json;
+  const annotations = isObject(out.annotations) && Array.isArray(out.annotations.list) ? out.annotations.list : [];
+  out.annotations = { list: [BUILTIN_ANNOTATION, ...annotations] };
+  if (Array.isArray(out.panels)) out.panels = out.panels.map((p) => (isObject(p) ? storePanel(p) : p));
+  delete out.uid;
+  return out;
+}
+
+const ok = (json: unknown): GrafanaResponse => ({ status: 200, json });
+const notFound: GrafanaResponse = { status: 404, json: { message: "not found" } };
+
+/** A {@link GrafanaHttp} over `state`, recording every request path in `calls`. */
+export function fakeGrafana(state: FakeGrafanaState, calls: string[] = []): GrafanaHttp {
+  const ns = state.namespace ?? "default";
+  const resource = (uid: string, d: FakeDashboard): Json => ({
+    apiVersion: `dashboard.grafana.app/${state.api}`,
+    kind: "Dashboard",
+    metadata: {
+      name: uid,
+      namespace: ns,
+      resourceVersion: "1",
+      generation: 1,
+      labels: { "grafana.app/deprecatedInternalID": "1", ...(d.labels ?? {}) },
+      annotations: { ...(d.folderUid ? { "grafana.app/folder": d.folderUid } : {}), ...(d.annotations ?? {}) },
+    },
+    spec: d.spec,
+    status: { conversion: { failed: false, storedVersion: d.storedVersion ?? "v0alpha1" } },
+  });
+  return async (method, path) => {
+    calls.push(`${method} ${path}`);
+    if (state.status !== undefined) return { status: state.status, json: { message: "refused" } };
+    const [route, query] = path.split("?");
+    if (route === "/apis/dashboard.grafana.app") {
+      if (state.api === "legacy") return notFound;
+      const versions = state.api === "v1" ? ["v2", "v2beta1", "v2alpha1", "v0alpha1", "v1", "v1beta1"] : ["v1beta1", "v0alpha1", "v2beta1", "v2alpha1"];
+      return ok({ kind: "APIGroup", name: "dashboard.grafana.app", versions: versions.map((version) => ({ groupVersion: `dashboard.grafana.app/${version}`, version })) });
+    }
+    const list = new RegExp(`^/apis/dashboard\\.grafana\\.app/${state.api}/namespaces/${ns}/dashboards$`).exec(route);
+    if (list && state.api !== "legacy") return ok({ items: Object.entries(state.dashboards).map(([uid, d]) => resource(uid, d)), metadata: {} });
+    const v2 = new RegExp(`^/apis/dashboard\\.grafana\\.app/(v2|v2beta1)/namespaces/${ns}/dashboards/([^/]+)$`).exec(route);
+    if (v2 && state.api !== "legacy" && (state.api === "v1" || v2[1] === "v2beta1")) {
+      const uid = decodeURIComponent(v2[2]);
+      const d = state.dashboards[uid];
+      if (!d?.v2) return notFound;
+      const r = resource(uid, d);
+      return ok({ ...r, apiVersion: `dashboard.grafana.app/${v2[1]}`, spec: d.v2, status: {} });
+    }
+    const one = new RegExp(`^/apis/dashboard\\.grafana\\.app/${state.api}/namespaces/${ns}/dashboards/([^/]+)$`).exec(route);
+    if (one && state.api !== "legacy") {
+      const d = state.dashboards[decodeURIComponent(one[1])];
+      return d ? ok(resource(decodeURIComponent(one[1]), d)) : notFound;
+    }
+    const legacy = /^\/api\/dashboards\/uid\/([^/]+)$/.exec(route);
+    if (legacy) {
+      const uid = decodeURIComponent(legacy[1]);
+      const d = state.dashboards[uid];
+      if (!d) return notFound;
+      const folderTitle = d.folderUid ? state.folders?.[d.folderUid] : undefined;
+      return ok({
+        dashboard: { ...d.spec, uid, id: 7, version: 3 },
+        meta: { provisioned: true, folderUid: d.folderUid ?? "", folderTitle: folderTitle ?? "Dashboards", version: 3 },
+      });
+    }
+    if (route === "/api/search") {
+      const page = Number(new URLSearchParams(query ?? "").get("page") ?? "1");
+      return ok(page === 1 ? Object.keys(state.dashboards).map((uid) => ({ uid, type: "dash-db" })) : []);
+    }
+    const folder = /^\/api\/folders\/([^/]+)$/.exec(route);
+    if (folder) {
+      const title = state.folders?.[decodeURIComponent(folder[1])];
+      return title ? ok({ uid: folder[1], title }) : notFound;
+    }
+    if (route === "/api/datasources") return ok(Object.values(state.datasources ?? {}).map(({ secureJsonFields: _s, ...rest }) => rest));
+    const ds = /^\/api\/datasources\/uid\/([^/]+)$/.exec(route);
+    if (ds) {
+      const d = state.datasources?.[decodeURIComponent(ds[1])];
+      return d ? ok(d) : notFound;
+    }
+    return notFound;
+  };
+}
+
+/** A datasource as `GET /api/datasources/uid/<uid>` returns one provisioned from a file. */
+export function liveDatasource(ds: { name: string; type: string; uid: string; url?: string; isDefault?: boolean; jsonData?: Json; secure?: string[]; readOnly?: boolean }): Json {
+  return {
+    id: 2,
+    uid: ds.uid,
+    orgId: 1,
+    name: ds.name,
+    type: ds.type,
+    typeLogoUrl: `public/plugins/${ds.type}/img/logo.svg`,
+    access: "proxy",
+    url: ds.url ?? "",
+    user: "",
+    database: "",
+    basicAuth: false,
+    basicAuthUser: "",
+    withCredentials: false,
+    isDefault: ds.isDefault ?? false,
+    jsonData: ds.jsonData ?? {},
+    secureJsonFields: Object.fromEntries((ds.secure ?? []).map((k) => [k, true])),
+    version: 1,
+    readOnly: ds.readOnly ?? true,
+    apiVersion: "",
+  };
+}

package/src/api/folders.ts

@@ -0,0 +1,265 @@
+/**
+ * Folders, for the API applier (#2948). Every folder decision the applier
+ * makes is in this module: which folders a build needs, the uid each gets,
+ * how one is read, written, listed and deleted, and on which API.
+ *
+ * ## What the lexicon models today
+ *
+ * A dashboard names its folder by title (`Dashboard.folder`), and a title
+ * holds no nesting (the build flattens `/` in it). So the applier derives
+ * one root-level folder per distinct title, with a stable uid made from the
+ * title ({@link folderUidFor}), and a second apply finds it again by that
+ * uid. {@link FolderPlan} already carries `parentUid`, and the writers
+ * already send it, so #2953 (folder uid and nesting on the declaration) only
+ * has to change {@link foldersForDashboards}.
+ *
+ * ## Which API
+ *
+ * Grafana 12.4 serves `folder.grafana.app/v1beta1` and 13.x also serves
+ * `v1`, both keeping `metadata.labels` as written (checked against 12.4.11
+ * and 13.2.2), so a folder carries chant's ownership labels the same way a
+ * dashboard does. The parent is the `grafana.app/folder` annotation, as on a
+ * dashboard. A server without the group (Grafana 11) is written over
+ * `/api/folders`, which has `parentUid` but no labels: a folder written
+ * there cannot be told apart from anyone else's, so it is never pruned.
+ */
+
+import { GrafanaApiError, type GrafanaClient } from "./client";
+import { slugUid } from "../util";
+
+type Json = Record<string, unknown>;
+
+function isObject(v: unknown): v is Json {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function stringMap(v: unknown): Record<string, string> {
+  if (!isObject(v)) return {};
+  return Object.fromEntries(Object.entries(v).filter(([, x]) => typeof x === "string")) as Record<string, string>;
+}
+
+export const FOLDER_GROUP = "folder.grafana.app";
+
+/** Folder API versions chant writes, newest first. */
+export const FOLDER_VERSIONS: readonly string[] = ["v1", "v1beta1"];
+
+/** The annotation that names a folder's (or a dashboard's) parent folder on `/apis`. */
+export const FOLDER_ANNOTATION = "grafana.app/folder";
+
+/** How this server serves folders. */
+export type FolderApi = { readonly kind: "apis"; readonly version: string } | { readonly kind: "legacy" };
+
+/** One folder a build needs. */
+export interface FolderPlan {
+  readonly uid: string;
+  readonly title: string;
+  /** The parent folder's uid; absent for a root-level folder. */
+  readonly parentUid?: string;
+}
+
+/** A folder as Grafana holds it. */
+export interface LiveFolder {
+  readonly uid: string;
+  readonly title: string;
+  readonly parentUid?: string;
+  /** `metadata.labels`; empty on the legacy API. */
+  readonly labels: Readonly<Record<string, string>>;
+  readonly via: "apis" | "legacy";
+  /** The request path it lives at. */
+  readonly address: string;
+  /** The legacy folder's `version`, which its update needs. */
+  readonly version?: number;
+}
+
+/**
+ * The uid chant gives the folder a dashboard names by title. Stable, so a
+ * second apply finds the folder the first one made; Grafana's own limit is
+ * 40 characters, which `slugUid` keeps to.
+ */
+export function folderUidFor(title: string): string {
+  return slugUid(title);
+}
+
+/**
+ * The folders a set of dashboards needs, one per distinct title, sorted by
+ * uid. The one place a dashboard's folder becomes a folder plan.
+ */
+export function foldersForDashboards(dashboards: Iterable<{ folder?: string }>): FolderPlan[] {
+  const byUid = new Map<string, FolderPlan>();
+  for (const d of dashboards) {
+    if (!d.folder) continue;
+    const uid = folderUidFor(d.folder);
+    const seen = byUid.get(uid);
+    if (seen && seen.title !== d.folder) {
+      throw new Error(`grafana apply: the folders "${seen.title}" and "${d.folder}" would both get the uid "${uid}"; rename one`);
+    }
+    byUid.set(uid, { uid, title: d.folder });
+  }
+  return [...byUid.values()].sort((a, b) => a.uid.localeCompare(b.uid));
+}
+
+/** The folder API the server behind `client` serves, discovered once per client. */
+export function folderApi(client: GrafanaClient): Promise<FolderApi> {
+  return client.once("folder-api", async () => {
+    const group = await client.get<{ versions?: Array<{ version?: string }> }>(`/apis/${FOLDER_GROUP}`);
+    const served = new Set((group?.versions ?? []).map((v) => v.version).filter((v): v is string => typeof v === "string"));
+    const version = FOLDER_VERSIONS.find((v) => served.has(v));
+    return version ? { kind: "apis", version } : { kind: "legacy" };
+  });
+}
+
+function collection(api: Extract<FolderApi, { kind: "apis" }>, namespace: string): string {
+  return `/apis/${FOLDER_GROUP}/${api.version}/namespaces/${encodeURIComponent(namespace)}/folders`;
+}
+
+/** The request path for one folder on this API. */
+export function folderPath(api: FolderApi, namespace: string, uid: string): string {
+  return api.kind === "apis" ? `${collection(api, namespace)}/${encodeURIComponent(uid)}` : `/api/folders/${encodeURIComponent(uid)}`;
+}
+
+function fromResource(resource: Json, address: string): LiveFolder {
+  const metadata = isObject(resource.metadata) ? resource.metadata : {};
+  const spec = isObject(resource.spec) ? resource.spec : {};
+  const parentUid = stringMap(metadata.annotations)[FOLDER_ANNOTATION];
+  return {
+    uid: typeof metadata.name === "string" ? metadata.name : "",
+    title: typeof spec.title === "string" ? spec.title : "",
+    ...(parentUid ? { parentUid } : {}),
+    labels: stringMap(metadata.labels),
+    via: "apis",
+    address,
+  };
+}
+
+function fromLegacy(body: Json, address: string): LiveFolder {
+  return {
+    uid: typeof body.uid === "string" ? body.uid : "",
+    title: typeof body.title === "string" ? body.title : "",
+    ...(typeof body.parentUid === "string" && body.parentUid !== "" ? { parentUid: body.parentUid } : {}),
+    labels: {},
+    via: "legacy",
+    address,
+    ...(typeof body.version === "number" ? { version: body.version } : {}),
+  };
+}
+
+/** Read one folder; undefined when there is none with that uid. */
+export async function readFolder(client: GrafanaClient, uid: string): Promise<LiveFolder | undefined> {
+  const api = await folderApi(client);
+  const address = folderPath(api, client.namespace, uid);
+  const body = await client.get<Json>(address);
+  if (body === undefined) return undefined;
+  return api.kind === "apis" ? fromResource(body, address) : fromLegacy(body, address);
+}
+
+/** Every folder in the organisation over `/apis`, paged. The legacy API has no labels to list by, so it is not listed. */
+export async function listFolders(client: GrafanaClient): Promise<LiveFolder[]> {
+  const api = await folderApi(client);
+  if (api.kind !== "apis") return [];
+  const base = collection(api, client.namespace);
+  const out: LiveFolder[] = [];
+  let next: string | undefined;
+  do {
+    const page = await client.get<{ items?: unknown[]; metadata?: { continue?: string } }>(
+      `${base}?limit=500${next ? `&continue=${encodeURIComponent(next)}` : ""}`,
+    );
+    for (const item of page?.items ?? []) {
+      if (!isObject(item)) continue;
+      const name = isObject(item.metadata) && typeof item.metadata.name === "string" ? item.metadata.name : "";
+      if (name) out.push(fromResource(item, `${base}/${encodeURIComponent(name)}`));
+    }
+    next = page?.metadata?.continue || undefined;
+  } while (next);
+  return out;
+}
+
+/** Send one write; throws {@link GrafanaApiError} on anything but a 2xx. */
+export async function send(client: GrafanaClient, method: string, path: string, body?: unknown): Promise<unknown> {
+  const res = await client.http(method, path, body);
+  if (res.status < 200 || res.status >= 300) throw new GrafanaApiError(res.status, method, path, res.json);
+  return res.json;
+}
+
+function sameLabels(live: Readonly<Record<string, string>>, want: Readonly<Record<string, string>>): boolean {
+  return Object.entries(want).every(([k, v]) => live[k] === v);
+}
+
+/**
+ * Create or update one folder so it matches `plan`, with chant's `labels`
+ * on it where the API keeps labels. Unchanged when title, parent and labels
+ * already match; nothing is written then.
+ */
+export async function ensureFolder(
+  client: GrafanaClient,
+  plan: FolderPlan,
+  labels: Readonly<Record<string, string>>,
+): Promise<{ action: "created" | "updated" | "unchanged"; address: string; via: "apis" | "legacy" }> {
+  const api = await folderApi(client);
+  const address = folderPath(api, client.namespace, plan.uid);
+  const live = await readFolder(client, plan.uid);
+  const sameParent = (live?.parentUid ?? "") === (plan.parentUid ?? "");
+  if (api.kind === "apis") {
+    if (live && live.title === plan.title && sameParent && sameLabels(live.labels, labels)) return { action: "unchanged", address, via: "apis" };
+    // A folder's labels are merged, so a label another tool put there stays.
+    const metadata = {
+      name: plan.uid,
+      labels: { ...(live?.labels ?? {}), ...labels },
+      ...(plan.parentUid ? { annotations: { [FOLDER_ANNOTATION]: plan.parentUid } } : {}),
+    };
+    const resource = { apiVersion: `${FOLDER_GROUP}/${api.version}`, kind: "Folder", metadata, spec: { title: plan.title } };
+    if (live) {
+      await send(client, "PUT", address, resource);
+      return { action: "updated", address, via: "apis" };
+    }
+    await send(client, "POST", collection(api, client.namespace), resource);
+    return { action: "created", address, via: "apis" };
+  }
+  if (live) {
+    if (live.title === plan.title && sameParent) return { action: "unchanged", address, via: "legacy" };
+    if (live.title !== plan.title) await send(client, "PUT", address, { title: plan.title, ...(live.version !== undefined ? { version: live.version } : {}), overwrite: true });
+    if (!sameParent) await send(client, "POST", `${address}/move`, { parentUid: plan.parentUid ?? "" });
+    return { action: "updated", address, via: "legacy" };
+  }
+  await send(client, "POST", "/api/folders", { uid: plan.uid, title: plan.title, ...(plan.parentUid ? { parentUid: plan.parentUid } : {}) });
+  return { action: "created", address, via: "legacy" };
+}
+
+/**
+ * How many things a folder holds (dashboards, folders, library panels, alert
+ * rules), from `GET /api/folders/<uid>/counts`. Grafana 12.4 and 13.2 name
+ * the keys differently, so every numeric value is summed.
+ */
+export async function folderContentCount(client: GrafanaClient, uid: string): Promise<number> {
+  const counts = await client.get<Json>(`/api/folders/${encodeURIComponent(uid)}/counts`);
+  if (!counts) return 0;
+  return Object.values(counts).reduce<number>((n, v) => n + (typeof v === "number" ? v : 0), 0);
+}
+
+/**
+ * Delete one folder over `/apis`. Only ever called for a folder that holds
+ * nothing: Grafana 12.4 and 13.2 refuse to delete a folder with anything in
+ * it over `/apis`, and the applier checks first, so a foreign dashboard in a
+ * folder chant made is never removed with it. False when it was already gone.
+ */
+export async function deleteFolder(client: GrafanaClient, folder: LiveFolder): Promise<boolean> {
+  if (folder.via !== "apis") throw new Error(`grafana apply: folder "${folder.uid}" was read over /api/folders, whose delete removes what the folder holds; chant does not delete it`);
+  const res = await client.http("DELETE", folder.address);
+  if (res.status === 404) return false;
+  if (res.status < 200 || res.status >= 300) throw new GrafanaApiError(res.status, "DELETE", folder.address, res.json);
+  return true;
+}
+
+/**
+ * Order folders so a child comes before its parent: the order to delete
+ * them in. Parents outside the set count as depth 0.
+ */
+export function childrenFirst(folders: readonly LiveFolder[]): LiveFolder[] {
+  const byUid = new Map(folders.map((f) => [f.uid, f]));
+  const depth = (f: LiveFolder, seen = new Set<string>()): number => {
+    if (!f.parentUid || seen.has(f.uid)) return 0;
+    seen.add(f.uid);
+    const parent = byUid.get(f.parentUid);
+    return parent ? 1 + depth(parent, seen) : 1;
+  };
+  return [...folders].sort((a, b) => depth(b) - depth(a) || a.uid.localeCompare(b.uid));
+}