@homeflare/alchemy 0.33.0 → 0.34.0

package/src/grafana/mute-timing.ts

@@ -0,0 +1,160 @@
+/**
+ * `Grafana.MuteTiming` — one Grafana alerting mute timing, keyed by `name` (there is no separate
+ * `uid` — `routeGetMuteTiming`/`routePutMuteTiming`/`routeDeleteMuteTiming` are all name-keyed on
+ * the wire, and `name` is the field a notification policy's own `mute_time_intervals` references).
+ *
+ * ★ `provenance`/`version` ARE READ THROUGH A WIDENED TYPE, NOT THE SDK's OWN `MuteTimeInterval` —
+ *   MEASURED, and a genuinely surprising result worth recording in full. The SDK's generated
+ *   `MuteTimeInterval` interface (`packages/distilled-grafana/src/services/grafana.ts`) declares
+ *   only `name`/`time_intervals` — no `provenance`, no `version` — unlike `EmbeddedContactPoint`/
+ *   `NotificationTemplate`/`ProvisionedAlertRule`/`Route`, which all carry `provenance`. A first
+ *   pass at this file assumed that meant the data was gone: decoding a raw payload containing both
+ *   fields through `S.decodeUnknownSync(MuteTimeInterval)` directly DOES strip them. But that is
+ *   the wrong code path — it is not what `routeGetMuteTiming` itself does. Proven empirically by
+ *   calling the REAL operation (through `fake-grafana.ts`'s harness, the exact path this file's own
+ *   `fetchLive` uses) with a response body containing `provenance`/`version`: both come through on
+ *   the decoded value intact. The mechanism, read from `@distilled.cloud/core@1.0.0-rc.12`'s
+ *   `protocol-rest.ts`/`protocol-http.ts` (the runtime this SDK's every operation shares): response
+ *   decoding is `JSON.parse` + `mapKeys` (renames only the field names a schema DOES declare) +
+ *   `wrapSensitive` (wraps only fields a schema marks sensitive in `Redacted`) — never a strict
+ *   `Schema.decode`. `protocol-http.ts`'s `mapKeys`, object branch: every response key NOT among a
+ *   type's declared `props` is copied to the output verbatim in a second pass
+ *   (`for (const [k, v] of Object.entries(value)) { if (consumed.has(k)) continue; out[k] = v; }`,
+ *   line ~297-311) — the doc comment on the sibling `wrapSensitive` states the same rule plainly:
+ *   "Keys the schema doesn't model pass through verbatim." So the TS type is simply narrower than
+ *   the runtime value; `MuteTimeIntervalWire` below is that same runtime value, typed honestly.
+ *   This is a real, worth-fixing SDK type-generation gap (tracked in `docs/upstream-conformance.md`,
+ *   same S22 route as the other named gaps) but NOT a data-loss gap — unlike, say, a field the wire
+ *   protocol itself never sent, this one is fully recoverable without touching vendored `src/`.
+ *
+ *   The same test proved the outbound direction too: an object with extra keys (`weekdays`, `times`
+ *   — the real Alertmanager time-interval fields Grafana's OpenAPI's own `TimeInterval` schema
+ *   apparently fails to model either, for the same reason) passed to `routePutMuteTiming` reaches
+ *   the wire body unchanged — `mapKeys`'s encode direction is the same verbatim-passthrough rule.
+ *   `MuteTimingProps.timeIntervals` is therefore typed as the opaque `Record<string, unknown>`
+ *   shape actually needed to declare a real mute timing (weekdays/times/months/etc.), not the
+ *   SDK's own too-narrow `TimeInterval`, and cast at the two call sites below.
+ *
+ * ⚠️ THE EVIDENCE ABOVE IS A HAND-AUTHORED FIXTURE, NOT A CAPTURED REAL RESPONSE — flagged by an
+ *   adversarial review of this PR. The estate has zero live mute timings to observe (grafana.md's
+ *   census), so nothing confirms Grafana always includes `provenance` on this route in practice,
+ *   or that some other SDK/version edge case never drops it. That is exactly why `attributes()`
+ *   below never coerces a missing `live.provenance` to `''` — see alerting-provenance.ts's "fails
+ *   open" note — an absent field refuses a write rather than being trusted as `ProvenanceNone`.
+ *
+ * ⛔ A FOREIGN-PROVENANCE MUTE TIMING REFUSES EVERY UPDATE AND DESTROY — `alerting-provenance.ts`,
+ *   shared with `Grafana.ContactPoint`/`MessageTemplate`/`AlertRuleGroup`/`NotificationPolicy`; see
+ *   that file's header. `create` is never at risk: it only runs when `fetchLive` already found
+ *   nothing with this `name`.
+ *
+ * ⚠️ `version` IS SENT ON DESTROY, NOT ON UPDATE — MEASURED: `RouteDeleteMuteTimingRequest.version`
+ *   ("Version of mute timing to use for optimistic concurrency. Leave empty to disable validation")
+ *   exists; `RoutePutMuteTimingRequest` has no `version` field at all, so an update has nothing to
+ *   send for it — a real Grafana API asymmetry between the two write routes, not an omission here.
+ *
+ * ⚠️ `X-Disable-Provenance` IS NEVER SET — same reasoning as `contact-point.ts`'s file header.
+ */
+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 { declaredContentMatches } from './subset-match.ts';
+
+export interface MuteTimingProps {
+  name: string;
+  /** Grafana's Alertmanager-style time-interval entries (`weekdays`/`times`/`months`/…), passed
+   *  through opaquely — see the file header for why this is not the SDK's own `TimeInterval`. */
+  timeIntervals: ReadonlyArray<Record<string, unknown>>;
+}
+
+export interface MuteTimingAttributes {
+  name: string;
+  timeIntervals: ReadonlyArray<Record<string, unknown>>;
+  /** `""`/`"api"` (this family may write); anything else, INCLUDING `undefined` (Grafana didn't
+   *  report the field, or the widened-type passthrough this file depends on turns out not to hold
+   *  for some response shape not yet observed), refuses — see alerting-provenance.ts's "fails
+   *  open" note. This is the field where that default matters most: unlike the other resources in
+   *  this family, `provenance` here is not even in the SDK's declared type. */
+  provenance: string | undefined;
+}
+
+export interface GrafanaMuteTiming extends Resource<
+  'Grafana.MuteTiming',
+  MuteTimingProps,
+  MuteTimingAttributes,
+  never
+> {}
+
+export const GrafanaMuteTiming = Resource<GrafanaMuteTiming>('Grafana.MuteTiming');
+
+/** The real runtime shape of a `GET`/list response — see the file header's "measured" note. */
+type MuteTimeIntervalWire = grafana.MuteTimeInterval & {
+  provenance?: string;
+  version?: string;
+};
+
+export const spec: GrafanaSpec<
+  MuteTimingProps,
+  MuteTimeIntervalWire,
+  MuteTimingAttributes,
+  | grafana.RouteGetMuteTimingError
+  | grafana.RoutePostMuteTimingError
+  | grafana.RoutePutMuteTimingError
+  | grafana.RouteDeleteMuteTimingError
+  | GrafanaProvisionedObjectError
+> = {
+  attributes: (live) => ({
+    name: live.name ?? '',
+    // ⛔ NEVER `?? ''` — see alerting-provenance.ts's "fails open" note, and this file's own
+    //   Attributes doc comment on why it matters most here.
+    provenance: live.provenance,
+    timeIntervals: (live.time_intervals ?? []) as unknown as ReadonlyArray<Record<string, unknown>>,
+  }),
+  create: (props) =>
+    grafana.routePostMuteTiming({
+      name: props.name,
+      time_intervals:
+        props.timeIntervals as unknown as grafana.RoutePostMuteTimingRequestTimeIntervalsList,
+    }),
+  destroy: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance('Grafana.MuteTiming', props.name, live.provenance);
+      }
+      yield* grafana.routeDeleteMuteTiming({
+        name: props.name,
+        ...(live.version === undefined ? {} : { version: live.version }),
+      });
+    }),
+  fetchLive: (props) =>
+    grafana.routeGetMuteTiming({ name: props.name }).pipe(
+      Effect.map((live) => live as MuteTimeIntervalWire),
+      Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+    ),
+  /** Subset match (subset-match.ts), not plain equality — tolerates a default Grafana might
+   *  inject into a time-interval entry the declaration never set. */
+  matches: (attributes, props) =>
+    declaredContentMatches(props.timeIntervals, attributes.timeIntervals),
+  update: (props, live) =>
+    Effect.gen(function* () {
+      if (isForeignProvenance(live.provenance)) {
+        return yield* refuseIfForeignProvenance('Grafana.MuteTiming', props.name, live.provenance);
+      }
+      yield* grafana.routePutMuteTiming({
+        name: props.name,
+        time_intervals:
+          props.timeIntervals as unknown as grafana.RoutePutMuteTimingRequestTimeIntervalsList,
+      });
+    }),
+};
+
+export const handlers = grafanaHandlers(spec);
+
+export const GrafanaMuteTimingProvider = () =>
+  Provider.effect(GrafanaMuteTiming, Effect.succeed(GrafanaMuteTiming.Provider.of(handlers)));

package/src/grafana/providers.ts

@@ -12,14 +12,20 @@
  *   deploys anything over HTTP already has one.
  */
 import * as Layer from 'effect/Layer';
+import { GrafanaContactPointProvider } from './contact-point.ts';
 import { type GrafanaTarget, grafanaCredentials } from './credentials.ts';
 import { GrafanaDashboardProvider } from './dashboard.ts';
 import { GrafanaDatasourceProvider } from './datasource.ts';
 import { GrafanaFolderProvider } from './folder.ts';
+import { GrafanaMessageTemplateProvider } from './message-template.ts';
+import { GrafanaMuteTimingProvider } from './mute-timing.ts';
 
 export const grafanaProviders = (target: GrafanaTarget) =>
   Layer.mergeAll(
     GrafanaDatasourceProvider(),
     GrafanaFolderProvider(),
     GrafanaDashboardProvider(),
+    GrafanaContactPointProvider(),
+    GrafanaMuteTimingProvider(),
+    GrafanaMessageTemplateProvider(),
   ).pipe(Layer.provide(grafanaCredentials(target)));

package/src/grafana/secret-refs.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared "secret stays in env, never in state" resolution (S25) for this family —
+ * `Grafana.Datasource`'s `secureJsonDataRefs` and `Grafana.ContactPoint`'s `secureSettingsRefs`
+ * are the identical shape: a map of field name to an env var NAME, resolved fresh from
+ * `process.env` inside the caller's own create/update effect (S24), never at plan time and never
+ * returned in `attributes`. Extracted here once a second family needed the exact same loop
+ * `datasource.ts` already had — see that file's original note for why this exists at all:
+ * Grafana's own read APIs never return a secret value, only whether one is set
+ * (`DataSource.secureJsonFields`'s booleans; a contact point's `settings` comes back with secure
+ * keys replaced by a literal redaction placeholder instead — see contact-point.ts).
+ */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+
+/** A named secure-field env var is unset — a domain refusal, not a distilled error. */
+export class GrafanaSecretRefUnsetError extends Data.TaggedError('GrafanaSecretRefUnsetError')<{
+  readonly message: string;
+}> {}
+
+/**
+ * Reads every named env var fresh, inside the caller's effect (S24) — never at plan time.
+ * `describeField` builds the refusal message's own field-specific phrase — each caller names its
+ * declaration path differently (`secureJsonData.<field>` for a datasource,
+ * `settings.<field>` for a contact point) — so the message stays accurate to what the caller
+ * itself declares.
+ */
+export const resolveSecretRefs = (
+  refs: Record<string, string> | undefined,
+  describeField: (field: string) => string,
+): Effect.Effect<Record<string, string> | undefined, GrafanaSecretRefUnsetError> =>
+  Effect.gen(function* () {
+    if (refs === undefined) return undefined;
+    const out: Record<string, string> = {};
+    for (const [field, envVar] of Object.entries(refs)) {
+      const raw = process.env[envVar];
+      if (raw === undefined || raw.trim() === '') {
+        return yield* Effect.fail(
+          new GrafanaSecretRefUnsetError({
+            message:
+              `${envVar} is unset. Export the value of ${describeField(field)} there — ` +
+              'never as an Alchemy prop.',
+          }),
+        );
+      }
+      out[field] = raw.trim();
+    }
+    return out;
+  });

package/src/grafana/subset-match.ts

@@ -0,0 +1,71 @@
+/**
+ * `declaredContentMatches` — "is the declaration a subset of what is live", not plain equality.
+ * Extracted out of `dashboard-model.ts` (where it was introduced, after an adversarial review of
+ * that PR found plain structural equality made an ordinary, never-edited dashboard show `update`
+ * FOREVER) once a second shape needed the identical rule: `Grafana.ContactPoint`'s `settings` is
+ * the same story — Grafana can inject default fields into a contact point's settings that the
+ * declaration never mentioned, and `Grafana.AlertRuleGroup`'s per-rule `data`/`annotations`/
+ * `labels` maps carry the same risk. Nothing about the reasoning below is dashboard-specific;
+ * `dashboard-model.ts` now just re-exports this.
+ *
+ * ★ `declared` NEED ONLY BE A SUBSET OF `live`. Grafana's own save/decode path can decorate an
+ *   object with fields the declaration never set (a dashboard panel's auto-resolved `datasource`
+ *   reference is the documented example dashboard-model.ts found — Grafana's schema migration
+ *   decorates any panel/target whose `datasource` is absent with an explicit `{type, uid}`
+ *   reference on save). This function instead asks only "does every field the DECLARATION
+ *   mentions, at any depth, still match what is live" — `live` may carry additional fields, at any
+ *   depth, that `declared` never mentioned, without being compared at all. A field `declared` DOES
+ *   mention that is missing, or different, in `live` still fails the match — real content drift is
+ *   still caught exactly as before; only fields the declaration is silent about are now tolerated.
+ *
+ * ⚠️ THE TRADE-OFF THIS ACCEPTS, DELIBERATELY: removing a field from the declaration (rather than
+ *   changing its value) can no longer force Grafana to drop it. If a previous declaration set a
+ *   field and a later one deletes that key entirely, `live` keeps whatever the last write set — the
+ *   declaration is silent about that key now, so nothing compares it, so no `update` ever fires to
+ *   change it. This is the same "undeclared means don't care, never means force-to-default"
+ *   convention already used everywhere else in this kit for a plain optional prop; it now also
+ *   applies inside a nested JSON value, not just at the top-level props. Declare an explicit
+ *   replacement value to change a field; omission never clears one that was set by a previous
+ *   declaration or by Grafana itself.
+ *
+ * ⚠️ ARRAYS COMPARE BY LENGTH, THEN ELEMENT-WISE SUBSET — never a looser "declared has fewer
+ *   items" rule. A caller whose array IS order-significant (dashboard `panels`/`targets`) or
+ *   position-keyed (an alert rule group's `rules`) gets that for free; a caller with a genuinely
+ *   unordered array would need its own normalization first (this file has no `sortedSet`, and
+ *   nothing in this kit's Grafana family needs one — see dashboard-model.ts's own note).
+ *
+ *   ⛔ NOT RE-MEASURED FOR EVERY CALLER — flagged by an adversarial review of this PR. The exact
+ *   length rule is confirmed for dashboards (the original, documented case), but whether Grafana
+ *   ever PADS or APPENDS a default entry to an array the way it decorates an object field (the
+ *   `datasource` auto-decoration above) is unverified for `Grafana.MuteTiming`'s `time_intervals`
+ *   specifically — no live mute timing exists in this house to observe (grafana.md's census), and
+ *   `mute-timing.test.ts`'s own fixtures are hand-authored, not captured. If a future live
+ *   observation finds Grafana appending an entry (e.g. a normalized default time range) to a
+ *   declared `time_intervals` array, the length check here would show a permanent false `update` —
+ *   the exact regression this whole file exists to prevent for OBJECT fields already. `mute-timing.
+ *   test.ts`'s "array length is exact, not tolerant" test pins today's behavior so that fix has an
+ *   obvious, single place to change (relax this rule, or give the mute-timing caller its own
+ *   length-tolerant wrapper) rather than being rediscovered from scratch.
+ * ⚠️ `null` ON EITHER SIDE OF A LEAF NEVER MISMATCHES (mirrors `alchemy/Diff`'s `deepEqual` with
+ *   `stripNullish: true`, which this function replaces wherever a caller needs subset semantics).
+ */
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+export const declaredContentMatches = (declared: unknown, live: unknown): boolean => {
+  if (declared == null) return true;
+  if (Array.isArray(declared)) {
+    return (
+      Array.isArray(live) &&
+      declared.length === live.length &&
+      declared.every((item, index) => declaredContentMatches(item, live[index]))
+    );
+  }
+  if (isPlainObject(declared)) {
+    return (
+      isPlainObject(live) &&
+      Object.entries(declared).every(([key, value]) => declaredContentMatches(value, live[key]))
+    );
+  }
+  return declared === live;
+};

package/src/linux/index-export.test.ts

@@ -0,0 +1,25 @@
+/**
+ * `renderContainerFile`/`containerPathFor` are reachable from the package entry — the same pure
+ * `.container` renderer `container-fixture.test.ts` (container-form.ts) already proves internally,
+ * now callable by a CONSUMER without a deep import.
+ *
+ * ★ WHY THIS WAS MISSING. `index.ts`'s barrel forwarded `QUADLET_DEFAULT_DIRECTORY`/
+ *   `QUADLET_SEARCH_DIRECTORIES` (constants) but not the renderer or the path rule, unlike
+ *   `Systemd.Unit`'s own pure helpers (`renderUnit`/`DEFAULT_UNIT_DIRECTORY`), which ARE both on
+ *   the barrel. A consumer (homeflare-ct100 PR #1) writing an equivalence test against a live
+ *   host — the same kind of test this package's own fixture tests are — had no import path to
+ *   the real renderer and had to reimplement the render contract by hand to write one at all.
+ */
+import { expect, test } from 'bun:test';
+import { containerPathFor, renderContainerFile } from './index.ts';
+
+test('renderContainerFile and containerPathFor are reachable from the package entry', () => {
+  const rendered = renderContainerFile({
+    container: { image: 'docker.io/library/busybox:1', network: 'host' },
+    name: 'smoke',
+  });
+  expect(rendered).toContain('[Container]');
+  expect(rendered).toContain('Image=docker.io/library/busybox:1');
+  expect(rendered).toContain('Network=host');
+  expect(containerPathFor({ name: 'smoke' })).toBe('/etc/containers/systemd/smoke.container');
+});

package/src/linux/index.ts

@@ -38,5 +38,19 @@ export type {
   PodmanContainerProps,
   PodmanUnitLine,
 } from './container.ts';
-export { QUADLET_DEFAULT_DIRECTORY, QUADLET_SEARCH_DIRECTORIES } from './container-form.ts';
+// ★ `renderContainerFile`/`containerPathFor` are the pure `.container` file renderer and its path
+//   rule — the same kind of pure helper `renderUnit`/`DEFAULT_UNIT_DIRECTORY` above already are
+//   for `Systemd.Unit`. A consumer needs these to prove ITS OWN declared props render into the
+//   directive set it expects (an equivalence/fixture test against a live host), the same way this
+//   package's own container-fixture.test.ts does internally — without them, a consuming repo has
+//   no import path to the real renderer and has to reimplement it to write that test at all
+//   (found: homeflare-ct100 PR #1). `containerProblems`/`refuseContainer`/`serviceNameFor` stay
+//   internal — no consumer need for those was raised, and validation/naming internals are a wider
+//   surface to commit to than one pure render function.
+export {
+  containerPathFor,
+  QUADLET_DEFAULT_DIRECTORY,
+  QUADLET_SEARCH_DIRECTORIES,
+  renderContainerFile,
+} from './container-form.ts';
 export { PodmanContainer, PodmanContainerProvider } from './container.ts';