@homeflare/alchemy 0.37.2 → 0.37.4

package/src/proxmox/notification-distilled.test.ts

@@ -0,0 +1,162 @@
+/** Notification lifecycles through the real SDK and upstream Alchemy test harness. */
+import { afterEach, beforeEach, expect, test as unit } from 'bun:test';
+import * as Test from 'alchemy/Test/Bun';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { fakeNotify } from './fake-pbs-notify.ts';
+import { FAKE_TARGET, fakePve, withoutBao } from './fake-pve.ts';
+import {
+  ProxmoxNotificationMatcher,
+  ProxmoxNotificationMatcherProvider,
+} from './notification-matcher.ts';
+import {
+  ProxmoxNotificationTarget,
+  ProxmoxNotificationTargetProvider,
+} from './notification-target.ts';
+import { readMatcher } from './notification-matcher-distilled.ts';
+import { readTarget } from './notification-target-distilled.ts';
+
+const fake = fakeNotify();
+let saved: [string, string | undefined][] = [];
+beforeEach(() => {
+  saved = Object.entries(process.env).filter(([key]) => /^(BAO|VAULT)_/.test(key));
+  for (const [key] of saved) delete process.env[key];
+  process.env['BAO_ADDR'] = 'http://bao.invalid';
+  fake.objects.clear();
+  fake.secrets.clear();
+  fake.calls.length = 0;
+});
+afterEach(() => {
+  for (const key of Object.keys(process.env))
+    if (/^(BAO|VAULT)_/.test(key)) delete process.env[key];
+  for (const [key, value] of saved) process.env[key] = value;
+});
+const { test } = Test.make({
+  adopt: true,
+  dev: false,
+  sidecar: false,
+  stage: 'test',
+  providers: Layer.mergeAll(
+    ProxmoxNotificationTargetProvider(),
+    ProxmoxNotificationMatcherProvider(),
+  ).pipe(Layer.provideMerge(fake.layer)),
+});
+const target = (clear = false) =>
+  ProxmoxNotificationTarget('mail', {
+    target: FAKE_TARGET,
+    type: 'sendmail',
+    name: 'mail',
+    mailto: clear ? [] : ['a@example.com', 'b@example.com'],
+    'mailto-user': ['root@pam'],
+  });
+const matcher = (clear = false) =>
+  ProxmoxNotificationMatcher('route', {
+    target: FAKE_TARGET,
+    name: 'route',
+    targets: ['mail'],
+    'match-field': clear ? [] : ['exact:type=prune,sync', 'regex:hostname=^node'],
+  });
+const stack = (clear = false) =>
+  Effect.gen(function* () {
+    yield* target(clear);
+    yield* matcher(clear);
+  });
+const existing = () => {
+  fake.objects.set('cluster/notifications/endpoints/sendmail/mail', {
+    name: 'mail',
+    mailto: ['b@example.com', 'a@example.com'],
+    'mailto-user': ['root@pam'],
+  });
+  fake.objects.set('cluster/notifications/matchers/route', {
+    name: 'route',
+    target: ['mail'],
+    'match-field': ['exact:type=prune,sync', 'regex:hostname=^node'],
+  });
+};
+const actions = (plan: { resources: Record<string, { action: string }> }) =>
+  Object.values(plan.resources)
+    .map((row) => row.action)
+    .sort();
+
+test.provider('matching target and matcher adopt with zero writes and redeploy noop', (scratch) =>
+  Effect.gen(function* () {
+    existing();
+    yield* scratch.deploy(stack());
+    expect(fake.writes()).toEqual([]);
+    expect(actions(yield* scratch.plan(stack()))).toEqual(['noop', 'noop']);
+  }),
+);
+test.provider('new rows send repeated arrays and preserve commas inside rules', (scratch) =>
+  Effect.gen(function* () {
+    yield* scratch.deploy(stack());
+    expect(fake.objects.get('cluster/notifications/matchers/route')?.['match-field']).toEqual([
+      'exact:type=prune,sync',
+      'regex:hostname=^node',
+    ]);
+    expect(fake.objects.get('cluster/notifications/endpoints/sendmail/mail')?.['mailto']).toEqual([
+      'a@example.com',
+      'b@example.com',
+    ]);
+    expect(actions(yield* scratch.plan(stack()))).toEqual(['noop', 'noop']);
+  }),
+);
+test.provider('empty recipient and rule arrays clear explicitly and settle to noop', (scratch) =>
+  Effect.gen(function* () {
+    existing();
+    yield* scratch.deploy(stack());
+    yield* scratch.deploy(stack(true));
+    expect(fake.objects.get('cluster/notifications/endpoints/sendmail/mail')).not.toHaveProperty(
+      'mailto',
+    );
+    expect(fake.objects.get('cluster/notifications/matchers/route')).not.toHaveProperty(
+      'match-field',
+    );
+    expect(actions(yield* scratch.plan(stack(true)))).toEqual(['noop', 'noop']);
+  }),
+);
+for (const status of [200, 400, 401, 403, 500]) {
+  unit(`malformed or refused HTTP ${status} cannot become absence`, async () => {
+    const broken = fakePve(() => Response.json({ data: null, message: 'refused' }, { status }));
+    await withoutBao(async () => {
+      const targetRead = readTarget({ target: FAKE_TARGET, name: 'mail', type: 'sendmail' });
+      const matcherRead = readMatcher({ target: FAKE_TARGET, name: 'route', targets: ['mail'] });
+      expect(
+        (await Effect.runPromise(Effect.exit(targetRead).pipe(Effect.provide(broken.layer))))._tag,
+      ).toBe('Failure');
+      expect(
+        (await Effect.runPromise(Effect.exit(matcherRead).pipe(Effect.provide(broken.layer))))._tag,
+      ).toBe('Failure');
+    });
+    expect(broken.writes()).toEqual([]);
+  });
+}
+
+test.provider('same-name endpoint type changes replace delete-first', (scratch) =>
+  Effect.gen(function* () {
+    const hook = ProxmoxNotificationTarget('endpoint', {
+      target: FAKE_TARGET,
+      name: 'pager',
+      type: 'webhook',
+      url: 'https://pager.example.com',
+      method: 'post',
+      header: ['name=X-One,value=b25l', 'name=X-Two,value=dHdv'],
+    });
+    const mail = ProxmoxNotificationTarget('endpoint', {
+      target: FAKE_TARGET,
+      name: 'pager',
+      type: 'sendmail',
+      'mailto-user': ['root@pam'],
+    });
+    yield* scratch.deploy(hook);
+    expect(fake.objects.get('cluster/notifications/endpoints/webhook/pager')?.['header']).toEqual([
+      'name=X-One,value=b25l',
+      'name=X-Two,value=dHdv',
+    ]);
+    yield* scratch.deploy(mail);
+    expect(fake.writes()).toEqual([
+      'POST cluster/notifications/endpoints/webhook',
+      'DELETE cluster/notifications/endpoints/webhook/pager',
+      'POST cluster/notifications/endpoints/sendmail',
+    ]);
+  }),
+);

package/src/proxmox/notification-matcher-distilled.ts

@@ -0,0 +1,60 @@
+/** PVE 9.2.11 matchers through distilled; 404 is measured absence, other failures propagate. */
+import * as cluster from '@distilled.cloud/proxmox/cluster';
+import * as Effect from 'effect/Effect';
+import type { NotificationMatcherProps } from './notification-matcher.ts';
+import {
+  matcherAttributes,
+  matcherCreateForm,
+  matcherUpdateForm,
+} from './notification-matcher-form.ts';
+import { runPve } from './distilled-pve.ts';
+import { notificationRequest, notificationResponse } from './notification-sdk-input.ts';
+
+export const readMatcher = (props: NotificationMatcherProps) =>
+  runPve(
+    props.target,
+    'read',
+    false,
+    cluster.getClusterNotificationMatcher({ name: props.name }),
+  ).pipe(
+    Effect.flatMap(notificationResponse(cluster.GetClusterNotificationMatcherResponse)),
+    Effect.map((live) =>
+      matcherAttributes(
+        {
+          ...live,
+          'invert-match': live.invert_match,
+          'match-calendar': live.match_calendar,
+          'match-field': live.match_field,
+          'match-severity': live.match_severity,
+        },
+        props.name,
+      ),
+    ),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+  );
+
+export const createMatcher = (props: NotificationMatcherProps) =>
+  Effect.gen(function* () {
+    const input = yield* notificationRequest(
+      cluster.CreateClusterNotificationMatcherRequest,
+      matcherCreateForm(props),
+    );
+    yield* runPve(props.target, 'provision', true, cluster.createClusterNotificationMatcher(input));
+  });
+
+export const updateMatcher = (props: NotificationMatcherProps) =>
+  Effect.gen(function* () {
+    const input = yield* notificationRequest(cluster.PutClusterNotificationMatcherRequest, {
+      ...matcherUpdateForm(props),
+      name: props.name,
+    });
+    yield* runPve(props.target, 'provision', true, cluster.putClusterNotificationMatcher(input));
+  });
+
+export const deleteMatcher = (props: NotificationMatcherProps) =>
+  runPve(
+    props.target,
+    'provision',
+    true,
+    cluster.deleteClusterNotificationMatcher({ name: props.name }),
+  ).pipe(Effect.catchTag('NotFound', () => Effect.void));

package/src/proxmox/notification-matcher-lifecycle.ts

@@ -0,0 +1,71 @@
+/** A matching PVE matcher adoption writes nothing; unreadable is never treated as absent. */
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type { NotificationMatcherProps as Props } from './notification-matcher.ts';
+import {
+  type NotificationMatcherAttributes as Attributes,
+  matcherCreateForm,
+  matcherMatches,
+  matcherUpdateForm,
+} from './notification-matcher-form.ts';
+import { guardForm } from './constraint-guard.ts';
+import {
+  createMatcher,
+  deleteMatcher,
+  readMatcher,
+  updateMatcher,
+} from './notification-matcher-distilled.ts';
+
+const guard = (props: Props, create: boolean) =>
+  guardForm('pve:POST /cluster/notifications/matchers', matcherCreateForm(props), create).pipe(
+    Effect.andThen(
+      guardForm('pve:PUT /cluster/notifications/matchers/{name}', matcherUpdateForm(props), false),
+    ),
+  );
+
+export const matcherHandlers = {
+  /** Built-ins and human-created matchers are not auto-enrolled; adoption is explicit. */
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: Props }) =>
+    Effect.gen(function* () {
+      const live = yield* readMatcher(olds);
+      yield* guard(olds, live === undefined);
+      return live;
+    }),
+  diff: ({
+    news,
+    olds,
+    output,
+  }: {
+    news: Input<Props>;
+    olds: Props;
+    output: Attributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      if (olds.name !== news.name) return { action: 'replace' } as const;
+      yield* guard(news, output === undefined);
+      if (output === undefined) return undefined;
+      const live = yield* readMatcher(news);
+      if (live === undefined) {
+        yield* guard(news, true);
+        return { action: 'update' } as const;
+      }
+      return { action: matcherMatches(live, news) ? 'noop' : 'update' } as const;
+    }),
+  reconcile: ({ news }: { news: Props }) =>
+    Effect.gen(function* () {
+      const live = yield* readMatcher(news);
+      yield* guard(news, live === undefined);
+      if (live === undefined) yield* createMatcher(news);
+      else if (!matcherMatches(live, news)) yield* updateMatcher(news);
+      const after = yield* readMatcher(news);
+      if (after === undefined)
+        return yield* Effect.die(
+          new Error(`Notification matcher ${news.name}: write returned but read-back is absent.`),
+        );
+      return after;
+    }),
+  delete: ({ olds }: { olds: Props }) => deleteMatcher(olds),
+};

package/src/proxmox/notification-matcher.ts

@@ -24,22 +24,19 @@
  *   ⛔ `Mapping.Use` IS NOT ENOUGH, though the COLLECTION GET accepts it: the per-object read this
  *     family makes lists only Audit and Modify (pve-manager API2/Cluster/Notifications.pm
  *     `get_matcher`, read at HEAD 2026-09-22 — corrected here; PR 95 said Use sufficed).
- *   ⛔ A MISSING READ PRIVILEGE LOOKS LIKE "ABSENT", not like a 403 — see the same file. For
- *     `default-matcher` that turns an adoption into a planned CREATE that PVE refuses as a
- *     duplicate: the noop below needs a read lease holding Mapping.Audit.
+ *   ⛔ THE OLD HAND CLIENT FOLDED A MISSING READ PRIVILEGE INTO "ABSENT", planning a duplicate
+ *     create. The distilled read now catches only NotFound: a refused read fails the plan.
+ *     The noop still requires a read lease holding Mapping.Audit.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import {
-  type NotificationMatcherAttributes,
-  type NotificationMatcherFields,
-  matcherAttributes,
-  matcherCreateForm,
-  matcherMatches,
-  matcherUpdateForm,
+import type {
+  NotificationMatcherAttributes,
+  NotificationMatcherFields,
 } from './notification-matcher-form.ts';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import type { PveRequirements, WithTarget } from './resource-spec.ts';
+import { matcherHandlers } from './notification-matcher-lifecycle.ts';
 
 export interface NotificationMatcherProps extends NotificationMatcherFields, WithTarget {}
 
@@ -60,22 +57,8 @@ export const ProxmoxNotificationMatcher = Resource<ProxmoxNotificationMatcher>(
   'Proxmox.NotificationMatcher',
 );
 
-const handlers = pveHandlers<NotificationMatcherProps, NotificationMatcherAttributes>({
-  attributes: (live, props) => matcherAttributes(live, props.name),
-  collection: () => 'cluster/notifications/matchers',
-  createForm: matcherCreateForm,
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: {
-    create: 'pve:POST /cluster/notifications/matchers',
-    update: 'pve:PUT /cluster/notifications/matchers/{name}',
-  },
-  matches: matcherMatches,
-  path: (props) => `cluster/notifications/matchers/${props.name}`,
-  updateForm: matcherUpdateForm,
-});
-
 export const ProxmoxNotificationMatcherProvider = () =>
   Provider.effect(
     ProxmoxNotificationMatcher,
-    Effect.succeed(ProxmoxNotificationMatcher.Provider.of(handlers)),
+    Effect.succeed(ProxmoxNotificationMatcher.Provider.of(matcherHandlers)),
   );

package/src/proxmox/notification-replacement.test.ts

@@ -0,0 +1,190 @@
+/** Real Plan/Apply must refuse an invalid replacement before deleting its working target. */
+import { afterEach, beforeEach, expect } from 'bun:test';
+import * as Test from 'alchemy/Test/Bun';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { fakeNotify } from './fake-pbs-notify.ts';
+import { FAKE_TARGET, fakePve } from './fake-pve.ts';
+import {
+  type NotificationTargetProps,
+  ProxmoxNotificationTarget,
+  ProxmoxNotificationTargetProvider,
+} from './notification-target.ts';
+import {
+  PbsNotificationTarget,
+  type PbsNotificationTargetProps,
+  PbsNotificationTargetProvider,
+} from './pbs-notification-target.ts';
+
+const MISSING = 'HF_NOTIFICATION_REPLACEMENT_MISSING';
+const PBS = { api: 'https://pbs.test:8007/api2/json', mount: 'pbs-test', scheme: 'pbs' } as const;
+const fake = fakeNotify();
+let saved: [string, string | undefined][] = [];
+beforeEach(() => {
+  saved = Object.entries(process.env).filter(
+    ([key]) => /^(BAO|VAULT)_/.test(key) || key === MISSING,
+  );
+  for (const [key] of saved) delete process.env[key];
+  process.env['BAO_ADDR'] = 'http://bao.invalid';
+  fake.objects.clear();
+  fake.secrets.clear();
+  fake.calls.length = 0;
+});
+afterEach(() => {
+  for (const key of Object.keys(process.env))
+    if (/^(BAO|VAULT)_/.test(key) || key === MISSING) delete process.env[key];
+  for (const [key, value] of saved) process.env[key] = value;
+});
+const { test } = Test.make({
+  adopt: true,
+  dev: false,
+  sidecar: false,
+  stage: 'test',
+  providers: Layer.mergeAll(
+    ProxmoxNotificationTargetProvider(),
+    PbsNotificationTargetProvider(),
+  ).pipe(Layer.provideMerge(fake.layer)),
+});
+
+const pve = (props: Omit<NotificationTargetProps, 'target'>) =>
+  ProxmoxNotificationTarget('endpoint', { ...props, target: FAKE_TARGET });
+const pbs = (props: Omit<PbsNotificationTargetProps, 'target'>) =>
+  PbsNotificationTarget('endpoint', { ...props, target: PBS });
+const invalidPve: readonly Omit<NotificationTargetProps, 'target' | 'name'>[] = [
+  { type: 'webhook', method: 'post' },
+  { type: 'gotify', server: 'https://gotify.example.com' },
+  { type: 'smtp', server: 'smtp.example.com' },
+  {
+    type: 'webhook',
+    method: 'post',
+    url: 'https://pager.example.com',
+    mailto: ['ops@example.com'],
+  },
+];
+const invalidPbs: readonly Omit<PbsNotificationTargetProps, 'target' | 'name'>[] = [
+  { type: 'webhook', method: 'post' },
+  {
+    type: 'webhook',
+    method: 'post',
+    url: 'https://pager.example.com',
+    secret: { token: { fromEnv: MISSING } },
+  },
+  { type: 'webhook', method: 'post', url: 'https://pager.example.com', comment: 'x'.repeat(129) },
+];
+for (const [index, props] of invalidPve.entries()) {
+  test.provider(`PVE replacement refusal ${index} preserves the old target`, (scratch) =>
+    Effect.gen(function* () {
+      const old = pve({ name: 'pager', type: 'sendmail' });
+      yield* scratch.deploy(old);
+      const path = 'cluster/notifications/endpoints/sendmail/pager';
+      const before = fake.objects.get(path);
+      fake.calls.length = 0;
+      expect((yield* Effect.exit(scratch.deploy(pve({ ...props, name: 'pager' }))))._tag).toBe(
+        'Failure',
+      );
+      expect(fake.writes()).toEqual([]);
+      expect(fake.objects.get(path)).toEqual(before);
+      expect(Object.values((yield* scratch.plan(old)).resources).map((row) => row.action)).toEqual([
+        'noop',
+      ]);
+    }),
+  );
+}
+for (const [index, props] of invalidPbs.entries()) {
+  test.provider(`PBS replacement refusal ${index} preserves the old target`, (scratch) =>
+    Effect.gen(function* () {
+      const old = pbs({ name: 'pager', type: 'sendmail' });
+      yield* scratch.deploy(old);
+      const path = 'config/notifications/endpoints/sendmail/pager';
+      const before = fake.objects.get(path);
+      fake.calls.length = 0;
+      expect((yield* Effect.exit(scratch.deploy(pbs({ ...props, name: 'pager' }))))._tag).toBe(
+        'Failure',
+      );
+      expect(fake.writes()).toEqual([]);
+      expect(fake.objects.get(path)).toEqual(before);
+      expect(Object.values((yield* scratch.plan(old)).resources).map((row) => row.action)).toEqual([
+        'noop',
+      ]);
+    }),
+  );
+}
+test.provider(
+  'PVE can replace by adopting an existing renamed gotify target without its token',
+  (scratch) =>
+    Effect.gen(function* () {
+      yield* scratch.deploy(pve({ name: 'old', type: 'sendmail' }));
+      const path = 'cluster/notifications/endpoints/gotify/existing';
+      fake.objects.set(path, { name: 'existing', server: 'https://gotify.example.com' });
+      fake.calls.length = 0;
+      yield* scratch.deploy(
+        pve({ name: 'existing', type: 'gotify', server: 'https://gotify.example.com' }),
+      );
+      expect(fake.objects.has(path)).toBe(true);
+      expect(fake.writes()).toEqual(['DELETE cluster/notifications/endpoints/sendmail/old']);
+    }),
+);
+
+const forbidden = fakePve((call) =>
+  call.path.endsWith('/sendmail/pager')
+    ? { name: 'pager' }
+    : Response.json({ message: 'forbidden' }, { status: 403 }),
+);
+const blocked = Test.make({
+  adopt: true,
+  dev: false,
+  sidecar: false,
+  stage: 'test',
+  providers: Layer.mergeAll(
+    ProxmoxNotificationTargetProvider(),
+    PbsNotificationTargetProvider(),
+  ).pipe(Layer.provideMerge(forbidden.layer)),
+}).test;
+for (const declare of [pve, pbs]) {
+  blocked.provider(`${declare.name} destination refusal prevents replacement deletion`, (scratch) =>
+    Effect.gen(function* () {
+      forbidden.calls.length = 0;
+      yield* scratch.deploy(
+        Effect.gen(function* () {
+          yield* declare({ name: 'pager', type: 'sendmail' });
+        }),
+      );
+      const replacement = Effect.gen(function* () {
+        yield* declare({
+          name: 'pager',
+          type: 'webhook',
+          url: 'https://pager.example.com',
+          method: 'post',
+        });
+      });
+      expect((yield* Effect.exit(scratch.deploy(replacement)))._tag).toBe('Failure');
+      expect(forbidden.writes()).toEqual([]);
+    }),
+  );
+}
+test.provider(
+  'PBS can replace by adopting an existing renamed webhook without its secret value',
+  (scratch) =>
+    Effect.gen(function* () {
+      yield* scratch.deploy(pbs({ name: 'old', type: 'sendmail' }));
+      const path = 'config/notifications/endpoints/webhook/existing';
+      fake.objects.set(path, {
+        name: 'existing',
+        url: 'https://pager.example.com',
+        method: 'post',
+        secret: ['name=token'],
+      });
+      fake.calls.length = 0;
+      yield* scratch.deploy(
+        pbs({
+          name: 'existing',
+          type: 'webhook',
+          url: 'https://pager.example.com',
+          method: 'post',
+          secret: { token: { fromEnv: MISSING } },
+        }),
+      );
+      expect(fake.objects.has(path)).toBe(true);
+      expect(fake.writes()).toEqual(['DELETE config/notifications/endpoints/sendmail/old']);
+    }),
+);

package/src/proxmox/notification-sdk-input.ts

@@ -0,0 +1,39 @@
+/** PVE 9.2.11 form names mapped to the generated SDK's TypeScript field names. */
+import { ProxmoxParseError } from '@distilled.cloud/proxmox/Errors';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+/** Local schema refusal names the operation, never a form value (headers may be sensitive). */
+export class NotificationRequestInvalid extends Data.TaggedError('NotificationRequestInvalid')<{
+  readonly operation: string;
+}> {}
+
+/**
+ * The provider's forms already enforce vendor constraints. This final generated-schema
+ * check validates the translated Type-side fields without a cast. Unexpected family fields
+ * fail explicitly instead of disappearing through the decoder's default excess-property stripping.
+ */
+export const notificationRequest = <S extends Schema.Top>(schema: S, fields: object) =>
+  Schema.decodeUnknownEffect(Schema.toType(schema), { onExcessProperty: 'error' })(
+    Object.fromEntries(
+      Object.entries(fields).map(([key, value]) => [key.replaceAll('-', '_'), value]),
+    ),
+  ).pipe(
+    Effect.mapError(() => new NotificationRequestInvalid({ operation: 'PVE notification write' })),
+  );
+
+/** Validate required response fields with the SDK schema without discarding vendor extras. */
+export const notificationResponse =
+  <S extends Schema.Top>(schema: S) =>
+  (body: S['Type']) =>
+    Schema.decodeUnknownEffect(Schema.toType(schema))(body).pipe(
+      Effect.as(body),
+      Effect.mapError(
+        () =>
+          new ProxmoxParseError({
+            body: undefined,
+            cause: 'PVE notification response does not match its SDK schema',
+          }),
+      ),
+    );