@homeflare/alchemy 0.31.0 → 0.31.2

package/src/proxmox/unreadable-read.test.ts

@@ -0,0 +1,83 @@
+/**
+ * The cries-wolf fix (unreadable-read.ts), proved end to end for `Proxmox.Acl` — the reference
+ * migrated family — through Alchemy's own Plan and Apply, over a fake cluster whose OpenBao mint
+ * can be flipped to DENY the `provision` role mid-test, the way the agent lane's policy denies it
+ * for real (measured 2026-09-24, decision doc's "cries wolf" entry: 14 ACLs read back as absent
+ * and forced `update` with nothing compared).
+ *
+ * ★ ONE ENGINE, ONE TRANSPORT, A MUTABLE DENIAL FLAG — not two fakes — because the state row this
+ *   test needs (`output !== undefined`, the exact case the bug forced `update` for) has to
+ *   survive from the first deploy (mint allowed) into the second plan (mint denied);
+ *   fake-engine.ts builds its in-memory state store fresh per `engineOver` call, so the same
+ *   engine instance is reused for both, and only the fake OpenBao's answer to `/creds/provision`
+ *   changes in between. `lease_duration: 0` on every fake mint (both branches) keeps
+ *   lease-cache.ts cold, so the second phase genuinely re-mints and hits the denial.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { engineOver } from '../verify/fake-engine.ts';
+import { ProxmoxAcl, ProxmoxAclProvider } from './acl.ts';
+import { FAKE_TARGET, withoutBao } from './fake-pve.ts';
+
+type Row = { path: string; type: string; ugid: string; roleid: string; propagate?: number };
+
+/** One ACL row, plus an OpenBao mint the test can deny for `provision` mid-run. */
+const clusterDenyingProvision = (rows: readonly Row[]) => {
+  let denyProvision = false;
+  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/')) {
+      if (denyProvision && url.pathname.endsWith('/creds/provision')) {
+        return Response.json({ errors: ['permission denied'] }, { status: 403 });
+      }
+      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\//, '')}${url.search}`;
+    if (request.method === 'GET' && path === 'access/acl') return Response.json({ data: rows });
+    // ⛔ Any other write is a bug this test would otherwise hide: once denied, `reconcile` must
+    //   never be reached (diff answers noop), so nothing should ever PUT here again.
+    return Response.json({ data: null });
+  };
+  const fetchStub = Object.assign(stub, { preconnect: globalThis.fetch.preconnect });
+  return {
+    deny: () => {
+      denyProvision = true;
+    },
+    layer: FetchHttpClient.layer.pipe(
+      Layer.provideMerge(Layer.succeed(FetchHttpClient.Fetch, fetchStub as typeof fetch)),
+    ),
+  };
+};
+
+const grant = () =>
+  ProxmoxAcl('auditor', {
+    path: '/',
+    roleid: 'PVEAuditor',
+    target: FAKE_TARGET,
+    type: 'user',
+    ugid: 'u@pve',
+  });
+
+describe('the cries-wolf fix: a refused provision mint reports noop, never update', () => {
+  test('an already-correct grant plans noop once the credential is denied, and nothing is written', async () => {
+    const rows: Row[] = [
+      { path: '/', propagate: 1, roleid: 'PVEAuditor', type: 'user', ugid: 'u@pve' },
+    ];
+    const fake = clusterDenyingProvision(rows);
+    await withoutBao(async () => {
+      const engine = engineOver(ProxmoxAclProvider().pipe(Layer.provideMerge(fake.layer)));
+      // First deploy: mint allowed, adopts the matching grant and records a state row.
+      expect(await engine.deploy(grant())).toEqual({ auditor: 'adopted' });
+      // Now the credential's role is denied -- exactly the measured agent-lane scenario.
+      fake.deny();
+      const report = await engine.verify(grant(), { all: true });
+      // ⛔ THE BUG THIS PROVES FIXED: before the fix this row read 'update' with nothing compared.
+      expect(report.rows[0]).toMatchObject({ diff: 'noop' });
+      expect(await engine.deploy(grant())).toEqual({ auditor: 'noop' });
+    });
+  });
+});

package/src/proxmox/unreadable-read.ts

@@ -0,0 +1,60 @@
+/**
+ * The "unreadable" outcome a refused read produces — distinct from `undefined` (genuinely
+ * absent) and from a real attributes object (present) — so `diff` stops treating a REFUSED read
+ * the same as a confirmed-gone one. Fixes the "cries wolf" bug (measured 2026-09-24): on a lane
+ * whose credential cannot mint `provision`, every already-correct ACL and storage row read back
+ * as absent, and `diff` forced `update` for every one of them without comparing a single field,
+ * because `.pipe(Effect.orElseSucceed(() => undefined))` folds every failure — a genuine 404, a
+ * network blip, AND a permission refusal — into the one "absent" value `diff` cannot tell apart.
+ *
+ * ★ WHY A SENTINEL, NOT A FAILED `diff`. Upstream's `Diff` type is exactly
+ *   `NoopDiff | UpdateDiff | ReplaceDiff` (`packages/alchemy/src/Diff.ts@v2.0.0-beta.79`) — there
+ *   is no fourth "unreadable" action to return. And `Plan.ts`'s resource pass runs every
+ *   resource's `diff` under `Effect.exit`, then FAILS THE WHOLE PLAN if even one failed
+ *   (`diffFailures.length > 0` -> `Effect.failCause`, `Plan.ts@v2.0.0-beta.79` ~lines 1711-1731).
+ *   So making `diff` FAIL on a refused read would not report one honest row — it would abort
+ *   `bun run plan` for every OTHER resource in the stack too, worse than today's false "update".
+ *   `{ action: 'noop' }` plus a logged warning is the only outcome that (a) never forces a write
+ *   on a lane that cannot prove one is needed and (b) never takes the rest of the plan down with
+ *   it — the "noop-with-warning" reading of the fix, over the alternative of a typed plan error.
+ *
+ * ⛔ ONLY THE CREDENTIAL DENIAL IS CAUGHT HERE. Every other read failure (a genuine
+ *   `Cause.TimeoutError`, `PveClusterExhausted`, a network error) keeps folding into `undefined`
+ *   exactly as it always has — this narrows ONE typed tag out of that fold, via `catchTag`, and
+ *   changes nothing else about it. See credential-errors.ts's own ⛔ for why 403 alone qualifies.
+ */
+import * as Effect from 'effect/Effect';
+import type { PveCredentialDenied } from './credential-errors.ts';
+
+/** Distinct from `undefined` (absent) and from a real attributes object (present). */
+export const UNREADABLE = Symbol('pve-unreadable');
+export type Unreadable = typeof UNREADABLE;
+
+/**
+ * Catches ONLY `PveCredentialDenied` and turns it into the sentinel, so a caller that also
+ * `.pipe(Effect.orElseSucceed(() => undefined))` for every OTHER failure never conflates a
+ * refusal with a genuine absence. Compose this INSIDE that fold, never after it.
+ *
+ * ⚠️ `E | PveCredentialDenied` IN, `E` OUT — not a generic `E` narrowed by `Exclude`. `catchTag`
+ *   needs the tag to be STATICALLY present in the error union to typecheck at all; a bare
+ *   unconstrained `E` gives it nothing to match against. Every caller's `runPve` already carries
+ *   `PveCredentialDenied` explicitly (distilled-pve.ts's own ★ on why), so this signature costs
+ *   nothing at the call site.
+ */
+export const readOrUnreadable = <A, E, R>(
+  effect: Effect.Effect<A, E | PveCredentialDenied, R>,
+): Effect.Effect<A | Unreadable, E, R> =>
+  effect.pipe(Effect.catchTag('PveCredentialDenied', () => Effect.succeed(UNREADABLE)));
+
+/**
+ * The warning `diff` logs when it reports `noop` for a row it could not actually read — visible
+ * in `bun run plan`'s own output (Effect's default logger), even though the Diff type has
+ * nowhere to carry the distinction through to the printed action. See the header for why a log
+ * line, not a failed diff or a fourth Diff action, is what "the plan reports" means here.
+ */
+export const unreadableWarning = (type: string, identity: string): Effect.Effect<void> =>
+  Effect.logWarning(
+    `${type} ${identity}: the read was refused (no grant for this credential's role) -- ` +
+      'reporting noop rather than forcing an update with nothing compared. Re-plan on a lane ' +
+      'that can read this object before trusting this row.',
+  );

package/src/proxmox/user-wire.ts

@@ -0,0 +1,148 @@
+/**
+ * `Proxmox.User`'s wire shape: PVE's create/update forms, how a live item becomes attributes,
+ * and the read itself. Split out of user.ts (2026-09-24, the distilled migration) to keep that
+ * file under the 250-line cap — the api-token.ts/api-token-form.ts seam.
+ */
+import * as access from '@distilled.cloud/proxmox/access';
+import * as Effect from 'effect/Effect';
+import { runPve } from './distilled-pve.ts';
+import type { UserAttributes, UserProps } from './user.ts';
+import { UNREADABLE, type Unreadable, readOrUnreadable } from './unreadable-read.ts';
+import { bool, text } from './values.ts';
+
+export const USER_CREATE = 'pve:POST /access/users';
+export const USER_UPDATE = 'pve:PUT /access/users/{userid}';
+
+/**
+ * ⚠️ MORE FORGIVING THAN `lxc.ts`'s `num`, ON PURPOSE, AND DELIBERATELY NOT `values.ts`'s
+ *   `int` (a different function of the same name, `Number.parseInt` on a STRING with a
+ *   caller-given fallback). PVE's JSON is generated from a Perl schema and an integer field can
+ *   arrive as `0` or `"0"` depending on the release and the endpoint; `Number(value ?? 0)`
+ *   accepts either without a strict `typeof === 'number'` that would silently fall back for the
+ *   string form and report an update `matches` can never 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) => text(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; distilled types it `tokens?: unknown` for the same reason (the item and index
+ *   responses disagree, and this provider only ever reads the item). Anything but that shape is
+ *   reported as "no tokens" rather than guessed at.
+ */
+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. 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 ?? '',
+});
+
+export const createForm = (props: UserProps): access.CreateAccessUserRequest => ({
+  ...shape(props),
+  userid: props.userid,
+});
+
+export const updateForm = (props: UserProps): access.PutAccessUserRequest => ({
+  ...shape(props),
+  userid: props.userid,
+});
+
+const attributesOf = (live: access.GetAccessUserResponse, props: UserProps): UserAttributes => ({
+  comment: text(live.comment),
+  email: text(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: text(live.firstname),
+  groups: groupSet(live.groups),
+  lastname: text(live.lastname),
+  tokens: tokenNames(live.tokens),
+  /** ⚠️ FROM PROPS: `GET /access/users/{userid}` does not echo the userid back in its data. */
+  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 PVE reports but will not accept is drift nobody can fix.
+ */
+export const matches = (attributes: UserAttributes, props: UserProps) =>
+  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(',');
+
+/**
+ * ★ Default `read` role for this family — only the write side needs `provision`.
+ * ⛔ `{ userid: props.userid }`, NEVER THE WHOLE `props` — MEASURED 2026-09-24, the regression in
+ *   kit 0.31.1. `GetAccessUserRequest`'s schema declares only `userid` (a path label); any OTHER
+ *   key on the object passed to `access.getAccessUser` — `target`, `comment`, every field this
+ *   family's own props carry — is treated by distilled's `buildRequest` as an "unknown key" and
+ *   JSON-encoded onto the request as a BODY, on every one of these bodyless GETs. A stricter
+ *   fetch client than a bare `bun run` of this file refuses a GET carrying any body at all
+ *   (`TypeError [ERR_INVALID_ARG_VALUE]: fetch() request with GET/HEAD method cannot have body`),
+ *   which `runPveWith` retries across every member and exhausts identically —
+ *   `PveClusterExhausted`, then silently folded to "absent" by the old `orElseSucceed`, forcing a
+ *   false `update` on every account.
+ */
+export const readUserOrFail = (props: UserProps) =>
+  readOrUnreadable(
+    runPve(props.target, 'read', false, access.getAccessUser({ userid: props.userid })),
+  ).pipe(Effect.map((live) => (live === UNREADABLE ? UNREADABLE : attributesOf(live, props))));
+
+/**
+ * ⛔ FOLDS A GENUINE READ FAILURE TO `undefined` TOO, AND ONLY `read`/`reconcile` MAY USE IT. A
+ *   missing user is a thrown 500 (user.ts's own header), so `reconcile`'s create branch NEEDS
+ *   "absent" from a failure to ever run — without this fold, a brand-new account could never be
+ *   created. Safe here because a wrongful fold costs at most a redundant `createAccessUser` POST,
+ *   which PVE refuses loudly rather than silently corrupting anything.
+ * ⛔ `user.ts`'s `diff` does **NOT** use this — the SAME bug class as the credential denial fix:
+ *   folding a TRANSIENT failure into "absent" at PLAN TIME is what forced a false `update` with
+ *   nothing compared. `diff` calls `readUserOrFail` directly, so a genuine failure there
+ *   propagates and fails the whole plan loudly instead.
+ */
+export const readUser = (props: UserProps) =>
+  readUserOrFail(props).pipe(Effect.orElseSucceed(() => undefined));
+
+/** `read`/`reconcile` return `Attributes | undefined`; only `diff` tells `UNREADABLE` apart. */
+export const dropUnreadable = (live: UserAttributes | Unreadable | undefined) =>
+  live === UNREADABLE ? undefined : live;

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']);
+  });
+});