@homeflare/alchemy 0.24.0 → 0.25.0

package/src/paperless/matching-identity.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Regression suite for the PR 163 red-team HIGH finding: `diff`/`reconcile` re-derived identity
+ * from `news` alone on every call, so renaming (or re-owning) an already-deployed Tag/
+ * DocumentType/StoragePath/CustomField missed the row it previously wrote, POSTed a second
+ * object under the new name/owner, and left the original permanently orphaned — while `diff`
+ * reported a plain `{action:'update'}`. See `matching.ts`'s header for the fix: once `output` is
+ * defined, identity is `output.id`, not `(name, owner)`.
+ *
+ * ⛔ EVERY TEST HERE FAILS ON THE PRE-FIX `matching.ts` (measured before the fix landed — see the
+ *   PR comment this file was introduced with):
+ *   - the two rename/re-own tests fail because a second POST fires and `fake.rows('tags').length`
+ *     is 2, not 1 (the exact duplicate-and-orphan bug);
+ *   - the deleted-out-of-band test fails because `diff` never called `fetchLive` at all when
+ *     `output` was ignored the pre-fix way — it silently returns `{action:'update'}`  instead of
+ *     refusing;
+ *   - the first-create and adopt tests already passed pre-fix (the no-state path was never
+ *     broken) and are here to prove the fix does not disturb them.
+ *
+ * ★ THE LAST `describe` BELOW IS A SECOND ROUND (re-review of this same PR): the d3983ff fix
+ *   rewired `diff`/`reconcile` to locate by `output.id`, but left `destroy` locating by
+ *   `(name, owner)` alone — the exact pre-fix mechanism, with the exact pre-fix consequence
+ *   (silently missing a live-but-renamed row) just on the delete path instead of update. See
+ *   `matching.ts`'s `destroy` for the fix this suite proves.
+ */
+import { describe, expect, test } from 'bun:test';
+import { paperless } from './client.ts';
+import { type MatchingProps, matchingHandlers, matchingOperations } from './matching.ts';
+import { run, withFake } from './fake-paperless.ts';
+
+interface Props extends MatchingProps {
+  note?: string;
+}
+/** ★ The same minimal spec `matching.test.ts` uses — this suite tests `matching.ts`'s own identity contract, not any one family's wiring. */
+const spec = {
+  attributes: (live: Record<string, unknown>, props: Props) => {
+    const id = live['id'];
+    if (typeof id !== 'number') return undefined;
+    return {
+      id,
+      name: typeof live['name'] === 'string' ? live['name'] : props.name,
+      note: typeof live['note'] === 'string' ? live['note'] : '',
+      owner: typeof live['owner'] === 'number' ? live['owner'] : undefined,
+    };
+  },
+  collection: 'tags' as const,
+  describe: (props: Props) => `tags ${props.name}`,
+  endpoint: { create: 'paperless:POST /api/tags/', update: 'paperless:PATCH /api/tags/{id}/' },
+  fields: [
+    { key: 'note', live: (r: Record<string, unknown>) => r['note'], prop: (p: Props) => p.note },
+  ],
+};
+
+const writesOf = (fake: { seen: readonly { method: string }[] }) =>
+  fake.seen.filter((s) => s.method !== 'GET');
+
+describe('renaming or re-owning an already-deployed object (PR 163)', () => {
+  test('a rename PATCHes the same id — no POST, no orphan', async () => {
+    await withFake(async (fake) => {
+      const handlers = matchingHandlers(spec);
+      const created = await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+      const before = writesOf(fake).length;
+
+      const renamed = await run(
+        handlers.reconcile({ news: { name: 'Invoices - Renamed' }, output: created }),
+      );
+
+      const writes = writesOf(fake);
+      const newWrites = writes.slice(before);
+      expect(writes.length).toBe(before + 1);
+      expect(newWrites.every((w) => w.method === 'PATCH')).toBe(true);
+      expect(fake.rows('tags').length).toBe(1);
+      expect(renamed?.id).toBe(created?.id);
+      expect(renamed?.name).toBe('Invoices - Renamed');
+    });
+  });
+
+  test('an owner change PATCHes the same id — no POST, no orphan', async () => {
+    await withFake(async (fake) => {
+      const handlers = matchingHandlers(spec);
+      const created = await run(handlers.reconcile({ news: { name: 'Invoices', owner: 7 } }));
+      const before = writesOf(fake).length;
+
+      const reowned = await run(
+        handlers.reconcile({ news: { name: 'Invoices', owner: 9 }, output: created }),
+      );
+
+      const writes = writesOf(fake);
+      expect(writes.length).toBe(before + 1);
+      expect(writes[writes.length - 1]?.method).toBe('PATCH');
+      expect(fake.rows('tags').length).toBe(1);
+      expect(reowned?.id).toBe(created?.id);
+      expect(reowned?.owner).toBe(9);
+    });
+  });
+});
+
+describe('a deleted-out-of-band object (PR 163)', () => {
+  test('diff refuses at plan rather than creating a replacement', async () => {
+    await withFake(async (fake) => {
+      const handlers = matchingHandlers(spec);
+      const created = await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+      await run(paperless('DELETE', `tags/${String(created?.id)}/`));
+
+      await expect(
+        run(handlers.diff({ news: { name: 'Invoices' }, output: created })),
+      ).rejects.toThrow(/no longer exists live|deleted out of band/);
+
+      expect(fake.rows('tags').length).toBe(0);
+    });
+  });
+
+  test('reconcile also refuses, not only diff, if called with no prior diff', async () => {
+    await withFake(async (fake) => {
+      const handlers = matchingHandlers(spec);
+      const created = await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+      await run(paperless('DELETE', `tags/${String(created?.id)}/`));
+
+      await expect(
+        run(handlers.reconcile({ news: { name: 'Invoices' }, output: created })),
+      ).rejects.toThrow(/no longer exists live|deleted out of band/);
+
+      expect(fake.rows('tags').length).toBe(0);
+    });
+  });
+});
+
+describe('the no-state path is unaffected (PR 163)', () => {
+  test('a first create still locates by name', async () => {
+    await withFake(async (fake) => {
+      const handlers = matchingHandlers(spec);
+      await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+
+      const get = fake.seen.find((s) => s.method === 'GET');
+      expect(get?.path).toContain('name__iexact=Invoices');
+      const post = fake.seen.find((s) => s.method === 'POST');
+      expect(post).toBeDefined();
+    });
+  });
+
+  test("adopt (output populated from the engine's own read) locates the id it read, no duplicate", async () => {
+    await withFake(async (fake) => {
+      const ops = matchingOperations(spec);
+      const handlers = matchingHandlers(spec);
+      // A pre-existing object, created out of band — what the engine's `provider.read` (always
+      // called with `output: undefined`) discovers during its adoption probe (`Plan.ts`).
+      await run(paperless('POST', 'tags/', { name: 'Invoices', owner: null }));
+      const readAttrs = await run(ops.read({ name: 'Invoices' }));
+      expect(readAttrs).toBeDefined();
+      if (readAttrs === undefined) throw new Error('unreachable: asserted defined above');
+
+      // The engine forces `action: 'adopted'` through the normal update/reconcile path with
+      // `output: node.state.attr` already the just-read attributes (Apply.ts).
+      const after = await run(
+        handlers.reconcile({ news: { name: 'Invoices' }, output: readAttrs }),
+      );
+
+      expect(fake.rows('tags').length).toBe(1);
+      expect(after?.id).toBe(readAttrs?.id);
+      expect(fake.seen.filter((s) => s.method === 'POST').length).toBe(1);
+    });
+  });
+});
+
+describe('delete locates by output.id, not by (possibly stale) olds.name (re-review)', () => {
+  test('a row renamed out of band is still found and deleted, by id', async () => {
+    await withFake(async (fake) => {
+      const handlers = matchingHandlers(spec);
+      const created = await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+      if (created === undefined) throw new Error('unreachable: reconcile always returns attrs');
+
+      // Nothing this package did — a human (or another tool) renamed the live object directly
+      // in Paperless. State's `olds` still says the OLD name; `output` still holds the real id.
+      await run(paperless('PATCH', `tags/${String(created.id)}/`, { name: 'Renamed Elsewhere' }));
+
+      await run(handlers.delete({ olds: { name: 'Invoices' }, output: created }));
+
+      expect(fake.rows('tags').length).toBe(0);
+      const deletes = fake.seen.filter((s) => s.method === 'DELETE');
+      expect(deletes.length).toBe(1);
+      expect(deletes[0]?.path).toBe(`/api/tags/${String(created.id)}/`);
+    });
+  });
+
+  test('with no output (no-state path), delete still falls back to locating by name', async () => {
+    await withFake(async (fake) => {
+      const handlers = matchingHandlers(spec);
+      await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+
+      await run(handlers.delete({ olds: { name: 'Invoices' } }));
+
+      expect(fake.rows('tags').length).toBe(0);
+    });
+  });
+});

package/src/paperless/matching-locate.ts

@@ -0,0 +1,104 @@
+/**
+ * The identity-resolution slice of `matching.ts`'s lifecycle, split into its own file so
+ * `matching.ts` stays under the house's 250-line-per-file cap. Owns exactly one question — which
+ * live Paperless row IS this declaration — by name while there is no state, by the stored
+ * `output.id` once there is one. See `matching.ts`'s header for the PR 163 red-team HIGH finding
+ * this identity switch fixes.
+ */
+import * as Effect from 'effect/Effect';
+import { PaperlessNotFound } from './errors.ts';
+import { type PaperlessList, type PaperlessRow, paperless } from './client.ts';
+import type { MatchingError, MatchingProps, MatchingRequirements } from './matching-types.ts';
+
+/**
+ * ⚠️ Only 404 folds to "absent" — a 401/403 is never read as absent (acceptance criteria).
+ * Exported — `matching.ts`'s `destroy` uses it directly around its own DELETE call.
+ */
+export const absentOn404 = <A>(io: Effect.Effect<A, MatchingError, MatchingRequirements>) =>
+  io.pipe(
+    Effect.catchIf(
+      (cause): cause is PaperlessNotFound => cause instanceof PaperlessNotFound,
+      () => Effect.succeed(undefined as A),
+    ),
+  );
+
+/** ★ Wide enough to see every case-variant candidate `name__iexact` returns; a natural key past it is not one. */
+const LOCATE_PAGE = 20;
+
+/** ⚠️ Exported — `matching.ts`'s `patchBody`/`matches` compare the live `owner` too (PR 163). */
+export const ownerOf = (row: PaperlessRow): number | undefined =>
+  typeof row['owner'] === 'number' ? row['owner'] : undefined;
+
+/**
+ * The name/id lookups every `matching.ts` operation shares, built once per family spec.
+ * `collection` and `describe` are all this slice needs out of a full `MatchingSpec`.
+ */
+export const matchingLocate = <Props extends MatchingProps>(spec: {
+  readonly collection: string;
+  readonly describe: (props: Props) => string;
+}) => {
+  /**
+   * ★ THE NO-STATE LOCATE. Used only when there is no `output` yet: a genuine first create, or
+   *   the engine's own adoption probe (`provider.read`, always called with `output: undefined`).
+   */
+  const fetchByName = (props: Props) =>
+    absentOn404(
+      paperless<PaperlessList<PaperlessRow>>(
+        'GET',
+        `${spec.collection}/?name__iexact=${encodeURIComponent(props.name)}&page_size=${String(LOCATE_PAGE)}`,
+      ),
+    ).pipe(
+      Effect.map((list) => {
+        if (list !== undefined && list.count > LOCATE_PAGE) {
+          throw new Error(
+            `${spec.describe(props)}: name__iexact matched ${String(list.count)} rows, more than ` +
+              `the ${String(LOCATE_PAGE)}-row page this reads. Narrow the name rather than paging.`,
+          );
+        }
+        const rows = (list?.results ?? []).filter(
+          (row) => row['name'] === props.name && ownerOf(row) === (props.owner ?? undefined),
+        );
+        if (rows.length > 1) {
+          throw new Error(
+            `${spec.describe(props)}: matched ${String(rows.length)} Paperless objects with the same (name, owner).`,
+          );
+        }
+        return rows[0];
+      }),
+    );
+
+  /** The stored id itself, once this declaration has one. A 404 here means the row is gone. */
+  const fetchById = (id: number) =>
+    absentOn404(paperless<PaperlessRow>('GET', `${spec.collection}/${String(id)}/`));
+
+  /**
+   * ⛔ THE IDENTITY SWITCH (PR 163, red-team HIGH finding — see `matching.ts`'s header). `output`
+   *   defined means this declaration has already written something: identity is `output.id`, full
+   *   stop, and a changed `name`/`owner` in `props` is drift to PATCH, never a reason to relocate.
+   *   `output` undefined means there is nothing to be wrong about yet — locate by name.
+   */
+  const fetchLive = <Attributes extends { readonly id: number }>(
+    props: Props,
+    output: Attributes | undefined,
+  ) =>
+    output === undefined
+      ? fetchByName(props)
+      : fetchById(output.id).pipe(
+          Effect.flatMap((live) =>
+            live === undefined
+              ? Effect.die(
+                  new Error(
+                    `${spec.describe(props)}: id ${String(output.id)} is recorded in state but no ` +
+                      'longer exists live (deleted out of band). Refusing to create a replacement ' +
+                      '— adopt the live object back under this declaration, or remove it from ' +
+                      'state, before deploying again.',
+                  ),
+                )
+              : Effect.succeed(live),
+          ),
+        );
+
+  const objectPath = (live: PaperlessRow): string => `${spec.collection}/${String(live['id'])}`;
+
+  return { fetchByName, fetchById, fetchLive, objectPath };
+};

package/src/paperless/matching-types.ts

@@ -0,0 +1,61 @@
+/**
+ * The contract every Paperless taxonomy object (Tag, DocumentType, StoragePath, CustomField)
+ * declares against `matching.ts`'s generic lifecycle — split into its own file so `matching.ts`
+ * itself (the identity/locate/create/patch logic the PR 163 red-team HIGH finding is about) stays
+ * under the house's 250-line-per-file cap. See `matching.ts`'s header for the identity design
+ * (`output.id` once a resource has state) this `MatchingSpec` shape supports.
+ */
+import type { PaperlessCredentialsError } from './credentials.ts';
+import type { PaperlessError } from './errors.ts';
+import type { PaperlessRequirements, PaperlessRow } from './client.ts';
+import type { EndpointKey } from './constraints.ts';
+
+/** = `client.ts`'s `PaperlessRequirements` — `HttpClient` and the credentials service both. */
+export type MatchingRequirements = PaperlessRequirements;
+export type MatchingError = PaperlessError | PaperlessCredentialsError;
+
+/** A wire field beyond `name`/`owner`: how to read it from props, and how to read it back. */
+export interface FieldSpec<Props> {
+  readonly key: string;
+  readonly prop: (props: Props) => unknown;
+  readonly live: (row: PaperlessRow) => unknown;
+}
+
+export interface MatchingProps {
+  readonly name: string;
+  /** `undefined` means undeclared — the create body still sends `owner: null` (see matching.ts's header). */
+  readonly owner?: number;
+}
+
+export interface MatchingSpec<
+  Props extends MatchingProps,
+  Attributes extends { readonly id: number },
+> {
+  /** `tags`, `document_types`, `storage_paths`, `custom_fields`. */
+  readonly collection: string;
+  /**
+   * ⚠️ DEFAULT `true`. `Tag`, `DocumentType` and `StoragePath` extend Paperless-ngx's
+   *   `OwnedObjectSerializer`; `CustomField` does not — its wire body has no `owner` key at all
+   *   (measured against the v3.1.1 schema: `CustomFieldRequest` is `{name, data_type,
+   *   extra_data}`). `false` stops `createBody` sending a field the vendor would silently ignore.
+   */
+  readonly owned?: boolean;
+  /** Compared, PATCHed when they differ, and sent on create. */
+  readonly fields: readonly FieldSpec<Props>[];
+  /**
+   * Sent on CREATE only — never compared, never PATCHed. `CustomField.dataType` (custom-field.ts)
+   * is the one user: it must reach the create body, but `immutable` is what refuses a later
+   * change, and `matches`/`patchBody` must never see it as ordinary drift.
+   */
+  readonly createOnly?: readonly FieldSpec<Props>[];
+  readonly attributes: (live: PaperlessRow, props: Props) => Attributes | undefined;
+  readonly endpoint: { readonly create: EndpointKey; readonly update?: EndpointKey };
+  readonly describe: (props: Props) => string;
+  /**
+   * A field this object refuses to change once set — `CustomField.dataType` (custom-field.ts):
+   * a replace would delete that field's value on every document, so neither a PATCH nor a
+   * replace is acceptable. Return the refusal message, or `undefined` when unchanged. Checked in
+   * `diff` (plan time) and again in `reconcile` (an adoption `diff` never saw).
+   */
+  readonly immutable?: (live: PaperlessRow, props: Props) => string | undefined;
+}

package/src/paperless/matching.test.ts

@@ -0,0 +1,128 @@
+/**
+ * `matching.ts`'s generic lifecycle against a fake Paperless: owner injection, the version
+ * header, 403-never-absent, case-sensitive identity inside a case-insensitive locate, and
+ * Unowned-on-every-match (H1).
+ *
+ * ⛔ THESE TESTS FAIL WITHOUT THE UNIT. `matching.ts`, `client.ts`, `credentials.ts` and
+ *   `errors.ts` did not exist before this change — there was nothing to import.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { describe, expect, test } from 'bun:test';
+import { run, runFailure, withFake } from './fake-paperless.ts';
+import { type MatchingProps, matchingHandlers, matchingOperations } from './matching.ts';
+
+interface Props extends MatchingProps {
+  note?: string;
+}
+/** ★ A minimal spec — this file tests `matching.ts`'s own contract, not any one family's wiring. */
+const spec = {
+  attributes: (live: Record<string, unknown>, props: Props) => {
+    const id = live['id'];
+    if (typeof id !== 'number') return undefined;
+    return {
+      id,
+      name: typeof live['name'] === 'string' ? live['name'] : props.name,
+      note: typeof live['note'] === 'string' ? live['note'] : '',
+      owner: typeof live['owner'] === 'number' ? live['owner'] : undefined,
+    };
+  },
+  collection: 'tags' as const,
+  describe: (props: Props) => `tags ${props.name}`,
+  endpoint: { create: 'paperless:POST /api/tags/', update: 'paperless:PATCH /api/tags/{id}/' },
+  fields: [
+    { key: 'note', live: (r: Record<string, unknown>) => r['note'], prop: (p: Props) => p.note },
+  ],
+};
+
+describe('create always carries owner, null when undeclared', () => {
+  test('a create with no owner prop sends owner: null', async () => {
+    await withFake(async (fake) => {
+      const handlers = matchingHandlers(spec);
+      await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+      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 () => {
+    await withFake(async (fake) => {
+      const handlers = matchingHandlers(spec);
+      await run(handlers.reconcile({ news: { name: 'Receipts', owner: 7 } }));
+      const post = fake.seen.find((s) => s.method === 'POST');
+      expect(JSON.parse(post?.body ?? '{}')).toMatchObject({ owner: 7 });
+    });
+  });
+});
+
+test('every request carries Accept: application/json; version=10', async () => {
+  await withFake(async (fake) => {
+    const handlers = matchingHandlers(spec);
+    await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+    expect(fake.seen.length).toBeGreaterThan(0);
+    for (const call of fake.seen) {
+      expect(call.headers.get('Accept')).toBe('application/json; version=10');
+    }
+  });
+});
+
+test('a no-drift reconcile makes zero writes', async () => {
+  await withFake(async (fake) => {
+    const handlers = matchingHandlers(spec);
+    await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+    const before = fake.seen.filter((s) => s.method !== 'GET').length;
+    await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+    const after = fake.seen.filter((s) => s.method !== 'GET').length;
+    expect(after).toBe(before);
+  });
+});
+
+test('a 403 fails rather than reading as absent', async () => {
+  await withFake(async (fake) => {
+    const ops = matchingOperations(spec);
+    fake.forceStatus = 403;
+    const error = await runFailure(ops.read({ name: 'Invoices' }));
+    expect((error as { _tag?: string })._tag).toBe('PaperlessUnauthorized');
+  });
+});
+
+test('a 404 on read folds to absent (create is the right plan)', async () => {
+  await withFake(async () => {
+    const ops = matchingOperations(spec);
+    expect(await run(ops.read({ name: 'Nothing here' }))).toBeUndefined();
+  });
+});
+
+describe('case-insensitive locate, case-sensitive identity', () => {
+  test('two differently-cased names never collapse into one object', async () => {
+    await withFake(async (fake) => {
+      const handlers = matchingHandlers(spec);
+      await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+      await run(handlers.reconcile({ news: { name: 'invoices' } }));
+      expect(fake.rows('tags').length).toBe(2);
+
+      const ops = matchingOperations(spec);
+      const exact = await run(ops.read({ name: 'Invoices' }));
+      expect(exact?.name).toBe('Invoices');
+      const other = await run(ops.read({ name: 'invoices' }));
+      expect(other?.name).toBe('invoices');
+    });
+  });
+});
+
+test('read answers Unowned on a match, even one identical to the declaration (H1)', async () => {
+  await withFake(async () => {
+    const handlers = matchingHandlers(spec);
+    await run(handlers.reconcile({ news: { name: 'Invoices' } }));
+    const result = await run(handlers.read({ olds: { name: 'Invoices' } }));
+    expect(result).toBeDefined();
+    expect(Unowned.is(result)).toBe(true);
+  });
+});
+
+test('read answers undefined, not Unowned, when nothing matches', async () => {
+  await withFake(async () => {
+    const handlers = matchingHandlers(spec);
+    expect(await run(handlers.read({ olds: { name: 'Nothing here' } }))).toBeUndefined();
+  });
+});