@homeflare/alchemy 0.1.0

package/src/proxmox/user.ts

@@ -0,0 +1,214 @@
+/**
+ * `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`
+ *   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),
+ *   not a bootstrap: the first mint user is made on a node with `pveum user add`, by a human, once.
+ *
+ * ⛔ THERE IS NO `password` PROP, AND ADDING ONE WOULD BE A LEAK RATHER THAN A FEATURE. Alchemy
+ *   writes resource state WITHOUT encryption — see the ⛔ in `credentials.ts` — so a password prop
+ *   would sit in clear in whatever database the stack points `state` at, and in every backup of it.
+ *   It is also unnecessary: `password` is accepted only by the CREATE call, changing one afterwards
+ *   is `PUT /access/password` (a different endpoint, a different privilege), and an account in a
+ *   realm such as `@pam`, `@ldap` or `@openid` has no PVE-side password at all — the realm holds
+ *   it. Out of scope by design. `keys` (TFA) is omitted for the same reason.
+ *
+ * ⚠️ `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.
+ *
+ * ⚠️ `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.
+ *
+ * ⚠️ RECONCILE NEEDS PRIVILEGES `LXCProvisioner` DOES NOT HOLD, so state them rather than meet a
+ *   403 in the middle of a deploy (pool.ts records how that went the last time):
+ *     · `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.
+ *     · `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.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import { type PveRequirements, type WithTarget, pveHandlers } from './resource.ts';
+import { bool } from './values.ts';
+
+export interface UserProps extends WithTarget {
+  /**
+   * ⛔ REALM-QUALIFIED, ALWAYS: `someone@pve`, `someone@pam`. The realm is part of PVE's primary
+   *   key, and a bare name is refused with "value does not look like a valid user id".
+   *
+   * ⚠️ PVE HAS NO RENAME. Editing this prop makes the path point at a DIFFERENT account, which
+   *   reads as absent and is then created — while the old one stays on the cluster with its tokens
+   *   and its ACL entries. Renaming is a delete and a create, and should be declared as one.
+   */
+  userid: string;
+  /** Free text shown in the UI. */
+  comment?: string;
+  /** PVE accepts the empty string here; that is how an address is cleared. */
+  email?: string;
+  /** Default true, matching PVE's own `enable=1`. False disables login without deleting anything. */
+  enable?: boolean;
+  /** Seconds since the epoch. 0 — the default — means the account never expires. */
+  expire?: number;
+  /** Group memberships. Order and duplicates carry no meaning — see the ⚠️ in the header. */
+  groups?: string[];
+  firstname?: string;
+  lastname?: string;
+}
+
+export interface UserAttributes {
+  userid: string;
+  comment: string;
+  email: string;
+  enable: boolean;
+  expire: number;
+  /** Normalised: sorted, deduplicated, whatever shape the cluster used on the wire. */
+  groups: string[];
+  firstname: string;
+  lastname: string;
+  /**
+   * API token names this account owns. Reported so a plan can show what a delete would revoke;
+   * never compared, because this endpoint cannot set them.
+   */
+  tokens: string[];
+}
+
+export interface ProxmoxUser extends Resource<
+  'Proxmox.User',
+  UserProps,
+  UserAttributes,
+  never,
+  PveRequirements
+> {}
+
+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();
+};
+
+/**
+ * ⚠️ 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()
+    : [];
+
+/** 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.
+   */
+  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)));

package/src/proxmox/values.test.ts

@@ -0,0 +1,193 @@
+/**
+ * The wire coercions, tested where they are load bearing.
+ *
+ * ★ THESE ARE NOT SMOKE TESTS. Every case here is a trap `values.ts` documents in prose, and prose
+ *   does not fail a build. Each one is written so that REVERTING the behaviour it describes turns
+ *   this file red — that is the only property that makes a test worth its lines.
+ *
+ * ⚠️ WHY THIS FILE EXISTS AT ALL, HONESTLY: `@homeflare/proxmox` declared a `test` script and
+ *   shipped no tests, so `bun test` exited 1 on "No tests found" and the pre-push gate refused
+ *   every push. The fix could have been a quieter test script. It is this instead, because the
+ *   package had just grown thirteen resources standing on one shared module with nothing checking
+ *   it.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  bool,
+  canonicalToken,
+  csv,
+  flag,
+  guestList,
+  int,
+  num,
+  propertyString,
+  text,
+  withClears,
+} from './values.ts';
+
+describe('bool — reading a PVE boolean off the wire', () => {
+  it('accepts all three spellings PVE actually sends', () => {
+    for (const value of [1, true, '1']) assert.equal(bool(value), true, `${String(value)} is true`);
+    for (const value of [0, false, '0'])
+      assert.equal(bool(value), false, `${String(value)} is false`);
+  });
+
+  /**
+   * ⛔ THE REGRESSION THIS FILE WAS WRITTEN FOR. An unset SectionConfig flag comes back `''`. Read
+   *   as `false`, `backup-job.enabled` and `user.enable` — the two fields in this package that
+   *   default ON — come back disabled, `matches` reports an update nobody asked for, and the
+   *   deploy WRITES `enabled=0` onto a live backup job. Flip `bool` back to treating `''` as false
+   *   and this case fails.
+   */
+  it('treats the empty string as absent, not as false', () => {
+    assert.equal(bool('', true), true, "'' must take the caller's fallback");
+    assert.equal(bool('', false), false);
+  });
+
+  it('treats null and undefined as absent', () => {
+    assert.equal(bool(undefined, true), true);
+    assert.equal(bool(null, true), true);
+  });
+
+  /** ⚠️ Documented limit: only `1` is true, so a multi-state flag cannot be read here by accident. */
+  it('does not read an arbitrary non-zero number as true', () => {
+    assert.equal(bool(2), false);
+  });
+});
+
+describe('flag — writing a boolean into a PVE form', () => {
+  it('is the inverse direction of bool, and says so in its types', () => {
+    assert.equal(flag(true), '1');
+    assert.equal(flag(false), '0');
+  });
+
+  /** ⛔ An undeclared field must not be sent: '0' would write PVE's default over what is live. */
+  it('answers undefined for an undeclared field rather than 0', () => {
+    assert.equal(flag(undefined), undefined);
+  });
+});
+
+describe('int — PVE may spell the same field as a number or a string', () => {
+  it('reads 8086 and "8086" as the same value', () => {
+    assert.equal(int(8086, -1), int('8086', -1));
+  });
+
+  it('falls back rather than yielding NaN', () => {
+    assert.equal(int('not-a-port', -1), -1);
+    assert.equal(int(undefined, -1), -1);
+  });
+
+  /** ⚠️ 0 is a legitimate value, so it must survive — this is why -1 is the absent-marker. */
+  it('keeps a real zero', () => {
+    assert.equal(int(0, -1), 0);
+  });
+});
+
+describe('num and text', () => {
+  it('num takes the fallback for null, which PVE sends for an unset field', () => {
+    assert.equal(num(null, 7), 7);
+    assert.equal(num(3, 7), 3);
+  });
+
+  it('text defaults to the empty string', () => {
+    assert.equal(text(undefined), '');
+    assert.equal(text(42), '');
+    assert.equal(text(42, 'fallback'), 'fallback', 'a non-string takes the fallback');
+  });
+});
+
+describe('csv — a set PVE does not give back in the order it was handed', () => {
+  it('is order insensitive, so two orderings compare equal', () => {
+    assert.equal(csv(['n3', 'n2']), csv('n2,n3'));
+  });
+
+  it('trims and drops empties, so a trailing comma is not a phantom member', () => {
+    assert.equal(csv('n2, n3,'), 'n2,n3');
+  });
+});
+
+describe('guestList — order is not meaning, and the sort must be numeric', () => {
+  /** ⛔ Sorted as TEXT, '101' precedes '99'. That is the whole reason this is not `csv`. */
+  it('sorts numerically, not lexically', () => {
+    assert.equal(guestList('99,101'), '99,101');
+    assert.equal(guestList([101, 99]), '99,101');
+  });
+
+  it('reads the array and the string form identically', () => {
+    assert.equal(guestList([101, 99]), guestList('101, 99'));
+  });
+});
+
+describe('canonicalToken', () => {
+  it('folds the words PVE accepts onto the digits it returns', () => {
+    for (const yes of ['yes', 'true', 'on', '1']) assert.equal(canonicalToken(yes), '1');
+    for (const no of ['no', 'false', 'off', '0']) assert.equal(canonicalToken(no), '0');
+  });
+});
+
+describe('propertyString — one value in two shapes', () => {
+  /**
+   * ⛔ THE MEASURED FOREVER-DIFF. `fleecing` is WRITTEN as `enabled=0` and READ BACK as the object
+   *   {"enabled":0}. If these two do not flatten to the same string, every plan reports an update
+   *   on a job nobody touched.
+   */
+  it('flattens the written string and the read-back object to the same value', () => {
+    assert.equal(
+      propertyString('enabled=0,storage=local'),
+      propertyString({ enabled: 0, storage: 'local' }),
+    );
+  });
+
+  it('is order insensitive', () => {
+    assert.equal(
+      propertyString('storage=local,enabled=1'),
+      propertyString('enabled=1,storage=local'),
+    );
+  });
+
+  /** ⚠️ `fleecing=1` is shorthand for `fleecing=enabled=1`; unexpanded they never compare equal. */
+  it('expands a bare token through defaultKey', () => {
+    assert.equal(propertyString('1', 'enabled'), propertyString({ enabled: 1 }));
+  });
+
+  it('passes a bare token through unchanged when there is no defaultKey', () => {
+    assert.notEqual(propertyString('1'), propertyString({ enabled: 1 }));
+  });
+
+  it('is empty for a value that is neither a string nor an object', () => {
+    assert.equal(propertyString(undefined), '');
+  });
+});
+
+describe('withClears — PVE refuses a key that is set and deleted at once', () => {
+  /**
+   * ⛔ THE FAILURE THIS GUARDS. PVE::SectionConfig::delete_from_config line 1860 dies with
+   *   "cannot set and delete property '$k' at the same time!" when the key is `defined` in the
+   *   body — and `'0'` is defined. Six families built this form by hand before it was extracted.
+   */
+  it('drops a cleared key from the body rather than sending both', () => {
+    const form = withClears({ comment: 'x', strict: '0' }, ['strict']);
+    assert.equal(form['strict'], undefined, 'strict must not be SET while it is being deleted');
+    assert.equal(form['delete'], 'strict');
+    assert.equal(form['comment'], 'x');
+  });
+
+  it("treats the empty string as set, because PVE's test is `defined` and not truth", () => {
+    const form = withClears({ comment: '' }, ['comment']);
+    assert.equal(form['comment'], undefined);
+    assert.equal(form['delete'], 'comment');
+  });
+
+  /** ⚠️ No clears means no `delete` key at all — an empty one would be a parameter PVE rejects. */
+  it('omits delete entirely when nothing is cleared', () => {
+    const form = withClears({ comment: 'x' }, []);
+    assert.equal(form['delete'], undefined);
+    assert.deepEqual(form, { comment: 'x' });
+  });
+
+  /** ⚠️ An undefined value is dropped, or URLSearchParams would send the text "undefined". */
+  it('drops undefined values instead of stringifying them', () => {
+    assert.deepEqual(withClears({ a: undefined, b: 'y' }, []), { b: 'y' });
+  });
+});

package/src/proxmox/values.ts

@@ -0,0 +1,203 @@
+/**
+ * How PVE spells a value on the wire, and how to get it back to something comparable.
+ *
+ * ⛔ EVERY FUNCTION HERE WAS FOUND IN TWO OR MORE RESOURCE FILES, AND THE COPIES HAD DRIFTED.
+ *   `num` was byte-identical in three files, so merging it is free. The boolean was NOT: four
+ *   files declared `const flag` and meant four different things by it, including one that ran the
+ *   other way round. That is the whole reason this module exists — not to save lines, but because
+ *   a name that means four things is a bug waiting for the person who assumes it means the first
+ *   one they read.
+ *
+ * ★ THE TWO DIRECTIONS ARE NAMED APART, DELIBERATELY. `bool` reads the wire and answers a
+ *   TypeScript boolean; `flag` writes a form field and answers PVE's `'1'`/`'0'`. `storage.ts`
+ *   held both under one name — `flag` there was the write direction while `flag` in three other
+ *   files was the read direction — which typechecks in both files and is exactly the confusion
+ *   that survives review.
+ *
+ * ⚠️ NOTHING HERE IS RESOURCE-SPECIFIC. A coercion that only one PVE object needs belongs in that
+ *   object's file, where its reasoning sits next to the field it serves. `role.ts` keeps its own
+ *   `canonical` for the same reason: that one sorts a privilege SET, which is a different idea
+ *   from `canonicalToken` below however similar the names read.
+ */
+
+/** ⚠️ `typeof value === 'number'` and not `Number(value)`: PVE sends `null` for an unset field. */
+export const num = (value: unknown, fallback: number) =>
+  typeof value === 'number' ? value : fallback;
+
+export const text = (value: unknown, fallback = '') =>
+  typeof value === 'string' ? value : fallback;
+
+/**
+ * A PVE boolean off the wire.
+ *
+ * ⛔ THE FOUR SPELLINGS THIS REPLACES, AND WHY THIS ONE IS A SUPERSET OF ALL OF THEM. Measured in
+ *   the files they came from: `backup-job` accepted `1 | true | '1'` with a caller's fallback;
+ *   `sdn-vnet` the same three with no fallback; `storage` accepted only `1 | true`; `user` ran the
+ *   value through `Number()` and asked `!== 0`. For the values PVE actually returns on these
+ *   endpoints — `0` and `1` — all four agree, so accepting the union changes no live answer.
+ *
+ * ⚠️ THE ONE REAL DIFFERENCE IS `2`. `user.ts` would have read any non-zero number as true; this
+ *   reads only `1`. No PVE field in this package is documented to return anything but 0 or 1, and
+ *   a field that did would be a flag with more than two states — which is not a boolean, and
+ *   should be read with `num` and named for what it is rather than quietly coerced here.
+ *
+ * ⚠️ `null`, `undefined` AND `''` ALL TAKE THE FALLBACK. An absent key means PVE's documented
+ *   default for that field, which is not always `false` — so the default is the CALLER's to state,
+ *   and `false` is only the fallback's own default for fields that really do default off.
+ *
+ * ⛔ THE EMPTY STRING IS ABSENT, NOT FALSE, AND GETTING THAT WRONG WRITES THE WRONG VALUE. A
+ *   metric server is a SectionConfig section and can hand back `''` for an unset flag. Read as
+ *   `false`, the two fields in this package that default ON — `backup-job.enabled` and
+ *   `user.enable` — would come back disabled, `matches` would report an update nobody asked for,
+ *   and the deploy would then WRITE `enabled=0` onto a live job. An empty string is not a
+ *   boolean; it is the absence of one.
+ */
+export const bool = (value: unknown, fallback = false) =>
+  value === undefined || value === null || value === ''
+    ? fallback
+    : value === 1 || value === true || value === '1';
+
+/**
+ * A boolean on its way INTO a PVE form.
+ *
+ * ⚠️ `undefined` IN, `undefined` OUT — an undeclared field must not be sent at all. Sending `'0'`
+ *   for a prop the caller never set would write PVE's default over whatever is live, turning an
+ *   omission into an edit.
+ */
+export const flag = (value?: boolean) => (value === undefined ? undefined : value ? '1' : '0');
+
+/**
+ * A comma list PVE does not promise to give back in the order it was handed.
+ *
+ * ⚠️ `nodes` IS A SET AND PVE DOES NOT PRESERVE ITS ORDER. The zone plugin decodes the list into a
+ *   hash and re-encodes it by joining that hash's keys, so the string you get back is not the one
+ *   you sent. Sorting both sides is what stops a plan reporting an update because two names came
+ *   back the other way round. `peers` gets the same treatment: it is a mesh, not a queue.
+ */
+export const csv = (value: readonly string[] | string | undefined) =>
+  (typeof value === 'string' ? value.split(',') : (value ?? []))
+    .map((part) => part.trim())
+    .filter((part) => part !== '')
+    .sort()
+    .join(',');
+
+/**
+ * A comma list of guest IDs, in numeric order.
+ *
+ * ⚠️ ORDER IS NOT MEANING IN A GUEST LIST, SO IT MUST NOT BE A DIFF. PVE stores `vmid` as the
+ *   comma-separated string it was handed and gives it back the same way, so a declaration listing
+ *   the same guests in another order would otherwise be an update that rewrites the job to say
+ *   exactly what it already said. Both sides are sorted numerically before they meet.
+ *
+ * ⚠️ NUMERIC, NOT LEXICAL — this is why it is not `csv`. Sorted as text, `101` precedes `99`.
+ */
+export const guestList = (value: unknown): string => {
+  const parts =
+    typeof value === 'string'
+      ? value.split(',')
+      : Array.isArray(value)
+        ? value.map((entry: unknown) => String(entry))
+        : [];
+  return parts
+    .map((part) => Number(part.trim()))
+    .filter((id) => Number.isFinite(id))
+    .sort((left, right) => left - right)
+    .map((id) => String(id))
+    .join(',');
+};
+
+/** `yes`/`true`/`on` and their opposites are the same value as 1/0 to PVE; make them one string. */
+export const canonicalToken = (raw: string) => {
+  const lowered = raw.trim().toLowerCase();
+  if (['1', 'yes', 'true', 'on'].includes(lowered)) return '1';
+  if (['0', 'no', 'false', 'off'].includes(lowered)) return '0';
+  return lowered;
+};
+
+/**
+ * A PVE property string, flattened to one comparable form.
+ *
+ * ⚠️ A PROPERTY STRING AND ITS PARSED FORM ARE ONE VALUE IN TWO SHAPES, AND PVE HANDS BACK
+ *   WHICHEVER IT LIKES. MEASURED: `fleecing` is WRITTEN as the property string `fleecing=enabled=0`
+ *   and READ BACK as the nested object {"enabled":0}. Comparing raw values would report an update
+ *   on every plan for a job nobody touched — the same forever-diff a create-only field causes. So
+ *   both sides are flattened here, sorted, and only then compared. `prune-backups` goes through
+ *   the same funnel: same kind of value, the normalisation is free, and guessing which shape it
+ *   comes back in is exactly the guess that costs a permanent diff.
+ *
+ * ⚠️ `defaultKey` EXISTS BECAUSE `fleecing=1` IS SHORTHAND FOR `fleecing=enabled=1`. PVE's format
+ *   for it is written `[enabled=]<1|0>`, so a bare token is legal on write and comes back expanded
+ *   on read; unexpanded, the short and long spellings never compare equal. `prune-backups` has no
+ *   default key, so a bare token there is passed through as-is rather than invented into one.
+ */
+export const propertyString = (value: unknown, defaultKey?: string): string => {
+  const pairs: [string, string][] =
+    typeof value === 'string'
+      ? value.split(',').map((part) => {
+          const [key, ...rest] = part.split('=');
+          return rest.length === 0 && defaultKey !== undefined
+            ? [defaultKey, key ?? '']
+            : [key ?? '', rest.join('=')];
+        })
+      : typeof value === 'object' && value !== null
+        ? Object.entries(value).map(([key, entry]) => [key, String(entry)])
+        : [];
+  return pairs
+    .map(([key, entry]) => [key.trim(), canonicalToken(entry)] as const)
+    .filter(([key]) => key !== '')
+    .map(([key, entry]) => `${key}=${entry}`)
+    .sort()
+    .join(',');
+};
+
+/**
+ * An integer PVE may have spelled as a string.
+ *
+ * ⚠️ PVE MAY HAND BACK EITHER `8086` OR `"8086"`. These objects are SectionConfig sections, and the
+ *   integer check VALIDATES the parsed string rather than converting it, so whether a number
+ *   arrives as a number is a property of the version you are talking to. `'8086' === 8086` is
+ *   false, and that is an update consisting of nothing, reported on every plan forever.
+ */
+export const int = (value: unknown, fallback: number) => {
+  if (typeof value === 'number') return value;
+  const parsed = Number.parseInt(text(value), 10);
+  return Number.isNaN(parsed) ? fallback : parsed;
+};
+
+/**
+ * A PVE update form with its clear-list attached, and the two guaranteed not to overlap.
+ *
+ * ⛔ PVE DIES IF A KEY IS SET AND DELETED IN ONE CALL, AND SIX FAMILIES HERE BUILT THAT FORM BY
+ *   HAND. Measured in the shipped Perl on n2 — `PVE::SectionConfig::delete_from_config`, line 1860:
+ *
+ *     die "cannot set and delete property '$k' at the same time!\n"
+ *         if defined($new_options->{$k});
+ *
+ *   `defined` is the test, not truth, so `strict=0` or `comment=''` in the body counts as SET. The
+ *   concrete failure: a live node-affinity rule with `strict 1` and a declaration carrying
+ *   `strict: false`. `matches` reports an update; the clear-list has to name `strict`, because a
+ *   PUT of `strict=0` merges a falsy value the plugin still stores; and if the body also emits
+ *   `strict: '0'` the PUT is refused. The update never lands, the next plan reports the same
+ *   update, and every deploy 500s — forever.
+ *
+ * ★ SO DISJOINTNESS IS ENFORCED HERE RATHER THAN REASONED ABOUT SIX TIMES. A cleared key is
+ *   dropped from the body: CLEAR WINS. That is the right way round because a clear-list entry is
+ *   computed from "this prop is absent, and absent means remove it", which is a deliberate
+ *   statement, while the body's value for the same key is the coercion of that same absence —
+ *   `flag(false)` is `'0'`, and `'0'` is exactly what must not be sent.
+ *
+ * ⚠️ UNDEFINED VALUES ARE DROPPED TOO, so a form builder may emit `undefined` for a field it does
+ *   not set without the caller filtering first. `new URLSearchParams` would otherwise stringify it
+ *   to the literal text "undefined".
+ */
+export const withClears = (
+  fields: Record<string, string | undefined>,
+  clear: readonly string[],
+): Record<string, string> => {
+  const cleared = new Set(clear);
+  const kept: Record<string, string> = {};
+  for (const [key, value] of Object.entries(fields)) {
+    if (value !== undefined && !cleared.has(key)) kept[key] = value;
+  }
+  return cleared.size === 0 ? kept : { ...kept, delete: [...cleared].join(',') };
+};