@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/op/activities/grafana-apply.test.ts

@@ -0,0 +1,229 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { describeApplyConformance } from "@intentius/chant-test-utils";
+import { normalizeApply } from "@intentius/chant/apply";
+import { grafanaApply, readBuiltDashboards, resolveMarker, toApplyResult, type GrafanaApplyDeps } from "./grafana-apply";
+import { emptyGrafana, writableGrafana, type WritableGrafanaState } from "../../api/fake-grafana-writes";
+import type { GrafanaHttp } from "../../api/client";
+
+type Json = Record<string, unknown>;
+
+const dirs: string[] = [];
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+const OURS = { "app.kubernetes.io/managed-by": "chant", "chant.intentius.io/stack": "shop", "chant.intentius.io/env": "prod" };
+
+function dashboard(uid: string, extra: Json = {}): Json {
+  return { uid, title: uid, schemaVersion: 41, panels: [{ id: 1, type: "stat", title: "a", gridPos: { x: 0, y: 0, w: 6, h: 4 } }], ...extra };
+}
+
+/** Write a build output the way `chant build -o <dir>/grafana.json` does: the index, and the dashboard files beside it. */
+function buildOutput(dashboards: Array<{ json: Json; folder?: string }>, opts: { combined?: boolean } = {}): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-grafana-apply-"));
+  dirs.push(dir);
+  const entries = dashboards.map(({ json, folder }) => {
+    const file = folder ? `dashboards/${folder}/${json.uid}.json` : `dashboards/${json.uid}.json`;
+    mkdirSync(dirname(join(dir, file)), { recursive: true });
+    writeFileSync(join(dir, file), JSON.stringify(json));
+    return { uid: json.uid, title: json.title, ...(folder ? { folder } : {}), file };
+  });
+  const index = { grafanaSchema: "test", dashboards: entries, datasources: [], files: entries.map((e) => e.file) };
+  const indexPath = join(dir, "grafana.json");
+  writeFileSync(indexPath, JSON.stringify(opts.combined ? { grafana: index, otel: {} } : index));
+  return indexPath;
+}
+
+function deps(state: WritableGrafanaState, extra: Partial<GrafanaApplyDeps> = {}, calls: string[] = []): GrafanaApplyDeps {
+  return {
+    http: writableGrafana(state, calls),
+    config: { grafana: { profiles: { test: { url: "http://grafana.test" } } }, ownership: { stack: "shop", env: "prod" } },
+    env: {},
+    ...extra,
+  };
+}
+
+describe("readBuiltDashboards", () => {
+  test("reads the index and the files it lists, with their folders", () => {
+    const indexPath = buildOutput([{ json: dashboard("a"), folder: "Team A" }, { json: dashboard("b") }]);
+    expect(readBuiltDashboards(indexPath)).toEqual([
+      { json: dashboard("a"), folder: "Team A" },
+      { json: dashboard("b") },
+    ]);
+  });
+
+  test("reads the grafana key of a combined multi-lexicon output", () => {
+    expect(readBuiltDashboards(buildOutput([{ json: dashboard("a") }], { combined: true }))).toEqual([{ json: dashboard("a") }]);
+  });
+
+  test("refuses a file that is not a grafana index", () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-grafana-apply-"));
+    dirs.push(dir);
+    writeFileSync(join(dir, "x.json"), "{}");
+    expect(() => readBuiltDashboards(join(dir, "x.json"))).toThrow(/not a grafana build index/);
+  });
+});
+
+describe("resolveMarker", () => {
+  test("arguments win over the project's ownership config", () => {
+    expect(resolveMarker({}, { ownership: { stack: "shop", env: "prod" } })).toEqual({ stack: "shop", env: "prod" });
+    expect(resolveMarker({ stack: "x", ownershipEnv: "dev" }, { ownership: { stack: "shop", env: "prod" } })).toEqual({ stack: "x", env: "dev" });
+    expect(resolveMarker({}, { ownership: { stack: "shop", enabled: false } })).toBeUndefined();
+    expect(resolveMarker({}, undefined)).toBeUndefined();
+  });
+
+  test("an env that is a build parameter reference needs ownershipEnv", () => {
+    expect(() => resolveMarker({}, { ownership: { stack: "shop", env: { param: "env" } } })).toThrow(/pass ownershipEnv/);
+    expect(resolveMarker({ ownershipEnv: "prod" }, { ownership: { stack: "shop", env: { param: "env" } } })).toEqual({ stack: "shop", env: "prod" });
+  });
+});
+
+describe("grafanaApply", () => {
+  test("binds grafana.profiles.<environment> and applies", async () => {
+    const state = emptyGrafana("v1");
+    const out = await grafanaApply({ indexPath: buildOutput([{ json: dashboard("a"), folder: "Team A" }]), environment: "test" }, undefined, deps(state));
+    expect(out.target).toBe("grafana.profiles.test");
+    expect(out.applied.map((a) => `${a.action} ${a.kind}/${a.name}`)).toEqual(["created Folder/team-a", "created Dashboard/a"]);
+    expect(state.dashboards.a.labels).toEqual(OURS);
+  });
+
+  test("no Grafana to bind is no-binding for every resource, with nothing sent", async () => {
+    const calls: string[] = [];
+    const out = await grafanaApply({ indexPath: buildOutput([{ json: dashboard("a"), folder: "Team A" }]), environment: "nowhere" }, undefined, deps(emptyGrafana("v1"), {}, calls));
+    expect(calls).toEqual([]);
+    expect(normalizeApply(toApplyResult(out)).notAttempted.map((n) => `${n.kind}/${n.name}:${n.reason}`)).toEqual(["Folder/team-a:no-binding", "Dashboard/a:no-binding"]);
+  });
+
+  test("a profile whose token variable is unset is no-credentials", async () => {
+    const out = await grafanaApply(
+      { indexPath: buildOutput([{ json: dashboard("a") }]), environment: "test" },
+      undefined,
+      deps(emptyGrafana("v1"), { config: { grafana: { profiles: { test: { url: "http://grafana.test", token: { env: "UNSET_TOKEN" } } } } } }),
+    );
+    expect(out.notAttempted).toEqual([expect.objectContaining({ kind: "Dashboard", name: "a", reason: "no-credentials", detail: expect.stringContaining("UNSET_TOKEN") })]);
+  });
+
+  test("toApplyResult keeps the request path and reports an unconsidered kind as <kind>/*", async () => {
+    const state = emptyGrafana("legacy");
+    const out = await grafanaApply({ indexPath: buildOutput([{ json: dashboard("a") }]), environment: "test", prune: true }, undefined, deps(state));
+    const result = normalizeApply(toApplyResult(out));
+    expect(result.applied).toEqual([{ kind: "Dashboard", name: "a", action: "created", physicalId: "/api/dashboards/uid/a" }]);
+    expect(result.notAttempted.map((n) => `${n.kind}/${n.name}:${n.reason}`)).toEqual(["Dashboard/*:not-prunable", "Folder/*:not-prunable"]);
+  });
+});
+
+// ── The shared apply conformance suite (applying-conformance.mdx) ──────────
+
+/** Apply one build against `state`, recording every delete path the transport was asked for. */
+async function run(state: WritableGrafanaState, dashboards: Array<{ json: Json; folder?: string }>, opts: { prune?: boolean } = {}) {
+  const deletes: string[] = [];
+  const base = writableGrafana(state);
+  const http: GrafanaHttp = async (method, path, body) => {
+    if (method === "DELETE") deletes.push(path);
+    return base(method, path, body);
+  };
+  const outcome = await grafanaApply({ indexPath: buildOutput(dashboards), environment: "test", ...(opts.prune ? { prune: true } : {}) }, undefined, deps(state, { http }));
+  return { result: toApplyResult(outcome), deletes };
+}
+
+const LIB = { uid: "burn", name: "Burn", kind: 1, model: { type: "stat", title: "Burn" } };
+const LIB_VAR = { uid: "region", name: "Region", kind: 2, model: {} };
+
+describeApplyConformance({
+  lexicon: "grafana",
+  scenarios: [
+    {
+      name: "a folder, a library panel and two dashboards on Grafana 13 (v1)",
+      plan: [
+        { kind: "Folder", name: "team-a" },
+        { kind: "LibraryPanel", name: "burn" },
+        { kind: "Dashboard", name: "api" },
+        { kind: "Dashboard", name: "home" },
+      ],
+      run: async () => (await run(emptyGrafana("v1"), [{ json: dashboard("api", { __elements: { burn: LIB } }), folder: "Team A" }, { json: dashboard("home") }])).result,
+      expectApplied: ["Folder/team-a", "LibraryPanel/burn", "Dashboard/api", "Dashboard/home"],
+    },
+    {
+      name: "a library variable in __elements beside a dashboard on Grafana 12.4 (v1beta1)",
+      plan: [
+        { kind: "Dashboard", name: "api" },
+        { kind: "LibraryElement", name: "region" },
+      ],
+      run: async () => (await run(emptyGrafana("v1beta1"), [{ json: dashboard("api", { __elements: { region: LIB_VAR } }) }])).result,
+      expectApplied: ["Dashboard/api"],
+      expectNotAttempted: ["LibraryElement/region"],
+    },
+    {
+      name: "a refused token",
+      plan: [
+        { kind: "Folder", name: "team-a" },
+        { kind: "Dashboard", name: "api" },
+      ],
+      run: async () => (await run({ ...emptyGrafana("v1"), status: 403 }, [{ json: dashboard("api"), folder: "Team A" }])).result,
+      expectNotAttempted: ["Folder/team-a", "Dashboard/api"],
+    },
+    {
+      name: "prune on Grafana 11, which has no marker channel",
+      plan: [{ kind: "Dashboard", name: "api" }],
+      run: async () => (await run(emptyGrafana("legacy"), [{ json: dashboard("api") }], { prune: true })).result,
+      expectApplied: ["Dashboard/api"],
+      expectNotAttempted: ["Dashboard/*", "Folder/*"],
+    },
+  ],
+  pruneScenarios: [
+    {
+      name: "an owned orphan dashboard beside one saved in the UI",
+      ownedOrphan: "/dashboards/orphan",
+      foreign: "/dashboards/foreign",
+      run: async () => {
+        const state = emptyGrafana("v1");
+        state.dashboards.orphan = { spec: { title: "o" }, labels: OURS, annotations: {} };
+        state.dashboards.foreign = { spec: { title: "f" }, labels: {}, annotations: {} };
+        return run(state, [{ json: dashboard("keep") }], { prune: true });
+      },
+    },
+    {
+      name: "an owned orphan dashboard beside another chant stack's",
+      ownedOrphan: "/dashboards/orphan",
+      foreign: "/dashboards/other-stack",
+      run: async () => {
+        const state = emptyGrafana("v1beta1");
+        state.dashboards.orphan = { spec: { title: "o" }, labels: OURS, annotations: {} };
+        state.dashboards["other-stack"] = { spec: { title: "x" }, labels: { ...OURS, "chant.intentius.io/stack": "billing" }, annotations: {} };
+        return run(state, [{ json: dashboard("keep") }], { prune: true });
+      },
+    },
+    {
+      name: "an owned orphan folder beside a foreign one",
+      ownedOrphan: "/folders/old-team",
+      foreign: "/folders/their-team",
+      run: async () => {
+        const state = emptyGrafana("v1");
+        state.folders["old-team"] = { spec: { title: "Old team" }, labels: OURS, annotations: {} };
+        state.folders["their-team"] = { spec: { title: "Their team" }, labels: {}, annotations: {} };
+        return run(state, [{ json: dashboard("keep"), folder: "Team A" }], { prune: true });
+      },
+    },
+  ],
+  idempotenceScenarios: [
+    {
+      name: "the same build applied twice on Grafana 13 (v1)",
+      run: async () => {
+        const state = emptyGrafana("v1");
+        const build = [{ json: dashboard("api", { __elements: { burn: LIB } }), folder: "Team A" }, { json: dashboard("home") }];
+        return { first: (await run(state, build)).result, second: (await run(state, build)).result };
+      },
+    },
+    {
+      name: "the same build applied twice on Grafana 11 (legacy API)",
+      run: async () => {
+        const state = emptyGrafana("legacy");
+        const build = [{ json: dashboard("api"), folder: "Team A" }];
+        return { first: (await run(state, build)).result, second: (await run(state, build)).result };
+      },
+    },
+  ],
+});

package/src/op/activities/grafana-apply.ts

@@ -0,0 +1,171 @@
+/**
+ * `grafanaApply`, the Op activity for the Grafana API applier (#2948), and
+ * `toApplyResult`, its projection onto core's apply envelope (#1446).
+ *
+ * It reads a build's output (the index the serializer writes as its primary
+ * output, and the dashboard files beside it), binds the environment's
+ * Grafana the way observe and export do (`grafana.profiles.<env>`, else
+ * `GRAFANA_URL`; ../../api/bind.ts), and hands the plan to `applyGrafana`
+ * (../../api/apply.ts), which holds the API decisions.
+ *
+ * The ownership marker is the project's: `ownership.stack` and
+ * `ownership.env` from `chant.config.ts`, or `stack`/`ownershipEnv` passed
+ * in. Without a stack the apply still runs, stamping only the managed-by
+ * label, and a prune declines (as `not-prunable`) rather than delete
+ * another stack's dashboards.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ChantConfig } from "@intentius/chant/config";
+import type { OwnershipMarker } from "@intentius/chant/ownership";
+import {
+  applyResult,
+  notAttemptedAll,
+  type AppliedResource,
+  type ApplyResult,
+  type NotAttemptedResource,
+} from "@intentius/chant/apply";
+import { bindGrafana, GrafanaBindingError, type BindOptions } from "../../api/bind";
+import type { GrafanaHttp } from "../../api/client";
+import { applyGrafana, parseDashboardFile, planFromDashboards, planRefs, type BuiltDashboardInput, type GrafanaApplyOutcome } from "../../api/apply";
+
+export type { GrafanaApplyOutcome } from "../../api/apply";
+
+export interface GrafanaApplyArgs {
+  /**
+   * The build's primary output: the index the grafana serializer writes
+   * (`chant build -o dist/grafana.json`). The dashboard files it lists are
+   * read from the same directory. A combined multi-lexicon output works too;
+   * its `grafana` key is used.
+   */
+  indexPath: string;
+  /** The chant environment, which selects `grafana.profiles.<environment>`. */
+  environment?: string;
+  /**
+   * Delete this project's dashboards and folders that the build no longer
+   * declares: only those carrying its ownership marker, stack and env.
+   * Destructive, so off by default.
+   */
+  prune?: boolean;
+  /** Ownership stack. Default: `ownership.stack` in `chant.config.ts`. */
+  stack?: string;
+  /** Ownership env. Default: `ownership.env` in `chant.config.ts` (a literal; a `{ param }` reference needs this). */
+  ownershipEnv?: string;
+  /** Project directory for `chant.config.ts`. Default: the working directory. */
+  cwd?: string;
+}
+
+/** What a test (or an embedding caller) may inject instead of the project's config, the process env and `fetch`. */
+export interface GrafanaApplyDeps {
+  http?: GrafanaHttp;
+  config?: Pick<ChantConfig, "grafana" | "ownership">;
+  env?: Record<string, string | undefined>;
+}
+
+type Json = Record<string, unknown>;
+
+function isObject(v: unknown): v is Json {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * The dashboards a build wrote, read from its index and the files beside
+ * it. Pure but for the file reads.
+ */
+export function readBuiltDashboards(indexPath: string, read: (path: string) => string = (p) => readFileSync(p, "utf8")): BuiltDashboardInput[] {
+  const raw = parseDashboardFile(read(indexPath), indexPath);
+  const index = isObject(raw.grafana) && Array.isArray(raw.grafana.dashboards) ? raw.grafana : raw;
+  if (!Array.isArray(index.dashboards)) throw new Error(`grafana apply: ${indexPath} is not a grafana build index (it has no "dashboards" list)`);
+  const dir = dirname(indexPath);
+  return index.dashboards.map((entry, i) => {
+    if (!isObject(entry) || typeof entry.file !== "string") throw new Error(`grafana apply: ${indexPath} dashboards[${i}] names no file`);
+    const file = join(dir, entry.file);
+    const json = parseDashboardFile(read(file), file);
+    return { json, ...(typeof entry.folder === "string" && entry.folder !== "" ? { folder: entry.folder } : {}) };
+  });
+}
+
+async function loadConfig(cwd: string): Promise<Pick<ChantConfig, "grafana" | "ownership"> | undefined> {
+  try {
+    const { loadChantConfig } = await import("@intentius/chant/config");
+    return (await loadChantConfig(cwd)).config;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The marker to stamp and prune by: the arguments, else the project's `ownership` config. */
+export function resolveMarker(args: Pick<GrafanaApplyArgs, "stack" | "ownershipEnv">, config: Pick<ChantConfig, "ownership"> | undefined): OwnershipMarker | undefined {
+  const o = config?.ownership;
+  const configured = o && o.enabled !== false ? o : undefined;
+  const stack = args.stack ?? configured?.stack;
+  if (!stack) return undefined;
+  const env = args.ownershipEnv ?? (typeof configured?.env === "string" ? configured.env : undefined);
+  if (env === undefined && configured?.env !== undefined) {
+    throw new Error("grafana apply: ownership.env is a build parameter reference, which an apply cannot resolve; pass ownershipEnv");
+  }
+  return { stack, ...(env ? { env } : {}) };
+}
+
+/**
+ * Apply a grafana build to the environment's Grafana over its HTTP API.
+ * Dashboards and folders get chant's ownership labels; with `prune`, this
+ * project's dashboards and folders the build no longer has are deleted.
+ * A target that cannot be bound returns every resource as not attempted,
+ * with the binding's reason.
+ */
+export async function grafanaApply(args: GrafanaApplyArgs, signal?: AbortSignal, deps: GrafanaApplyDeps = {}): Promise<GrafanaApplyOutcome> {
+  const plan = planFromDashboards(readBuiltDashboards(args.indexPath));
+  const config = deps.config ?? (await loadConfig(args.cwd ?? process.cwd()));
+  const marker = resolveMarker(args, config);
+  const bind: BindOptions = {
+    ...(args.environment !== undefined ? { environment: args.environment } : {}),
+    config: config ?? {},
+    ...(deps.env ? { env: deps.env } : {}),
+    ...(deps.http ? { http: deps.http } : {}),
+  };
+  let client;
+  try {
+    client = await bindGrafana(bind);
+  } catch (err) {
+    if (!(err instanceof GrafanaBindingError)) throw err;
+    return {
+      target: "",
+      api: "",
+      applied: [],
+      pruned: [],
+      notAttempted: [
+        ...plan.unsupported.map((u) => ({ kind: u.kind, name: u.name, reason: "unsupported-kind" as const, detail: u.detail })),
+        ...notAttemptedAll(
+          planRefs(plan).filter((r) => !plan.unsupported.some((u) => u.kind === r.kind && u.name === r.name)),
+          err.unresolved.reason,
+          err.unresolved.detail,
+        ),
+      ],
+      notPrunable: [],
+    };
+  }
+  const outcome = await applyGrafana(client, plan, { ...(marker ? { marker } : {}), ...(args.prune ? { prune: true } : {}), ...(signal ? { signal } : {}) });
+  for (const a of outcome.applied) console.log(`${a.action}: ${a.kind}/${a.name} (${outcome.target})`);
+  for (const p of outcome.pruned) console.log(`pruned: ${p.kind}/${p.name} (${outcome.target})`);
+  for (const n of outcome.notAttempted) console.log(`not attempted: ${n.kind}/${n.name}: ${n.reason}${n.detail ? ` (${n.detail})` : ""}`);
+  for (const n of outcome.notPrunable) console.log(`prune: ${n.kind} not considered: ${n.detail}`);
+  return outcome;
+}
+
+/**
+ * Project a grafana apply outcome onto core's apply envelope. The outcome
+ * keeps what the envelope has no room for (the request path, the API
+ * version, the binding's source); a kind the prune could not consider has no
+ * single resource name, so it is reported as `<kind>/*`, `not-prunable`,
+ * as the gcp applier does.
+ */
+export function toApplyResult(outcome: GrafanaApplyOutcome): ApplyResult {
+  const applied: AppliedResource[] = outcome.applied.map((a) => ({ kind: a.kind, name: a.name, action: a.action, physicalId: a.address }));
+  const notAttempted: NotAttemptedResource[] = [
+    ...outcome.notAttempted.map((n) => ({ kind: n.kind, name: n.name, reason: n.reason, ...(n.detail ? { detail: n.detail } : {}) })),
+    ...outcome.notPrunable.map((n) => ({ kind: n.kind, name: "*", reason: "not-prunable" as const, detail: n.detail })),
+  ];
+  return applyResult(applied, outcome.pruned.map((p) => ({ kind: p.kind, name: p.name, deleted: p.deleted })), notAttempted);
+}

package/src/op/activities/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Grafana Op activities, resolved by the core activity registry when a
+ * project's `chant.config.ts` lists the `grafana` lexicon. Contributes the
+ * API applier (`grafanaApply`, #2948) and its envelope projection
+ * (`toApplyResult`), which core's apply activity looks up by name.
+ */
+export { grafanaApply, toApplyResult, readBuiltDashboards, resolveMarker } from "./grafana-apply";
+export type { GrafanaApplyArgs, GrafanaApplyDeps, GrafanaApplyOutcome } from "./grafana-apply";

package/src/op/builders.test.ts

@@ -0,0 +1,40 @@
+/**
+ * The typed step builder (chant #1288 Stage 2): the ActivityStep it makes,
+ * and the authoring-time type errors its `opts` type gives.
+ */
+
+import { describe, test, expect } from "vitest";
+import { activity, stepOutput, type StepOutputRef } from "@intentius/chant/op";
+import { grafanaApply } from "./builders";
+import * as activities from "./activities";
+
+describe("grafana typed step builder", () => {
+  test("grafanaApply: the activity named as the module exports it, on the longInfra profile", () => {
+    expect(grafanaApply("dist/grafana.json")).toEqual(activity("grafanaApply", { indexPath: "dist/grafana.json" }, { profile: "longInfra" }));
+    expect(typeof activities.grafanaApply).toBe("function");
+    expect(typeof activities.toApplyResult).toBe("function");
+  });
+
+  test("grafanaApply: opts are the activity's own arguments", () => {
+    const step = grafanaApply("dist/grafana.json", { environment: "prod", prune: true, profile: "fastIdempotent" });
+    expect(step.args).toEqual({ indexPath: "dist/grafana.json", environment: "prod", prune: true });
+    expect(step.profile).toBe("fastIdempotent");
+  });
+
+  test("grafanaApply: accepts a StepOutputRef in a typed slot, and .out is reachable with an id", () => {
+    const ref = stepOutput("resolve-env", "environment");
+    expect(grafanaApply("dist/grafana.json", { environment: ref }).args?.environment).toBe(ref);
+    const out: StepOutputRef = grafanaApply("dist/grafana.json", { id: "apply" }).out.applied;
+    expect(out.step).toBe("apply");
+  });
+});
+
+// ── Compile-time-only: authoring-time type errors (never executed) ──────────
+function _typeChecksOnly(): void {
+  // @ts-expect-error — "env" is not a key of GrafanaApplyArgs (the field is `environment`).
+  grafanaApply("dist/grafana.json", { env: "prod" });
+
+  // @ts-expect-error — prune must be a boolean.
+  grafanaApply("dist/grafana.json", { prune: "true" });
+}
+void _typeChecksOnly;

package/src/op/builders.ts

@@ -0,0 +1,34 @@
+/**
+ * Typed step builder for this lexicon's activity (chant #1288 Stage 2),
+ * beside its `*Args` interface for the reason `lexicons/k8s/src/op/builders.ts`
+ * gives: core cannot import a lexicon's types. `opts` is
+ * {@link GrafanaApplyArgs} itself (via `Omit`/`WithStepRefs`), never
+ * restated.
+ */
+
+import {
+  activity,
+  takeProfileAndId,
+  type ActivityStep,
+  type NamedActivityStep,
+  type WithStepRefs,
+} from "@intentius/chant/op";
+import type { GrafanaApplyArgs } from "./activities/grafana-apply";
+
+/** Extra opts the builder accepts alongside the activity's own fields. */
+type StepOpts = { profile?: ActivityStep["profile"]; id?: string };
+
+/**
+ * Apply a grafana build to the environment's Grafana over its HTTP API
+ * (#2948): folders, library panels and dashboards, stamped with chant's
+ * ownership labels, and with `prune`, this project's orphans deleted.
+ * `opts` is {@link GrafanaApplyArgs} minus the positional `indexPath`.
+ * Defaults to the `longInfra` profile, as the other API appliers do.
+ */
+export const grafanaApply = (
+  indexPath: string,
+  opts?: WithStepRefs<Omit<GrafanaApplyArgs, "indexPath">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("grafanaApply", { indexPath, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};

package/src/ownership.ts

@@ -0,0 +1,103 @@
+/**
+ * Whose a live dashboard is (#2946).
+ *
+ * `serializer.ts` used to say Grafana had no metadata channel. It has two,
+ * both on the `dashboard.grafana.app` resource and neither in the dashboard
+ * JSON:
+ *
+ * - **`metadata.labels`**, which Grafana keeps as written for a dashboard
+ *   created or updated through `/apis`. chant's marker there is the shared
+ *   Kubernetes label convention, `LABEL_OWNERSHIP_KEYS`
+ *   (`app.kubernetes.io/managed-by: chant` plus the stack and env labels).
+ *   The API applier (#2948) stamps it with {@link grafanaOwnershipLabels};
+ *   this reads it back, stack and env included.
+ * - **`metadata.annotations`**, which Grafana writes itself for a
+ *   file-provisioned dashboard: `grafana.app/managedBy:
+ *   classic-file-provisioning` and `grafana.app/managerId: <provider name>`.
+ *   The provider name is the one chant writes into
+ *   `provisioning/dashboards/chant.yaml` (`chant` unless a
+ *   `DashboardProvider` names another), so a dashboard whose manager is one
+ *   of the project's providers is chant's. That channel carries no stack or
+ *   env, so it gives a verdict and never a marker.
+ *
+ * Anything else a read can see (a dashboard saved in the UI, one another
+ * provider or tool manages) is `foreign`.
+ *
+ * Two reads have no channel at all, and say `unknown` rather than guess:
+ * the legacy `/api/dashboards/uid` read Grafana 11 is observed through, and
+ * every datasource read (`/api/datasources` returns no labels, and the
+ * `readOnly` flag says a datasource is provisioned, not by whom).
+ */
+
+import {
+  LABEL_OWNERSHIP_KEYS,
+  OWNERSHIP_MANAGED_BY_VALUE,
+  classifyOwnership,
+  hasOwnershipMarker,
+  ownershipEntries,
+  readOwnership,
+  type ChannelKeys,
+  type OwnershipMarker,
+} from "@intentius/chant/ownership";
+import { DASHBOARD_PROVIDER_TYPE } from "./dashboard";
+import type { LiveDashboard } from "./api/dashboards";
+
+/** The label keys chant's marker uses on a `dashboard.grafana.app` resource. */
+export const GRAFANA_OWNERSHIP_KEYS: ChannelKeys = LABEL_OWNERSHIP_KEYS;
+
+export const MANAGED_BY_ANNOTATION = "grafana.app/managedBy";
+export const MANAGER_ID_ANNOTATION = "grafana.app/managerId";
+/** `grafana.app/managedBy` for a dashboard loaded by a file provider. */
+export const FILE_PROVISIONING_MANAGER = "classic-file-provisioning";
+
+/**
+ * The provider name the build writes when a project declares none. It is
+ * chant's managed-by value on purpose: it comes back from Grafana as the
+ * `grafana.app/managerId` of every dashboard the provider loads.
+ */
+export const DEFAULT_PROVIDER_NAME = OWNERSHIP_MANAGED_BY_VALUE;
+
+export type OwnershipVerdict = "owned" | "foreign" | "unknown";
+
+/** The labels the API applier (#2948) writes on a dashboard it creates, for this build's stack and env. */
+export function grafanaOwnershipLabels(ownership: { stack: string; env?: string }): Record<string, string> {
+  return ownershipEntries(GRAFANA_OWNERSHIP_KEYS, ownership);
+}
+
+/**
+ * The provider names that load this project's dashboards: every declared
+ * `DashboardProvider`, or the default one the build writes when there is
+ * none.
+ */
+export function chantProviderNames(entities: Iterable<{ entityType: string; props: Record<string, unknown> }>): Set<string> {
+  const names = new Set<string>();
+  for (const e of entities) {
+    if (e.entityType === DASHBOARD_PROVIDER_TYPE && typeof e.props.name === "string") names.add(e.props.name);
+  }
+  if (names.size === 0) names.add(DEFAULT_PROVIDER_NAME);
+  return names;
+}
+
+/** Why a verdict is what it is, for an `owned: true` read to put in its `filtered` detail. */
+export function ownershipGap(dashboard: LiveDashboard): string {
+  return dashboard.via === "legacy"
+    ? "it was read over /api/dashboards/uid (Grafana 11), which returns no labels or annotations"
+    : "it carries neither chant's managed-by label nor a manager annotation naming one of this project's dashboard providers";
+}
+
+/** A dashboard's ownership verdict, and the stack/env marker when its labels carry one. */
+export function dashboardOwnership(
+  dashboard: LiveDashboard,
+  providers: ReadonlySet<string>,
+): { ownership: OwnershipVerdict; marker?: OwnershipMarker } {
+  if (dashboard.via === "legacy") return { ownership: "unknown" };
+  if (hasOwnershipMarker(dashboard.labels, GRAFANA_OWNERSHIP_KEYS)) {
+    const marker = readOwnership(dashboard.labels, GRAFANA_OWNERSHIP_KEYS);
+    return { ownership: classifyOwnership(dashboard.labels, GRAFANA_OWNERSHIP_KEYS), ...(marker ? { marker } : {}) };
+  }
+  const manager = dashboard.annotations[MANAGER_ID_ANNOTATION];
+  if (dashboard.annotations[MANAGED_BY_ANNOTATION] === FILE_PROVISIONING_MANAGER && manager !== undefined && providers.has(manager)) {
+    return { ownership: "owned" };
+  }
+  return { ownership: "foreign" };
+}

package/src/panel-options.ts

@@ -0,0 +1,66 @@
+/**
+ * Hand-written option types for the built-in panels that have no schema.
+ *
+ * The alert list and flame graph panels define their options in TypeScript
+ * inside Grafana's frontend, with no CUE kind, so foundation-sdk publishes
+ * no JSON Schema for them and `npm run generate` has nothing to read. The
+ * types here follow Grafana's source at v13.2.2, cited per type. GRAF107
+ * checks these panels' envelope (the dashboard schema's `Panel`) but not
+ * their `options`; the traces panel is in the same position and keeps
+ * untyped options.
+ */
+
+import type { ThresholdsConfig, ValueMapping } from "./schema/dashboard.gen";
+
+/**
+ * How the alert list orders rules: `SortOrder` in
+ * public/app/plugins/panel/alertlist/types.ts:4-10 (a numeric enum starting at 1).
+ * 1 alphabetical ascending, 2 descending, 3 by importance, 4 time ascending, 5 time descending.
+ */
+export type AlertListSortOrder = 1 | 2 | 3 | 4 | 5;
+
+/** Which rule states the alert list shows: `StateFilter`, public/app/plugins/panel/alertlist/types.ts:22-30. */
+export interface AlertListStateFilter {
+  firing: boolean;
+  pending: boolean;
+  /** Kept for dashboards saved before 9.x. */
+  inactive: boolean;
+  recovering: boolean;
+  noData: boolean;
+  normal: boolean;
+  error: boolean;
+}
+
+/**
+ * The alert list panel's options: `UnifiedAlertListOptions`,
+ * public/app/plugins/panel/alertlist/types.ts:32-49 at v13.2.2. Defaults are in
+ * public/app/plugins/panel/alertlist/module.tsx.
+ */
+export interface AlertListOptions {
+  maxItems: number;
+  sortOrder: AlertListSortOrder;
+  /** Only rules from the dashboard the panel is on. */
+  dashboardAlerts: boolean;
+  groupMode: "default" | "custom";
+  groupBy: string[];
+  alertName: string;
+  showInstances: boolean;
+  /** Only rules in this folder; null for any. */
+  folder: { uid: string; title: string } | null;
+  stateFilter: AlertListStateFilter;
+  alertInstanceLabelFilter: string;
+  /** The rule source's datasource name, or null for all. */
+  datasource: string | null;
+  viewMode: "list" | "stat";
+  showInactiveAlerts: boolean;
+  /** `BigValueColorMode`, packages/grafana-ui/src/components/BigValue/BigValueTypes.ts:8-13. */
+  statColorMode: "background" | "background_solid" | "none" | "value";
+  statThresholds: ThresholdsConfig;
+  statValueMappings: ValueMapping[];
+}
+
+/** The flame graph panel's options: `Options`, public/app/plugins/panel/flamegraph/types.ts:1-3 at v13.2.2. */
+export interface FlameGraphOptions {
+  /** Hide the top table and show only the flame graph. */
+  showFlameGraphOnly: boolean;
+}