@homeflare/alchemy 0.31.0 → 0.31.1

package/src/proxmox/user.test.ts

@@ -0,0 +1,142 @@
+/**
+ * `Proxmox.User` through Alchemy's own Plan and Apply, over a fake cluster driving the REAL
+ * `@distilled.cloud/proxmox` protocol — create, drift (including the `groups` array/comma-string
+ * asymmetry the header warns about), and delete. adopt-noop.test.ts (via Group) proves the
+ * shared "adopting a matching object only reads" property; this file is User's own write paths.
+ *
+ * ⚠️ A MISSING USER IS A REAL 500, NOT `fakePve`'s USUAL 200-with-null. user.ts's own header
+ *   measures this, and it matters here: `GetAccessUserResponse` has NO required field, so a
+ *   200-with-`{}` (what `fakePve` always answers) decodes as a fully-present, all-default
+ *   account rather than "absent" — the read would never fail and `create` would never trigger.
+ *   `missingAs500` below is a small custom stub, not `fake-pve.ts`'s `fakePve`, for that reason.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { engineOver } from '../verify/fake-engine.ts';
+import { FAKE_TARGET, type PveCall, fakePve, withoutBao } from './fake-pve.ts';
+import { ProxmoxUser, ProxmoxUserProvider, type UserProps } from './user.ts';
+
+type Live = { comment: string; enable: string; expire: string; groups: readonly string[] };
+
+/** `access/users` (POST) and `access/users/{userid}` (GET/PUT), a missing GET answering 500. */
+const missingAs500 = (users: Map<string, Live>) => {
+  const stub = async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    if (url.pathname.includes('/creds/')) {
+      const data = { secret: 'fake-secret-not-real', token_id: 'hf-test@pve!fake' };
+      return Response.json({ data, lease_duration: 0 });
+    }
+    const path = url.pathname.replace(/^\/api2\/json\//, '');
+    const match = /^access\/users(?:\/(.+))?$/.exec(path);
+    if (match === null) return Response.json({ data: null });
+    // ⚠️ distilled percent-encodes a `{userid}` label substitution (`iac@pve` -> `iac%40pve`,
+    //   MEASURED) where client.ts's plain string concatenation never did. A real PVE decodes it
+    //   like any HTTP server; this fake must too, or every userid with an `@` "vanishes".
+    const userid = match[1] === undefined ? undefined : decodeURIComponent(match[1]);
+    const params = new URLSearchParams(await request.text());
+    const form = Object.fromEntries(params);
+    if (request.method === 'GET' && userid !== undefined) {
+      const live = users.get(userid);
+      // ⚠️ THE TRAP THIS FILE EXISTS TO PROVE FIXED: measured PVE answers 500, not 200-null.
+      if (live === undefined)
+        return Response.json({ message: `no such user ('${userid}')` }, { status: 500 });
+      return Response.json({ data: { ...live, groups: [...live.groups] } });
+    }
+    if (request.method === 'POST' && userid === undefined) {
+      const { userid: id, ...rest } = form;
+      if (id !== undefined) {
+        users.set(id, {
+          comment: rest['comment'] ?? '',
+          enable: rest['enable'] ?? '1',
+          expire: rest['expire'] ?? '0',
+          groups:
+            rest['groups'] === undefined || rest['groups'] === '' ? [] : rest['groups'].split(','),
+        });
+      }
+      return Response.json({ data: null });
+    }
+    if (request.method === 'PUT' && userid !== undefined) {
+      const live = users.get(userid);
+      if (live !== undefined) {
+        users.set(userid, {
+          comment: form['comment'] ?? live.comment,
+          enable: form['enable'] ?? live.enable,
+          expire: form['expire'] ?? live.expire,
+          groups:
+            form['groups'] === undefined || form['groups'] === '' ? [] : form['groups'].split(','),
+        });
+      }
+      return Response.json({ data: null });
+    }
+    if (request.method === 'DELETE' && userid !== undefined) {
+      users.delete(userid);
+      return Response.json({ data: null });
+    }
+    return Response.json({ data: null });
+  };
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, fetchStub as typeof fetch)),
+    ),
+  };
+};
+
+const declare = (over: Partial<UserProps> = {}): UserProps => ({
+  target: FAKE_TARGET,
+  userid: 'iac@pve',
+  ...over,
+});
+
+describe('Proxmox.User over the distilled protocol', () => {
+  test('creating an account that does not exist yet: one POST, defaults sent explicitly', async () => {
+    const users = new Map<string, Live>();
+    const fake = missingAs500(users);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxUserProvider().pipe(Layer.provideMerge(fake.layer)));
+      expect(await engine.deploy(ProxmoxUser('iac', declare()))).toEqual({ iac: 'create' });
+    });
+    expect(users.get('iac@pve')).toEqual({ comment: '', enable: '1', expire: '0', groups: [] });
+  });
+
+  test('a drifted comment settles, and an unsorted live groups array is not itself drift', async () => {
+    const users = new Map<string, Live>([
+      ['iac@pve', { comment: 'old', enable: '1', expire: '0', groups: ['b', 'a'] }],
+    ]);
+    const fake = missingAs500(users);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxUserProvider().pipe(Layer.provideMerge(fake.layer)));
+      const declared = () => ProxmoxUser('iac', declare({ comment: 'new', groups: ['a', 'b'] }));
+      const report = await engine.verify(declared());
+      expect(report.rows[0]).toMatchObject({ changed: ['comment'], diff: 'update' });
+      expect(await engine.deploy(declared())).toEqual({ iac: 'adopted' });
+    });
+    expect(users.get('iac@pve')).toMatchObject({ comment: 'new', groups: ['a', 'b'] });
+  });
+
+  test('deleting removes the account (no retain default for User)', async () => {
+    const users = new Map<string, Live>([
+      ['iac@pve', { comment: '', enable: '1', expire: '0', groups: [] }],
+    ]);
+    const fake = fakePve((call: PveCall) => {
+      const match = /^access\/users\/(.+)$/.exec(call.path);
+      if (match === null) return undefined;
+      // ⚠️ decodeURIComponent — see the ⚠️ on `missingAs500` above: distilled percent-encodes it.
+      const userid = decodeURIComponent(match[1] as string);
+      if (call.method === 'GET') return users.get(userid);
+      if (call.method === 'DELETE') users.delete(userid);
+      return undefined;
+    });
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxUserProvider().pipe(Layer.provideMerge(fake.layer)));
+      await engine.deploy(ProxmoxUser('iac', declare()));
+      expect(await engine.deploy(Effect.void)).toEqual({});
+    });
+    expect(users.has('iac@pve')).toBe(false);
+    expect(fake.writes()).toEqual(['DELETE access/users/iac%40pve']);
+  });
+});

package/src/proxmox/user.ts

@@ -2,7 +2,7 @@
  * `Proxmox.User` — a PVE account. The identity every other resource in this package borrows.
  *
  * ★ THIS IS THE ONE OBJECT THAT CAN CUT THE BRANCH IT SITS ON. The user the credential mount vends
- *   tokens for, and the group whose members are allowed to mint, are what `src/credentials.ts`
+ *   tokens for, and the group whose members are allowed to mint, are what `credentials.ts`
  *   ultimately asks OpenBao for. A cluster rebuilt without them cannot plan ANY resource here —
  *   including the plan that would recreate them, which needs a credential to run. So this resource
  *   is drift repair for an account that already exists (comment, email, enable, expire, groups),
@@ -18,39 +18,62 @@
  *
  * ⚠️ `groups` COMES BACK AS AN ARRAY AND GOES OUT AS A COMMA STRING, and the asymmetry is the whole
  *   trap. GET answers `["a","b"]`, POST/PUT want `a,b`, and PVE returns the list in ITS order, not
- *   the declared one. Compared naively, `matches` reads ['b','a'] against 'a,b' and every plan for
- *   the rest of time says "1 to update". Both sides are normalised to a sorted, deduplicated set
- *   below. Joining is a safe comparison precisely because a group id cannot contain a comma — the
- *   wire format is comma-separated, so PVE refuses one.
+ *   the declared one. Both sides are normalised to a sorted, deduplicated set — see user-wire.ts.
  *
  * ⚠️ `tokens` IS NESTED AND IS NOT SETTABLE THROUGH THIS ENDPOINT. The read hands back a map of the
  *   account's API tokens; `PUT /access/users/{userid}` has no parameter for them, because they are
- *   their own objects under `.../token/{tokenid}`. So they are reported as an attribute — a plan
- *   can then say what a delete would take with it — and kept OUT of `matches`, exactly like
- *   `pool.members`. Reported, never declared.
+ *   their own objects under `.../token/{tokenid}` (api-token.ts). So they are reported as an
+ *   attribute and kept OUT of `matches`, exactly like `pool.members`. Reported, never declared.
  *
  * ⚠️ RECONCILE NEEDS PRIVILEGES A GUEST-ONLY ROLE DOES NOT HOLD, so they are stated rather than met
- *   as a 403 in the middle of a deploy (pool.ts records how that went the last time).
- *   `PROVISION_PRIVILEGES` (provision-baseline.ts) carries every one of them:
+ *   as a 403 in the middle of a deploy. `PROVISION_PRIVILEGES` (provision-baseline.ts) carries:
  *     · `Realm.AllocateUser` on `/access/realm/<realm>` — create and delete.
  *     · `User.Modify` on `/access/groups`, and on `/access/groups/<group>` for EVERY group named in
  *       `groups` — create, update and delete. PVE checks the groups you are granting, not just the
- *       user, so a role wide enough to edit the account can still be refused for one group in the
- *       list.
+ *       user, so a role wide enough to edit the account can still be refused for one group.
  *     · `Sys.Audit` (or `User.Modify`) for the read, which the `read` role's auditor already has.
- *   `Permissions.Modify` is NOT on this list: that governs ACL entries, which are a different PVE
- *   object and would be a different resource here.
  *
- * ⚠️ A MISSING USER IS A 500, NOT A 404 — "no such user ('x@pve')" — and the factory turns any
- *   failed read into "absent". A 403 therefore also reads as absent, and the honest error arrives
- *   one step later, from the create: "Permission check failed (/access/groups, User.Modify)". That
- *   string is the one to grep for when a plan insists on creating an account that plainly exists.
+ * ⚠️ A MISSING USER IS A 500, NOT A 404 — "no such user ('x@pve')". distilled turns that into an
+ *   `UnknownProxmoxError` (protocol.ts), and `readOrUnreadable`'s own `orElseSucceed` folds it
+ *   into "absent" same as the old hand-rolled client did. A 403 therefore also reads as absent
+ *   UNLESS it is the one refusal `readOrUnreadable` catches (unreadable-read.ts): a REFUSED
+ *   `provision` mint, the cries-wolf case. Any other refusal still reads as absent, and the
+ *   honest error arrives one step later, from the create.
+ *
+ * ⚠️ THE WIRE URL FOR THIS FAMILY CHANGED, THOUGH NOTHING A CALLER SEES DID. MEASURED
+ *   (user.test.ts): distilled's `{userid}` label substitution percent-encodes it —
+ *   `iac@pve` -> `.../access/users/iac%40pve` — where `client.ts`'s plain string concatenation
+ *   sent the `@` literally. A real PVE (any HTTP server) decodes both the same way, so this is
+ *   not a behaviour change a stack observes; a fake in a test has to decode it, `client.ts`'s
+ *   own fixtures never had to.
+ *
+ * ★ MIGRATED OFF `client.ts`'s generic `pve()`/`pveHandlers` ONTO `@distilled.cloud/proxmox`'s
+ *   typed `access.getAccessUser`/`createAccessUser`/`putAccessUser`/`deleteAccessUser`
+ *   (2026-09-24, decision 43's proxmox walk-down, access sub-area). `distilled-pve.ts`'s `runPve`
+ *   replaces `pve()` as in acl.ts and group.ts; the cries-wolf fix is wired the same way.
  */
 import { Resource } from 'alchemy';
+import { isResolved } from 'alchemy/Diff';
 import * as Provider from 'alchemy/Provider';
+import * as access from '@distilled.cloud/proxmox/access';
 import * as Effect from 'effect/Effect';
-import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
-import { bool } from './values.ts';
+import { guardWrite } from './distilled-guard.ts';
+import type { PveRequirements, WithTarget } from './resource-spec.ts';
+import { runPve } from './distilled-pve.ts';
+import {
+  UNREADABLE,
+  type Unreadable,
+  readOrUnreadable,
+  unreadableWarning,
+} from './unreadable-read.ts';
+import {
+  USER_CREATE,
+  USER_UPDATE,
+  attributesOf,
+  createForm,
+  matches,
+  updateForm,
+} from './user-wire.ts';
 
 export interface UserProps extends WithTarget {
   /**
@@ -103,115 +126,95 @@ export interface ProxmoxUser extends Resource<
 
 export const ProxmoxUser = Resource<ProxmoxUser>('Proxmox.User');
 
-const str = (value: unknown) => (typeof value === 'string' ? value : '');
-
-/**
- * ⚠️ MORE FORGIVING THAN `lxc.ts`'s `num`, ON PURPOSE. PVE's JSON is generated from a Perl schema
- *   and an integer field can arrive as `0` or as `"0"` depending on the release and the endpoint. A
- *   strict `typeof === 'number'` would silently fall back to 0 for the string form, so a declared
- *   `expire` would never equal the live one and the plan would report an update it cannot settle.
- */
-const int = (value: unknown) => {
-  const parsed = typeof value === 'number' ? value : Number(value ?? 0);
-  return Number.isFinite(parsed) ? parsed : 0;
-};
-
-/**
- * An array (what the read returns), a comma string (what older releases and the write side use), or
- * nothing — in; a sorted, deduplicated list out. Both sides of `matches` go through this, which is
- * the only reason the diff ever settles.
- */
-const groupSet = (value: unknown): string[] => {
-  const raw: unknown[] = Array.isArray(value)
-    ? value
-    : typeof value === 'string'
-      ? value.split(',')
-      : [];
-  const names = raw.map((group) => str(group).trim()).filter((group) => group !== '');
-  return [...new Set(names)].sort();
-};
+/** ★ Default `read` role for this family — only the write side needs `provision`. */
+const readUser = (props: UserProps) =>
+  readOrUnreadable(runPve(props.target, 'read', false, access.getAccessUser(props))).pipe(
+    Effect.map((live) => (live === UNREADABLE ? UNREADABLE : attributesOf(live, props))),
+    Effect.orElseSucceed(() => undefined),
+  );
 
-/**
- * ⚠️ THE SHAPE DEPENDS ON WHICH ENDPOINT YOU ASKED. Reading ONE user gives an object keyed by token
- *   name; the collection read gives an array of records. This provider only ever reads the single
- *   user path, so the map is what arrives — anything else is reported as "no tokens" rather than
- *   guessed at, because a wrong guess here would show up as a phantom revocation in a plan.
- */
-const tokenNames = (value: unknown): string[] =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-    ? Object.keys(value).sort()
-    : [];
+/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
+const dropUnreadable = (live: UserAttributes | Unreadable | undefined) =>
+  live === UNREADABLE ? undefined : live;
 
-/** Everything mutable, in the form PVE wants. Create adds `userid`; update sends exactly this. */
-const shape = (props: UserProps) => ({
-  comment: props.comment ?? '',
-  email: props.email ?? '',
-  enable: props.enable === false ? '0' : '1',
-  expire: String(props.expire ?? 0),
-  firstname: props.firstname ?? '',
-  /**
-   * ⚠️ ALWAYS SENT, EVEN EMPTY. Omitting `groups` on a PUT leaves the existing memberships in
-   *   place, so a group removed from the declaration would never actually be removed — and
-   *   `matches` would keep reporting an update that the update cannot fix. Same for `email` and
-   *   `comment`: the empty string is how PVE is told to clear a field.
-   * ⚠️ AND `append` IS DELIBERATELY NOT SET. Its default (0) REPLACES the list; setting it to 1
-   *   would turn every reconcile into an add-only merge, which is the same non-settling diff.
-   */
-  groups: groupSet(props.groups).join(','),
-  lastname: props.lastname ?? '',
-});
-
-const handlers = pveHandlers<UserProps, UserAttributes>({
-  attributes: (live, props) => ({
-    comment: str(live['comment']),
-    email: str(live['email']),
-    /**
-     * ⚠️ ABSENT MEANS ENABLED. PVE's schema defaults `enable` to 1 and does not always write the
-     *   key back for an enabled account. Reading absence as `false` would report an update on every
-     *   plan and then DISABLE the account on the deploy that "fixed" it.
-     */
-    enable: bool(live['enable'], true),
-    expire: int(live['expire']),
-    firstname: str(live['firstname']),
-    groups: groupSet(live['groups']),
-    lastname: str(live['lastname']),
-    tokens: tokenNames(live['tokens']),
-    /** ⚠️ FROM PROPS: `GET /access/users/{userid}` does not echo the userid back in its data. */
-    userid: props.userid,
-  }),
-  collection: () => 'access/users',
-  createForm: (props) => ({ ...shape(props), userid: props.userid }),
-  /**
-   * ⚠️ `tokens` IS NOT COMPARED, and neither is anything create-only. What is compared is exactly
-   *   what a PUT can put back; a field that PVE reports but will not accept is drift nobody can
-   *   fix, and diffing it would report an update on every plan forever.
-   */
-  /** The vendor rules these forms are checked against at plan time — resource-spec.ts. */
-  endpoint: { create: 'pve:POST /access/users', update: 'pve:PUT /access/users/{userid}' },
-  matches: (attributes, props) =>
-    attributes.comment === (props.comment ?? '') &&
-    attributes.email === (props.email ?? '') &&
-    attributes.enable === (props.enable !== false) &&
-    attributes.expire === (props.expire ?? 0) &&
-    attributes.firstname === (props.firstname ?? '') &&
-    attributes.lastname === (props.lastname ?? '') &&
-    attributes.groups.join(',') === groupSet(props.groups).join(','),
-  path: (props) => `access/users/${props.userid}`,
-  updateForm: shape,
-});
-
-/**
-* ⛔ EMPTY, AND MORE POINTEDLY SO HERE THAN ANYWHERE ELSE. `GET /access/users` answers with
-*   every account on the cluster: `root@pam`, every human who logs in, every service
-*   identity someone made years ago. Handing that list to Alchemy would invite it to adopt
-*   — and therefore one day DELETE — people. Adoption is an explicit act.
- 
- *
-* ⛔ DELETING A USER TAKES ITS API TOKENS AND ITS ACL ENTRIES WITH IT, in one call and
-*   without a confirmation. For the identity a credential mount vends from, that revokes
-*   every outstanding lease at once and every plan in this package stops working — this one
-*   included. PVE refuses only for `root@pam`; for everyone else it simply obeys.
- 
- */
 export const ProxmoxUserProvider = () =>
-  Provider.effect(ProxmoxUser, Effect.succeed(ProxmoxUser.Provider.of(handlers)));
+  Provider.effect(
+    ProxmoxUser,
+    Effect.succeed(
+      ProxmoxUser.Provider.of({
+        /**
+         * ⛔ EMPTY, AND MORE POINTEDLY SO HERE THAN ANYWHERE ELSE. `GET /access/users` answers
+         *   with every account on the cluster: `root@pam`, every human who logs in, every service
+         *   identity someone made years ago. Adoption is an explicit act.
+         */
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ olds }) {
+          return dropUnreadable(yield* readUser(olds));
+        }),
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news)) return undefined;
+          yield* guardWrite(USER_CREATE, createForm(news), output === undefined);
+          yield* guardWrite(USER_UPDATE, updateForm(news), false);
+          if (output === undefined) return undefined;
+          const live = yield* readUser(news);
+          // ⛔ THE CRIES-WOLF FIX: a refused read used to fall into `undefined` below and force
+          //   `update` on an account that was plainly there — see unreadable-read.ts.
+          if (live === UNREADABLE) {
+            yield* unreadableWarning('Proxmox.User', news.userid);
+            return { action: 'noop' } as const;
+          }
+          if (live === undefined) {
+            yield* guardWrite(USER_CREATE, createForm(news), true);
+            return { action: 'update' } as const;
+          }
+          return matches(live, news)
+            ? ({ action: 'noop' } as const)
+            : ({ action: 'update' } as const);
+        }),
+        reconcile: Effect.fn(function* ({ news }) {
+          // ⚠️ `dropUnreadable`: reconcile only runs once `provision` already minted for the
+          //   write below, so `UNREADABLE` here is a narrow race, not the routine case `diff`
+          //   handles — and a wrongful create in that race fails loudly ("already exists")
+          //   rather than silently duplicating, group.ts's reconcile has the same note.
+          const before = dropUnreadable(yield* readUser(news));
+          yield* guardWrite(USER_CREATE, createForm(news), before === undefined);
+          yield* guardWrite(USER_UPDATE, updateForm(news), false);
+          if (before === undefined) {
+            yield* runPve(
+              news.target,
+              'provision',
+              true,
+              access.createAccessUser(createForm(news)),
+            );
+          } else if (!matches(before, news)) {
+            yield* runPve(news.target, 'provision', true, access.putAccessUser(updateForm(news)));
+          }
+          const after = dropUnreadable(yield* readUser(news));
+          if (after === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `access/users/${news.userid}: the write returned no error but the account is ` +
+                  'still absent. PVE wraps every answer in {"data":...} and can report success ' +
+                  'on a call that did nothing -- read back rather than trusting the status code.',
+              ),
+            );
+          }
+          return after;
+        }),
+        /**
+         * ⛔ DELETING A USER TAKES ITS API TOKENS AND ITS ACL ENTRIES WITH IT, in one call and
+         *   without a confirmation. For the identity a credential mount vends from, that revokes
+         *   every outstanding lease at once and every plan in this package stops working — this
+         *   one included. PVE refuses only for `root@pam`; for everyone else it simply obeys.
+         */
+        delete: Effect.fn(function* ({ olds }) {
+          yield* runPve(
+            olds.target,
+            'provision',
+            true,
+            access.deleteAccessUser({ userid: olds.userid }),
+          );
+        }),
+      }),
+    ),
+  );