@homeflare/alchemy 0.11.0 → 0.12.0

package/src/proxmox/provision-baseline.ts

@@ -0,0 +1,162 @@
+/**
+ * The provisioning baseline: the access every PVE cluster and node needs before a stack built on
+ * this package can manage it — one role, the users OpenBao mints tokens for, the group that fences
+ * the mint, and the grants that bind them. ONE description, read by both halves:
+ *   · provision-declare.ts turns it into `Proxmox.Role`/`Group`/`User`/`Acl` resources, so a stack
+ *     adopts the baseline and keeps it (drift is a plan, not a 403 weeks later);
+ *   · provision-bootstrap.ts turns it into the one-time root commands for a NEW cluster or node.
+ * The two cannot drift apart because neither holds a name or a privilege of its own.
+ *
+ * ⛔ THE PROVISION LANE CANNOT CREATE ITSELF. Every write here runs as a token OpenBao mints for the
+ *   provision user, and minting needs that user to exist, in the mint group, bound to this role.
+ *   So a new cluster is bootstrapped ONCE by root@pam with the generated commands, and the stack
+ *   then adopts what they made (docs/provision-baseline.md).
+ *
+ * ★ ONE PRIVILEGE LIST FOR EVERY FAMILY, NOT A ROLE PER RESOURCE. The list is what the families'
+ *   reconciles need, unioned — the set a hand-kept provision role reached one 403 at a time, each
+ *   step recorded where it was hit (pool.ts, sdn-vnet.ts, ha-rule.ts). It includes what the lane needs
+ *   to manage THIS baseline (`Sys.Modify` for the role, `Realm.AllocateUser`/`User.Modify` for the
+ *   users, `Group.Allocate`, `Permissions.Modify` for the grants), so declaring it can never narrow
+ *   the lane out of its own repair (role.ts: "A ROLE CAN LOCK ITS OWN PROVIDER OUT").
+ * ⚠️ NOT EVERY FAMILY: root@pam-only writes (device passthrough, bind mounts — lxc-judge.ts) and
+ *   privileges a family names as still missing (`VM.Replicate`, replication-job.ts) are outside it.
+ */
+
+/** The provision role's privileges, sorted — the exact set, never an addition to a live one. */
+export const PROVISION_PRIVILEGES: readonly string[] = Object.freeze([
+  'Datastore.Allocate',
+  'Datastore.AllocateSpace',
+  'Datastore.Audit',
+  'Group.Allocate',
+  'Mapping.Audit',
+  'Mapping.Modify',
+  'Permissions.Modify',
+  'Pool.Allocate',
+  'Pool.Audit',
+  'Realm.AllocateUser',
+  'SDN.Allocate',
+  'SDN.Audit',
+  'SDN.Use',
+  'Sys.Audit',
+  'Sys.Console',
+  'Sys.Modify',
+  'User.Modify',
+  'VM.Allocate',
+  'VM.Audit',
+  'VM.Backup',
+  'VM.Config.CPU',
+  'VM.Config.Disk',
+  'VM.Config.HWType',
+  'VM.Config.Memory',
+  'VM.Config.Network',
+  'VM.Config.Options',
+  'VM.PowerMgmt',
+]);
+
+/** The names a baseline uses. Every field has a generic default (`PROVISION_DEFAULTS`). */
+export interface ProvisionNames {
+  /** The role holding `PROVISION_PRIVILEGES` on `/`. */
+  readonly role?: string | undefined;
+  /** The user OpenBao's `provision` role mints tokens for, realm-qualified. */
+  readonly provisionUser?: string | undefined;
+  /** The group whose members OpenBao may mint for — the fence around the mint. */
+  readonly mintGroup?: string | undefined;
+  /** The user OpenBao's `read` role mints for, or `null` for a baseline with no read lane. */
+  readonly readUser?: string | null | undefined;
+  /** The role the read user holds on `/`. ⛔ It must already exist: a built-in, or one you declare. */
+  readonly readRole?: string | undefined;
+  /** The comment on the group and both users — how a person on the node learns what they are. */
+  readonly comment?: string | undefined;
+}
+
+/** Every name, resolved: what `PROVISION_DEFAULTS` holds and what a baseline is built from. */
+export type ResolvedProvisionNames = {
+  readonly [K in keyof ProvisionNames]-?: Exclude<ProvisionNames[K], undefined>;
+};
+
+/** ★ Generic, kit-prefixed names: nothing here is any one estate's. */
+export const PROVISION_DEFAULTS: ResolvedProvisionNames = Object.freeze({
+  comment:
+    'provision baseline from @homeflare/alchemy - OpenBao mints short-lived tokens for members',
+  mintGroup: 'hf-mint',
+  provisionUser: 'hf-provision@pve',
+  readRole: 'PVEAuditor',
+  readUser: 'hf-read@pve',
+  role: 'HfProvisioner',
+});
+
+/** Which credential lane a user or a grant belongs to — the OpenBao role that mints for it. */
+export type ProvisionLane = 'provision' | 'read';
+
+/** A baseline, resolved: exactly what the declaration holds and the bootstrap makes. */
+export interface ProvisionBaseline {
+  readonly role: { readonly roleid: string; readonly privs: readonly string[] };
+  readonly group: { readonly groupid: string; readonly comment: string };
+  readonly users: readonly {
+    readonly lane: ProvisionLane;
+    readonly userid: string;
+    readonly comment: string;
+    readonly groups: readonly string[];
+  }[];
+  /** Each binds one user to one role on `/`, with propagate — the only shape the lanes need. */
+  readonly grants: readonly {
+    readonly lane: ProvisionLane;
+    readonly userid: string;
+    readonly roleid: string;
+  }[];
+}
+
+/**
+ * ⛔ NAMES ARE CHECKED HERE, ONCE, FOR BOTH HALVES — and conservatively. The bootstrap pastes them
+ *   into a root shell, so a name that would need quoting is refused rather than quoted: PVE's own
+ *   ids (`pve-roleid`, `pve-groupid`, `pve-userid`) are narrower than what a shell tolerates.
+ */
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const USERID = /^[A-Za-z0-9][A-Za-z0-9._-]*@[A-Za-z][A-Za-z0-9._-]*$/;
+const COMMENT = /^[A-Za-z0-9 ._,()@/+-]*$/;
+
+const problems = (names: ResolvedProvisionNames): string[] => {
+  const found: string[] = [];
+  if (!ID.test(names.role)) found.push(`role \`${names.role}\` is not a PVE role id`);
+  if (!ID.test(names.mintGroup)) found.push(`mintGroup \`${names.mintGroup}\` is not a group id`);
+  if (!ID.test(names.readRole)) found.push(`readRole \`${names.readRole}\` is not a PVE role id`);
+  for (const [field, userid] of [
+    ['provisionUser', names.provisionUser],
+    ['readUser', names.readUser],
+  ] as const) {
+    if (userid !== null && !USERID.test(userid)) {
+      found.push(`${field} \`${userid}\` is not a realm-qualified user id (name@realm)`);
+    }
+  }
+  if (names.readUser === names.provisionUser) found.push('readUser and provisionUser are one user');
+  if (!COMMENT.test(names.comment))
+    found.push('comment holds a character the bootstrap will not quote');
+  return found;
+};
+
+/** Resolve `names` over the defaults and check them. Throws with every problem at once. */
+export const provisionBaseline = (names: ProvisionNames = {}): ProvisionBaseline => {
+  // ⚠️ An explicit `undefined` means "the default", not "blank": spread alone would keep it.
+  const given = Object.entries(names).filter(([, value]) => value !== undefined);
+  const resolved: ResolvedProvisionNames = {
+    ...PROVISION_DEFAULTS,
+    ...Object.fromEntries(given),
+  };
+  const found = problems(resolved);
+  if (found.length > 0) throw new Error(`provision baseline: ${found.join('; ')}`);
+  const lanes: [ProvisionLane, string, string][] = [
+    ['provision', resolved.provisionUser, resolved.role],
+  ];
+  if (resolved.readUser !== null) lanes.push(['read', resolved.readUser, resolved.readRole]);
+  return {
+    grants: lanes.map(([lane, userid, roleid]) => ({ lane, roleid, userid })),
+    group: { comment: resolved.comment, groupid: resolved.mintGroup },
+    role: { privs: PROVISION_PRIVILEGES, roleid: resolved.role },
+    users: lanes.map(([lane, userid]) => ({
+      comment: resolved.comment,
+      groups: [resolved.mintGroup],
+      lane,
+      userid,
+    })),
+  };
+};

package/src/proxmox/provision-bootstrap.test.ts

@@ -0,0 +1,132 @@
+/**
+ * The generated bootstrap, RUN: under `sh`, with real Perl, against provision-cli-fake.ts's
+ * `pvesh`/`pveum`. What these pin: a fresh cluster gets exactly the baseline in an order PVE accepts;
+ * a second run (or a node joining a cluster that has it) writes nothing; drift converges with only
+ * the writes it needs; a read role that is missing stops the script before any write; and the
+ * script never makes a token or sets a password.
+ */
+import { describe, expect, test } from 'bun:test';
+import { type CliState, freshCluster, runScript } from './provision-cli-fake.ts';
+import { PROVISION_DEFAULTS, PROVISION_PRIVILEGES } from './provision-baseline.ts';
+import { provisionBootstrap } from './provision-bootstrap.ts';
+
+const COMMENT = PROVISION_DEFAULTS.comment;
+const lane = (groups: string[]) => ({
+  comment: COMMENT,
+  email: '',
+  enable: 1,
+  expire: 0,
+  firstname: '',
+  groups,
+  lastname: '',
+});
+
+/** What a fresh cluster holds after the default script: the baseline, and nothing else. */
+const BOOTSTRAPPED: CliState = {
+  acl: [
+    { path: '/', propagate: 1, roleid: 'HfProvisioner', type: 'user', ugid: 'hf-provision@pve' },
+    { path: '/', propagate: 1, roleid: 'PVEAuditor', type: 'user', ugid: 'hf-read@pve' },
+  ],
+  groups: { 'hf-mint': { comment: COMMENT } },
+  roles: { ...freshCluster().roles, HfProvisioner: [...PROVISION_PRIVILEGES] },
+  users: { 'hf-provision@pve': lane(['hf-mint']), 'hf-read@pve': lane(['hf-mint']) },
+};
+
+describe('the script as text', () => {
+  const script = provisionBootstrap();
+
+  test('never makes a token or sets a password: its only writes are add/modify of the four', () => {
+    const calls = new Set(script.match(/pveum \w+ \w+/g));
+    expect([...calls].sort()).toEqual([
+      'pveum acl modify',
+      'pveum group add',
+      'pveum group modify',
+      'pveum role add',
+      'pveum role modify',
+      'pveum user add',
+      'pveum user modify',
+    ]);
+    expect(script).not.toMatch(/--password|passwd|user token/);
+    expect(script).toStartWith('#!/bin/sh\n');
+    expect(script).toContain('\nset -eu\n');
+  });
+
+  test('carries the one privilege list, sorted, as the role it adds', () => {
+    expect(script).toContain(`want='${PROVISION_PRIVILEGES.join(',')}'`);
+    expect(script).toContain('pveum role add HfProvisioner --privs "$want"');
+  });
+});
+
+describe('run against a cluster', () => {
+  test('a fresh cluster gets exactly the baseline, role and group before what needs them', async () => {
+    const run = await runScript(provisionBootstrap(), freshCluster());
+    expect(run.stderr).toBe('');
+    expect(run.code).toBe(0);
+    expect(run.writes.map((w) => w.split(' --')[0])).toEqual([
+      'pveum role add HfProvisioner',
+      'pveum group add hf-mint',
+      'pveum user add hf-provision@pve',
+      'pveum user add hf-read@pve',
+      'pveum acl modify /',
+      'pveum acl modify /',
+    ]);
+    expect(run.state).toEqual(BOOTSTRAPPED);
+  });
+
+  test('a second run, or a node joining a cluster that has it, writes nothing', async () => {
+    const run = await runScript(provisionBootstrap(), structuredClone(BOOTSTRAPPED));
+    expect(run.code).toBe(0);
+    expect(run.writes).toEqual([]);
+    expect(run.stdout.split('\n').filter((line) => line.endsWith(': ok'))).toHaveLength(6);
+  });
+
+  test('drift converges with only the writes it needs', async () => {
+    const drifted = structuredClone(BOOTSTRAPPED);
+    drifted.roles['HfProvisioner'] = [...PROVISION_PRIVILEGES.slice(1), 'VM.Console'];
+    drifted.groups['admins'] = { comment: '' };
+    drifted.users['hf-read@pve'] = { ...lane(['admins', 'hf-mint']), email: 'x@example.com' };
+    drifted.acl = drifted.acl.slice(0, 1);
+    const run = await runScript(provisionBootstrap(), drifted);
+    expect(run.code).toBe(0);
+    expect(run.writes.map((w) => w.split(' --')[0])).toEqual([
+      'pveum role modify HfProvisioner',
+      'pveum user modify hf-read@pve',
+      'pveum acl modify /',
+    ]);
+    expect(run.state).toEqual({ ...BOOTSTRAPPED, groups: drifted.groups });
+  });
+
+  test('a read role that does not exist stops the script before any write', async () => {
+    const run = await runScript(provisionBootstrap({ readRole: 'Auditor' }), freshCluster());
+    expect(run.code).toBe(1);
+    expect(run.stderr).toContain('role Auditor does not exist');
+    expect(run.writes).toEqual([]);
+  });
+
+  test('no read lane: one user, one grant, no read role needed', async () => {
+    const run = await runScript(provisionBootstrap({ readUser: null }), {
+      ...freshCluster(),
+      roles: {},
+    });
+    expect(run.code).toBe(0);
+    expect(Object.keys(run.state.users)).toEqual(['hf-provision@pve']);
+    expect(run.state.acl.map((g) => g.ugid)).toEqual(['hf-provision@pve']);
+  });
+
+  test("a site's own names flow through every step", async () => {
+    const names = {
+      mintGroup: 'mint',
+      provisionUser: 'provisioner@pve',
+      readUser: 'auditor@pve',
+      role: 'Provisioner',
+    };
+    const run = await runScript(provisionBootstrap(names), freshCluster());
+    expect(run.code).toBe(0);
+    expect(Object.keys(run.state.roles).sort()).toEqual(['PVEAuditor', 'Provisioner']);
+    expect(run.state.users['provisioner@pve']?.groups).toEqual(['mint']);
+    expect(run.state.acl.map((g) => `${g.ugid} ${g.roleid}`)).toEqual([
+      'provisioner@pve Provisioner',
+      'auditor@pve PVEAuditor',
+    ]);
+  });
+});

package/src/proxmox/provision-bootstrap.ts

@@ -0,0 +1,135 @@
+/**
+ * `provisionBootstrap` — the provisioning baseline (provision-baseline.ts) as the one-time root
+ * commands for a NEW cluster or node: a POSIX `sh` script, printed, never run from here.
+ *
+ *     bun -e "import { provisionBootstrap } from '@homeflare/alchemy/proxmox';
+ *             process.stdout.write(provisionBootstrap())" | ssh root@<node> sh
+ *
+ * ⛔ WHY IT EXISTS: THE PROVISION LANE CANNOT CREATE ITSELF. Every resource in this package runs as a
+ *   token OpenBao mints for the provision user, and a cluster without that user, its group and its
+ *   grant has nothing to mint for — the plan that would create them cannot authenticate. So root
+ *   makes them once, and the stack adopts and keeps them (provision-declare.ts). This is the only
+ *   hand step, and it is generated from the same baseline the stack declares.
+ * ⛔ NEVER A TOKEN, NEVER A PASSWORD. The users are created with neither: OpenBao mints short-lived
+ *   tokens for them later, and an `@pve` user with no password cannot log in to the UI. Nothing
+ *   secret is in the script, so it can be read, reviewed and pasted.
+ * ★ CHECK, THEN CHANGE — IDEMPOTENT BY CONSTRUCTION. Each object is read first (`pvesh get … json`,
+ *   parsed with Perl's core JSON::PP, which every PVE node has), compared with the baseline, and
+ *   written only when it differs, naming what it does. A second run prints `ok` for everything and
+ *   writes nothing. It also CONVERGES: a role with other privileges is set to exactly the baseline,
+ *   as the stack's `Proxmox.Role` would set it (role.ts: a declaration replaces the set).
+ * ★ ONE NODE PER CLUSTER. Users, groups, roles and ACLs live in `/etc/pve/user.cfg`, which pmxcfs
+ *   shares across the cluster: a node joining a cluster that has the baseline needs nothing, and a
+ *   run there is all `ok`. A new standalone node or a new cluster is where it creates.
+ * ⚠️ NAMES ARE NOT QUOTED INTO SAFETY, THEY ARE REFUSED INTO IT: provision-baseline.ts admits only
+ *   characters that need no quoting in `sh` or in a Perl `q{}`.
+ */
+import {
+  type ProvisionBaseline,
+  type ProvisionNames,
+  provisionBaseline,
+} from './provision-baseline.ts';
+
+const HEADER = `#!/bin/sh
+# Provisioning baseline bootstrap, generated by @homeflare/alchemy (provisionBootstrap).
+# Run ONCE, as root, on one node of a NEW cluster (or a new standalone node). Every step reads
+# first and writes only what differs; a second run changes nothing. No token, no password.
+set -eu
+[ "$(id -u)" -eq 0 ] || { echo 'bootstrap: run this as root' >&2; exit 1; }
+command -v pvesh >/dev/null 2>&1 || { echo 'bootstrap: no pvesh; run this on a PVE node' >&2; exit 1; }
+perl -MJSON::PP -e 1 || { echo 'bootstrap: perl cannot load JSON::PP' >&2; exit 1; }
+
+# get <api-path> <perl>: print <perl> evaluated over the object at <api-path> (as $d).
+# Fails, silently, when the object does not exist: the empty input is not JSON.
+get() {
+  pvesh get "$1" --output-format json 2>/dev/null | perl -MJSON::PP -0777 -ne "\\$d = decode_json(\\$_); $2" 2>/dev/null
+}
+`;
+
+/** A Perl string literal with no interpolation — `@pve` in a double-quoted one is an array. */
+const perlText = (text: string) => `q{${text}}`;
+
+/** The user fields `Proxmox.User` compares, as one line both sides can produce. */
+const USER_STATE =
+  'my $g = $d->{groups} // []; $g = [split /,/, $g] unless ref $g; ' +
+  'print join(";", "groups=" . join(",", sort @$g), "enable=" . (($d->{enable} // 1) ? 1 : 0), ' +
+  '"expire=" . ($d->{expire} // 0), "email=" . ($d->{email} // ""), ' +
+  '"firstname=" . ($d->{firstname} // ""), "lastname=" . ($d->{lastname} // ""), ' +
+  '"comment=" . ($d->{comment} // ""))';
+
+const roleStep = ({ role }: ProvisionBaseline): string => {
+  const privs = [...role.privs].sort().join(',');
+  return `
+# Role ${role.roleid}: exactly the provision privileges, on no path yet.
+want='${privs}'
+if have=$(get /access/roles/${role.roleid} 'print join(",", sort grep { /\\./ } keys %$d)'); then
+  if [ "$have" = "$want" ]; then echo 'role ${role.roleid}: ok'
+  else echo 'role ${role.roleid}: setting the baseline privileges'; pveum role modify ${role.roleid} --privs "$want"; fi
+else
+  echo 'role ${role.roleid}: adding'; pveum role add ${role.roleid} --privs "$want"
+fi
+`;
+};
+
+const groupStep = ({ group }: ProvisionBaseline): string => `
+# Group ${group.groupid}: OpenBao may mint only for its members.
+if have=$(get /access/groups/${group.groupid} 'print $d->{comment} // ""'); then
+  if [ "$have" = '${group.comment}' ]; then echo 'group ${group.groupid}: ok'
+  else echo 'group ${group.groupid}: setting the comment'; pveum group modify ${group.groupid} --comment '${group.comment}'; fi
+else
+  echo 'group ${group.groupid}: adding'; pveum group add ${group.groupid} --comment '${group.comment}'
+fi
+`;
+
+const userStep = (user: ProvisionBaseline['users'][number]): string => {
+  const groups = [...user.groups].sort().join(',');
+  const want = `groups=${groups};enable=1;expire=0;email=;firstname=;lastname=;comment=${user.comment}`;
+  const fields = `--groups ${groups} --comment '${user.comment}'`;
+  return `
+# User ${user.userid} (the ${user.lane} lane): in ${groups}, enabled, no password.
+if have=$(get /access/users/${user.userid} '${USER_STATE}'); then
+  if [ "$have" = '${want}' ]; then echo 'user ${user.userid}: ok'
+  else echo 'user ${user.userid}: setting groups, comment and account fields'
+    pveum user modify ${user.userid} ${fields} --enable 1 --expire 0 --email '' --firstname '' --lastname ''; fi
+else
+  echo 'user ${user.userid}: adding'; pveum user add ${user.userid} ${fields}
+fi
+`;
+};
+
+const grantStep = (grant: ProvisionBaseline['grants'][number]): string => {
+  const match =
+    `print scalar grep { $_->{path} eq "/" && $_->{type} eq "user" && ` +
+    `$_->{ugid} eq ${perlText(grant.userid)} && $_->{roleid} eq ${perlText(grant.roleid)} && ` +
+    `($_->{propagate} // 1) } @$d`;
+  return `
+# Grant: ${grant.userid} holds ${grant.roleid} on /, propagated (the ${grant.lane} lane).
+if [ "$(get /access/acl '${match}')" = 1 ]; then echo 'grant ${grant.userid} ${grant.roleid} /: ok'
+else echo 'grant ${grant.userid} ${grant.roleid} /: adding'; pveum acl modify / --users ${grant.userid} --roles ${grant.roleid} --propagate 1; fi
+`;
+};
+
+/** A role the baseline binds but does not own — the read lane's — must already exist. */
+const requireRole = (roleid: string): string => `
+get /access/roles/${roleid} 'print 1' >/dev/null || { echo 'bootstrap: role ${roleid} does not exist; create it, or name another readRole' >&2; exit 1; }
+`;
+
+/**
+ * The script for `names` (defaults: `PROVISION_DEFAULTS`). Pure: it reads nothing and runs nothing.
+ * Throws, like `provisionBaseline`, on a name the baseline refuses.
+ */
+export const provisionBootstrap = (names: ProvisionNames = {}): string => {
+  const baseline = provisionBaseline(names);
+  const borrowed = baseline.grants
+    .map((grant) => grant.roleid)
+    .filter((roleid) => roleid !== baseline.role.roleid);
+  return [
+    HEADER,
+    ...[...new Set(borrowed)].map(requireRole),
+    roleStep(baseline),
+    groupStep(baseline),
+    ...baseline.users.map(userStep),
+    ...baseline.grants.map(grantStep),
+    `\necho 'provision baseline: done. Next: point the OpenBao proxmox mount at these users, then deploy the stack that declares this baseline with --adopt.'\n`,
+  ].join('');
+};

package/src/proxmox/provision-cli-fake.ts

@@ -0,0 +1,217 @@
+/**
+ * A fake `pvesh` / `pveum` / `id` for the bootstrap tests: the generated script runs for real, under
+ * `sh`, with real Perl parsing the JSON, against an access config held in one JSON file — so what is
+ * tested is the script a person pipes to a node, not a model of it.
+ *
+ * ⛔ TEST-ONLY. No provider imports this file. Run as a program (`import.meta.main`), it IS the fake
+ *   CLI; imported, it is the harness that writes the wrappers and runs a script against them.
+ * ★ IT REFUSES WHAT PVE REFUSES WHERE ORDER MATTERS: adding an object that exists, modifying one
+ *   that does not, a user in a group that does not exist, a grant of a role that does not exist.
+ *   A script that runs its steps in the wrong order fails here as it would on a node.
+ * ★ READS ANSWER IN THE ITEM SHAPES access/*.ts DOCUMENT: a role is a privilege map, a user's
+ *   groups an array, empty strings omitted. `apiView` is also what the engine test's fake PVE
+ *   serves, so the bootstrap's result and the declaration are compared on one picture.
+ */
+import { appendFileSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export type CliUser = {
+  comment: string;
+  email: string;
+  enable: number;
+  expire: number;
+  firstname: string;
+  lastname: string;
+  groups: string[];
+};
+export type CliGrant = {
+  path: string;
+  type: string;
+  ugid: string;
+  roleid: string;
+  propagate: number;
+};
+export type CliState = {
+  roles: Record<string, string[]>;
+  groups: Record<string, { comment: string }>;
+  users: Record<string, CliUser>;
+  acl: CliGrant[];
+};
+
+/** A cluster as PVE installs it: the built-in auditor role, and nothing of the baseline. */
+export const freshCluster = (): CliState => ({
+  acl: [],
+  groups: {},
+  roles: {
+    PVEAuditor: [
+      'Datastore.Audit',
+      'Mapping.Audit',
+      'Pool.Audit',
+      'SDN.Audit',
+      'Sys.Audit',
+      'VM.Audit',
+    ],
+  },
+  users: {},
+});
+
+const text = (key: string, value: string) => (value === '' ? {} : { [key]: value });
+
+/** Every item GET the scripts and the providers make, keyed `access/…` without a leading slash. */
+export const apiView = (state: CliState): Record<string, unknown> => {
+  const view: Record<string, unknown> = { 'access/acl': state.acl };
+  for (const [id, privs] of Object.entries(state.roles)) {
+    view[`access/roles/${id}`] = Object.fromEntries(privs.map((priv) => [priv, 1]));
+  }
+  for (const [id, group] of Object.entries(state.groups)) {
+    const members = Object.keys(state.users).filter((u) => state.users[u]?.groups.includes(id));
+    view[`access/groups/${id}`] = { ...text('comment', group.comment), members };
+  }
+  for (const [id, user] of Object.entries(state.users)) {
+    view[`access/users/${id}`] = {
+      ...text('comment', user.comment),
+      ...text('email', user.email),
+      ...text('firstname', user.firstname),
+      ...text('lastname', user.lastname),
+      enable: user.enable,
+      expire: user.expire,
+      groups: user.groups,
+      tokens: {},
+    };
+  }
+  return view;
+};
+
+const flags = (args: string[]) => {
+  const out: Record<string, string> = {};
+  for (let i = 0; i < args.length; i += 2)
+    out[(args[i] ?? '').replace(/^--/, '')] = args[i + 1] ?? '';
+  return out;
+};
+
+/** One pveum call against `state`; returns the refusal PVE would print, or undefined. */
+const pveum = (state: CliState, [kind, verb, id = '', ...rest]: string[]): string | undefined => {
+  const f = flags(rest);
+  const list = (csv: string | undefined) => (csv ?? '').split(',').filter((s) => s !== '');
+  if (kind === 'role') {
+    if ((verb === 'add') === id in state.roles) return `role '${id}': wrong state for ${verb}`;
+    state.roles[id] = list(f['privs']);
+  } else if (kind === 'group') {
+    if ((verb === 'add') === id in state.groups) return `group '${id}': wrong state for ${verb}`;
+    state.groups[id] = { comment: f['comment'] ?? '' };
+  } else if (kind === 'user') {
+    const had = state.users[id];
+    if ((verb === 'add') === (had !== undefined)) return `user '${id}': wrong state for ${verb}`;
+    const groups = f['groups'] === undefined ? (had?.groups ?? []) : list(f['groups']);
+    const missing = groups.find((g) => !(g in state.groups));
+    if (missing !== undefined) return `no such group '${missing}'`;
+    const base: CliUser = had ?? {
+      comment: '',
+      email: '',
+      enable: 1,
+      expire: 0,
+      firstname: '',
+      lastname: '',
+      groups: [],
+    };
+    state.users[id] = {
+      comment: f['comment'] ?? base.comment,
+      email: f['email'] ?? base.email,
+      enable: f['enable'] === undefined ? base.enable : Number(f['enable']),
+      expire: f['expire'] === undefined ? base.expire : Number(f['expire']),
+      firstname: f['firstname'] ?? base.firstname,
+      groups,
+      lastname: f['lastname'] ?? base.lastname,
+    };
+  } else if (kind === 'acl' && verb === 'modify') {
+    const roleid = f['roles'] ?? '';
+    if (!(roleid in state.roles)) return `role '${roleid}' does not exist`;
+    const grant = {
+      path: id,
+      propagate: Number(f['propagate'] ?? 1),
+      roleid,
+      type: 'user',
+      ugid: f['users'] ?? '',
+    };
+    state.acl = state.acl.filter(
+      (g) => !(g.path === id && g.ugid === grant.ugid && g.roleid === roleid),
+    );
+    state.acl.push(grant);
+  } else return `unknown pveum call: ${kind} ${verb}`;
+  return undefined;
+};
+
+/** The fake CLI's entry point: `<tool> <args…>`, with FAKE_PVE_STATE and FAKE_PVE_LOG set. */
+const runCli = ([tool, ...args]: string[]): number => {
+  if (tool === 'id') {
+    process.stdout.write('0\n');
+    return 0;
+  }
+  const file = process.env['FAKE_PVE_STATE'] ?? '';
+  const state = JSON.parse(readFileSync(file, 'utf8')) as CliState;
+  if (tool === 'pvesh') {
+    const found = apiView(state)[(args[1] ?? '').replace(/^\//, '')];
+    if (found === undefined) {
+      process.stderr.write(`no such object ${args[1] ?? ''}\n`);
+      return 2;
+    }
+    process.stdout.write(JSON.stringify(found));
+    return 0;
+  }
+  appendFileSync(process.env['FAKE_PVE_LOG'] ?? '', `pveum ${args.join(' ')}\n`);
+  const refused = pveum(state, args);
+  if (refused !== undefined) {
+    process.stderr.write(`${refused}\n`);
+    return 255;
+  }
+  writeFileSync(file, JSON.stringify(state));
+  return 0;
+};
+
+if (import.meta.main) process.exit(runCli(process.argv.slice(2)));
+
+export type ScriptRun = {
+  code: number;
+  stdout: string;
+  stderr: string;
+  writes: string[];
+  state: CliState;
+};
+
+/** Run `script` under `sh` against `state`, with the fakes first on PATH. */
+export const runScript = async (script: string, state: CliState): Promise<ScriptRun> => {
+  const dir = mkdtempSync(join(tmpdir(), 'hf-bootstrap-'));
+  for (const tool of ['id', 'pvesh', 'pveum']) {
+    const wrapper = `#!/bin/sh\nexec '${process.execPath}' '${import.meta.path}' ${tool} "$@"\n`;
+    writeFileSync(join(dir, tool), wrapper, { mode: 0o755 });
+  }
+  const stateFile = join(dir, 'state.json');
+  const log = join(dir, 'pveum.log');
+  writeFileSync(stateFile, JSON.stringify(state));
+  writeFileSync(log, '');
+  try {
+    const child = Bun.spawn(['sh', '-s'], {
+      env: {
+        FAKE_PVE_LOG: log,
+        FAKE_PVE_STATE: stateFile,
+        PATH: `${dir}:${process.env['PATH'] ?? ''}`,
+      },
+      stderr: 'pipe',
+      stdin: new TextEncoder().encode(script),
+      stdout: 'pipe',
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    const writes = readFileSync(log, 'utf8')
+      .split('\n')
+      .filter((line) => line !== '');
+    const after = JSON.parse(readFileSync(stateFile, 'utf8')) as CliState;
+    return { code, state: after, stderr, stdout, writes };
+  } finally {
+    rmSync(dir, { force: true, recursive: true });
+  }
+};