@intentius/chant-lexicon-grafana 0.99.0 → 0.100.0

package/src/datasource.ts

@@ -10,9 +10,14 @@
 import { createResource } from "@intentius/chant/runtime";
 import type { Declarable } from "@intentius/chant/declarable";
 import { slugUid } from "./util";
+import type { DatasourceJsonData, DatasourceSecureJsonData, TypedDatasourceType } from "./datasource-settings";
 
-/** Datasource plugin types this lexicon types queries for. Any other plugin id is accepted as a string. */
-export type KnownDatasourceType = "prometheus" | "tempo" | "loki";
+/**
+ * Datasource plugin types this lexicon types queries and settings for
+ * (`postgres` is the PostgreSQL plugin's old id). Any other plugin id is
+ * accepted as a string.
+ */
+export type KnownDatasourceType = TypedDatasourceType;
 
 /** How Grafana reaches the datasource: through its backend (`proxy`) or from the browser (`direct`). */
 export type DatasourceAccess = "proxy" | "direct";
@@ -20,7 +25,7 @@ export type DatasourceAccess = "proxy" | "direct";
 export interface DatasourceProps<T extends string = string> {
   /** Display name, unique within the Grafana organisation. */
   name: string;
-  /** The datasource plugin id, e.g. `prometheus`, `tempo`, `loki`. */
+  /** The datasource plugin id, e.g. `prometheus`, `tempo`, `loki`, `grafana-postgresql-datasource`. */
   type: T;
   /** Stable id panels refer to. Defaults to the name as a uid (`Prometheus` becomes `prometheus`). */
   uid?: string;
@@ -33,17 +38,20 @@ export interface DatasourceProps<T extends string = string> {
   database?: string;
   withCredentials?: boolean;
   /**
-   * Plugin settings. A declared `Datasource` anywhere in here is written as
-   * its uid, so `tracesToLogsV2: { datasourceUid: loki }` links Tempo to a
-   * declared Loki.
+   * Plugin settings, typed for the plugins in `DatasourceJsonDataTypes`
+   * (`./datasource-settings.ts`) and any object for others. A declared
+   * `Datasource` anywhere in here is written as its uid, so
+   * `tracesToLogsV2: { datasourceUid: loki }` links Tempo to a declared Loki;
+   * a typed field that names a datasource accepts only the plugin types
+   * Grafana offers there.
    */
-  jsonData?: Record<string, unknown>;
+  jsonData?: DatasourceJsonData<T>;
   /**
-   * Secrets. Write them as Grafana provisioning expands them
-   * (`$__env{NAME}`, `$__file{/path}`, `${NAME}`), not as literals: GRAF002
-   * flags a literal.
+   * Secrets, by the keys the plugin reads. Write them as Grafana provisioning
+   * expands them (`$__env{NAME}`, `$__file{/path}`, `${NAME}`), not as
+   * literals: GRAF002 flags a literal.
    */
-  secureJsonData?: Record<string, string>;
+  secureJsonData?: DatasourceSecureJsonData<T>;
   /** Whether users may edit the provisioned datasource in the UI. Defaults to false. */
   editable?: boolean;
   orgId?: number;
@@ -143,3 +151,55 @@ export interface DatasourceRef<T extends string = string> {
 
 /** Grafana's own pseudo-datasources, which need no declaration. */
 export const BUILTIN_DATASOURCE_UIDS: ReadonlySet<string> = new Set(["grafana", "-- Grafana --", "-- Mixed --", "-- Dashboard --"]);
+
+export const DATASOURCE_PROVISIONING_TYPE = "Grafana::DatasourceProvisioning";
+
+/** A datasource the provisioning file deletes, by its name in an organisation. */
+export interface DeletedDatasource {
+  name: string;
+  /** Defaults to 1, as in Grafana. */
+  orgId?: number;
+}
+
+export interface DatasourceProvisioningProps {
+  /**
+   * Written as the file's `prune`. Grafana marks every datasource this file
+   * provisions as prunable, and deletes a prunable datasource once no
+   * provisioning file lists it any more, so removing a `Datasource` removes
+   * it from Grafana on the next provisioning run. Datasources provisioned
+   * without it, or made in the UI or API, are never pruned. Defaults to
+   * true; set false to keep a removed datasource in Grafana.
+   */
+  prune?: boolean;
+  /**
+   * Written as the file's `deleteDatasources`: Grafana deletes these by name
+   * before it provisions the file's datasources. Name one the file also
+   * provisions to have Grafana re-create it from the file on every run.
+   */
+  deleteDatasources?: DeletedDatasource[];
+}
+
+export interface DatasourceProvisioningEntity extends Declarable {
+  readonly props: DatasourceProvisioningProps;
+}
+
+const ProvisioningBase = createResource(DATASOURCE_PROVISIONING_TYPE, "grafana", {}) as unknown as (this: object, props: Record<string, unknown>) => void;
+
+/**
+ * The settings of the datasource provisioning file itself: `prune` and
+ * `deleteDatasources`. Optional: without one the file prunes. Declare at
+ * most one per build.
+ */
+export const DatasourceProvisioning = function (this: object, props: DatasourceProvisioningProps) {
+  ProvisioningBase.call(this, props as unknown as Record<string, unknown>);
+} as unknown as new (props: DatasourceProvisioningProps) => DatasourceProvisioningEntity;
+Object.defineProperty(DatasourceProvisioning, "name", { value: "DatasourceProvisioning" });
+
+export function isDatasourceProvisioningEntity(value: unknown): value is DatasourceProvisioningEntity {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Declarable).entityType === DATASOURCE_PROVISIONING_TYPE &&
+    (value as Declarable).lexicon === "grafana"
+  );
+}

package/src/deep-observe-hooks.ts

@@ -41,6 +41,7 @@
 import type { DeepArrayElement, DeepNode, DeepNormalizationHooks } from "@intentius/chant/deep-observation";
 import { DASHBOARD_TYPE } from "./dashboard";
 import { DATASOURCE_TYPE, EXTERNAL_DATASOURCE_TYPE } from "./datasource";
+import { FOLDER_TYPE } from "./folder";
 import { registeredQueries } from "./query";
 import { DASHBOARD_SCHEMA_VERSION } from "./schema/dashboard.gen";
 import { BOOKKEEPING_KEYS, LINK_DEFAULTS, deepEqual, isBuiltinAnnotation } from "./import/normalize";
@@ -49,7 +50,7 @@ import { DATASOURCE_API_DEFAULTS } from "./import/live-export";
 type Json = Record<string, unknown>;
 
 /** Where a node sits in a dashboard tree, from its index-erased pattern. */
-type Level = "dashboard" | "panel" | "target" | "variable" | "link";
+type Level = "dashboard" | "panel" | "target" | "variable" | "link" | "annotation";
 
 const SEGMENT = "([^.\\[\\]]+)";
 const PANEL = "panels\\[\\](?:\\.panels\\[\\])?";
@@ -59,6 +60,7 @@ const LEVELS: ReadonlyArray<[Level, RegExp]> = [
   ["target", new RegExp(`^${PANEL}\\.targets\\[\\]\\.${SEGMENT}$`)],
   ["variable", new RegExp(`^variables\\[\\]\\.${SEGMENT}$`)],
   ["link", new RegExp(`^(?:${PANEL}\\.)?links\\[\\]\\.${SEGMENT}$`)],
+  ["annotation", new RegExp(`^annotations\\[\\]\\.${SEGMENT}$`)],
 ];
 
 function levelOf(pattern: string): { level: Level; key: string } | undefined {
@@ -122,8 +124,13 @@ export const PROP_DEFAULTS: Readonly<Record<Level, Readonly<Json>>> = {
     autoMin: "10s",
   },
   link: LINK_DEFAULTS,
+  // Grafana 13.2 drops `hide: false` from an annotation it stores.
+  annotation: { hide: false },
 };
 
+/** What the build writes into an annotation that leaves them out (annotations.ts `annotationJson`). */
+const ANNOTATION_BUILD_DEFAULTS: Readonly<Json> = { enable: true, iconColor: "red" };
+
 /**
  * Keys the build fills in when a declaration leaves them out, by level:
  * the dashboard's uid (from its export name) and schema version, a panel's
@@ -141,6 +148,7 @@ export const BUILD_DERIVED: Readonly<Record<Level, ReadonlySet<string>>> = {
   // A query variable's selection is whatever the viewer last saved; the build writes one only when it is declared.
   variable: new Set(["current", "datasource"]),
   link: new Set(),
+  annotation: new Set(),
 };
 
 /** Defaults the build merges into a query from its class (`queryType: "traceql"`, `filters: []`): any key some class defaults, at that value. */
@@ -214,6 +222,7 @@ function pruneDashboard(node: DeepNode): boolean {
     if (at.level === "dashboard" && at.key === "timezone" && node.value === "browser") return true;
     if (at.level === "target" && queryDefault(at.key, node.value)) return true;
     if (at.level === "link" && at.key in LINK_DEFAULTS && deepEqual(LINK_DEFAULTS[at.key], node.value)) return true;
+    if (at.level === "annotation" && at.key in ANNOTATION_BUILD_DEFAULTS && deepEqual(ANNOTATION_BUILD_DEFAULTS[at.key], node.value)) return true;
     return false;
   }
 
@@ -223,9 +232,15 @@ function pruneDashboard(node: DeepNode): boolean {
   return at.key in defaults && deepEqual(defaults[at.key], node.value);
 }
 
+/** A folder's uid comes from its path when it is not declared. */
+function pruneFolder(node: DeepNode): boolean {
+  return node.side === "live" && node.counterpart === "absent" && node.pattern === "uid";
+}
+
 export const grafanaDeepNormalizationHooks: DeepNormalizationHooks = {
   prune(node: DeepNode): boolean {
     if (node.entityType === DASHBOARD_TYPE) return pruneDashboard(node);
+    if (node.entityType === FOLDER_TYPE) return pruneFolder(node);
     if (isDatasourceType(node.entityType)) return pruneDatasource(node);
     return false;
   },

package/src/deep-observe.test.ts

@@ -22,7 +22,9 @@ import { observeResourcesDeepGrafana } from "./deep-observe";
 import { grafanaDeepNormalizationHooks } from "./deep-observe-hooks";
 import { fakeGrafana, liveDatasource, storedDashboard, type FakeGrafanaState } from "./api/fake-grafana";
 import { load } from "js-yaml";
-import { DATASOURCES_FILE, type GrafanaIndex } from "./build";
+import { DATASOURCES_FILE, buildGrafana, type GrafanaIndex } from "./build";
+import { Dashboard } from "./dashboard";
+import { Folder } from "./folder";
 
 const { diffDeepObservation } = await import("@intentius/chant/lifecycle/deep-observe");
 const { normalizeDeepObservation } = await import("@intentius/chant/deep-observation");
@@ -263,3 +265,47 @@ describe("what cannot be read is not observed, never a clean tree", () => {
     expect(unobserved.prometheus.reason).toBe("filtered");
   });
 });
+
+describe("folders (#2953)", () => {
+  const platform = new Folder({ title: "Platform", uid: "plat" });
+  const k8s = new Folder({ title: "Kubernetes", parent: platform });
+  const pods = new Dashboard({ title: "Pods", uid: "pods", folder: k8s });
+
+  function nested(): { built: Built; state: FakeGrafanaState } {
+    const out = buildGrafana(new Map<string, never>([["pods", pods as never], ["k8s", k8s as never]]));
+    const entities: Entities = new Map([
+      ["pods", { entityType: pods.entityType, props: pods.props as Record<string, unknown> }],
+      ["k8s", { entityType: k8s.entityType, props: k8s.props as unknown as Record<string, unknown> }],
+    ]);
+    const state: FakeGrafanaState = {
+      api: "v1",
+      dashboards: {
+        pods: {
+          spec: storedDashboard(JSON.parse(out.files["dashboards/Platform/Kubernetes/pods.json"]) as Json),
+          annotations: { "grafana.app/managedBy": "classic-file-provisioning", "grafana.app/managerId": "chant" },
+          folderUid: "platform-kubernetes",
+        },
+      },
+      folders: { plat: "Platform", "platform-kubernetes": "Kubernetes", other: "Other" },
+      folderParents: { "platform-kubernetes": "plat" },
+    };
+    return { built: { entities, index: out.index, files: out.files }, state };
+  }
+
+  it("a dashboard in a nested Folder reads back as its path, and the Folder by its uid, with no drift", async () => {
+    const { built, state } = nested();
+    const { live, result } = await diff(built, state);
+    expect(normalizeDeepObservation(live).unobserved).toEqual({});
+    expect(driftPaths(result)).toEqual([]);
+    expect(unclaimedPaths(result)).toEqual([]);
+  });
+
+  it("a nested folder moved or renamed shows on the dashboard's path and the Folder's title", async () => {
+    const { built, state } = nested();
+    state.folderParents!["platform-kubernetes"] = "other";
+    expect(driftPaths((await diff(built, state)).result)).toEqual(["pods:changed:folder"]);
+    state.folderParents!["platform-kubernetes"] = "plat";
+    state.folders!["platform-kubernetes"] = "K8s";
+    expect(driftPaths((await diff(built, state)).result).sort()).toEqual(["k8s:changed:title", "pods:changed:folder"]);
+  });
+});

package/src/deep-observe.ts

@@ -18,10 +18,15 @@
  *   diffed against the declaration: a tab added in the UI is a row that
  *   the declaration does not have.
  * - The folder is not in the JSON. It is read from the resource's folder
- *   and written as its title, the form `Dashboard.folder` takes; when the
- *   declaration's folder name is one the build had to rewrite to make a
- *   directory (`Ops/Team` becomes `Ops-Team`), the declared spelling is
- *   kept, since the two name the same folder.
+ *   and written as its path, its titles from the root joined with `/`, the
+ *   form `Dashboard.folder` takes (a `Folder` given for it is held as its
+ *   path too); when the declared path is one the build had to rewrite to
+ *   make directories (` Ops / Team ` becomes `Ops/Team`), the declared
+ *   spelling is kept, since the two name the same folder.
+ * - A `Folder` is read by its uid: its title, and its parent's uid when it
+ *   is nested. A declared `parent` is a reference, which core does not
+ *   compare, so a folder moved to another parent shows as drift on the
+ *   dashboards it holds, whose paths change.
  * - A datasource's API payload is put into `DatasourceProps` vocabulary,
  *   secrets as key names only.
  *
@@ -39,7 +44,9 @@ import { deepObservation, normalizeDeepProperties } from "@intentius/chant/deep-
 import { boundedConcurrently, unobservedAll } from "@intentius/chant/observation";
 import { bindGrafana, classifyGrafanaFailure } from "./api/bind";
 import type { GrafanaClient } from "./api/client";
-import { classicDashboardOf, dashboardApi, folderTitleOf, readDashboard } from "./api/dashboards";
+import { classicDashboardOf, dashboardApi, readDashboard } from "./api/dashboards";
+import { liveFolderPath, readFolder } from "./api/folders";
+import { FOLDER_TYPE, folderLevels, folderUidOf } from "./folder";
 import { readDatasource } from "./api/datasources";
 import { DASHBOARD_PROVIDER_TYPE, DASHBOARD_TYPE } from "./dashboard";
 import { DATASOURCE_TYPE, EXTERNAL_DATASOURCE_TYPE } from "./datasource";
@@ -47,15 +54,15 @@ import { grafanaDeepNormalizationHooks } from "./deep-observe-hooks";
 import { ORPHAN_PART, PROVIDER_NOT_OBSERVABLE, declaredUid, type GrafanaObserveOptions } from "./describe-resources";
 import { dashboardMembers, isDashboardPart } from "./members";
 import { dashboardTree, datasourceProps } from "./import/live-export";
-import { chantProviderNames, dashboardOwnership, ownershipGap } from "./ownership";
+import { chantProviderNames, dashboardOwnership, folderOwnership, ownershipGap } from "./ownership";
 
 export { grafanaDeepNormalizationHooks };
 
 type Json = Record<string, unknown>;
 
-/** The directory name the build writes a folder to (build.ts `folderDir`), which is the title Grafana gives it. */
-function folderDirName(folder: string): string {
-  return folder.replace(/[/\\]+/g, "-").replace(/^\.+/, "").trim() || "General";
+/** A folder path as the build writes it (build.ts `folderDir`), which is the path Grafana's folders take. */
+function samePath(declared: string, live: string): boolean {
+  return folderLevels(declared).join("/") === live;
 }
 
 async function dashboardProperties(client: GrafanaClient, uid: string, declared: Json, providers: ReadonlySet<string>, owned: boolean | undefined): Promise<DeepResourceObservation | UnobservedEntity | undefined> {
@@ -73,10 +80,10 @@ async function dashboardProperties(client: GrafanaClient, uid: string, declared:
     }
   }
   const { tree } = dashboardTree(classic.json);
-  const folder = await folderTitleOf(client, live);
+  const folder = live.folderUid ? await liveFolderPath(client, live.folderUid) : undefined;
   if (folder !== undefined) {
     const declaredFolder = typeof declared.folder === "string" ? declared.folder : undefined;
-    tree.folder = declaredFolder !== undefined && folderDirName(declaredFolder) === folder ? declaredFolder : folder;
+    tree.folder = declaredFolder !== undefined && samePath(declaredFolder, folder) ? declaredFolder : folder;
   }
   return {
     type: DASHBOARD_TYPE,
@@ -85,6 +92,19 @@ async function dashboardProperties(client: GrafanaClient, uid: string, declared:
   };
 }
 
+async function folderProperties(client: GrafanaClient, uid: string, providers: ReadonlySet<string>, owned: boolean | undefined): Promise<DeepResourceObservation | UnobservedEntity | undefined> {
+  const live = await readFolder(client, uid);
+  if (!live) return undefined;
+  if (owned) {
+    const { ownership } = folderOwnership(live, providers);
+    if (ownership !== "owned") {
+      return { type: FOLDER_TYPE, reason: "filtered", detail: `folder "${uid}" is ${ownership === "unknown" ? "of unknown ownership (read over /api/folders, which has no labels)" : "not chant's"}`, queried: live.address };
+    }
+  }
+  const tree: Json = { title: live.title, uid: live.uid, ...(live.parentUid ? { parent: live.parentUid } : {}) };
+  return { type: FOLDER_TYPE, physicalId: uid, properties: normalizeDeepProperties(tree, { entityType: FOLDER_TYPE, side: "live", hooks: grafanaDeepNormalizationHooks }) };
+}
+
 async function datasourceProperties(client: GrafanaClient, uid: string, entityType: string, owned: boolean | undefined): Promise<DeepResourceObservation | UnobservedEntity | undefined> {
   const read = await readDatasource(client, uid);
   if ("absent" in read) return undefined;
@@ -135,8 +155,9 @@ export async function observeResourcesDeepGrafana(options: GrafanaObserveOptions
       return;
     }
     const isDashboard = entityType === DASHBOARD_TYPE;
+    const isFolder = entityType === FOLDER_TYPE;
     const isDatasource = entityType === DATASOURCE_TYPE || entityType === EXTERNAL_DATASOURCE_TYPE;
-    if (!isDashboard && !isDatasource) {
+    if (!isDashboard && !isDatasource && !isFolder) {
       unobserved[name] = { type: entityType, reason: "unsupported-kind", detail: `no grafana deep reader for ${entityType}` };
       return;
     }
@@ -148,7 +169,9 @@ export async function observeResourcesDeepGrafana(options: GrafanaObserveOptions
     try {
       const result = isDashboard
         ? await dashboardProperties(client, uid, props, providers, options.owned)
-        : await datasourceProperties(client, uid, entityType, options.owned);
+        : isFolder
+          ? await folderProperties(client, uid, providers, options.owned)
+          : await datasourceProperties(client, uid, entityType, options.owned);
       // Not there: the thin read reports it missing; restating it as a property hole would say it twice.
       if (result === undefined) return;
       if (isUnobserved(result)) unobserved[name] = result;

package/src/describe-resources.test.ts

@@ -14,6 +14,7 @@ import { Datasource, ExternalDatasource } from "./datasource";
 import { StatPanel, Row } from "./panels";
 import { PromQuery } from "./query";
 import { CustomVariable } from "./variables";
+import { Folder } from "./folder";
 
 type Entities = GrafanaObserveOptions["entities"];
 
@@ -253,3 +254,18 @@ describe("unobserved reasons", () => {
     expect(failing.unobserved.overview.reason).toBe("read-failed");
   });
 });
+
+describe("folders (#2953)", () => {
+  it("a Folder is read by its uid, from its own or its path", async () => {
+    const platform = new Folder({ title: "Platform" });
+    const k8s = new Folder({ title: "Kubernetes", parent: platform, uid: "k8s" });
+    const gone = new Folder({ title: "Gone" });
+    const folders = entities({ platform, k8s, gone });
+    const s = state({ folders: { platform: "Platform", k8s: "Kubernetes" }, folderParents: { k8s: "platform" } });
+    const out = normalizeObservation(await describeResources({ environment: "prod", entityNames: [...folders.keys()], entities: folders, config: CONFIG, env: ENV, http: fakeGrafana(s) }));
+    expect(out.resources.platform).toMatchObject({ physicalId: "platform", status: "PRESENT", attributes: { title: "Platform" } });
+    // The fake serves folders over /api/folders only (Grafana 11), which carries no labels.
+    expect(out.resources.k8s).toMatchObject({ physicalId: "k8s", ownership: "unknown", attributes: { title: "Kubernetes", parentUid: "platform" } });
+    expect(out.resources.gone).toBeUndefined();
+  });
+});

package/src/describe-resources.ts

@@ -11,6 +11,7 @@
  * |---|---|---|---|
  * | `Dashboard` | `/apis/dashboard.grafana.app/<v>/.../dashboards/<uid>` (Grafana 11: `/api/dashboards/uid/<uid>`) | absent | a v2-stored dashboard the server does not serve at v2: `unsupported-kind` |
  * | `Datasource`, `ExternalDatasource` | `/api/datasources/uid/<uid>` | absent | |
+ * | `Folder` | `/apis/folder.grafana.app/<v>/.../folders/<uid>` (Grafana 11: `/api/folders/<uid>`) | absent | |
  * | a panel, row, query or variable | its dashboard's read (./members.ts) | its dashboard's | its dashboard's |
  * | `DashboardProvider` | none: a provisioning-file setting Grafana serves no API for | | `unsupported-kind` |
  *
@@ -42,7 +43,9 @@ import { readDatasource } from "./api/datasources";
 import { DASHBOARD_PROVIDER_TYPE, DASHBOARD_TYPE } from "./dashboard";
 import { DATASOURCE_TYPE, EXTERNAL_DATASOURCE_TYPE } from "./datasource";
 import { dashboardMembers, isDashboardPart } from "./members";
-import { chantProviderNames, dashboardOwnership, ownershipGap } from "./ownership";
+import { readFolder } from "./api/folders";
+import { FOLDER_TYPE, folderUidOf } from "./folder";
+import { chantProviderNames, dashboardOwnership, folderOwnership, ownershipGap } from "./ownership";
 import { slugUid } from "./util";
 
 export interface GrafanaObserveOptions extends Omit<BindOptions, "environment"> {
@@ -55,6 +58,7 @@ export interface GrafanaObserveOptions extends Omit<BindOptions, "environment">
 
 /** The uid a declared dashboard or datasource has in Grafana: the one the build gives it. */
 export function declaredUid(name: string, entityType: string, props: Record<string, unknown>): string | undefined {
+  if (entityType === FOLDER_TYPE) return folderUidOf(props);
   if (typeof props.uid === "string" && props.uid !== "") return props.uid;
   if (entityType === DASHBOARD_TYPE) return slugUid(name || String(props.title ?? ""));
   if (entityType === DATASOURCE_TYPE && typeof props.name === "string") return slugUid(props.name);
@@ -121,6 +125,34 @@ async function observeDashboard(client: GrafanaClient, uid: string, providers: R
   return { present: meta, queried: live.address };
 }
 
+async function observeFolder(client: GrafanaClient, uid: string, providers: ReadonlySet<string>, owned: boolean | undefined): Promise<EntityObservation> {
+  let live;
+  try {
+    live = await readFolder(client, uid);
+  } catch (err) {
+    return unobservedFrom(err);
+  }
+  if (!live) return { absent: true };
+  const { ownership, marker } = folderOwnership(live, providers);
+  if (owned && ownership !== "owned") {
+    return {
+      unobserved: { reason: "filtered", detail: `folder "${uid}" exists but ${ownership === "unknown" ? "its ownership cannot be read: /api/folders returns no labels" : "is not chant's"}` },
+      queried: live.address,
+    };
+  }
+  return {
+    present: {
+      type: FOLDER_TYPE,
+      physicalId: uid,
+      status: "PRESENT",
+      ownership,
+      ...(marker ? { marker } : {}),
+      attributes: { title: live.title, via: live.via, ...(live.parentUid ? { parentUid: live.parentUid } : {}) },
+    },
+    queried: live.address,
+  };
+}
+
 async function observeDatasource(client: GrafanaClient, entity: DeclaredEntity, uid: string, owned: boolean | undefined): Promise<EntityObservation> {
   let read;
   try {
@@ -189,6 +221,9 @@ function adapter(options: GrafanaObserveOptions): ObserverAdapter<GrafanaClient>
       if (entity.type === DASHBOARD_TYPE) {
         return uid ? dashboardOnce(client, uid) : { unobserved: { reason: "read-failed", detail: `"${entity.name}" does not resolve to a uid` } };
       }
+      if (entity.type === FOLDER_TYPE) {
+        return uid ? observeFolder(client, uid, providers, options.owned) : { unobserved: { reason: "read-failed", detail: `"${entity.name}" does not resolve to a uid` } };
+      }
       if (entity.type === DATASOURCE_TYPE || entity.type === EXTERNAL_DATASOURCE_TYPE) {
         return uid ? observeDatasource(client, entity, uid, options.owned) : { unobserved: { reason: "read-failed", detail: `"${entity.name}" does not resolve to a uid` } };
       }

package/src/detect.ts

@@ -41,9 +41,9 @@ export function looksLikeDashboardApiResponse(data: unknown): data is { dashboar
   return isObject(data) && isObject(data.meta) && (looksLikeDashboard(data.dashboard) || looksLikeLegacyRowsDashboard(data.dashboard));
 }
 
-/** A datasource provisioning file: `apiVersion` and a `datasources` list. */
-export function looksLikeDatasourceProvisioning(data: unknown): data is { apiVersion: unknown; datasources: unknown[] } {
-  return isObject(data) && data.apiVersion !== undefined && Array.isArray(data.datasources);
+/** A datasource provisioning file: `apiVersion` and a `datasources` or `deleteDatasources` list. */
+export function looksLikeDatasourceProvisioning(data: unknown): data is { apiVersion: unknown; datasources?: unknown[]; deleteDatasources?: unknown[]; prune?: unknown } {
+  return isObject(data) && data.apiVersion !== undefined && (Array.isArray(data.datasources) || Array.isArray(data.deleteDatasources));
 }
 
 /** A dashboard provisioning file: `apiVersion` and a `providers` list. */

package/src/folder.ts

@@ -0,0 +1,118 @@
+/**
+ * `Folder`: a Grafana folder with a stable uid, nested with `parent`.
+ *
+ * A dashboard names its folder either as a path string
+ * (`folder: "Platform/Kubernetes"`) or as a `Folder`. Both give the same
+ * folders: one per level, each with the uid `folderUidFor` makes from its
+ * path unless a `Folder` sets one. A `Folder` is needed only to pin a uid
+ * (for links, alert rules, permissions set elsewhere) or to declare a folder
+ * that holds no dashboard yet.
+ *
+ * How each delivery carries it:
+ *
+ * - File provisioning writes the dashboard under `dashboards/<level>/...`,
+ *   and a provider with `foldersFromFilesStructure` makes one folder per
+ *   level (nested on Grafana 13.1 and later; GRAF109 says what earlier
+ *   versions do). Grafana finds each level's folder by title under its
+ *   parent and creates it when missing, with a uid of its own: file
+ *   provisioning has no field for a nested folder's uid. A folder the API
+ *   applier made first keeps the uid it was given. A `DashboardProvider`
+ *   whose `folder` is a root-level `Folder` writes its `folderUid`.
+ * - The API applier (./api/apply.ts) creates every folder with its uid and
+ *   parent, parents first.
+ * - Observation reads a dashboard's folder back as its path, and a `Folder`
+ *   by its uid.
+ *
+ * The rules for turning folders into uids and parents are in one place,
+ * `resolveFolders` in ./api/folders.ts, which the build, the applier and
+ * observation all call.
+ */
+
+import { createResource } from "@intentius/chant/runtime";
+import type { Declarable } from "@intentius/chant/declarable";
+import { slugUid } from "./util";
+
+export interface FolderProps {
+  /** The title Grafana shows. A single level: nest with `parent`, not with `/`. */
+  title: string;
+  /**
+   * Stable id: letters, digits, `-` and `_`, at most 40 characters, and not
+   * `general`, which Grafana keeps for its root. Defaults to the folder's
+   * path as a uid (`Platform/Kubernetes` becomes `platform-kubernetes`), the
+   * same uid a dashboard's `folder: "Platform/Kubernetes"` gives it.
+   */
+  uid?: string;
+  /** The folder this one is in. Leave it out for a folder at the root. */
+  parent?: FolderEntity;
+}
+
+export interface FolderEntity extends Declarable {
+  readonly props: FolderProps;
+  /** The uid Grafana gives the folder: its own, else one made from its path. */
+  readonly uid: string;
+  /** Its titles from the root, joined with `/`: the directory the build writes it to. */
+  readonly path: string;
+}
+
+export const FOLDER_TYPE = "Grafana::Folder";
+
+/**
+ * The levels of a folder path, as the build writes them to directories:
+ * split on `/`, a backslash made `-`, leading dots and surrounding blanks
+ * dropped, so no level names a directory outside `dashboards/`. Empty levels
+ * are dropped; no levels at all is the General folder.
+ */
+export function folderLevels(path: string): string[] {
+  return path
+    .split("/")
+    .map((level) => level.replace(/\\+/g, "-").trim().replace(/^\.+/, "").trim())
+    .filter((level) => level !== "");
+}
+
+/** The uid chant gives a folder it only knows by path. Stable, so a second apply finds the folder the first one made. */
+export function folderUidFor(path: string): string {
+  return slugUid(folderLevels(path).join("/"));
+}
+
+const Base = createResource(FOLDER_TYPE, "grafana", {}) as unknown as (this: object, props: Record<string, unknown>) => void;
+
+/** A Grafana folder. */
+export const Folder = function (this: object, props: FolderProps) {
+  const title = props.title;
+  if (typeof title !== "string" || folderLevels(title).length !== 1 || folderLevels(title)[0] !== title) {
+    throw new Error(
+      `grafana: Folder title ${JSON.stringify(title)} is not one folder level: use parent to nest folders, and leave out "/", "\\", leading dots and surrounding blanks, which file provisioning cannot write as a directory`,
+    );
+  }
+  if (props.parent !== undefined && !isFolderEntity(props.parent)) throw new Error(`grafana: Folder "${title}" has a parent that is not a Folder`);
+  Base.call(this, props as unknown as Record<string, unknown>);
+  const path = props.parent ? `${props.parent.path}/${title}` : title;
+  Object.defineProperty(this, "path", { value: path, enumerable: false });
+  Object.defineProperty(this, "uid", { value: props.uid ?? folderUidFor(path), enumerable: false });
+} as unknown as new (props: FolderProps) => FolderEntity;
+Object.defineProperty(Folder, "name", { value: "Folder" });
+
+export function isFolderEntity(value: unknown): value is FolderEntity {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Declarable).entityType === FOLDER_TYPE &&
+    (value as Declarable).lexicon === "grafana"
+  );
+}
+
+/** A folder's uid from its props, as observation sees them (the props of a `Folder`, parents included). */
+export function folderUidOf(props: Record<string, unknown>): string | undefined {
+  if (typeof props.uid === "string" && props.uid !== "") return props.uid;
+  const path = folderPathOf(props);
+  return path ? folderUidFor(path) : undefined;
+}
+
+/** A folder's path from its props, walking `parent`. */
+export function folderPathOf(props: Record<string, unknown>): string | undefined {
+  if (typeof props.title !== "string") return undefined;
+  const parent = props.parent as { props?: Record<string, unknown> } | undefined;
+  if (!parent) return props.title;
+  const up = parent.props ? folderPathOf(parent.props) : undefined;
+  return up === undefined ? undefined : `${up}/${props.title}`;
+}