@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/dist/config.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The `grafana` namespace in `chant.config.ts` (#2946): which Grafana each
+ * chant environment observes, exports from and (#2948) applies to.
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ * import "@intentius/chant-lexicon-grafana";   // brings the `grafana` key into ChantConfig
+ *
+ * export default {
+ *   lexicons: ["grafana"],
+ *   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;
+ * ```
+ *
+ * A profile is keyed by chant environment, as `k8s.profiles.<env>` is.
+ * Credentials are named by their environment variable, never written in
+ * the config. An environment with no profile falls back to `GRAFANA_URL`
+ * with `GRAFANA_TOKEN`, or `GRAFANA_USER` and `GRAFANA_PASSWORD` (see
+ * `resolveGrafanaTarget`).
+ *
+ * One schema, three consumers, as in the fountain lexicon: core validates the
+ * namespace against it at load, the type is derived from it, and that type
+ * augments `ChantConfig`.
+ */
+import { z } from "zod";
+import type { ChantConfig } from "@intentius/chant/config";
+import type { GrafanaTarget } from "./api/client.js";
+export declare const grafanaProfileSchema: z.ZodObject<{
+    /** Base URL of the Grafana instance. */
+    url: z.ZodString;
+    /** A service account token, named by its environment variable. */
+    token: z.ZodOptional<z.ZodObject<{
+        env: z.ZodString;
+    }, z.core.$strict>>;
+    /** Basic auth, each half named by its environment variable. For a local instance; use a token elsewhere. */
+    basicAuth: z.ZodOptional<z.ZodObject<{
+        user: z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>;
+        password: z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    /** Organisation id. Defaults to 1. */
+    orgId: z.ZodOptional<z.ZodNumber>;
+    /** The `dashboard.grafana.app` namespace, when it is not `default` / `org-<id>` (Grafana Cloud: `stacks-<id>`). */
+    namespace: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const grafanaConfigSchema: z.ZodObject<{
+    /** One Grafana per chant environment. */
+    profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** Base URL of the Grafana instance. */
+        url: z.ZodString;
+        /** A service account token, named by its environment variable. */
+        token: z.ZodOptional<z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>>;
+        /** Basic auth, each half named by its environment variable. For a local instance; use a token elsewhere. */
+        basicAuth: z.ZodOptional<z.ZodObject<{
+            user: z.ZodObject<{
+                env: z.ZodString;
+            }, z.core.$strict>;
+            password: z.ZodObject<{
+                env: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        /** Organisation id. Defaults to 1. */
+        orgId: z.ZodOptional<z.ZodNumber>;
+        /** The `dashboard.grafana.app` namespace, when it is not `default` / `org-<id>` (Grafana Cloud: `stacks-<id>`). */
+        namespace: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type GrafanaProfile = z.infer<typeof grafanaProfileSchema>;
+export type GrafanaConfig = z.infer<typeof grafanaConfigSchema>;
+declare module "@intentius/chant/config" {
+    interface ChantConfig {
+        grafana?: GrafanaConfig;
+    }
+}
+/** Compile-time proof that the augmentation reaches `ChantConfig`. */
+export type GrafanaConfigNamespace = NonNullable<ChantConfig["grafana"]>;
+/** Why no target could be resolved, in the observation vocabulary. */
+export interface UnresolvedTarget {
+    readonly reason: "no-binding" | "no-credentials";
+    readonly detail: string;
+}
+declare function isUnresolved(v: GrafanaTarget | UnresolvedTarget): v is UnresolvedTarget;
+export { isUnresolved as isUnresolvedTarget };
+/**
+ * The Grafana an environment reads from. Pure: `config` and `env` are
+ * passed in.
+ *
+ * 1. `grafana.profiles.<environment>`. A profile that names a credential
+ *    variable which is not set is `no-credentials`, not an anonymous read:
+ *    the profile said how to authenticate.
+ * 2. `GRAFANA_URL`, with `GRAFANA_TOKEN`, or `GRAFANA_USER` and
+ *    `GRAFANA_PASSWORD`, or neither (an instance with anonymous access; a
+ *    refused read is then `no-credentials`).
+ * 3. Otherwise `no-binding`.
+ */
+export declare function resolveGrafanaTarget(input: {
+    environment?: string;
+    config?: Pick<ChantConfig, "grafana">;
+    env?: Record<string, string | undefined>;
+}): GrafanaTarget | UnresolvedTarget;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,cAAc,CAAC;AAI/D,eAAO,MAAM,oBAAoB;IAC/B,wCAAwC;;IAExC,kEAAkE;;;;IAElE,4GAA4G;;;;;;;;;IAE5G,sCAAsC;;IAEtC,mHAAmH;;kBAEnH,CAAC;AAEH,eAAO,MAAM,mBAAmB;IAC9B,yCAAyC;;QAbzC,wCAAwC;;QAExC,kEAAkE;;;;QAElE,4GAA4G;;;;;;;;;QAE5G,sCAAsC;;QAEtC,mHAAmH;;;kBAOnH,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,OAAO,CAAC,EAAE,aAAa,CAAC;KACzB;CACF;AAED,sEAAsE;AACtE,MAAM,MAAM,sBAAsB,GAAG,WAAW,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC;AAEzE,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,iBAAS,YAAY,CAAC,CAAC,EAAE,aAAa,GAAG,gBAAgB,GAAG,CAAC,IAAI,gBAAgB,CAEhF;AAED,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C,GAAG,aAAa,GAAG,gBAAgB,CA2CnC"}

package/dist/contact-point-secrets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The contact point settings Grafana stores encrypted, per integration: the
+ * options marked `secure` by `GET /api/alert-notifiers?version=2` on
+ * `grafana/grafana:13.2.2` (commit 1bea008f; the same list on 12.4.11).
+ * Nested settings are dotted paths (`tlsConfig.clientKey`).
+ *
+ * GRAF002 flags a literal at one of these paths, and the importer replaces
+ * the `[REDACTED]` that an export without secrets writes there.
+ */
+export declare const CONTACT_POINT_SECRET_SETTINGS: Readonly<Record<string, readonly string[]>>;
+/** How Grafana provisioning reads a value from outside the file: `$VAR`, `${VAR}`, `$__env{…}`, `$__file{…}`, `$__vault{…}`. */
+export declare const EXPANDED_VALUE: RegExp;
+/** What an export without secrets writes in place of each one. */
+export declare const REDACTED = "[REDACTED]";
+/** The secret settings of one receiver present in `settings`, with their values: `[path, value]`. */
+export declare function secretSettings(type: string, settings: Record<string, unknown>): Array<[string, unknown]>;
+//# sourceMappingURL=contact-point-secrets.d.ts.map

package/dist/contact-point-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-point-secrets.d.ts","sourceRoot":"","sources":["../src/contact-point-secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAoCpF,CAAC;AAEH,gIAAgI;AAChI,eAAO,MAAM,cAAc,QAAsF,CAAC;AAElH,kEAAkE;AAClE,eAAO,MAAM,QAAQ,eAAe,CAAC;AAErC,qGAAqG;AACrG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAQxG"}

package/dist/dashboard.d.ts

@@ -39,6 +39,13 @@ export interface DashboardProps {
     graphTooltip?: "default" | "sharedCrosshair" | "sharedTooltip";
     /** Whether users may edit it in the UI. Defaults to true, as in Grafana. */
     editable?: boolean;
+    /**
+     * The dashboard schema version the JSON is written at. Leave it out for
+     * the pinned one (`DASHBOARD_SCHEMA_VERSION`). `chant import` sets it for
+     * a dashboard saved by an older Grafana, so Grafana still runs its
+     * migrations when it loads the rebuilt JSON.
+     */
+    schemaVersion?: number;
     variables?: VariableEntity<any>[];
     /** Panels and rows, top to bottom. A row's own `panels` follow it. */
     panels?: Array<PanelEntity<any, any> | RowEntity>;
@@ -46,7 +53,10 @@ export interface DashboardProps {
     /**
      * The Grafana folder to provision it into. Written as a subdirectory of
      * `dashboards/`, which the provider maps to folders
-     * (`foldersFromFilesStructure`). Leave it out for the General folder.
+     * (`foldersFromFilesStructure`). `"Platform/Kubernetes"` nests one
+     * directory in another, which Grafana 13.1 and later make a Kubernetes
+     * folder inside Platform; earlier versions use only the last level
+     * (GRAF109 warns). Leave it out for the General folder.
      */
     folder?: string;
 }
@@ -63,7 +73,11 @@ export interface DashboardProviderProps {
     /** Provider name, unique in the provisioning file. */
     name: string;
     orgId?: number;
-    /** Folder for dashboards not in a subdirectory. */
+    /**
+     * Put every dashboard this provider loads in this folder. Setting it (or
+     * `folderUid`) turns `foldersFromFilesStructure` off by default, so each
+     * dashboard's own `folder` is ignored (GRAF109 warns).
+     */
     folder?: string;
     folderUid?: string;
     /** Where the `dashboards/` output is mounted in the Grafana container. Defaults to `/var/lib/grafana/dashboards`. */

package/dist/dashboard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE9E,mGAAmG;AACnG,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;AAEhG,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,wDAAwD;IACxD,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,iDAAiD;IACjD,YAAY,CAAC,EAAE,SAAS,GAAG,iBAAiB,GAAG,eAAe,CAAC;IAC/D,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,SAAS,CAAC,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;IAClC,sEAAsE;IAEtE,MAAM,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;IAClD,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC7B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC;AAED,eAAO,MAAM,cAAc,uBAAuB,CAAC;AAInD,2BAA2B;AAC3B,eAAO,MAAM,SAAS,EAEN,KAAK,KAAK,EAAE,cAAc,KAAK,eAAe,CAAC;AAG/D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAO1E;AAED,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,gCAAgC,CAAC;AAErE,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qHAAqH;IACrH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+GAA+G;IAC/G,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,uBAAwB,SAAQ,UAAU;IACzD,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;CACxC;AAED,eAAO,MAAM,uBAAuB,+BAA+B,CAAC;AAOpE,6GAA6G;AAC7G,eAAO,MAAM,iBAAiB,EAEd,KAAK,KAAK,EAAE,sBAAsB,KAAK,uBAAuB,CAAC;AAG/E,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAO1F"}

package/dist/datasource-refs.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Which datasource each panel, query and query variable in built dashboard
+ * JSON sends its request to.
+ *
+ * GRAF101 and GRAF102 use this to check references against the datasources
+ * a build knows about: the ones it provisions (`Datasource`) and the ones it
+ * only references (`ExternalDatasource`). Any other check that needs to know
+ * which plugin runs a query (a PromQL syntax check only wants the queries
+ * that reach a Prometheus) can call `datasourceUses()` and read
+ * `resolved.type`.
+ */
+import type { ExternalDatasourceRecord, ProvisionedDatasource } from "./build.js";
+type Json = Record<string, unknown>;
+/** A `{ type, uid }` datasource reference as dashboard JSON holds it. */
+export interface DatasourceRefJson {
+    type?: string;
+    uid?: string;
+}
+/** A datasource the build knows by uid: provisioned by it, or declared external. */
+export interface KnownDatasource {
+    uid: string;
+    type: string;
+    name?: string;
+    /** Declared with `ExternalDatasource`: referenced, not provisioned. */
+    external: boolean;
+}
+/**
+ * Where a reference leads.
+ *
+ * - `declared`: a known datasource; `type` is its plugin type.
+ * - `variable`: a `${name}` uid; `type` is the datasource variable's plugin type, else the ref's own.
+ * - `builtin`: one of Grafana's pseudo-datasources (`-- Mixed --`, `-- Dashboard --`, `grafana`).
+ * - `undeclared`: a uid the build does not know; `type` is whatever the ref says.
+ * - `default`: no uid, so Grafana picks its default datasource; `type` is the ref's, if it has one.
+ */
+export type ResolvedDatasource = {
+    kind: "declared";
+    type: string;
+    datasource: KnownDatasource;
+} | {
+    kind: "variable";
+    type?: string;
+    variable: string;
+    declared: boolean;
+} | {
+    kind: "builtin";
+    type?: string;
+} | {
+    kind: "undeclared";
+    type?: string;
+    uid: string;
+} | {
+    kind: "default";
+    type?: string;
+};
+/** One place a dashboard names, or inherits, a datasource. */
+export interface DatasourceUse {
+    /** A panel's own `datasource`, one of its queries (`targets`), or a query variable. */
+    kind: "panel" | "query" | "variable";
+    /** A human description, e.g. `panel "Latency" (id 3) query B`. */
+    where: string;
+    panel?: Json;
+    target?: Json;
+    variable?: Json;
+    /** The ref written on this panel, query or variable; unset when a query inherits its panel's. */
+    ref?: DatasourceRefJson;
+    /** Where the request goes: the query's own ref, else its panel's. */
+    resolved: ResolvedDatasource;
+}
+/** Every datasource a build knows by uid. A provisioned one wins over an external one of the same uid (GRAF104 reports the clash). */
+export declare function knownDatasources(datasources: readonly ProvisionedDatasource[], external?: readonly ExternalDatasourceRecord[]): Map<string, KnownDatasource>;
+export interface PanelInfo {
+    panel: Json;
+    /** Panels inside a collapsed row are laid out in their own group. */
+    group: string;
+}
+/** Every panel of a dashboard, including those inside collapsed rows, and the rows themselves. */
+export declare function panelsOf(dashboard: Json): PanelInfo[];
+export declare function describePanel(panel: Json): string;
+/** A dashboard's `templating.list`. */
+export declare function variablesOf(dashboard: Json): Json[];
+/** Every variable name referenced in a string. */
+export declare function variableReferences(text: string): string[];
+/** Grafana's own pseudo-datasources, which no build declares. */
+export declare function isPseudoRef(ref: DatasourceRefJson): boolean;
+/** Where one reference leads, given the dashboard's datasource variables and the known datasources. */
+export declare function resolveDatasourceRef(ref: DatasourceRefJson | undefined, dsVariables: ReadonlyMap<string, Json>, known: ReadonlyMap<string, KnownDatasource>): ResolvedDatasource;
+/**
+ * Every place a dashboard names or inherits a datasource: each panel's own
+ * ref, each query (with its own ref, or its panel's when it has none), and
+ * each query variable. Rows are left out; their panels carry the ref.
+ */
+export declare function datasourceUses(dashboard: Json, known: ReadonlyMap<string, KnownDatasource>): DatasourceUse[];
+export {};
+//# sourceMappingURL=datasource-refs.d.ts.map

package/dist/datasource-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasource-refs.d.ts","sourceRoot":"","sources":["../src/datasource-refs.ts"],"names":[],"mappings":"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"}

package/dist/datasource.d.ts

@@ -57,6 +57,35 @@ export interface DatasourceConstructor {
 /** A Grafana datasource, provisioned from `provisioning/datasources/chant.yaml`. */
 export declare const Datasource: DatasourceConstructor;
 export declare function isDatasourceEntity(value: unknown): value is DatasourceEntity;
+export declare const EXTERNAL_DATASOURCE_TYPE = "Grafana::ExternalDatasource";
+export interface ExternalDatasourceProps<T extends string = string> {
+    /** The datasource plugin id, e.g. `prometheus`. */
+    type: T;
+    /** The uid the datasource already has in Grafana. */
+    uid: string;
+    /** Its display name in Grafana, for messages and for a `DatasourceVariable` `regex`. */
+    name?: string;
+}
+export interface ExternalDatasourceEntity<T extends string = string> extends Declarable {
+    readonly props: ExternalDatasourceProps<T>;
+    /** The plugin id. */
+    readonly datasourceType: T;
+    /** The uid panels will reference. */
+    readonly uid: string;
+}
+export interface ExternalDatasourceConstructor {
+    new <T extends string>(props: ExternalDatasourceProps<T>): ExternalDatasourceEntity<T>;
+}
+/**
+ * A datasource that already exists in Grafana: provisioned by hand, by
+ * another build root, or by another tool. It is never written to the
+ * provisioning file. Panels, queries and variables use it like a
+ * `Datasource`, and GRAF101/GRAF102 check references against it.
+ */
+export declare const ExternalDatasource: ExternalDatasourceConstructor;
+export declare function isExternalDatasource(value: unknown): value is ExternalDatasourceEntity;
+/** A declared or an external datasource: anything a panel can hold that has a fixed uid. */
+export declare function isDatasourceDeclaration(value: unknown): value is DatasourceEntity | ExternalDatasourceEntity;
 /** A datasource declared somewhere this build can't see, named by its Grafana ref. */
 export interface DatasourceRef<T extends string = string> {
     type: T;

package/dist/datasource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"datasource.d.ts","sourceRoot":"","sources":["../src/datasource.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,2GAA2G;AAC3G,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;AAElE,wGAAwG;AACxG,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAElD,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACxD,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,IAAI,EAAE,CAAC,CAAC;IACR,oGAAoG;IACpG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,sFAAsF;IACtF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,UAAU;IAC7E,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;IACnC,qBAAqB;IACrB,QAAQ,CAAC,cAAc,EAAE,CAAC,CAAC;IAC3B,qCAAqC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,eAAe,wBAAwB,CAAC;AAIrD,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;CACxE;AAED,oFAAoF;AACpF,eAAO,MAAM,UAAU,EAIP,qBAAqB,CAAC;AAGtC,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAO5E;AAED,sFAAsF;AACtF,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACtD,IAAI,EAAE,CAAC,CAAC;IACR,GAAG,EAAE,MAAM,CAAC;CACb;AAED,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAA2E,CAAC"}
+{"version":3,"file":"datasource.d.ts","sourceRoot":"","sources":["../src/datasource.ts"],"names":[],"mappings":"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"}

package/dist/deep-observe-hooks.d.ts

@@ -0,0 +1,64 @@
+/**
+ * grafana deep-observation noise rules (#2946).
+ *
+ * Plain data on the plugin, because core applies the same rules to the
+ * declared tree (a `Dashboard`'s props, panels and queries inlined), which
+ * no reader touches. The live tree is the stored dashboard put back into the
+ * same vocabulary by the importer (./import/live-export.ts), so what is left
+ * to name here is what the translation cannot decide: values the build
+ * wrote that the author did not, values Grafana adds or drops on save, and
+ * values an author wrote out that are also what happens when they are left
+ * out.
+ *
+ * Measured against Grafana 12.4.11 and 13.2.2 (the e2e in
+ * ./observe.e2e.test.ts): read over `/api/dashboards/uid`, a stored dashboard
+ * differs from the built one only by the `id` and `version` Grafana adds
+ * (../test/e2e/stored-model.ts). Read over `/apis/dashboard.grafana.app`, its
+ * spec has no `id` or `version`, but it carries the built-in "Annotations &
+ * Alerts" annotation, and empty `options` and `fieldConfig` and every `null`
+ * are gone. The rest of this table is the build's own choices: panel ids,
+ * grid positions, query refIds, a panel's datasource taken from its queries.
+ *
+ * Every rule is one of four kinds, and they are in this order below:
+ *
+ * 1. **Never compared**, on either side: Grafana's bookkeeping.
+ * 2. **Empty is absent**, on both sides: `null`, `{}` and `[]` mean the same
+ *    as leaving a key out, everywhere in a dashboard or datasource. The cost
+ *    is that values added where the declaration wrote `[]` are reported as
+ *    unclaimed rather than as drift.
+ * 3. **Build-derived**, on the live side where the declaration has nothing:
+ *    the build filled it in, so it cannot disagree with what was declared.
+ * 4. **Default written out**, on the declared side where the live side has
+ *    nothing: the author wrote the value Grafana assumes, which the
+ *    translation leaves out.
+ *
+ * Rules 3 and 4 are gated on `counterpart === "absent"`, so a value the
+ * author did declare is always compared, and a change away from it is drift.
+ * (That relies on core walking a panel's props when it lists the declared
+ * paths, which #2946 fixed in `deepPathSet`.)
+ */
+import type { DeepNormalizationHooks } from "@intentius/chant/deep-observation";
+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";
+/**
+ * Defaults in the props vocabulary: a key an author may write at this value,
+ * and the translation leaves out because Grafana assumes it. The dashboard
+ * and panel entries mirror `DASHBOARD_DEFAULTS` and `PANEL_DEFAULTS` in
+ * ./import/normalize.ts, with `graphTooltip` spelled as `Dashboard` takes it.
+ */
+export declare const PROP_DEFAULTS: Readonly<Record<Level, Readonly<Json>>>;
+/**
+ * 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
+ * id, grid position and datasource (from its queries), a query's refId.
+ * Grafana keeps what the build wrote, so undeclared, they read back as the
+ * build's choice rather than as anybody's edit.
+ *
+ * `timezone` is here as a value, not a key: chant writes `browser` for a
+ * dashboard that names none, where Grafana's own default is `""`.
+ */
+export declare const BUILD_DERIVED: Readonly<Record<Level, ReadonlySet<string>>>;
+export declare const grafanaDeepNormalizationHooks: DeepNormalizationHooks;
+export {};
+//# sourceMappingURL=deep-observe-hooks.d.ts.map

package/dist/deep-observe-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-observe-hooks.d.ts","sourceRoot":"","sources":["../src/deep-observe-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAA8B,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAQ5G,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpC,4EAA4E;AAC5E,KAAK,KAAK,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;AAoBpE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CA+CjE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAOtE,CAAC;AAkFF,eAAO,MAAM,6BAA6B,EAAE,sBA0B3C,CAAC"}

package/dist/deep-observe.d.ts

@@ -0,0 +1,42 @@
+/**
+ * grafana deep observation (#2946): the property tree of each declared
+ * dashboard and datasource as Grafana holds it, so a dashboard edited in the
+ * UI shows up in `chant lifecycle diff --live` path by path.
+ *
+ * The read is the thin read's (./describe-resources.ts): same binding, same
+ * discovered API, same uid. What differs is what is done with the answer.
+ *
+ * - A dashboard's stored JSON goes through the importer
+ *   (./import/live-export.ts `dashboardTree`), which puts it into the
+ *   vocabulary its declaration is written in: `graphTooltip:
+ *   "sharedCrosshair"` rather than `1`, rows holding their panels, queries
+ *   without the refIds the build numbered. Core then diffs that against the
+ *   declaration's props, normalized on both sides by
+ *   ./deep-observe-hooks.ts.
+ * - A dashboard Grafana stores as v2 is read at v2 and converted to the
+ *   classic JSON the importer makes of it (#2947), so the tree is
+ *   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.
+ * - A datasource's API payload is put into `DatasourceProps` vocabulary,
+ *   secrets as key names only.
+ *
+ * Tri-state, one level down: a dashboard that is not there is left out (the
+ * thin read reports it missing); one that cannot be read (a failed
+ * request, withheld by `owned`, a v2-stored dashboard the server cannot
+ * serve at v2) is NOT-OBSERVED with its reason; a
+ * provider has no API and is `unsupported-kind`. Nothing unreadable comes
+ * back as a clean tree. A declared panel, row, query or variable has no tree
+ * of its own (./members.ts): its properties are in its dashboard's.
+ */
+import type { DeepObservationResult } from "@intentius/chant/lexicon";
+import { grafanaDeepNormalizationHooks } from "./deep-observe-hooks.js";
+import { type GrafanaObserveOptions } from "./describe-resources.js";
+export { grafanaDeepNormalizationHooks };
+/** Read the live property tree of every declared grafana entity. */
+export declare function observeResourcesDeepGrafana(options: GrafanaObserveOptions): Promise<DeepObservationResult>;
+//# sourceMappingURL=deep-observe.d.ts.map

package/dist/deep-observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../src/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAA6C,MAAM,0BAA0B,CAAC;AASjH,OAAO,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAqD,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAKrH,OAAO,EAAE,6BAA6B,EAAE,CAAC;AAwDzC,oEAAoE;AACpE,wBAAsB,2BAA2B,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAuDhH"}

package/dist/describe-resources.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `describeResources()` for grafana (#2946): does each declared dashboard
+ * and datasource exist in the environment's Grafana, and whose is it.
+ *
+ * Runs on core's observer harness. `bind()` resolves the environment's
+ * Grafana (`grafana.profiles.<env>`, else `GRAFANA_URL`) and discovers which
+ * dashboard API it serves; each entity is one GET, by the uid the build gives
+ * it. Verdicts:
+ *
+ * | Entity | Read | 404 | Not readable |
+ * |---|---|---|---|
+ * | `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 | |
+ * | 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` |
+ *
+ * A dashboard Grafana stores as v2 is read at v2 and converted (#2947);
+ * its metadata says `schema: "v2"` and lists what the classic form cannot
+ * hold under `v2Lossy`.
+ *
+ * A refused token is `no-credentials` for every entity, a missing binding
+ * `no-binding`, anything else `read-failed`, never absent.
+ *
+ * Ownership is read where Grafana has a channel (./ownership.ts): a
+ * dashboard over `/apis` resolves `owned` or `foreign`; a dashboard over the
+ * legacy API and every datasource say `unknown`, and an `owned: true` read
+ * withholds them as `filtered`, since it cannot show they are chant's.
+ */
+import { type DescribeResourcesResult } from "@intentius/chant/observation";
+import { type BindOptions } from "./api/bind.js";
+export interface GrafanaObserveOptions extends Omit<BindOptions, "environment"> {
+    environment: string;
+    buildOutput?: string;
+    entityNames: string[];
+    entities: Map<string, {
+        entityType: string;
+        props: Record<string, unknown>;
+    }>;
+    owned?: boolean;
+}
+/** The uid a declared dashboard or datasource has in Grafana: the one the build gives it. */
+export declare function declaredUid(name: string, entityType: string, props: Record<string, unknown>): string | undefined;
+/** What `unsupported-kind` says about a provider. */
+export declare const PROVIDER_NOT_OBSERVABLE = "a dashboard provider is a setting in Grafana's provisioning file, which Grafana serves no API for; its dashboards are observed instead";
+/** What `unsupported-kind` says about a panel, row, query or variable that no declared dashboard holds. */
+export declare const ORPHAN_PART = "panels, rows, queries and variables exist in Grafana only inside a dashboard, and no declared dashboard holds this one";
+/** Observe every declared grafana entity against the environment's Grafana. */
+export declare function describeResources(options: GrafanaObserveOptions): Promise<DescribeResourcesResult>;
+//# sourceMappingURL=describe-resources.d.ts.map

package/dist/describe-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAGL,KAAK,uBAAuB,EAG7B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAuC,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAUnF,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAKhH;AAED,qDAAqD;AACrD,eAAO,MAAM,uBAAuB,2IACsG,CAAC;AAE3I,2GAA2G;AAC3G,eAAO,MAAM,WAAW,2HACkG,CAAC;AAkI3H,+EAA+E;AAC/E,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAQxG"}

package/dist/detect.d.ts

@@ -5,6 +5,21 @@
  */
 /** Dashboard JSON: a `panels` array plus a `schemaVersion` or a `templating` block. */
 export declare function looksLikeDashboard(data: unknown): data is Record<string, unknown>;
+/** A dashboard saved before Grafana 5.0: panels inside a top-level `rows` list. */
+export declare function looksLikeLegacyRowsDashboard(data: unknown): data is Record<string, unknown>;
+/** A dashboard as the `dashboard.grafana.app` API serves it: `apiVersion`, `kind: Dashboard` and a `spec`. */
+export declare function looksLikeDashboardResource(data: unknown): data is {
+    apiVersion: string;
+    kind: "Dashboard";
+    spec: Record<string, unknown>;
+};
+/** A v2 dashboard: a `dashboard.grafana.app/v2*` resource, or a bare v2 spec (`elements` and `layout`). */
+export declare function looksLikeV2Dashboard(data: unknown): boolean;
+/** What `GET /api/dashboards/uid/<uid>` returns: `{ dashboard, meta }`. */
+export declare function looksLikeDashboardApiResponse(data: unknown): data is {
+    dashboard: Record<string, unknown>;
+    meta: unknown;
+};
 /** A datasource provisioning file: `apiVersion` and a `datasources` list. */
 export declare function looksLikeDatasourceProvisioning(data: unknown): data is {
     apiVersion: unknown;
@@ -15,6 +30,18 @@ export declare function looksLikeDashboardProvisioning(data: unknown): data is {
     apiVersion: unknown;
     providers: unknown[];
 };
-/** Template detection for `chant import` and friends: any of the three. */
+/**
+ * An alerting provisioning file (`provisioning/alerting/*.yaml`, or what
+ * `/api/v1/provisioning/*\/export` writes): at least one of the alerting
+ * lists at the top level and nothing but those and `apiVersion`. A `groups`
+ * list must hold Grafana rule groups, so a Prometheus rule file (`groups:`
+ * of `name` and `rules` with `expr`) is not mistaken for one.
+ */
+export declare function looksLikeAlertingProvisioning(data: unknown): data is Record<string, unknown>;
+/**
+ * Template detection for `chant import` and friends: dashboard JSON in any
+ * of the shapes above (v2 included, #2947), or a datasource, dashboard or
+ * alerting provisioning file.
+ */
 export declare function detectTemplate(data: unknown): boolean;
 //# sourceMappingURL=detect.d.ts.map

package/dist/detect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGjF;AAED,6EAA6E;AAC7E,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,EAAE,CAAA;CAAE,CAEtH;AAED,0EAA0E;AAC1E,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,EAAE,CAAA;CAAE,CAEnH;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAErD"}
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGjF;AAED,mFAAmF;AACnF,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE3F;AAED,8GAA8G;AAC9G,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAQ1I;AAED,2GAA2G;AAC3G,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAG3D;AAED,2EAA2E;AAC3E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAE1H;AAED,6EAA6E;AAC7E,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,EAAE,CAAA;CAAE,CAEtH;AAED,0EAA0E;AAC1E,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,EAAE,CAAA;CAAE,CAEnH;AAuBD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAO5F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAWrD"}

package/dist/export-resources.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Live export for grafana (#2946): `chant import --from <env>` writes the
+ * environment's dashboards and datasources as chant TypeScript.
+ *
+ * All I/O is here; the mapping is pure in ./import/live-export.ts, and the
+ * IR it builds is the importer's own (#2945), so a dashboard exported from
+ * Grafana and the same dashboard's JSON given to `chant import` generate the
+ * same source through the same `GrafanaGenerator`.
+ *
+ * - Every dashboard in the organisation is listed over the API the thin
+ *   read uses (`/apis/dashboard.grafana.app`, or `/api/search` plus
+ *   `/api/dashboards/uid` on Grafana 11). A dashboard stored as v2 is read at
+ *   v2 and exported through its classic form, with a warning for each thing
+ *   the classic form cannot hold (#2947).
+ * - Every datasource is read by uid, for `secureJsonFields`; secrets come
+ *   back as key names only (see `datasourceProps`).
+ * - `selector.type` is `Grafana::Dashboard` or `Grafana::Datasource`;
+ *   `selector.name` is a uid.
+ * - `owned` keeps only dashboards that are chant's (./ownership.ts), and
+ *   leaves datasources out, since their ownership cannot be read. There is no
+ *   project here to name its providers, so a file-provisioned dashboard is
+ *   chant's when its provider is the default one, `chant`.
+ * - `verbatim` keeps datasource keys at the API's "not set" values. A
+ *   dashboard is always planned by the importer, which leaves out keys at
+ *   Grafana's defaults either way.
+ */
+import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
+import { type BindOptions } from "./api/bind.js";
+export interface GrafanaExportOptions extends Omit<BindOptions, "environment"> {
+    environment: string;
+    stack?: string;
+    region?: string;
+    selector?: ResourceSelector;
+    owned?: boolean;
+    verbatim?: boolean;
+}
+export declare function exportResources(options: GrafanaExportOptions): Promise<ExportedTemplate>;
+//# sourceMappingURL=export-resources.d.ts.map

package/dist/export-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-resources.d.ts","sourceRoot":"","sources":["../src/export-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAU3D,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoC9F"}