@homeflare/alchemy 0.32.0 → 0.34.0

package/src/grafana/contact-point.test.ts

@@ -0,0 +1,123 @@
+/**
+ * `Grafana.ContactPoint` against a fake Grafana — the list-then-filter-by-uid read (no by-uid GET
+ * exists), the observe-before-write "adopt" posture, and subset-match tolerance. Mirrors
+ * `datasource.test.ts`. Secure-settings-ref tests: `contact-point-secrets.test.ts`. Provenance
+ * refusal tests (foreign and missing): `contact-point-provenance.test.ts` — split out to keep each
+ * file under the house's 250-line cap.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { ITEM_PATH, LIST_PATH, liveJson, props } from './contact-point-fixtures.ts';
+import { fakeFailure, fakeGrafana, fakeGrafanaLayer } from './fake-grafana.ts';
+import { grafanaOperations } from './resource.ts';
+import { spec } from './contact-point.ts';
+
+describe('spec.fetchLive', () => {
+  test('lists and filters by uid client-side — no by-uid GET route exists', async () => {
+    const other = { ...liveJson, name: 'Other', uid: 'other' };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json([other, liveJson])
+        : fakeFailure(404, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(live !== undefined && spec.attributes(live, props)).toEqual({
+      disableResolveMessage: false,
+      name: 'On-call Slack',
+      provenance: 'api',
+      settings: { recipient: '#oncall' },
+      type: 'slack',
+      uid: 'slack-oncall',
+    });
+    // ⛔ THE POINT: a GET never carries a body.
+    expect(fake.bodies[0]).toBeUndefined();
+  });
+
+  test('a uid absent from the list decodes to undefined, not an error', async () => {
+    const fake = fakeGrafana(() => Response.json([]));
+    const result = await Effect.runPromise(
+      spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test('a 403 propagates — never folded to absent', async () => {
+    const fake = fakeGrafana(() => fakeFailure(403, 'forbidden'));
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchLive(props).pipe(Effect.provide(fakeGrafanaLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('Forbidden');
+  });
+});
+
+describe('subset match — tolerates a default Grafana injects into settings', () => {
+  test('an unchanged declaration is a noop despite an extra live settings field it never declared', async () => {
+    const decorated = { ...liveJson, settings: { ...liveJson.settings, severity: 'critical' } };
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json([decorated])
+        : fakeFailure(500, 'reconcile should not write when content is unchanged'),
+    );
+    const after = await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(after.uid).toBe('slack-oncall');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+describe('reconcile — adopt semantics', () => {
+  test('declaring exactly what is live is a noop: no write is ever sent', async () => {
+    const fake = fakeGrafana((method, url) =>
+      method === 'GET' && url.pathname === LIST_PATH
+        ? Response.json([liveJson])
+        : fakeFailure(500, 'reconcile should not write when nothing changed'),
+    );
+    const after = await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(after.uid).toBe('slack-oncall');
+    expect(fake.seen.every((s) => s.method === 'GET')).toBe(true);
+  });
+});
+
+describe('update and destroy — normal, api-provenance writes', () => {
+  test("an api-provenance contact point (this family's own writes) updates normally", async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === LIST_PATH) return Response.json([liveJson]);
+      if (method === 'PUT' && url.pathname === ITEM_PATH) {
+        return Response.json({ ...liveJson, name: 'Renamed' });
+      }
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .reconcile({ ...props, name: 'Renamed' })
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen.some((s) => s.method === 'PUT' && s.path === ITEM_PATH)).toBe(true);
+  });
+
+  test('deletes a live, api-provenance contact point by uid', async () => {
+    const fake = fakeGrafana((method, url) => {
+      if (method === 'GET' && url.pathname === LIST_PATH) return Response.json([liveJson]);
+      if (method === 'DELETE' && url.pathname === ITEM_PATH) return Response.json({});
+      return fakeFailure(500, 'unexpected request');
+    });
+    await Effect.runPromise(
+      grafanaOperations(spec)
+        .destroy(props)
+        .pipe(Effect.provide(fakeGrafanaLayer(fake.fetch))),
+    );
+    expect(fake.seen).toEqual([
+      { method: 'GET', path: LIST_PATH },
+      { method: 'DELETE', path: ITEM_PATH },
+    ]);
+  });
+});

package/src/grafana/contact-point.ts

@@ -0,0 +1,179 @@
+/**
+ * `Grafana.ContactPoint` — one Grafana alerting contact point, keyed by `uid`.
+ *
+ * ⚠️ NO GET-BY-UID ROUTE EXISTS — MEASURED against the SDK's generated operations (grep across
+ *   `services/grafana.ts` for `routeGet.*[Cc]ontactpoint`: only `routeGetContactpoints` (list,
+ *   with an optional `name` filter) and `routeGetContactpointsExport`). Unlike
+ *   `Grafana.Datasource`/`Grafana.Folder`/`Grafana.Dashboard`, `fetchLive` cannot key its read
+ *   directly on `uid`. Filtering server-side by `name` is NOT a substitute: `name` is a grouping
+ *   label a declaration can rename (`uid` is the only field this resource keys on, and Grafana's
+ *   own doc calls `name` "used as grouping key in the UI" — several contact points can share one),
+ *   so narrowing the GET to the DECLARED name would miss a live object still filed under an OLDER
+ *   name mid-rename, reporting it absent and attempting a duplicate `create`. `fetchLive` instead
+ *   lists every contact point (`routeGetContactpoints({})`, no filter) and matches `uid`
+ *   client-side — the same ambiguity `resource.ts`'s header and netbox's `soleMatch` name, resolved
+ *   the same way: requiring the one field the API is actually keyed on.
+ *
+ * ⛔ SECRET SETTINGS NEVER APPEAR AS A LITERAL PROP (S25) — same shape as `Grafana.Datasource`'s
+ *   `secureJsonDataRefs` (`secret-refs.ts`, shared). Grafana does not use a separate top-level
+ *   "secure settings" field for contact points the way it does for datasources; a secure key (a
+ *   webhook URL with an embedded token, an API key, …) lives INSIDE `settings` on write, and comes
+ *   back inside `settings` REDACTED on read — Grafana's own docs for the contact-points EXPORT
+ *   route say as much explicitly ("Redacted settings will contain RedactedValue instead"; the
+ *   plain, non-export GET this resource calls has no `decrypt` option at all, so it is redacted
+ *   unconditionally). `secureSettingsRefs` therefore names which keys of `settings` are secret —
+ *   value resolved from an env var NAME fresh inside `create`/`update`'s own effect (S24), merged
+ *   into `settings` only at that point, never stored and never diffed (see `matches` below).
+ *
+ * ⛔ A FOREIGN-PROVENANCE CONTACT POINT REFUSES EVERY UPDATE AND DESTROY — `alerting-provenance.ts`,
+ *   shared with `Grafana.MessageTemplate`/`Grafana.AlertRuleGroup`/`Grafana.NotificationPolicy`.
+ *   See that file's header for the full reasoning and citations. `create` is never at risk: it only
+ *   runs when `fetchLive` already found nothing with this `uid`.
+ *
+ * ⚠️ `X-Disable-Provenance` IS NEVER SET, BY DESIGN. Every create/update through this resource
+ *   therefore leaves the contact point with `provenance: "api"` (Grafana's own default for an
+ *   object this API just wrote) — which the docs describe as blocking that same object from being
+ *   edited in the Grafana UI afterward. That is the intended outcome, not an oversight: an object
+ *   this family declares is meant to be owned by the declaration, the same "one owner per resource"
+ *   posture `provisioned.ts` establishes for folders/dashboards — handing it back to UI-editability
+ *   by default would silently create the two-owner situation this whole file exists to prevent.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as grafana from '@distilled.cloud/grafana';
+import * as Effect from 'effect/Effect';
+import {
+  type GrafanaProvisionedObjectError,
+  isForeignProvenance,
+  refuseIfForeignProvenance,
+} from './alerting-provenance.ts';
+import { type GrafanaSpec, grafanaHandlers } from './resource.ts';
+import { GrafanaSecretRefUnsetError, resolveSecretRefs } from './secret-refs.ts';
+import { declaredContentMatches } from './subset-match.ts';
+
+export { GrafanaSecretRefUnsetError };
+
+export interface ContactPointProps {
+  uid: string;
+  name: string;
+  /** Grafana integration id — `slack`, `webhook`, `email`, `pagerduty`, `opsgenie`, … */
+  type: string;
+  /** Non-secret settings — shape depends on `type`. Never put a secret VALUE here — declare it
+   *  in `secureSettingsRefs` instead; see the file header. */
+  settings: Record<string, unknown>;
+  /** Secure field name (e.g. `url`, `token`, `password`) -> env var NAME holding its value. */
+  secureSettingsRefs?: Record<string, string>;
+  disableResolveMessage?: boolean;
+}
+
+export interface ContactPointAttributes {
+  uid: string;
+  name: string;
+  type: string;
+  /** As Grafana returns it — any secure key is a redaction placeholder, never the real value. */
+  settings: Record<string, unknown>;
+  disableResolveMessage: boolean;
+  /** `""`/`"api"` (this family may write); anything else, INCLUDING `undefined` (Grafana didn't
+   *  report the field), refuses — see alerting-provenance.ts's "fails open" note. */
+  provenance: string | undefined;
+}
+
+export interface GrafanaContactPoint extends Resource<
+  'Grafana.ContactPoint',
+  ContactPointProps,
+  ContactPointAttributes,
+  never
+> {}
+
+export const GrafanaContactPoint = Resource<GrafanaContactPoint>('Grafana.ContactPoint');
+
+/** `settings` minus every key `secureSettingsRefs` names — the only part `matches` ever compares
+ *  (a secure key's live value is always a redaction placeholder, never comparable). */
+const nonSecretSettings = (props: ContactPointProps): Record<string, unknown> => {
+  const refs = props.secureSettingsRefs;
+  if (refs === undefined) return props.settings;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(props.settings)) {
+    if (!(key in refs)) out[key] = value;
+  }
+  return out;
+};
+
+const resolveSettings = (props: ContactPointProps) =>
+  Effect.map(
+    resolveSecretRefs(props.secureSettingsRefs, (field) => `settings.${field}`),
+    (secrets) => (secrets === undefined ? props.settings : { ...props.settings, ...secrets }),
+  );
+
+export const spec: GrafanaSpec<
+  ContactPointProps,
+  grafana.EmbeddedContactPoint,
+  ContactPointAttributes,
+  | grafana.RouteGetContactpointsError
+  | grafana.RoutePostContactpointsError
+  | grafana.RoutePutContactpointError
+  | grafana.RouteDeleteContactpointsError
+  | GrafanaProvisionedObjectError
+  | GrafanaSecretRefUnsetError
+> = {
+  attributes: (live) => ({
+    disableResolveMessage: live.disableResolveMessage ?? false,
+    name: live.name ?? '',
+    // ⛔ NEVER `?? ''` — an absent field must stay distinguishable from an explicit `""`
+    //   (ProvenanceNone); see alerting-provenance.ts's "fails open" note.
+    provenance: live.provenance,
+    settings: (live.settings ?? {}) as Record<string, unknown>,
+    type: live.type,
+    uid: live.uid ?? '',
+  }),
+  create: (props) =>
+    Effect.flatMap(resolveSettings(props), (settings) =>
+      grafana.routePostContactpoints({
+        name: props.name,
+        settings,
+        type: props.type,
+        uid: props.uid,
+        ...(props.disableResolveMessage === undefined
+          ? {}
+          : { disableResolveMessage: props.disableResolveMessage }),
+      }),
+    ),
+  destroy: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance('Grafana.ContactPoint', props.uid, live.provenance);
+      }
+      yield* grafana.routeDeleteContactpoints({ UID: props.uid });
+    }),
+  fetchLive: (props) =>
+    grafana
+      .routeGetContactpoints({})
+      .pipe(Effect.map((points) => points.find((point) => point.uid === props.uid))),
+  matches: (attributes, props) =>
+    attributes.name === props.name &&
+    attributes.type === props.type &&
+    attributes.disableResolveMessage === (props.disableResolveMessage ?? false) &&
+    declaredContentMatches(nonSecretSettings(props), attributes.settings),
+  update: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance('Grafana.ContactPoint', props.uid, live.provenance);
+      }
+      const settings = yield* resolveSettings(props);
+      yield* grafana.routePutContactpoint({
+        UID: props.uid,
+        name: props.name,
+        settings,
+        type: props.type,
+        uid: props.uid,
+        ...(props.disableResolveMessage === undefined
+          ? {}
+          : { disableResolveMessage: props.disableResolveMessage }),
+      });
+    }),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaContactPointProvider = () =>
+  Provider.effect(GrafanaContactPoint, Effect.succeed(GrafanaContactPoint.Provider.of(handlers)));

package/src/grafana/dashboard-model.test.ts

@@ -0,0 +1,111 @@
+/**
+ * `normalizeModel`/`modelTitle`/`declaredContentMatches` in isolation — no SDK, no fake, no
+ * Effect. Proves the volatile fields (`id`, `version`, `iteration`) are stripped and `uid` is
+ * forced to the canonical value regardless of where — or whether — the source model carried one,
+ * and that `declaredContentMatches` tolerates Grafana's own schema-migration auto-decoration
+ * without hiding genuine content drift. All of which is what makes a pasted "Export as JSON" and
+ * a freshly-read live model compare equal in dashboard.test.ts.
+ */
+import { describe, expect, test } from 'bun:test';
+import { declaredContentMatches, modelTitle, normalizeModel } from './dashboard-model.ts';
+
+describe('normalizeModel', () => {
+  test('strips id, version and iteration', () => {
+    const model = { id: 42, iteration: 1700000000, title: 'Fleet', version: 7 };
+    expect(normalizeModel(model, 'fleet')).toEqual({ title: 'Fleet', uid: 'fleet' });
+  });
+
+  test('forces uid to the canonical value, overwriting a stale embedded one', () => {
+    const exported = { title: 'Fleet', uid: 'some-old-uid-from-an-export' };
+    expect(normalizeModel(exported, 'fleet')).toEqual({ title: 'Fleet', uid: 'fleet' });
+  });
+
+  test('injects uid when the source model has none at all — a never-saved dashboard', () => {
+    const neverSaved = { title: 'Fleet' };
+    expect(normalizeModel(neverSaved, 'fleet')).toEqual({ title: 'Fleet', uid: 'fleet' });
+  });
+
+  test('a declared model and a live model that only disagree on volatile fields normalize equal', () => {
+    const declared = { panels: [{ id: 1, title: 'CPU' }], title: 'Fleet' };
+    const live = {
+      id: 42,
+      iteration: 1700000000,
+      panels: [{ id: 1, title: 'CPU' }],
+      title: 'Fleet',
+      uid: 'fleet',
+      version: 9,
+    };
+    expect(normalizeModel(declared, 'fleet')).toEqual(normalizeModel(live, 'fleet'));
+  });
+
+  test('preserves array order — panels and targets are position-significant, not a set', () => {
+    const model = { panels: [{ title: 'B' }, { title: 'A' }] };
+    expect(normalizeModel(model, 'x').panels).toEqual([{ title: 'B' }, { title: 'A' }]);
+  });
+
+  test('leaves an unrelated field genuinely different, so a real content change still shows', () => {
+    const declared = { title: 'Fleet v2' };
+    const live = { title: 'Fleet', uid: 'fleet' };
+    expect(normalizeModel(declared, 'fleet')).not.toEqual(normalizeModel(live, 'fleet'));
+  });
+});
+
+describe('modelTitle', () => {
+  test('reads the model title', () => {
+    expect(modelTitle({ title: 'Fleet' })).toBe('Fleet');
+  });
+
+  test('answers empty for a model with no title', () => {
+    expect(modelTitle({})).toBe('');
+  });
+});
+
+describe('declaredContentMatches', () => {
+  // ⛔ THE REGRESSION THIS FUNCTION EXISTS TO FIX — found by an adversarial review of this PR.
+  //   Grafana's own dashboard-save schema migration decorates a panel/target whose `datasource`
+  //   is absent with an explicit `{type, uid}` reference. Before this function existed, a
+  //   declared panel that never set `datasource` disagreed with what it read back FOREVER.
+  test('tolerates Grafana auto-decorating a panel/target with a datasource it never declared', () => {
+    const declared = {
+      panels: [{ targets: [{ refId: 'A' }], title: 'CPU' }],
+      title: 'Fleet',
+    };
+    const live = {
+      panels: [
+        {
+          datasource: { type: 'postgres', uid: 'teslamate' },
+          targets: [{ datasource: { type: 'postgres', uid: 'teslamate' }, refId: 'A' }],
+          title: 'CPU',
+        },
+      ],
+      title: 'Fleet',
+    };
+    expect(declaredContentMatches(declared, live)).toBe(true);
+  });
+
+  test('still catches a genuine change to a field the declaration DOES mention', () => {
+    const declared = { panels: [{ title: 'CPU' }] };
+    const live = { panels: [{ datasource: { uid: 'teslamate' }, title: 'Memory' }] };
+    expect(declaredContentMatches(declared, live)).toBe(false);
+  });
+
+  test('still fails when live is missing a field the declaration mentions', () => {
+    expect(declaredContentMatches({ title: 'Fleet' }, {})).toBe(false);
+  });
+
+  test('still fails on an array length mismatch — panels are not padded away', () => {
+    const declared = { panels: [{ title: 'A' }, { title: 'B' }] };
+    const live = { panels: [{ title: 'A' }] };
+    expect(declaredContentMatches(declared, live)).toBe(false);
+  });
+
+  test('ignores an extra top-level field live carries that the declaration never mentioned', () => {
+    expect(declaredContentMatches({ title: 'Fleet' }, { schemaVersion: 39, title: 'Fleet' })).toBe(
+      true,
+    );
+  });
+
+  test('null (or undefined) on a declared leaf never mismatches, mirroring stripNullish', () => {
+    expect(declaredContentMatches({ description: null }, { description: 'set live' })).toBe(true);
+  });
+});

package/src/grafana/dashboard-model.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure functions over a dashboard JSON model — no SDK call, no Effect. Split out of dashboard.ts
+ * so that file stays under the house's 250-line cap, and so `normalizeModel`'s no-change-is-noop
+ * behavior is exercised directly in dashboard-model.test.ts without a fake Grafana in the way.
+ */
+export type DashboardModel = Record<string, unknown>;
+
+/** Grafana injects or increments these on every save; a declared model never sets them meaningfully. */
+const VOLATILE_FIELDS = ['id', 'version', 'iteration'] as const;
+
+/**
+ * ★ NORMALIZES BOTH SIDES THE SAME WAY, so a no-change plan is a true noop
+ *   (docs/grafana-folder-dashboard.md). Strips `id`/`version`/`iteration` (Grafana-managed, never
+ *   declared content) and forces `uid` to this resource's OWN canonical value, wherever — or
+ *   whether — the source object carried one. That second part is "uid placement": a dashboard
+ *   pasted from Grafana's own "Export as JSON" always embeds the OLD live uid (or none, for a
+ *   never-saved dashboard), while the live model this resource reads back always carries the
+ *   CURRENT one; forcing both to `props.uid` before comparing is what makes those two shapes equal
+ *   instead of permanently disagreeing on one field neither side is meant to declare independently
+ *   (`DashboardProps.uid` — see dashboard.ts — is the single source of truth).
+ *
+ * ⚠️ EVERY OTHER DECLARED FIELD COMPARES STRUCTURALLY, ARRAY ORDER INCLUDED — dashboard.ts's
+ *   `matches` runs this output through THIS FILE's own `declaredContentMatches` (below), which
+ *   never reorders an array. That is correct here: `panels` is position-significant (screen layout
+ *   via its own `gridPos`, but the array order also drives Grafana's internal panel indexing and
+ *   any `repeat` behavior) and each panel's `targets` is execution/legend order. Nothing in a
+ *   dashboard model is a genuinely unordered SET the way UniFi's `trustedDhcpServerIpAddresses` is
+ *   (unifi/network-form.ts's `sortedSet`) — this family has no field that needs one.
+ * ⚠️ `schemaVersion` IS DELIBERATELY **NOT** NORMALIZED — NOT MEASURED against a live instance (no
+ *   live calls in this PR). Community reports say Grafana can rewrite an old dashboard's
+ *   `schemaVersion` upward on load; IF that also happens on every plain save of an
+ *   already-current-schema dashboard, every plan against it would show a false `update` forever —
+ *   but silently normalizing it away on a guess would just as easily hide a genuine schema
+ *   mismatch. Left comparing until measured: add it to `VOLATILE_FIELDS` with a dated, measured
+ *   comment the day it is seen live, the same standard every other row in this file meets.
+ */
+export const normalizeModel = (model: DashboardModel, uid: string): DashboardModel => {
+  const normalized: DashboardModel = {};
+  for (const [key, value] of Object.entries(model)) {
+    if (key === 'uid') continue;
+    if ((VOLATILE_FIELDS as readonly string[]).includes(key)) continue;
+    normalized[key] = value;
+  }
+  normalized.uid = uid;
+  return normalized;
+};
+
+/** The model's own declared title — reporting only. It is never compared on its own; the whole
+ *  normalized model is, in dashboard.ts's `matches`, so a title-only mismatch still shows `update`. */
+export const modelTitle = (model: DashboardModel): string =>
+  typeof model.title === 'string' ? model.title : '';
+
+/**
+ * `declared` need only be a subset of `live` — dashboard.ts's `matches` runs `normalizeModel`'s
+ * output through this. Moved to `subset-match.ts` once `Grafana.ContactPoint`'s `settings` needed
+ * the identical "declaration silent about a field means don't compare it" rule; re-exported here
+ * under its original name so this file's own callers and dashboard-model.test.ts are unchanged.
+ * See subset-match.ts for the full reasoning, including the regression this exists to fix
+ * (Grafana's dashboard-save schema migration auto-decorating a panel's `datasource`) and the
+ * trade-off it accepts (an omitted field can no longer force-clear a previously-set one).
+ */
+export { declaredContentMatches } from './subset-match.ts';