@homeflare/alchemy 0.29.1 → 0.30.0

package/src/grafana/fake-grafana.ts

@@ -0,0 +1,64 @@
+/**
+ * A minimal in-memory Grafana HTTP API for this family's tests — an in-memory `fetch` handed to
+ * Effect's real `FetchHttpClient` through its `Fetch` reference, mirroring
+ * `../forgejo/fake-forgejo.ts` and `../netbox/fake-netbox.ts`. Tests exercise distilled's REAL
+ * path assembly, JSON encode/decode and status→typed-error matching (`404` → `NotFound`, `403` →
+ * `Forbidden`, …) — nothing about that matching is re-implemented here, only the wire responses a
+ * scenario needs.
+ *
+ * ⛔ TEST-ONLY, AND NO NETWORK. No provider imports this file. The base URL is RFC 2606
+ *   `grafana.example.com`, and the token is a placeholder.
+ */
+import { type Credentials, fromApiKey } from '@distilled.cloud/grafana/Credentials';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+
+export const FAKE_BASE = 'https://grafana.example.com';
+export const FAKE_TOKEN = 'placeholder-grafana-token';
+
+export type Seen = { readonly method: string; readonly path: string };
+
+/** Grafana's `{ message?, status? }` failure envelope — matching the SDK's own protocol.ts note. */
+export const fakeFailure = (status: number, message: string) =>
+  Response.json({ message }, { status });
+
+/**
+ * `route` decides every response; this wrapper only records what was sent and adapts to
+ * `globalThis.fetch`'s signature. A test that expects no request at all asserts `seen` is empty.
+ *
+ * ★ `bodies` IS A SEPARATE, PARALLEL ARRAY (index-matched to `seen`), NOT FOLDED INTO IT — so
+ *   every existing `expect(fake.seen).toEqual([{method, path}, …])` stays exact rather than
+ *   growing an unrelated `body` key it would then have to repeat on every entry. A test that
+ *   cares what was actually sent (not just that a request was) reads `bodies[n]` instead of only
+ *   checking a request landed — the request landing is not proof of what it carried.
+ */
+export const fakeGrafana = (route: (method: string, url: URL, body: unknown) => Response) => {
+  const seen: Seen[] = [];
+  const bodies: unknown[] = [];
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    const text = await request.text();
+    const body: unknown = text === '' ? undefined : JSON.parse(text);
+    seen.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    bodies.push(body);
+    return route(request.method, url, body);
+  }) as typeof globalThis.fetch;
+  return { fetch, seen, bodies };
+};
+
+/**
+ * distilled `Credentials` (via the SDK's own `fromApiKey`) + the real `FetchHttpClient` over the
+ * fake — `GrafanaOpContext`, what every resource file's exported `spec.fetchLive`/`create`/
+ * `update`/`destroy` needs. Unlike `grafanaHandlers`'s production callers, this never touches
+ * `process.env` — `grafanaCredentials` reads `tokenEnv` fresh per call (credentials.ts's own
+ * note), which a test-time `process.env` mutation cannot reliably reach either (measured for the
+ * same reason in the forgejo/netbox migrations: Effect's default `Config` provider snapshots the
+ * environment). Passing an explicit layer exercises exactly the same production code without
+ * that seam.
+ */
+export const fakeGrafanaLayer = (
+  fetchFn: typeof globalThis.fetch,
+  creds: Layer.Layer<Credentials> = fromApiKey({ apiBaseUrl: FAKE_BASE, apiKey: FAKE_TOKEN }),
+) => Layer.mergeAll(creds, FetchHttpClient.layer, Layer.succeed(FetchHttpClient.Fetch, fetchFn));

package/src/grafana/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Grafana providers for Alchemy.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. These are
+ *   the symbols a real stack consumes; the rest of the files (resource.ts's engine, fake-grafana.ts)
+ *   are internals a provider needs but a consumer should not depend on.
+ *
+ * ⛔ ONLY `Grafana.Datasource` SHIPS HERE. `@distilled.cloud/grafana@1.0.0-rc.12` has no folder,
+ *   dashboard, alert-rule or contact-point CRUD operations — see docs/grafana.md and
+ *   docs/upstream-conformance.md for the measured gap. Adding those resources now would mean
+ *   hand-rolling an `HttpClient` client for them, which S23 forbids for a vendor distilled
+ *   already covers in part; the right fix is upstream, in distilled, not a house workaround here.
+ */
+export {
+  type DatasourceAttributes,
+  type DatasourceProps,
+  GrafanaDatasource,
+  GrafanaDatasourceProvider,
+  GrafanaSecretRefUnsetError,
+} from './datasource.ts';
+export { type GrafanaTarget, grafanaCredentials } from './credentials.ts';
+export { grafanaProviders } from './providers.ts';

package/src/grafana/providers.ts

@@ -0,0 +1,19 @@
+/**
+ * The Grafana providers for one instance, with its credentials, as one layer for a stack.
+ *
+ *     Layer.mergeAll(grafanaProviders({ baseUrl: '...', tokenEnv: 'GRAFANA_TOKEN' }), …)
+ *
+ * ★ ONE CALL PER INSTANCE. A stack declaring resources against both `grafana.homeflare.dev` and
+ *   `teslamate-grafana` composes `grafanaProviders(targetA)` and `grafanaProviders(targetB)` —
+ *   each resource type's `Resource` constructor is a single global registration, so the SAME
+ *   `Grafana.Datasource` type serves both; only the credential layer differs per call.
+ * ⚠️ `HttpClient` is NOT provided here. It is ambient in every Alchemy runtime, the same as
+ *   `litellmProviders`/`netboxProviders`-style families in this kit assume; a stack that already
+ *   deploys anything over HTTP already has one.
+ */
+import * as Layer from 'effect/Layer';
+import { type GrafanaTarget, grafanaCredentials } from './credentials.ts';
+import { GrafanaDatasourceProvider } from './datasource.ts';
+
+export const grafanaProviders = (target: GrafanaTarget) =>
+  GrafanaDatasourceProvider().pipe(Layer.provide(grafanaCredentials(target)));

package/src/grafana/resource.ts

@@ -0,0 +1,120 @@
+/**
+ * One shape for every Grafana object this family declares — mirroring `../forgejo/resource.ts`
+ * and `../netbox/resource.ts` exactly, minus the credentials wrapping those two bake in.
+ *
+ * ★ CREDENTIALS ARE NOT PROVIDED HERE. Forgejo and NetBox each manage exactly one instance for
+ *   this house, so their engines close over a hardcoded `CredentialsFromEnv`. Grafana does not —
+ *   see `credentials.ts`'s note on `grafana.homeflare.dev` vs `teslamate-grafana` — so `Credentials`
+ *   stays a context requirement on every handler here, and `providers.ts`'s `grafanaProviders`
+ *   supplies it per target with `Layer.provide`, the same composition `litellm/providers.ts` uses.
+ *
+ * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE — the
+ *   same split forgejo's and netbox's engines use. `Effect.catchTag`'s tag-literal inference needs
+ *   a concrete error union to resolve `"NotFound"` against; a spec's `E` is only concrete at each
+ *   resource file's own call site.
+ */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import type { GrafanaOpContext } from '@distilled.cloud/grafana/Protocol';
+import * as Effect from 'effect/Effect';
+
+/**
+ * One Grafana object's distilled calls. `Live` is whatever the SDK decodes (a `DataSource`, …) —
+ * no untyped `Record<string, unknown>`. `E` is left to each resource file to declare (the union
+ * of the distilled operations it actually calls plus any domain refusal, e.g. an unset secret-ref
+ * env var), so a call site's precise error union flows straight through instead of being widened
+ * by hand here.
+ */
+export type GrafanaSpec<Props extends object, Live, Attributes, E> = {
+  /** Already folds the SDK's `NotFound` to `undefined` via its own `catchTag` — see the note above. */
+  readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, GrafanaOpContext>;
+  readonly attributes: (live: Live, props: Props) => Attributes | undefined;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  readonly create: (props: Props) => Effect.Effect<unknown, E, GrafanaOpContext>;
+  readonly update?: (props: Props, live: Live) => Effect.Effect<unknown, E, GrafanaOpContext>;
+  readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, GrafanaOpContext>;
+};
+
+export const grafanaOperations = <Props extends object, Live, Attributes, E>(
+  spec: GrafanaSpec<Props, Live, Attributes, E>,
+) => {
+  const read = (props: Props) =>
+    spec
+      .fetchLive(props)
+      .pipe(Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))));
+
+  return {
+    read,
+
+    diff: (news: Input<Props>, output: Attributes | undefined) =>
+      Effect.gen(function* () {
+        if (output === undefined || !isResolved(news)) return undefined;
+        const live = yield* read(news);
+        if (live === undefined) return { action: 'update' } as const;
+        if (spec.matches(live, news)) return { action: 'noop' } as const;
+        return spec.update === undefined
+          ? ({ action: 'replace' } as const)
+          : ({ action: 'update' } as const);
+      }),
+
+    /**
+     * ★ OBSERVES BEFORE IT WRITES (S9, S10) — THE WHOLE OF "ADOPT" FOR THIS FAMILY. A `uid` this
+     *   Grafana instance already has is bound and, when it already matches the declaration,
+     *   left alone; only a genuinely absent `uid` is created. Declaring exactly what is live
+     *   changes nothing on `reconcile`, the same posture netbox/resource.ts documents as
+     *   "adopt is the default posture, not a flag".
+     */
+    reconcile: (news: Props) =>
+      Effect.gen(function* () {
+        const before = yield* spec.fetchLive(news);
+        if (before === undefined) {
+          yield* spec.create(news);
+        } else if (spec.update !== undefined) {
+          const mapped = spec.attributes(before, news);
+          if (mapped === undefined || spec.matches(mapped, news)) {
+            /* adoption or already converged — no write */
+          } else {
+            yield* spec.update(news, before);
+          }
+        }
+        const after = yield* read(news);
+        if (after === undefined) {
+          return yield* Effect.die(
+            new Error(
+              'grafanaOperations: the write returned no error but the object is still absent. ' +
+                'Read back rather than trusting the response status.',
+            ),
+          );
+        }
+        return after;
+      }),
+
+    destroy: (olds: Props) =>
+      Effect.gen(function* () {
+        const live = yield* spec.fetchLive(olds);
+        if (live === undefined) return;
+        yield* spec.destroy(olds, live);
+      }),
+  };
+};
+
+/**
+ * The five provider handlers for a spec'd Grafana object, wired once. `Credentials` and
+ * `HttpClient.HttpClient` stay ambient context requirements — see the file header.
+ *
+ * ⚠️ `list` answers empty — an org's full datasource list is not a page this family sweeps for
+ *   adoption; adoption stays explicit, the same reasoning forgejo's and netbox's engines give.
+ */
+export const grafanaHandlers = <Props extends object, Live, Attributes extends object, E>(
+  spec: GrafanaSpec<Props, Live, Attributes, E>,
+) => {
+  const ops = grafanaOperations(spec);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds }: { olds: Props }) => ops.read(olds),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      ops.diff(news, output),
+    reconcile: ({ news }: { news: Props }) => ops.reconcile(news),
+    delete: ({ olds }: { olds: Props }) => ops.destroy(olds),
+  };
+};