@homeflare/alchemy 0.28.0 → 0.29.0

package/src/paperless/tag.test.ts

@@ -0,0 +1,100 @@
+/**
+ * `Tag`'s exported production `spec`, driven through `matchingOperations` against a fake
+ * Paperless-ngx that speaks the real distilled wire protocol — the successor to the pre-migration
+ * `matching.test.ts`, now proving `@distilled.cloud/paperless-ngx`'s real path assembly, JSON
+ * encode/decode and status→typed-error matching (`404` → `NotFound`, `403` → `Forbidden`, …)
+ * instead of a hand-rolled minimal spec against a status-carrying `PaperlessError`.
+ * `matching-locate.test.ts` covers the pure identity rule; `tag-identity.test.ts` covers the
+ * PR 163 rename/re-own/delete-out-of-band regression suite this file does not repeat.
+ *
+ * ⚠️ `handlers` (tag.ts's own export, built by `matchingHandlers`) IS NOT USED HERE — it bakes in
+ *   `CredentialsFromEnv`, which resolves through Effect `Config` and cannot be redirected to a
+ *   fake once built (fake-paperless.ts's own header). Every test calls `matchingOperations(spec)`
+ *   instead, with an explicit fake `Credentials` layer — the same seam
+ *   `../netbox/prefix.test.ts`/`../forgejo/repository.test.ts` use.
+ */
+import { describe, expect, test } from 'bun:test';
+import { fakePaperless, run, runFailure } from './fake-paperless.ts';
+import { matchingOperations } from './matching.ts';
+import { spec } from './tag.ts';
+
+const ops = matchingOperations(spec);
+
+describe('create always carries owner, null when undeclared', () => {
+  test('a create with no owner prop sends owner: null', async () => {
+    const fake = fakePaperless();
+    await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+    const post = fake.seen.find((s) => s.method === 'POST');
+    expect(post).toBeDefined();
+    expect(JSON.parse(post?.body ?? '{}')).toMatchObject({ name: 'Invoices', owner: null });
+  });
+
+  test('a create with an owner prop sends that owner', async () => {
+    const fake = fakePaperless();
+    await run(ops.reconcile({ name: 'Receipts', owner: 7 }, undefined), fake.fetch);
+    const post = fake.seen.find((s) => s.method === 'POST');
+    expect(JSON.parse(post?.body ?? '{}')).toMatchObject({ owner: 7 });
+  });
+});
+
+test('a no-drift reconcile makes zero writes', async () => {
+  const fake = fakePaperless();
+  await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+  const before = fake.seen.filter((s) => s.method !== 'GET').length;
+  await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+  expect(fake.seen.filter((s) => s.method !== 'GET').length).toBe(before);
+});
+
+test('a 403 fails as Forbidden rather than reading as absent', async () => {
+  const fake = fakePaperless();
+  fake.forceStatus = 403;
+  const error = await runFailure(ops.read({ name: 'Invoices' }), fake.fetch);
+  expect((error as { _tag?: string })._tag).toBe('Forbidden');
+});
+
+test('a 404 on read folds to absent (create is the right plan)', async () => {
+  const fake = fakePaperless();
+  expect(await run(ops.read({ name: 'Nothing here' }), fake.fetch)).toBeUndefined();
+});
+
+describe('case-insensitive locate, case-sensitive identity', () => {
+  test('two differently-cased names never collapse into one object', async () => {
+    const fake = fakePaperless();
+    await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+    await run(ops.reconcile({ name: 'invoices' }, undefined), fake.fetch);
+    expect(fake.rows('tags').length).toBe(2);
+
+    const exact = await run(ops.read({ name: 'Invoices' }), fake.fetch);
+    expect(exact?.name).toBe('Invoices');
+    const other = await run(ops.read({ name: 'invoices' }), fake.fetch);
+    expect(other?.name).toBe('invoices');
+  });
+});
+
+test('a PATCH sends only the fields that differ from the live row', async () => {
+  const fake = fakePaperless();
+  await run(ops.reconcile({ color: '#a6cee3', name: 'Invoices' }, undefined), fake.fetch);
+  const created = await run(ops.read({ name: 'Invoices' }), fake.fetch);
+
+  const after = await run(
+    ops.reconcile({ color: '#a6cee3', match: 'invoice', name: 'Invoices' }, created),
+    fake.fetch,
+  );
+
+  const patch = fake.seen.find((s) => s.method === 'PATCH');
+  expect(patch).toBeDefined();
+  expect(JSON.parse(patch?.body ?? '{}')).toEqual({ match: 'invoice' });
+  expect(after?.match).toBe('invoice');
+});
+
+test('destroy DELETEs the live row and is idempotent when already gone', async () => {
+  const fake = fakePaperless();
+  await run(ops.reconcile({ name: 'Invoices' }, undefined), fake.fetch);
+  const created = await run(ops.read({ name: 'Invoices' }), fake.fetch);
+
+  await run(ops.destroy({ name: 'Invoices' }, created), fake.fetch);
+  expect(fake.rows('tags').length).toBe(0);
+
+  // ⚠️ A second destroy of the same (now-absent) row must not throw.
+  await run(ops.destroy({ name: 'Invoices' }, created), fake.fetch);
+});

package/src/paperless/tag.ts

@@ -2,24 +2,32 @@
  * `Paperless.Tag` — a Paperless-ngx tag, create-or-update and never deleted by default.
  *
  * ★ `matchingAlgorithm` AND THE OTHER ENUM-SHAPED FIELDS ARE INDEXED OFF THE GENERATED REQUEST
- *   TYPE (`PaperlessTagRequest['matching_algorithm']`), NEVER RETYPED. The literal union `0 | 1 |
- *   … | 6` comes from `codegen/paperless.ts`'s reading of the vendor's own `MatchingAlgorithm`
- *   enum — copying it by hand here would be exactly the guess `schema-provenance` doctrine
- *   forbids, and a vendor that adds a seventh algorithm would leave this type silently stale.
+ *   TYPE (`PaperlessTagRequest['matching_algorithm']`), NEVER RETYPED — see this family's header
+ *   in `docs/paperless.md`. Unchanged by the 2026-09-24 transport migration below: that generated
+ *   table is `codegen/paperless.ts`'s own concern, not `@distilled.cloud/paperless-ngx`'s.
  *
- * ⛔ NO CREDENTIAL IS A PROP. `PAPERLESS_URL`/`PAPERLESS_TOKEN` come from `credentials.ts`.
+ * ⛔ NO CREDENTIAL IS A PROP. `PAPERLESS_URL`/`PAPERLESS_TOKEN` come from
+ *   `@distilled.cloud/paperless-ngx`'s `CredentialsFromEnv` (matching.ts), the same two variable
+ *   names the retired hand-rolled `credentials.ts` read.
  * ⛔ `defaultRemovalPolicy: 'retain'` — the reconciler this replaces never deletes taxonomy, and
  *   a tag's id is referenced by every document it is attached to.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as tags from '@distilled.cloud/paperless-ngx/tags';
 import * as Effect from 'effect/Effect';
 import type { PaperlessTagRequest } from './generated/types/tags.ts';
-import { type MatchingProps, type MatchingRequirements, matchingHandlers } from './matching.ts';
+import {
+  LOCATE_PAGE,
+  type MatchingRequirements,
+  type MatchingSpec,
+  matchingHandlers,
+} from './matching.ts';
 
-export interface TagProps extends MatchingProps {
+export interface TagProps {
   /** ⚠️ maxLength 128 (generated constraint table). The locate key — see matching.ts's header. */
   name: string;
+  owner?: number;
   /** ⚠️ minLength 1, maxLength 7 (a CSS hex color, generated table doesn't enforce the `#`). */
   color?: string;
   /** ⚠️ maxLength 256. The text or pattern documents are matched against. */
@@ -54,38 +62,60 @@ export interface Tag extends Resource<
 
 export const Tag = Resource<Tag>('Paperless.Tag', { defaultRemovalPolicy: 'retain' });
 
-const handlers = matchingHandlers<TagProps, TagAttributes>({
-  attributes: (live, props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    return {
-      color: typeof live['color'] === 'string' ? live['color'] : '',
-      id,
-      isInboxTag: live['is_inbox_tag'] === true,
-      isInsensitive: live['is_insensitive'] === true,
-      match: typeof live['match'] === 'string' ? live['match'] : '',
-      matchingAlgorithm:
-        typeof live['matching_algorithm'] === 'number' ? live['matching_algorithm'] : 0,
-      name: typeof live['name'] === 'string' ? live['name'] : props.name,
-      owner: typeof live['owner'] === 'number' ? live['owner'] : undefined,
-      parent: typeof live['parent'] === 'number' ? live['parent'] : undefined,
-    };
-  },
-  collection: 'tags',
+/**
+ * ★ EXPORTED, NOT JUST PASSED INLINE — so a test can call `matchingOperations(spec)` directly
+ *   (tag.test.ts does), against an explicit fake `Credentials` layer, without touching
+ *   `matchingHandlers`'s baked-in `CredentialsFromEnv` — the same seam `../forgejo/repository.ts`
+ *   and `../netbox/prefix.ts` use.
+ */
+export const spec: MatchingSpec<
+  TagProps,
+  tags.Tag,
+  TagAttributes,
+  | tags.CreateTagError
+  | tags.GetTagError
+  | tags.ListTagsError
+  | tags.UpdateTagsPartialError
+  | tags.TagsDestroyError
+> = {
+  attributes: (live, props) => ({
+    color: live.color ?? '',
+    id: live.id,
+    isInboxTag: live.is_inbox_tag === true,
+    isInsensitive: live.is_insensitive === true,
+    match: live.match ?? '',
+    matchingAlgorithm: live.matching_algorithm ?? 0,
+    name: live.name,
+    owner: live.owner ?? undefined,
+    parent: live.parent ?? undefined,
+  }),
+  create: (body) => tags.createTag(body as unknown as tags.CreateTagRequest),
   describe: (props) => `tags ${props.name}`,
+  destroy: (id) => tags.tagsDestroy({ id }),
   endpoint: { create: 'paperless:POST /api/tags/', update: 'paperless:PATCH /api/tags/{id}/' },
   fields: [
-    { key: 'color', live: (r) => r['color'], prop: (p) => p.color },
-    { key: 'match', live: (r) => r['match'], prop: (p) => p.match },
+    { key: 'color', live: (r) => r.color, prop: (p) => p.color },
+    { key: 'match', live: (r) => r.match, prop: (p) => p.match },
     {
       key: 'matching_algorithm',
-      live: (r) => r['matching_algorithm'],
+      live: (r) => r.matching_algorithm,
       prop: (p) => p.matchingAlgorithm,
     },
-    { key: 'is_insensitive', live: (r) => r['is_insensitive'], prop: (p) => p.isInsensitive },
-    { key: 'is_inbox_tag', live: (r) => r['is_inbox_tag'], prop: (p) => p.isInboxTag },
-    { key: 'parent', live: (r) => r['parent'], prop: (p) => p.parent },
+    { key: 'is_insensitive', live: (r) => r.is_insensitive, prop: (p) => p.isInsensitive },
+    { key: 'is_inbox_tag', live: (r) => r.is_inbox_tag, prop: (p) => p.isInboxTag },
+    { key: 'parent', live: (r) => r.parent, prop: (p) => p.parent },
   ],
-});
+  getById: (id) =>
+    tags.getTag({ id }).pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
+  list: (props) => tags.listTags({ name__iexact: props.name, page_size: LOCATE_PAGE }),
+  ownerOf: (live) => live.owner ?? undefined,
+  update: (id, body) =>
+    tags.updateTagsPartial({
+      ...(body as unknown as Omit<tags.UpdateTagsPartialRequest, 'id'>),
+      id,
+    }),
+};
+
+export const handlers = matchingHandlers(spec);
 
 export const TagProvider = () => Provider.effect(Tag, Effect.succeed(Tag.Provider.of(handlers)));

package/src/proxmox/acl.test.ts

@@ -0,0 +1,145 @@
+/**
+ * `Proxmox.Acl` through Alchemy's own Plan and Apply, over a fake cluster driving the REAL
+ * `@distilled.cloud/proxmox` protocol (real path assembly, real form-urlencoded PUT body, real
+ * `{"data": ...}` envelope) — the same harness `adopt-noop.test.ts` already runs this family
+ * through (that file is the cross-family proof that an already-matching grant is read-only; this
+ * one is the family's own write/delete/replace/read-back paths).
+ */
+import { describe, 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 { ProxmoxAcl, ProxmoxAclProvider } from './acl.ts';
+import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
+
+type Row = { path: string; type: string; ugid: string; roleid: string; propagate?: number };
+
+/** A cluster holding `rows`; a PUT mutates them the way PVE's own ACL handler does. */
+const cluster = (rows: Row[]) =>
+  fakePve((call: PveCall) => {
+    if (call.method === 'GET' && call.path === 'access/acl') return rows;
+    if (call.method !== 'PUT' || call.path !== 'access/acl') return undefined;
+    const ugid = call.form['users'] ?? call.form['groups'] ?? call.form['tokens'];
+    const type =
+      call.form['users'] !== undefined
+        ? 'user'
+        : call.form['groups'] !== undefined
+          ? 'group'
+          : 'token';
+    const idx = rows.findIndex(
+      (r) => r.path === call.form['path'] && r.roleid === call.form['roles'] && r.ugid === ugid,
+    );
+    if (call.form['delete'] === '1') {
+      if (idx !== -1) rows.splice(idx, 1);
+      return undefined; // PVE answers {"data": null} on a successful PUT.
+    }
+    const row: Row = {
+      path: call.form['path'] ?? '',
+      propagate: call.form['propagate'] === '0' ? 0 : 1,
+      roleid: call.form['roles'] ?? '',
+      type,
+      ugid: ugid ?? '',
+    };
+    if (idx === -1) rows.push(row);
+    else rows[idx] = row;
+    return undefined;
+  });
+
+const grant = (roleid = 'PVEAuditor') =>
+  ProxmoxAcl('auditor', { path: '/', roleid, target: FAKE_TARGET, type: 'user', ugid: 'u@pve' });
+
+const engineFor = (fake: ReturnType<typeof cluster>) =>
+  engineOver(ProxmoxAclProvider().pipe(Layer.provideMerge(fake.layer)));
+
+describe('Proxmox.Acl over the distilled protocol', () => {
+  test('creating a grant that does not exist yet: one PUT, propagate defaults on', async () => {
+    const fake = cluster([]);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      // ⚠️ 'adopted', not 'created' — `diff` answers `undefined` when there is no prior state
+      //   (there is no create verb for this family to plan one for; see the file header), so
+      //   Alchemy reports the same label an adoption gets. `reconcile` still PUTs it below.
+      expect(await engine.deploy(grant())).toEqual({ auditor: 'adopted' });
+    });
+    expect(fake.writes()).toEqual(['PUT access/acl']);
+    const [call] = fake.calls.filter((c) => c.method === 'PUT');
+    expect(call?.form).toMatchObject({
+      path: '/',
+      propagate: '1',
+      roles: 'PVEAuditor',
+      users: 'u@pve',
+    });
+  });
+
+  test('a drifted propagate is corrected with exactly one PUT', async () => {
+    const fake = cluster([
+      { path: '/', propagate: 0, roleid: 'PVEAuditor', type: 'user', ugid: 'u@pve' },
+    ]);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      const report = await engine.verify(grant());
+      expect(report.rows[0]).toMatchObject({ diff: 'update' });
+      expect(await engine.deploy(grant())).toEqual({ auditor: 'adopted' });
+    });
+    expect(fake.writes()).toEqual(['PUT access/acl']);
+    const [putCall] = fake.calls.filter((c) => c.method === 'PUT');
+    expect(putCall?.form['propagate']).toBe('1');
+  });
+
+  test('orphaning: the delete PUT carries delete=1, no propagate field, and removes the row', async () => {
+    const fake = cluster([]);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(grant());
+      expect(await engine.deploy(Effect.void)).toEqual({});
+    });
+    const [, deleteCall] = fake.calls.filter((c) => c.method === 'PUT');
+    expect(deleteCall?.form).toMatchObject({
+      delete: '1',
+      path: '/',
+      roles: 'PVEAuditor',
+      users: 'u@pve',
+    });
+    expect(deleteCall?.form['propagate']).toBeUndefined();
+    expect(fake.calls.filter((c) => c.method === 'GET').at(-1)).toBeDefined();
+  });
+
+  test('an identity change (roleid) replaces: the old grant is gone, the new one is bound', async () => {
+    const fake = cluster([]);
+    await withoutBao(async () => {
+      const engine = engineFor(fake);
+      await engine.deploy(grant('PVEAuditor'));
+      // ⚠️ `{ all: true }` — this row already has state, and `verify` reports only stateless
+      //   rows by default (verify.ts's `VerifyOptions.all`).
+      const report = await engine.verify(grant('PVEAdmin'), { all: true });
+      expect(report.rows[0]).toMatchObject({ diff: 'replace' });
+      await engine.deploy(grant('PVEAdmin'));
+      // The live cluster now holds only the new grant — a fresh adopt of it plans noop.
+      const after = await engine.verify(grant('PVEAdmin'), { all: true });
+      expect(after.rows[0]).toMatchObject({ diff: 'noop' });
+    });
+    // Create-first (Alchemy's default): the new grant is PUT before the old one is removed.
+    const puts = fake.calls.filter((c) => c.method === 'PUT');
+    expect(puts.length).toBeGreaterThanOrEqual(2);
+    expect(puts.some((c) => c.form['roles'] === 'PVEAdmin' && c.form['delete'] === undefined)).toBe(
+      true,
+    );
+    expect(puts.some((c) => c.form['roles'] === 'PVEAuditor' && c.form['delete'] === '1')).toBe(
+      true,
+    );
+  });
+
+  test('a PUT that silently no-ops is refused, not recorded as landed', async () => {
+    // ⚠️ A cluster whose PUT never actually lands the row — the permission-filtered case the
+    //   header describes: PVE answers 200 with no error, but the grant never appears on GET.
+    const fake = fakePve((call) =>
+      call.method === 'GET' && call.path === 'access/acl' ? [] : undefined,
+    );
+    await expect(
+      withoutBao(async () => {
+        const engine = engineFor(fake);
+        await engine.deploy(grant());
+      }),
+    ).rejects.toThrow(/still not bound/);
+  });
+});