@homeflare/distilled-proxmox 0.2.0 → 0.3.1

package/src/errors.ts

@@ -23,7 +23,11 @@
  *   - `ClusterNodeUnreachable` is added via an ACTUAL RFC-6902 patch —
  *     `patches/nodes/task-polling.json` — to the four `/nodes/{node}/
  *     tasks/…` operations the vendor schema itself marks `proxyto: "node"`
- *     (this package's own `src/task.ts` polls one of them). It is NOT
+ *     (a caller polling `GetNodeTaskStatus` — this package's own generated
+ *     operation — can hit any of the four; task polling itself is
+ *     provider-side, not this package's, per P13/Q3 of the 2026-09-24
+ *     walk-down: no distilled precedent for a package-level poll helper).
+ *     It is NOT
  *     global: most PVE calls are answered by the node you connected to
  *     directly and never proxy at all, so declaring a 595 possible on
  *     every operation would be a claim the schema does not support for
@@ -48,16 +52,9 @@ export {
   DEFAULT_ERRORS,
   API_ERRORS,
 } from "@distilled.cloud/core/errors";
-// `export { X } from "mod"` (above) is a RE-EXPORT ONLY — it creates no local
-// binding for `X`, so `BadRequest` needs its own `import type` to be usable
-// in this file's own `DefaultErrors` union below. Caught by the kit's copy
-// of this package typechecking under `verbatimModuleSyntax`, not by this
-// package's own `tsc -b` — see `docs/distilled-interim.md`'s "prove it in
-// both places" step for why that gap exists at all.
-import type {
-  BadRequest,
-  DefaultErrors as CoreDefaultErrors,
-} from "@distilled.cloud/core/errors";
+// Re-exports do not bind names locally. The operation union must cover every
+// class the package protocol can return through core's HTTP_STATUS_MAP.
+import type { API_ERRORS } from "@distilled.cloud/core/errors";
 
 import * as Schema from "effect/Schema";
 import * as Category from "@distilled.cloud/core/category";
@@ -118,10 +115,13 @@ export class ProxmoxParseError extends Schema.TaggedError<ProxmoxParseError>()(
 ).pipe(Category.withParseError) {}
 
 /**
- * A polled task ended with an `exitstatus` other than exactly `"OK"` — see
- * `src/task.ts`. `exitstatus` carries PVE's own failure text verbatim
- * (e.g. `"job errors"`, `"OK (warnings)"` — the latter is why the compare
- * is exact-equality against `"OK"`, never a prefix/substring check).
+ * A polled task ended with an `exitstatus` other than exactly `"OK"`.
+ * `exitstatus` carries PVE's own failure text verbatim (e.g. `"job
+ * errors"`, `"OK (warnings)"` — the latter is why a caller's compare must
+ * be exact-equality against `"OK"`, never a prefix/substring check).
+ * Exported for a provider-side poll to construct: this package no longer
+ * ships its own `awaitTask` helper (removed 2026-09-24 — polling belongs
+ * in the provider, P13; no distilled precedent for a package-level poll).
  */
 export class ProxmoxTaskFailed extends Schema.TaggedError<ProxmoxTaskFailed>()(
   "ProxmoxTaskFailed",
@@ -146,7 +146,6 @@ export type ClientErrors = UnknownProxmoxError | ProxmoxParseError;
  * task-polling.json` adds it to.
  */
 export type DefaultErrors =
-  | CoreDefaultErrors
-  | BadRequest
+  | InstanceType<(typeof API_ERRORS)[number]>
   | ParameterVerificationFailed
   | ClientErrors;

package/src/index.ts

@@ -30,4 +30,3 @@ export {
 } from "./protocol.ts";
 export * as Retry from "./retry.ts";
 export * as Services from "./services/index.ts";
-export { awaitTask, type TaskRef, type AwaitTaskOptions } from "./task.ts";

package/src/not-found-errors.test.ts

@@ -0,0 +1,112 @@
+/**
+ * WI-3: proves each resource-specific not-found shape actually decodes
+ * from PVE's real wire response — not just that the class exists and
+ * carries a non-transient category (checked separately, by hand, with
+ * `Category.isTransientError` against one instance of each class; see the
+ * WI-3 report). Each fixture here is the literal or closely-paraphrased
+ * text cited in the corresponding `patches/<segment>/_errors.json`
+ * patch's own description.
+ */
+import { describe, expect, test } from "bun:test";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import { credentials } from "./credentials.ts";
+import type { ProxmoxOpContext } from "./protocol.ts";
+import * as Retry from "./retry.ts";
+import {
+  getAccessGroup,
+  getAccessUser,
+  GroupNotFound,
+  UserNotFound,
+} from "./services/access.ts";
+import {
+  CephFsNotFound,
+  CephPoolNotFound,
+  deleteNodeCephFs,
+  getNodeCephPoolStatus,
+} from "./services/nodes.ts";
+import { getStorage, StorageNotFound } from "./services/storage.ts";
+
+const testCredentials = credentials({
+  tokenId: "root@pam!test",
+  secret: "test-secret",
+  baseUrl: "https://pve.test:8006",
+});
+
+const fakePve = (status: number, body: unknown) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) =>
+      Effect.sync(() =>
+        HttpClientResponse.fromWeb(
+          request,
+          new Response(JSON.stringify(body), { status }),
+        ),
+      ),
+    ),
+  );
+
+const flipped = <A, E>(
+  effect: Effect.Effect<A, E, ProxmoxOpContext>,
+  status: number,
+  body: unknown,
+) =>
+  Effect.runPromise(
+    effect.pipe(
+      Retry.none,
+      Effect.provide(Layer.mergeAll(fakePve(status, body), testCredentials)),
+      Effect.flip,
+    ),
+  );
+
+describe("WI-3 typed not-found errors decode from PVE's real wire shape", () => {
+  test("a missing user's 500 decodes to UserNotFound", async () => {
+    const error = await flipped(getAccessUser({ userid: "x@pve" }), 500, {
+      message: "no such user ('x@pve')",
+    });
+    expect(error).toBeInstanceOf(UserNotFound);
+  });
+
+  test("a missing group's 500 decodes to GroupNotFound", async () => {
+    const error = await flipped(getAccessGroup({ groupid: "ghosts" }), 500, {
+      message: "group 'ghosts' does not exist",
+    });
+    expect(error).toBeInstanceOf(GroupNotFound);
+  });
+
+  test("a missing storage's 500 decodes to StorageNotFound", async () => {
+    const error = await flipped(
+      getStorage({ storage: "hf-measure-nonexistent-probe" }),
+      500,
+      {
+        message: "storage 'hf-measure-nonexistent-probe' does not exist\n",
+        data: null,
+      },
+    );
+    expect(error).toBeInstanceOf(StorageNotFound);
+  });
+
+  test("a missing Ceph pool's 500 decodes to CephPoolNotFound", async () => {
+    const error = await flipped(
+      getNodeCephPoolStatus({ node: "n2", name: "ghost-pool" }),
+      500,
+      {
+        data: null,
+        message:
+          "error with 'osd pool get': mon_cmd failed - unrecognized pool 'ghost-pool'\n",
+      },
+    );
+    expect(error).toBeInstanceOf(CephPoolNotFound);
+  });
+
+  test("a missing Ceph filesystem's 500 (on destroy) decodes to CephFsNotFound", async () => {
+    const error = await flipped(
+      deleteNodeCephFs({ node: "n2", name: "ghost-fs" }),
+      500,
+      { message: "no such cephfs 'ghost-fs'\n" },
+    );
+    expect(error).toBeInstanceOf(CephFsNotFound);
+  });
+});

package/src/protocol-form.test.ts

@@ -0,0 +1,102 @@
+/** PVE 9.2.11 schema arrays must survive the vendor's repeated-key decoder. */
+import { expect, test } from "bun:test";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+import { credentials } from "./credentials.ts";
+import type { ProxmoxOpContext } from "./protocol.ts";
+import * as Retry from "./retry.ts";
+import * as cluster from "./services/cluster.ts";
+import * as nodes from "./services/nodes.ts";
+
+const capture = async <A, E>(op: Effect.Effect<A, E, ProxmoxOpContext>) => {
+  const requests: HttpClientRequest.HttpClientRequest[] = [];
+  await Effect.runPromise(
+    op.pipe(
+      Retry.none,
+      Effect.provide(
+        credentials({
+          baseUrl: "https://pve.test:8006",
+          tokenId: "test@pve!test",
+          secret: "fake",
+        }),
+      ),
+      Effect.provide(
+        Layer.succeed(
+          HttpClient.HttpClient,
+          HttpClient.make((request) => {
+            requests.push(request);
+            return Effect.succeed(
+              HttpClientResponse.fromWeb(
+                request,
+                Response.json({ data: null }),
+              ),
+            );
+          }),
+        ),
+      ),
+    ),
+  );
+  const request = requests[0]!;
+  const form =
+    request.body._tag === "Uint8Array"
+      ? new URLSearchParams(new TextDecoder().decode(request.body.body))
+      : new URLSearchParams();
+  return { request, form };
+};
+
+test("matcher arrays repeat the wire key; commas within a rule stay inside that item", async () => {
+  const { request, form } = await capture(
+    cluster.createClusterNotificationMatcher({
+      name: "matcher",
+      target: ["mail", "webhook"],
+      match_field: ["exact:type=vzdump", "regex:hostname=one,two"],
+    }),
+  );
+  expect(request.method).toBe("POST");
+  expect(form.getAll("target")).toEqual(["mail", "webhook"]);
+  expect(form.getAll("match-field")).toEqual([
+    "exact:type=vzdump",
+    "regex:hostname=one,two",
+  ]);
+  expect([...form.keys()].some((key) => key.includes("["))).toBe(false);
+});
+
+test("webhook property-string headers remain separate values", async () => {
+  const headers = ["name=X-One,value=YQ==", "name=X-Two,value=Yg=="];
+  const { form } = await capture(
+    cluster.createClusterNotificationEndpointWebhook({
+      name: "webhook",
+      method: "post",
+      url: "https://example.com/hook",
+      header: headers,
+    }),
+  );
+  expect(form.getAll("header")).toEqual(headers);
+});
+
+test("array delete fields repeat while scalar comma lists remain scalar", async () => {
+  const { form } = await capture(
+    cluster.putClusterNotificationMatcher({
+      name: "matcher",
+      delete: ["match-field", "match-calendar"],
+    }),
+  );
+  expect(form.getAll("delete")).toEqual(["match-field", "match-calendar"]);
+  const scalar = await capture(
+    cluster.putClusterBackup({ id: "job", vmid: "100,101" }),
+  );
+  expect(scalar.form.getAll("vmid")).toEqual(["100,101"]);
+});
+
+test("DELETE stays bodyless and its flags stay query parameters", async () => {
+  const { request, form } = await capture(
+    nodes.deleteNodeCephFs({ node: "node", name: "fs", remove_pools: "1" }),
+  );
+  expect(request.method).toBe("DELETE");
+  expect(request.body._tag).toBe("Empty");
+  expect(new URL(request.url).searchParams.get("remove-pools")).toBe("1");
+  expect([...form]).toEqual([]);
+});

package/src/protocol-form.ts

@@ -0,0 +1,49 @@
+/**
+ * PVE's form arrays use repeated keys, never Stripe's indexed fields.
+ *
+ * PVE 9.2.11 notification schemas declare arrays (mailto, header, target,
+ * match-field, delete). The vendor UI submits repeated keys; its Perl
+ * URL-encoded decoder joins them with NUL before schema validation. The
+ * existing kit notification-target-form.ts records that decoder/UI evidence
+ * (2026-09-14); no production multi-header write was made for this fix.
+ *
+ * Keep core's credentials, labels, schema key mapping, and query encoding.
+ * Only top-level scalar list entries in a form body change: header[0]=a
+ * becomes header=a. A property-string item's commas remain inside the item.
+ * A scalar comma list, an embedded NUL, or a GET/DELETE query is unchanged.
+ */
+import * as API from "@distilled.cloud/core/api";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+
+const repeatedFormKeys = (request: HttpClientRequest.HttpClientRequest) => {
+  if (
+    request.body._tag !== "Uint8Array" ||
+    request.body.contentType !== "application/x-www-form-urlencoded"
+  )
+    return request;
+  const fields = new URLSearchParams(
+    new TextDecoder().decode(request.body.body),
+  );
+  const repeated: [string, string][] = [];
+  for (const [key, value] of fields) {
+    repeated.push([key.replace(/^([^\[\]]+)\[\d+\]$/, "$1"), value]);
+  }
+  return HttpClientRequest.bodyUrlParams(request, repeated);
+};
+
+export const withPveFormArrays = (
+  base: Layer.Layer<API.Protocol>,
+): Layer.Layer<API.Protocol> =>
+  Layer.effect(
+    API.Protocol,
+    Effect.gen(function* () {
+      const protocol = yield* API.Protocol;
+      return API.Protocol.of({
+        ...protocol,
+        encode: (args) =>
+          protocol.encode(args).pipe(Effect.map(repeatedFormKeys)),
+      });
+    }),
+  ).pipe(Layer.provide(base));

package/src/protocol.ts

@@ -24,13 +24,15 @@
  * (a) **Async POST/PUT/DELETE answer 200 with a UPID and can fail later.**
  *     PVE hands back a bare task id string (`"UPID:node:...);"`) for any
  *     long-running action — a VM start, a backup, a storage scan — and the
- *     200 means "the task was QUEUED", not "the task succeeded". Handled
- *     with real code: `src/task.ts`'s `awaitTask`, which polls
- *     `GetNodeTaskStatus` (this package's own generated operation) until
- *     `exitstatus` is present, then fails with the typed
- *     `ProxmoxTaskFailed` unless it is EXACTLY `"OK"` — PVE also answers
- *     `"OK (warnings)"`, which is not a bare-prefix match on purpose (see
- *     that file).
+ *     200 means "the task was QUEUED", not "the task succeeded". A caller
+ *     must poll `GetNodeTaskStatus` (this package's own generated
+ *     operation) until `exitstatus` is present, then treat anything other
+ *     than EXACTLY `"OK"` as a failure — PVE also answers `"OK
+ *     (warnings)"`, so a bare-prefix match is wrong. This package ships
+ *     the typed `ProxmoxTaskFailed` for that comparison but not the poll
+ *     loop itself: polling is provider-side (P13 of the 2026-09-24
+ *     walk-down; no distilled precedent for a package-level poll helper —
+ *     see `errors.ts`'s `ProxmoxTaskFailed` doc for the removal note).
  *
  * (b) **Some PUTs answer 200 `{"data":null}` even when nothing changed.**
  *     PVE's update handlers commonly return `null` unconditionally on
@@ -79,6 +81,7 @@ import {
   type RestErrorEnvelope,
 } from "@distilled.cloud/core/protocol-rest";
 import { Credentials, type Config } from "./credentials.ts";
+import { withPveFormArrays } from "./protocol-form.ts";
 import {
   ParameterVerificationFailed,
   UnknownProxmoxError,
@@ -110,6 +113,24 @@ export type ProxmoxOpContext = Credentials | HttpClient.HttpClient;
 const errorEnvelope = (body: unknown): RestErrorEnvelope | undefined => {
   if (body === null || typeof body !== "object") return undefined;
   const b = body as Record<string, unknown>;
+  // PVE's backup read/delete missing-id exception is a 400 with the useful
+  // message in errors.id (Backup.pm:406,458 at pve-manager 9.2.11). Expose
+  // ONLY that exact sole-field detail to the operation's typed matcher.
+  // Multiple errors, other fields, and unrelated validation stay unchanged.
+  const errors = b.errors;
+  if (
+    (b.message === "Parameter verification failed." ||
+      b.message === "Parameter verification failed.\n") &&
+    errors !== null &&
+    typeof errors === "object" &&
+    !Array.isArray(errors) &&
+    Object.keys(errors).length === 1 &&
+    "id" in errors &&
+    typeof errors.id === "string" &&
+    /^No such job '[^']+'$/.test(errors.id)
+  ) {
+    return { message: errors.id };
+  }
   return { message: typeof b.message === "string" ? b.message : undefined };
 };
 
@@ -126,7 +147,7 @@ const PROXMOX_STATUS_MAP: Record<number, new (args: any) => unknown> = {
 };
 delete (PROXMOX_STATUS_MAP as Record<number, unknown>)[400];
 
-export const ProxmoxProtocol: Layer.Layer<API.Protocol> =
+export const ProxmoxProtocol: Layer.Layer<API.Protocol> = withPveFormArrays(
   makeRestProtocol<Config>({
     // Resolved on the CALLING fiber per request (the layer is memoized per
     // process); the Credentials service holds an effect, so a token rotated
@@ -201,4 +222,5 @@ export const ProxmoxProtocol: Layer.Layer<API.Protocol> =
       }
       return new UnknownProxmoxError({ status, message, body });
     },
-  });
+  }),
+);

package/src/services/access.ts

@@ -1,6 +1,7 @@
 // AUTO-GENERATED by scripts/generate.ts from .generated-specs (apidata.js, via scripts/apidoc.ts — see its header). Do not edit.
 import * as S from "@distilled.cloud/core/schema";
 import * as API from "@distilled.cloud/core/api";
+import * as C from "@distilled.cloud/core/category";
 import * as T from "../traits.ts";
 import {
   ProxmoxProtocol,
@@ -11,6 +12,24 @@ import * as Retry from "../retry.ts";
 
 export type { ProxmoxOpError, ProxmoxOpContext };
 
+/** The group does not exist. PVE answers this as HTTP 500, the same shape as UserNotFound. Traced to source, not paraphrased: `pve-access-control` (commit dff26b458651b4e1141ff0a41a296d2904b16228, package version 9.1.2) `src/PVE/API2/Group.pm:201`, inside `register_method({ name => 'read_group', path => '{groupid}', method => 'GET', description => "Get group configuration." })` — matching this operation's own doc string exactly: `die "group '$group' does not exist\n" if !$data;`. Corroborated by the kit's own prior wire evidence: `taslabs-net/homeflare-kit`'s `packages/alchemy/src/proxmox/group-wire.ts:80-81` ("MEASURED against the live cluster: `GET /access/groups/{missing}` answers a genuine 500"). */
+export class GroupNotFound
+  extends /*@__PURE__*/ T.applyErrorMatchers(
+    /*@__PURE__*/ S.TaggedError<GroupNotFound>()("GroupNotFound", {
+      message: S.String,
+    }).pipe(C.withBadRequestError),
+    [{ status: 500, message: { matches: "^group '[^']*' does not exist" } }],
+  ) {}
+
+/** The user does not exist. PVE answers this as HTTP 500 with a bare `{"message":"no such user ('<userid>')"}` — this shape states the honest status (404) while matching the wire's real one. Traced to source, not paraphrased: `pve-access-control` (git.proxmox.com/git/pve-access-control.git, commit dff26b458651b4e1141ff0a41a296d2904b16228, package version 9.1.2) `src/PVE/AccessControl.pm:678`, `sub check_user_exist`: `die "no such user ('$username')\n" if !$noerr;`. Reachability confirmed, not assumed: `src/PVE/API2/User.pm`'s `GET .../users/{userid}` handler (`description => "Get user configuration."`, matching this operation's own doc string exactly) calls `PVE::AccessControl::check_user_exist($usercfg, $username)` at line ~415 with no `$noerr` argument, so `!$noerr` is true and the die fires whenever `$username` is absent from `user.cfg`. Corroborated by the kit's own prior wire evidence: `taslabs-net/homeflare-kit`'s `packages/alchemy/src/proxmox/user.test.ts:46` fixture, `no such user ('${userid}')` at 500. */
+export class UserNotFound
+  extends /*@__PURE__*/ T.applyErrorMatchers(
+    /*@__PURE__*/ S.TaggedError<UserNotFound>()("UserNotFound", {
+      message: S.String,
+    }).pipe(C.withBadRequestError),
+    [{ status: 500, message: { matches: "^no such user \\(" } }],
+  ) {}
+
 export type CreateAccessDomainRequestMode = "ldap" | "ldaps" | "ldap+starttls";
 export const CreateAccessDomainRequestMode = S.String;
 
@@ -479,14 +498,9 @@ export const DeleteAccessTfaRequest = /*@__PURE__*/ S.suspend(() =>
   S.Struct({
     userid: S.String.pipe(T.Label()),
     id: S.String.pipe(T.Label()),
-    password: S.optional(S.String),
+    password: S.optional(S.String.pipe(T.Query())),
   }).pipe(
-    T.Http({
-      method: "DELETE",
-      uri: "/access/tfa/{userid}/{id}",
-      code: 200,
-      contentType: "form-urlencoded",
-    }),
+    T.Http({ method: "DELETE", uri: "/access/tfa/{userid}/{id}", code: 200 }),
   ),
 ).annotate({
   identifier: "DeleteAccessTfaRequest",
@@ -2256,7 +2270,7 @@ export const getAccessDomain: API.OperationMethod<
   retry: Retry.Retry,
 }));
 
-export type GetAccessGroupError = ProxmoxOpError;
+export type GetAccessGroupError = GroupNotFound | ProxmoxOpError;
 /** Get group configuration. */
 export const getAccessGroup: API.OperationMethod<
   GetAccessGroupRequest,
@@ -2266,7 +2280,7 @@ export const getAccessGroup: API.OperationMethod<
 > = /*@__PURE__*/ API.make(() => ({
   input: GetAccessGroupRequest,
   output: GetAccessGroupResponse,
-  errors: [],
+  errors: [GroupNotFound],
   protocol: ProxmoxProtocol,
   retry: Retry.Retry,
 }));
@@ -2346,7 +2360,7 @@ export const getAccessTicket: API.OperationMethod<
   retry: Retry.Retry,
 }));
 
-export type GetAccessUserError = ProxmoxOpError;
+export type GetAccessUserError = UserNotFound | ProxmoxOpError;
 /** Get user configuration. */
 export const getAccessUser: API.OperationMethod<
   GetAccessUserRequest,
@@ -2356,7 +2370,7 @@ export const getAccessUser: API.OperationMethod<
 > = /*@__PURE__*/ API.make(() => ({
   input: GetAccessUserRequest,
   output: GetAccessUserResponse,
-  errors: [],
+  errors: [UserNotFound],
   protocol: ProxmoxProtocol,
   retry: Retry.Retry,
 }));