@homeflare/alchemy 0.37.2 → 0.37.3

package/src/proxmox/pbs-jobs-sdk.test.ts

@@ -0,0 +1,215 @@
+/** Four PBS families through the real SDK and Alchemy's upstream test harness. */
+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 { PBS_JOBS_TARGET, fakePbsJobs } from './fake-pbs-jobs.ts';
+import { PbsDatastore, PbsDatastoreProvider } from './pbs-datastore.ts';
+import { deleteOne as deleteDatastore } from './pbs-datastore-wire.ts';
+import { PbsPruneJob, PbsPruneJobProvider } from './pbs-prune-job.ts';
+import { PbsSyncJob, PbsSyncJobProvider } from './pbs-sync-job.ts';
+import { PbsVerifyJob, PbsVerifyJobProvider } from './pbs-verify-job.ts';
+
+const fake = fakePbsJobs();
+// ⛔ Test harness hooks take Effects, so isolate the shell before its per-test runtime starts.
+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.reset();
+});
+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(
+    PbsDatastoreProvider(),
+    PbsPruneJobProvider(),
+    PbsSyncJobProvider(),
+    PbsVerifyJobProvider(),
+  ).pipe(Layer.provideMerge(fake.layer)),
+});
+
+const stack = (comment = 'current') =>
+  Effect.gen(function* () {
+    yield* PbsDatastore('store', {
+      name: 'store',
+      path: '/mnt/store',
+      'gc-schedule': 'daily',
+      'verify-new': false,
+      comment,
+      target: PBS_JOBS_TARGET,
+    });
+    yield* PbsPruneJob('prune', {
+      id: 'prune',
+      store: 'store',
+      schedule: 'daily',
+      'keep-daily': 30,
+      'max-depth': 0,
+      comment,
+      target: PBS_JOBS_TARGET,
+    });
+    yield* PbsSyncJob('sync', {
+      id: 'sync',
+      store: 'store',
+      'remote-store': 'other',
+      'remote-ns': 'archive',
+      'remove-vanished': false,
+      'max-depth': 0,
+      'verified-only': true,
+      comment,
+      target: PBS_JOBS_TARGET,
+    });
+    yield* PbsVerifyJob('verify', {
+      id: 'verify',
+      store: 'store',
+      schedule: null,
+      'outdated-after': 30,
+      comment,
+      target: PBS_JOBS_TARGET,
+    });
+  });
+
+const existing = () => {
+  fake.rows.set('config/datastore/store', {
+    name: 'store',
+    path: '/mnt/store',
+    'gc-schedule': 'daily',
+    'verify-new': false,
+    comment: 'current',
+  });
+  fake.rows.set('config/prune/prune', {
+    id: 'prune',
+    store: 'store',
+    schedule: 'daily',
+    'keep-daily': 30,
+    'max-depth': 0,
+    comment: 'current',
+  });
+  fake.rows.set('config/sync/sync', {
+    id: 'sync',
+    store: 'store',
+    'remote-store': 'other',
+    'remote-ns': 'archive',
+    'remove-vanished': false,
+    'max-depth': 0,
+    'verified-only': true,
+    comment: 'current',
+  });
+  fake.rows.set('config/verify/verify', {
+    id: 'verify',
+    store: 'store',
+    'ignore-verified': true,
+    'outdated-after': 30,
+    comment: 'current',
+  });
+};
+
+const actions = (plan: { resources: Record<string, { action: string }> }) =>
+  Object.values(plan.resources)
+    .map((row) => row.action)
+    .sort();
+
+test.provider(
+  'matching datastore and three job families adopt without writes, then plan noop',
+  (scratch) =>
+    Effect.gen(function* () {
+      existing();
+      yield* scratch.deploy(stack());
+      expect(fake.writes).toEqual([]);
+      expect(actions(yield* scratch.plan(stack()))).toEqual(['noop', 'noop', 'noop', 'noop']);
+    }),
+);
+
+test.provider(
+  'measured missing sections create through typed SDK forms and settle to noop',
+  (scratch) =>
+    Effect.gen(function* () {
+      yield* scratch.deploy(stack());
+      expect(fake.writes.map((row) => `${row.method} ${row.path}`).sort()).toEqual([
+        'POST config/datastore',
+        'POST config/prune',
+        'POST config/sync',
+        'POST config/verify',
+      ]);
+      expect(fake.writes.find((row) => row.path === 'config/prune')?.form).toMatchObject({
+        'keep-daily': '30',
+        'max-depth': '0',
+      });
+      expect(fake.writes.find((row) => row.path === 'config/sync')?.form).toMatchObject({
+        'remote-store': 'other',
+        'remote-ns': 'archive',
+        'remove-vanished': '0',
+        'verified-only': '1',
+      });
+      expect(fake.writes.find((row) => row.path === 'config/verify')?.form).not.toHaveProperty(
+        'schedule',
+      );
+      expect(actions(yield* scratch.plan(stack()))).toEqual(['noop', 'noop', 'noop', 'noop']);
+    }),
+);
+
+test.provider(
+  'drift updates only declared fields through SDK forms and the next plan is noop',
+  (scratch) =>
+    Effect.gen(function* () {
+      existing();
+      yield* scratch.deploy(stack());
+      yield* scratch.deploy(stack('changed'));
+      expect(fake.writes.map((row) => `${row.method} ${row.path}`).sort()).toEqual([
+        'PUT config/datastore/store',
+        'PUT config/prune/prune',
+        'PUT config/sync/sync',
+        'PUT config/verify/verify',
+      ]);
+      for (const write of fake.writes) expect(write.form).not.toHaveProperty('delete');
+      expect(actions(yield* scratch.plan(stack('changed')))).toEqual([
+        'noop',
+        'noop',
+        'noop',
+        'noop',
+      ]);
+    }),
+);
+
+for (const status of [200, 400, 401, 403, 500]) {
+  test.provider(
+    `HTTP ${status} malformed or refused read never becomes create or noop`,
+    (scratch) =>
+      Effect.gen(function* () {
+        existing();
+        yield* scratch.deploy(stack());
+        fake.failRead(status, { message: 'unrelated server refusal', data: null });
+        const result = yield* Effect.exit(scratch.plan(stack()));
+        expect(result._tag).toBe('Failure');
+        expect(fake.writes).toEqual([]);
+        // Clear the injected failure before Test.Bun's automatic fixture teardown.
+        fake.reset();
+      }),
+  );
+}
+
+test.provider(
+  'a refused datastore delete read cannot confirm deletion; already absent needs no write',
+  (scratch) =>
+    Effect.gen(function* () {
+      existing();
+      yield* scratch.deploy(stack());
+      const props = { name: 'store', path: '/mnt/store', target: PBS_JOBS_TARGET };
+      fake.failRead(403, { message: 'permission denied', data: null });
+      expect((yield* Effect.exit(deleteDatastore(props)))._tag).toBe('Failure');
+      expect(fake.writes).toEqual([]);
+      fake.reset();
+      yield* deleteDatastore(props);
+      yield* scratch.destroy();
+      expect(fake.writes).toEqual([]);
+    }),
+);

package/src/proxmox/pbs-notification-errors.test.ts

@@ -0,0 +1,93 @@
+/** Read failures must never turn an existing notification route into a planned create. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import type { PbsTarget } from './credentials.ts';
+import { fakePve, withoutBao } from './fake-pve.ts';
+import { deleteMatcher, readMatcher } from './pbs-notification-matcher-distilled.ts';
+import {
+  PbsNotificationMatcher,
+  PbsNotificationMatcherProvider,
+} from './pbs-notification-matcher.ts';
+import { createTarget, deleteTarget, readTarget } from './pbs-notification-target-distilled.ts';
+import { PbsNotificationTarget, PbsNotificationTargetProvider } from './pbs-notification-target.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007', mount: 'pbs-test', scheme: 'pbs' };
+const MATCHER = { name: 'pager', target: PBS, targets: ['mail-to-root'] };
+const TARGET = { name: 'mail-to-root', target: PBS, type: 'sendmail' as const };
+
+for (const status of [401, 403, 500, 503]) {
+  test(`PBS ${String(status)} fails cold adoption and cannot POST either notification family`, async () => {
+    const fake = fakePve(() => Response.json({ message: 'read refused' }, { status }));
+    const providers = Layer.mergeAll(
+      PbsNotificationMatcherProvider(),
+      PbsNotificationTargetProvider(),
+    );
+    const stack = Effect.gen(function* () {
+      yield* PbsNotificationMatcher('pager', MATCHER);
+      yield* PbsNotificationTarget('mail', TARGET);
+    });
+    await withoutBao(async () => {
+      const engine = engineOver(providers.pipe(Layer.provideMerge(fake.layer)));
+      await expect(engine.deploy(stack)).rejects.toBeDefined();
+    });
+    expect(fake.writes()).toEqual([]);
+  });
+}
+
+test('only the typed NotFound is absence, and deleting it is idempotent for both families', async () => {
+  // PBS 4.2 read-only missing-name probe, 2026-09-24: notification absence is plain-text 404.
+  const fake = fakePve(() => new Response("matcher 'pager' not found", { status: 404 }));
+  await withoutBao(async () => {
+    const outcome = await Effect.runPromise(
+      Effect.gen(function* () {
+        const matcher = yield* readMatcher(MATCHER);
+        const target = yield* readTarget(TARGET);
+        yield* deleteMatcher(MATCHER);
+        yield* deleteTarget(TARGET);
+        return { matcher, target };
+      }).pipe(Effect.provide(fake.layer)),
+    );
+    expect(outcome).toEqual({ matcher: undefined, target: undefined });
+  });
+});
+
+test('a malformed successful resource response is a failure, never absence', async () => {
+  const fake = fakePve(() => undefined);
+  await withoutBao(async () => {
+    for (const read of [
+      readMatcher(MATCHER).pipe(Effect.asVoid),
+      readTarget(TARGET).pipe(Effect.asVoid),
+    ]) {
+      await expect(Effect.runPromise(read.pipe(Effect.provide(fake.layer)))).rejects.toBeDefined();
+    }
+  });
+  expect(fake.writes()).toEqual([]);
+});
+
+test('typed write errors also propagate instead of being treated as completed deletes', async () => {
+  const fake = fakePve(() => Response.json({ message: 'permission denied' }, { status: 403 }));
+  await withoutBao(async () => {
+    for (const remove of [deleteMatcher(MATCHER), deleteTarget(TARGET)]) {
+      const error = await Effect.runPromise(remove.pipe(Effect.flip, Effect.provide(fake.layer)));
+      expect(error).toMatchObject({ _tag: 'Forbidden' });
+    }
+  });
+  expect(fake.writes()).toHaveLength(2);
+});
+
+test('invalid SDK input never echoes a write-only value or sends a vendor request', async () => {
+  const fake = fakePve(() => undefined);
+  await withoutBao(async () => {
+    const error = await Effect.runPromise(
+      createTarget(
+        { ...TARGET, type: 'smtp' },
+        { name: TARGET.name, password: 'invalid-input-secret-must-stay-private' },
+      ).pipe(Effect.flip, Effect.provide(fake.layer)),
+    );
+    expect(error).toMatchObject({ _tag: 'PbsNotificationInputRefusal' });
+    expect(JSON.stringify(error)).not.toContain('invalid-input-secret-must-stay-private');
+  });
+  expect(fake.calls).toEqual([]);
+});

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

@@ -0,0 +1,25 @@
+/** Validate translated fields with the SDK's own schema without echoing write-only values. */
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+export class PbsNotificationInputRefusal extends Data.TaggedError('PbsNotificationInputRefusal')<{
+  readonly message: string;
+}> {}
+
+/**
+ * Fields already use SDK Type-side names; toType validates without any wire transforms.
+ * A schema diagnostic can reproduce the whole submitted form, including a webhook secret or
+ * SMTP password. Sanitize only our pre-request validation failure. SDK operation errors below
+ * this boundary retain their original typed tags and are never remapped.
+ */
+export const notificationInput = <S extends Schema.Top>(schema: S, fields: unknown) =>
+  Schema.decodeUnknownEffect(Schema.toType(schema))(fields).pipe(
+    Effect.mapError(
+      () =>
+        new PbsNotificationInputRefusal({
+          message:
+            'PBS notification fields do not match the SDK request schema; no PBS request was sent.',
+        }),
+    ),
+  );

package/src/proxmox/pbs-notification-mail.test.ts

@@ -0,0 +1,64 @@
+/** Mail target CRUD uses the SDK's field spellings without losing lists or the password seal. */
+import { afterEach, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import { engineOver } from '../verify/fake-engine.ts';
+import type { PbsTarget } from './credentials.ts';
+import { fakeNotify } from './fake-pbs-notify.ts';
+import { withoutBao } from './fake-pve.ts';
+import { PbsNotificationTarget, PbsNotificationTargetProvider } from './pbs-notification-target.ts';
+
+const PBS: PbsTarget = { api: 'https://pbs.test:8007', mount: 'pbs-test', scheme: 'pbs' };
+const PASSWORD = 'smtp-test-secret-not-real';
+afterEach(() => {
+  delete process.env['HF_PBS_SMTP_TEST_PASSWORD'];
+});
+
+for (const type of ['sendmail', 'smtp'] as const) {
+  test(`${type} creates, reads its dashed fields, clears recipients and redeploys without a write`, async () => {
+    process.env['HF_PBS_SMTP_TEST_PASSWORD'] = PASSWORD;
+    const fake = fakeNotify();
+    const declare = (mailto: readonly string[]) =>
+      PbsNotificationTarget('pager', {
+        type,
+        name: 'pager',
+        target: PBS,
+        'from-address': 'sender@example.com',
+        'mailto-user': ['root@pam'],
+        mailto,
+        ...(type === 'smtp'
+          ? {
+              mode: 'starttls' as const,
+              password: { fromEnv: 'HF_PBS_SMTP_TEST_PASSWORD' },
+              port: 587,
+              server: 'smtp.example.com',
+              username: 'pager',
+            }
+          : {}),
+      });
+    await withoutBao(async () => {
+      const engine = engineOver(
+        PbsNotificationTargetProvider().pipe(Layer.provideMerge(fake.layer)),
+      );
+      await engine.deploy(declare(['ops@example.com', 'backup@example.com']));
+      expect(
+        (await engine.verify(declare(['ops@example.com', 'backup@example.com']), { all: true }))
+          .rows[0]?.diff,
+      ).toBe('noop');
+      expect(engine.stored()).not.toContain(PASSWORD);
+      await engine.deploy(declare([]));
+      expect((await engine.verify(declare([]), { all: true })).rows[0]?.diff).toBe('noop');
+      await engine.deploy(declare([]));
+    });
+    expect(fake.writes()).toEqual([
+      `POST config/notifications/endpoints/${type}`,
+      `PUT config/notifications/endpoints/${type}/pager`,
+    ]);
+    const post = fake.calls.find((call) => call.method === 'POST');
+    expect(post?.pairs).toContainEqual(['from-address', 'sender@example.com']);
+    expect(post?.pairs).toContainEqual(['mailto-user', 'root@pam']);
+    expect(post?.pairs.filter(([key]) => key === 'mailto')).toHaveLength(2);
+    const put = fake.calls.find((call) => call.method === 'PUT');
+    expect(put?.pairs).toContainEqual(['delete', 'mailto']);
+    expect(put?.pairs.map(([key]) => key)).not.toContain('password');
+  });
+}

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

@@ -0,0 +1,65 @@
+/** PBS 4.2.6-1 matcher operations through SDK 0.3.0; failed reads never become absence. */
+import * as config from '@distilled.cloud/proxmox-backup/config';
+import * as Effect from 'effect/Effect';
+import { notificationInput } from './pbs-notification-input.ts';
+import { runPbs } from './distilled-pbs.ts';
+import {
+  type MatcherCreateForm,
+  type MatcherUpdateForm,
+  matcherAttributes,
+} from './notification-matcher-form.ts';
+import type { PbsNotificationMatcherProps as Props } from './pbs-notification-matcher.ts';
+
+export const readMatcher = (props: Props) =>
+  runPbs(props.target, 'read', config.getConfigNotificationMatcher({ name: props.name })).pipe(
+    Effect.map((row) =>
+      matcherAttributes(
+        {
+          ...row,
+          'invert-match': row.invert_match,
+          'match-calendar': row.match_calendar,
+          'match-field': row.match_field,
+          'match-severity': row.match_severity,
+        },
+        props.name,
+      ),
+    ),
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+  );
+
+/** Validate with the SDK's request schema after spelling the shared PVE/PBS form's keys. */
+const requestFields = (props: Props, form: MatcherCreateForm | MatcherUpdateForm) => ({
+  ...form,
+  invert_match: form['invert-match'],
+  match_calendar: form['match-calendar'],
+  match_field: form['match-field'],
+  match_severity: form['match-severity'],
+  name: props.name,
+});
+
+export const createMatcher = (props: Props, form: MatcherCreateForm) =>
+  runPbs(
+    props.target,
+    'provision',
+    notificationInput(
+      config.CreateConfigNotificationMatcherRequest,
+      requestFields(props, form),
+    ).pipe(Effect.flatMap(config.createConfigNotificationMatcher)),
+  );
+
+export const updateMatcher = (props: Props, form: MatcherUpdateForm) =>
+  runPbs(
+    props.target,
+    'provision',
+    notificationInput(config.PutConfigNotificationMatcherRequest, requestFields(props, form)).pipe(
+      Effect.flatMap(config.putConfigNotificationMatcher),
+    ),
+  );
+
+/** PBS reverts built-ins on deletion; it reports NotFound only for an absent user-created row. */
+export const deleteMatcher = (props: Props) =>
+  runPbs(
+    props.target,
+    'provision',
+    config.deleteConfigNotificationMatcher({ name: props.name }),
+  ).pipe(Effect.catchTag('NotFound', () => Effect.void));

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

@@ -36,21 +36,30 @@
  * ★ WHAT THIS NEEDS, READ OFF THE SERVER'S SCHEMA (generated/pbs.ts source):
  *     read      GET                 Sys.Audit  on /system/notifications
  *     write     POST, PUT, DELETE   Sys.Modify on /system/notifications
- *   ⚠️ NOT A DATASTORE PRIVILEGE. A PBS credential scoped to `/datastore/...` reads every matcher
- *     as absent — the "absent, then already exists" signature notification-target.ts describes.
+ *   ⚠️ NOT A DATASTORE PRIVILEGE. A credential scoped to `/datastore/...` cannot read matchers;
+ *     the old client treated that refusal as absent — notification-target.ts describes the
+ *     resulting "absent, then already exists" signature.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
 import * as Effect from 'effect/Effect';
 import {
   type NotificationMatcherAttributes,
   type NotificationMatcherFields,
-  matcherAttributes,
   matcherCreateForm,
   matcherMatches,
   matcherUpdateForm,
 } from './notification-matcher-form.ts';
-import { type PveRequirements, type WithPbsTarget, pveHandlers } from './resource.ts';
+import type { PveRequirements, WithPbsTarget } from './resource.ts';
+import { guardForm } from './constraint-guard.ts';
+import {
+  createMatcher,
+  deleteMatcher,
+  readMatcher,
+  updateMatcher,
+} from './pbs-notification-matcher-distilled.ts';
 
 export interface PbsNotificationMatcherProps extends NotificationMatcherFields, WithPbsTarget {}
 
@@ -65,19 +74,63 @@ export interface PbsNotificationMatcher extends Resource<
 /** ⚠️ No `retain`, for notification-matcher.ts's reason; a built-in REVERTS on delete. */
 export const PbsNotificationMatcher = Resource<PbsNotificationMatcher>('Pbs.NotificationMatcher');
 
-const handlers = pveHandlers<PbsNotificationMatcherProps, NotificationMatcherAttributes>({
-  attributes: (live, props) => matcherAttributes(live, props.name),
-  collection: () => 'config/notifications/matchers',
-  createForm: matcherCreateForm,
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: {
-    create: 'pbs:POST /config/notifications/matchers',
-    update: 'pbs:PUT /config/notifications/matchers/{name}',
-  },
-  matches: matcherMatches,
-  path: (props) => `config/notifications/matchers/${props.name}`,
-  updateForm: matcherUpdateForm,
-});
+type Props = PbsNotificationMatcherProps;
+type Attributes = NotificationMatcherAttributes;
+
+const guardCreate = (props: Props, requirePresence: boolean) =>
+  guardForm('pbs:POST /config/notifications/matchers', matcherCreateForm(props), requirePresence);
+const guardUpdate = (props: Props) =>
+  guardForm('pbs:PUT /config/notifications/matchers/{name}', matcherUpdateForm(props), false);
+
+/**
+ * SDK-backed lifecycle: read before writing and compare the entire rule so adoption is free.
+ * ⛔ A 401, 403, malformed response or failed credential mint must fail the plan. Only the
+ *   SDK's typed NotFound means absent; the old factory turned all of these into false creates.
+ */
+const handlers = {
+  /** Built-ins belong to the host; adopting them must stay an explicit declaration. */
+  list: () => Effect.succeed([]),
+  read: ({ olds }: { olds: Props }) => readMatcher(olds),
+  diff: ({
+    news,
+    olds,
+    output,
+  }: {
+    news: Input<Props>;
+    olds: Props;
+    output: Attributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* guardCreate(news, output === undefined);
+      yield* guardUpdate(news);
+      if (output === undefined) return undefined;
+      if (olds.name !== news.name) return { action: 'replace' } as const;
+      const live = yield* readMatcher(news);
+      if (live === undefined) {
+        yield* guardCreate(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* guardCreate(news, live === undefined);
+      yield* guardUpdate(news);
+      if (live === undefined) yield* createMatcher(news, matcherCreateForm(news));
+      else if (!matcherMatches(live, news)) yield* updateMatcher(news, matcherUpdateForm(news));
+      const after = yield* readMatcher(news);
+      if (after === undefined)
+        return yield* Effect.fail(
+          new Error(
+            `config/notifications/matchers/${news.name}: the write returned no error but the matcher is still absent.`,
+          ),
+        );
+      return after;
+    }),
+  delete: ({ olds }: { olds: Props }) => deleteMatcher(olds),
+};
 
 export const PbsNotificationMatcherProvider = () =>
   Provider.effect(