@astrofoundry/pi-astro 0.19.3 → 0.20.0

package/specialists/proxmox/run.ts

@@ -0,0 +1,330 @@
+import { join } from "node:path";
+import { readConfig } from "../lib/config.ts";
+import { ServiceError, UsageError } from "../lib/errors.ts";
+import { main } from "../lib/main.ts";
+import { printJson, printRaw } from "../lib/output.ts";
+import { specialistsHome } from "../lib/paths.ts";
+import { pinnedRequest } from "../lib/pinned.ts";
+import { redactSecrets } from "../lib/sanitize.ts";
+import { readSecret, secretPath } from "../lib/secrets.ts";
+import { sshFixed } from "../lib/ssh.ts";
+
+const SERVICE = "proxmox";
+
+interface ProxmoxConfig extends Record<string, string> {
+    /** e.g. https://10.0.10.37:8006 */
+    apiUrl: string;
+    /** SHA-256 fingerprint of the pveproxy certificate, colon-separated uppercase hex. */
+    certSha256: string;
+    node: string;
+    pulsarHost: string;
+    pulsarUser: string;
+}
+
+const SHAPE = { apiUrl: "string", certSha256: "string", node: "string", pulsarHost: "string", pulsarUser: "string" } as const;
+
+const TIMEOUT_MS = 30_000;
+const TASK_POLL_MS = 2_000;
+const VMID = /^\d{3,9}$/;
+const SNAPNAME = /^[A-Za-z][A-Za-z0-9_-]{0,39}$/;
+const API_PATH = /^\/[A-Za-z0-9_\-/.?=&%]{1,300}$/;
+
+/** Guest power actions; all but start need --confirm. */
+export const POWER_ACTIONS = ["start", "stop", "shutdown", "reboot"] as const;
+type PowerAction = (typeof POWER_ACTIONS)[number];
+
+/** Config keys `set` may change, per guest type; the role grants no disk or allocation privilege. */
+export const SET_KEYS: Readonly<Record<"qemu" | "lxc", readonly string[]>> = {
+    qemu: ["cores", "sockets", "memory", "balloon", "onboot", "startup", "description", "tags", "protection"],
+    lxc: ["cores", "memory", "swap", "onboot", "startup", "description", "tags", "protection"],
+};
+const NET_KEY = /^net\d{1,2}$/;
+
+/** Fixed remote commands on Pulsar; the forced command accepts exactly these names. */
+export const HOST_COMMANDS: Readonly<Record<string, { args: number; help: string }>> = {
+    "host-status": { args: 0, help: "pveversion, uptime, load, memory, root disk, temperatures" },
+    "host-journal": { args: 1, help: "host-journal <since>        warnings and errors of the host journal" },
+    updates: { args: 0, help: "upgradable packages on the host" },
+    "guest-exec": { args: 2, help: "guest-exec <vmid> <status|journal|df|updates>   fixed read inside a guest (pct exec or qm guest exec)" },
+};
+export const GUEST_EXEC = ["status", "journal", "df", "updates"];
+const SINCE = /^[A-Za-z0-9 :\-+]{1,40}$/;
+
+const HELP = `proxmox specialist (Proxmox VE on Pulsar)
+
+  guests                              every VM and container: vmid, name, type, status, resources (JSON)
+  guest <vmid>                        current status and configuration of one guest (JSON)
+  get <path>                          any GET under /api2/json, e.g. /nodes/pulsar/status, /cluster/resources?type=storage
+  tasks [n]                           last n tasks on the node (default 20)
+  task <upid>                         status and log of one task
+  ${POWER_ACTIONS.join("|")} <vmid> [--confirm]   power action, waits for the task; --confirm needed except for start
+  snapshots <vmid>                    snapshot list
+  snapshot-create <vmid> <name> [description]
+  snapshot-delete <vmid> <name> --confirm
+  snapshot-rollback <vmid> <name> --confirm
+  set <vmid> key=value...             VM: ${SET_KEYS.qemu.join(", ")}, netN; CT: ${SET_KEYS.lxc.join(", ")}, netN
+${Object.entries(HOST_COMMANDS)
+    .map(([name, c]) => `  ${name.padEnd(35)} ${c.help}`)
+    .join("\n")}
+
+Not available: create, clone, destroy, disk changes, host power or configuration. Those are operator tasks.`;
+
+interface PveEnvelope {
+    data?: unknown;
+    errors?: Record<string, string>;
+    message?: string;
+}
+
+interface GuestResource {
+    vmid: number;
+    name?: string;
+    type: "qemu" | "lxc";
+    node: string;
+    status: string;
+    maxmem?: number;
+    mem?: number;
+    maxcpu?: number;
+    cpu?: number;
+    maxdisk?: number;
+    uptime?: number;
+    tags?: string;
+}
+
+async function api(config: ProxmoxConfig, method: string, path: string, form?: Record<string, string>): Promise<unknown> {
+    const tokenId = readSecret(SERVICE, "PVE_TOKEN_ID");
+    const secret = readSecret(SERVICE, "PVE_TOKEN_SECRET");
+    const body = form === undefined ? undefined : new URLSearchParams(form).toString();
+    const response = await pinnedRequest(new URL(`/api2/json${path}`, config.apiUrl), {
+        method,
+        headers: {
+            Authorization: `PVEAPIToken=${tokenId}=${secret}`,
+            Accept: "application/json",
+            ...(body === undefined ? {} : { "Content-Type": "application/x-www-form-urlencoded", "Content-Length": String(Buffer.byteLength(body)) }),
+        },
+        body,
+        expectedFingerprint: config.certSha256,
+        timeoutMs: TIMEOUT_MS,
+    });
+    let envelope: PveEnvelope = {};
+    try {
+        envelope = JSON.parse(response.body) as PveEnvelope;
+    } catch {
+        /* error bodies can be plain text */
+    }
+    if (response.status < 200 || response.status >= 300) {
+        const detail = envelope.errors ? Object.entries(envelope.errors).map(([k, v]) => `${k}: ${v}`).join("; ") : envelope.message ?? response.body.trim();
+        throw new ServiceError(`Proxmox ${method} ${path} answered ${response.status}${detail ? `: ${detail}` : ""}`);
+    }
+    return envelope.data;
+}
+
+export function parseVmid(value: string | undefined): number {
+    if (value === undefined || !VMID.test(value)) throw new UsageError("vmid must be a number from 100 upwards");
+    return Number(value);
+}
+
+export function validateApiPath(path: string | undefined): string {
+    if (path === undefined || !API_PATH.test(path) || path.includes("..")) throw new UsageError("path must start with / and contain no spaces");
+    return path;
+}
+
+export function parseSetPairs(type: "qemu" | "lxc", pairs: string[]): Record<string, string> {
+    if (pairs.length === 0) throw new UsageError("set <vmid> key=value...");
+    const form: Record<string, string> = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0) throw new UsageError(`expected key=value, got ${pair}`);
+        const key = pair.slice(0, eq);
+        if (!SET_KEYS[type].includes(key) && !NET_KEY.test(key)) throw new UsageError(`${key} is not a key this specialist may set on a ${type} guest`);
+        form[key] = pair.slice(eq + 1);
+    }
+    return form;
+}
+
+export function needsConfirm(args: string[]): string[] {
+    const index = args.indexOf("--confirm");
+    if (index === -1) throw new UsageError(`${args[0]} interrupts a guest; add --confirm when the task asks for it explicitly`);
+    return args.filter((_, i) => i !== index);
+}
+
+async function guestResource(config: ProxmoxConfig, vmid: number): Promise<GuestResource> {
+    const resources = (await api(config, "GET", "/cluster/resources?type=vm")) as GuestResource[];
+    const guest = resources.find((r) => r.vmid === vmid);
+    if (!guest) throw new UsageError(`no guest with vmid ${vmid}`);
+    return guest;
+}
+
+function guestPath(guest: GuestResource): string {
+    return `/nodes/${guest.node}/${guest.type}/${guest.vmid}`;
+}
+
+interface TaskStatus {
+    status: string;
+    exitstatus?: string;
+    type?: string;
+    starttime?: number;
+    endtime?: number;
+}
+
+async function waitTask(config: ProxmoxConfig, upid: string, timeoutMs: number): Promise<TaskStatus> {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const status = (await api(config, "GET", `/nodes/${config.node}/tasks/${encodeURIComponent(upid)}/status`)) as TaskStatus;
+        if (status.status === "stopped") return status;
+        if (Date.now() > deadline) throw new ServiceError(`task ${upid} still running after ${timeoutMs} ms`);
+        await new Promise((resolve) => setTimeout(resolve, TASK_POLL_MS));
+    }
+}
+
+async function runTask(config: ProxmoxConfig, method: string, path: string, form: Record<string, string> | undefined, label: string): Promise<number> {
+    const upid = (await api(config, method, path, form)) as string;
+    const status = await waitTask(config, upid, 300_000);
+    printJson({ action: label, upid, exitstatus: status.exitstatus, endtime: status.endtime });
+    if (status.exitstatus !== "OK") throw new ServiceError(`${label} failed: ${status.exitstatus ?? "unknown"}`);
+    return 0;
+}
+
+async function apiCommand(config: ProxmoxConfig, args: string[]): Promise<number> {
+    const [name, ...rest] = args;
+    switch (name) {
+        case "guests": {
+            const resources = (await api(config, "GET", "/cluster/resources?type=vm")) as GuestResource[];
+            printJson(
+                resources
+                    .sort((a, b) => a.vmid - b.vmid)
+                    .map(({ vmid, name: guestName, type, status, node, maxmem, mem, maxcpu, cpu, maxdisk, uptime, tags }) => ({
+                        vmid,
+                        name: guestName,
+                        type,
+                        status,
+                        node,
+                        maxmem,
+                        mem,
+                        maxcpu,
+                        cpu,
+                        maxdisk,
+                        uptime,
+                        tags,
+                    })),
+            );
+            return 0;
+        }
+        case "guest": {
+            const guest = await guestResource(config, parseVmid(rest[0]));
+            const base = guestPath(guest);
+            const [status, guestConfig] = await Promise.all([api(config, "GET", `${base}/status/current`), api(config, "GET", `${base}/config`)]);
+            printJson({ guest, status, config: redactSecrets(guestConfig) });
+            return 0;
+        }
+        case "get":
+            if (rest.length !== 1) throw new UsageError("get <path>");
+            printJson(redactSecrets(await api(config, "GET", validateApiPath(rest[0]))));
+            return 0;
+        case "tasks": {
+            const n = rest[0] === undefined ? 20 : Number(rest[0]);
+            if (!Number.isInteger(n) || n < 1 || n > 200) throw new UsageError("tasks [n]: n must be 1..200");
+            printJson(await api(config, "GET", `/nodes/${config.node}/tasks?limit=${n}`));
+            return 0;
+        }
+        case "task": {
+            if (rest.length !== 1 || !/^UPID:[A-Za-z0-9:_.@-]+$/.test(rest[0])) throw new UsageError("task <upid>");
+            const upid = encodeURIComponent(rest[0]);
+            const [status, log] = await Promise.all([
+                api(config, "GET", `/nodes/${config.node}/tasks/${upid}/status`),
+                api(config, "GET", `/nodes/${config.node}/tasks/${upid}/log?limit=200`),
+            ]);
+            printJson({ status, log });
+            return 0;
+        }
+        case "start":
+        case "stop":
+        case "shutdown":
+        case "reboot": {
+            const action = name as PowerAction;
+            const positional = action === "start" ? rest : needsConfirm(args).slice(1);
+            if (positional.length !== 1) throw new UsageError(`${action} <vmid>${action === "start" ? "" : " --confirm"}`);
+            const guest = await guestResource(config, parseVmid(positional[0]));
+            return runTask(config, "POST", `${guestPath(guest)}/status/${action}`, {}, `${action} ${guest.vmid}`);
+        }
+        case "snapshots": {
+            const guest = await guestResource(config, parseVmid(rest[0]));
+            printJson(await api(config, "GET", `${guestPath(guest)}/snapshot`));
+            return 0;
+        }
+        case "snapshot-create": {
+            if (rest.length < 2 || rest.length > 3) throw new UsageError("snapshot-create <vmid> <name> [description]");
+            if (!SNAPNAME.test(rest[1])) throw new UsageError("snapshot name: letter first, then letters, digits, dash, underscore");
+            const guest = await guestResource(config, parseVmid(rest[0]));
+            const form: Record<string, string> = { snapname: rest[1], ...(rest[2] === undefined ? {} : { description: rest[2] }) };
+            return runTask(config, "POST", `${guestPath(guest)}/snapshot`, form, `snapshot-create ${guest.vmid} ${rest[1]}`);
+        }
+        case "snapshot-delete":
+        case "snapshot-rollback": {
+            const positional = needsConfirm(args).slice(1);
+            if (positional.length !== 2 || !SNAPNAME.test(positional[1])) throw new UsageError(`${name} <vmid> <name> --confirm`);
+            const guest = await guestResource(config, parseVmid(positional[0]));
+            const snapshotPath = `${guestPath(guest)}/snapshot/${positional[1]}`;
+            return name === "snapshot-delete"
+                ? runTask(config, "DELETE", snapshotPath, undefined, `snapshot-delete ${guest.vmid} ${positional[1]}`)
+                : runTask(config, "POST", `${snapshotPath}/rollback`, {}, `snapshot-rollback ${guest.vmid} ${positional[1]}`);
+        }
+        case "set": {
+            const guest = await guestResource(config, parseVmid(rest[0]));
+            const form = parseSetPairs(guest.type, rest.slice(1));
+            await api(config, "PUT", `${guestPath(guest)}/config`, form);
+            printJson({ vmid: guest.vmid, set: form, config: redactSecrets(await api(config, "GET", `${guestPath(guest)}/config`)) });
+            return 0;
+        }
+        default:
+            throw new UsageError(`unknown command: ${name ?? "(none)"}\n${HELP}`);
+    }
+}
+
+export function buildHostRemote(args: string[]): string {
+    const [name, ...rest] = args;
+    const spec = name === undefined ? undefined : HOST_COMMANDS[name];
+    if (!spec) throw new UsageError(`unknown host command: ${name ?? "(none)"}`);
+    if (rest.length !== spec.args) throw new UsageError(`${name} takes ${spec.args} argument(s)`);
+    if (name === "host-journal" && !SINCE.test(rest[0])) throw new UsageError("since: letters, digits, spaces, colon, plus, minus only");
+    if (name === "guest-exec") {
+        parseVmid(rest[0]);
+        if (!GUEST_EXEC.includes(rest[1])) throw new UsageError(`guest-exec action must be one of ${GUEST_EXEC.join(", ")}`);
+    }
+    return [name, ...rest].join(" ");
+}
+
+async function host(config: ProxmoxConfig, args: string[]): Promise<number> {
+    const remote = buildHostRemote(args);
+    const result = await sshFixed(
+        {
+            host: config.pulsarHost,
+            user: config.pulsarUser,
+            keyFile: secretPath(SERVICE, "SSH_KEY_PULSAR"),
+            knownHostsFile: join(specialistsHome(), "config", "known_hosts"),
+        },
+        remote,
+        120_000,
+    );
+    if (result.stdout.length > 0) printRaw(result.stdout);
+    if (result.code !== 0) throw new ServiceError(result.stderr.trim() || `${args[0]} exited ${result.code}`);
+    return 0;
+}
+
+export async function command(args: string[]): Promise<number> {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "help") {
+        printRaw(HELP);
+        return 0;
+    }
+    const config = readConfig<ProxmoxConfig>(SERVICE, SHAPE);
+    if (args[0] === "fingerprint") {
+        const probe = await pinnedRequest(new URL("/", config.apiUrl), { method: "GET", headers: {}, expectedFingerprint: null, timeoutMs: TIMEOUT_MS });
+        printJson({ host: new URL(config.apiUrl).host, fingerprint256: probe.fingerprint });
+        return 0;
+    }
+    if (args[0] in HOST_COMMANDS) return host(config, args);
+    return apiCommand(config, args);
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+    await main(SERVICE, command);
+}

package/specialists/security/run.ts

@@ -92,7 +92,7 @@ interface CrowdsecAlert {
     scenario?: string;
     events_count?: number;
     source?: { ip?: string; range?: string; as_number?: string; as_name?: string; cn?: string };
-    decisions?: { type?: string; duration?: string; value?: string }[];
+    decisions?: CrowdsecDecision[];
 }
 
 interface CompactAlert {
@@ -188,17 +188,32 @@ interface CrowdsecDecision {
     origin?: string;
 }
 
-/** Keeps the fields an operator needs from `cscli decisions list -o json`. */
-export function compactDecisions(text: string): { count: number; decisions: CrowdsecDecision[] } {
-    const decisions = parseJsonArray<CrowdsecDecision>(text, "decisions").map(({ id, value, scope, type, duration, scenario, origin }) => ({
-        id,
-        value,
-        scope,
-        type,
-        duration,
-        scenario,
-        origin,
-    }));
+interface CompactDecision extends CrowdsecDecision {
+    alertId?: number;
+    country?: string;
+}
+
+/**
+ * `cscli decisions list -o json` returns alerts, each with its active decisions
+ * (the table's ALERT ID, COUNTRY, and AS columns are alert fields). Flattens to one row per decision.
+ */
+export function compactDecisions(text: string): { count: number; decisions: CompactDecision[] } {
+    const decisions: CompactDecision[] = [];
+    for (const alert of parseJsonArray<CrowdsecAlert & { decisions?: CrowdsecDecision[] }>(text, "decisions")) {
+        for (const d of alert.decisions ?? []) {
+            decisions.push({
+                id: d.id,
+                value: d.value,
+                scope: d.scope,
+                type: d.type,
+                duration: d.duration,
+                scenario: d.scenario ?? alert.scenario,
+                origin: d.origin,
+                alertId: alert.id,
+                country: alert.source?.cn,
+            });
+        }
+    }
     return { count: decisions.length, decisions };
 }
 

package/specialists/wrappers.test.ts

@@ -3,12 +3,15 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { refusedPrefix, command as arcaneCommand } from "./arcane/run.ts";
+import { buildBackupRemote, command as backupCommand } from "./backup/run.ts";
 import { parseParams, parseRecordFilters, technitiumRequest, command as dnsCommand } from "./dns/run.ts";
 import { buildVpsRemote, command as edgeCommand } from "./edge/run.ts";
 import { API_PREFIXES, buildDmzRemote, validateApiPath, command as identityCommand } from "./identity/run.ts";
+import { buildInferenceRemote, compactReleases, command as inferenceCommand } from "./inference/run.ts";
 import { UsageError } from "./lib/errors.ts";
 import { safeRepoPath, safeWritePath } from "./lib/repo.ts";
 import { buildPulsarRemote, parseQuery, unifiPath, command as networkCommand } from "./network/run.ts";
+import { buildHostRemote, needsConfirm, parseSetPairs, parseVmid, validateApiPath as validatePvePath, command as proxmoxCommand } from "./proxmox/run.ts";
 import { buildObsRemote, compactDecisions, summariseAlerts, summariseWazuh, command as securityCommand } from "./security/run.ts";
 
 describe("arcane wrapper", () => {
@@ -244,9 +247,18 @@ describe("security wrapper", () => {
         expect(summary.latest[0]).toMatchObject({ id: 3, ip: "203.0.113.9", decisions: ["ban 4h"], country: "US" });
         expect(summariseAlerts(text, 7, "45.79.207.181").latest.map((a) => a.id)).toEqual([2, 1]);
         expect(summariseAlerts("null", 7)).toMatchObject({ count: 0, uniqueIps: 0 });
-        expect(compactDecisions(JSON.stringify([{ id: 9, value: "203.0.113.9", scope: "Ip", type: "ban", duration: "3h59m", scenario: "x", origin: "crowdsec", extra: 1 }]))).toEqual({
+        const decisionsText = JSON.stringify([
+            {
+                id: 364,
+                scenario: "37pla/frontdoor-sni-scanning",
+                source: { ip: "203.0.113.9", cn: "US" },
+                decisions: [{ id: 9, value: "203.0.113.9", scope: "Ip", type: "ban", duration: "3h59m", origin: "crowdsec", simulated: false }],
+            },
+            { id: 365, scenario: "x", source: {}, decisions: [] },
+        ]);
+        expect(compactDecisions(decisionsText)).toEqual({
             count: 1,
-            decisions: [{ id: 9, value: "203.0.113.9", scope: "Ip", type: "ban", duration: "3h59m", scenario: "x", origin: "crowdsec" }],
+            decisions: [{ id: 9, value: "203.0.113.9", scope: "Ip", type: "ban", duration: "3h59m", scenario: "37pla/frontdoor-sni-scanning", origin: "crowdsec", alertId: 364, country: "US" }],
         });
         expect(() => summariseAlerts("not json", 7)).toThrow(/no JSON/);
     });
@@ -259,6 +271,94 @@ describe("security wrapper", () => {
     });
 });
 
+describe("backup wrapper", () => {
+    it("maps commands to targets and validates arguments", () => {
+        expect(buildBackupRemote(["vzdump-tasks"])).toMatchObject({ remote: "vzdump-tasks", spec: { target: "pulsar" } });
+        expect(buildBackupRemote(["vzdump-run", "107"]).remote).toBe("vzdump-run 107");
+        expect(buildBackupRemote(["restic-snapshots", "pulsar-host"]).remote).toBe("restic-snapshots pulsar-host");
+        expect(buildBackupRemote(["restic-ls", "latest", "/etc/pve"]).remote).toBe("restic-ls latest /etc/pve");
+        expect(buildBackupRemote(["restic-restore", "08a509d6", "/etc/pve/storage.cfg"]).remote).toBe("restic-restore 08a509d6 /etc/pve/storage.cfg");
+        expect(buildBackupRemote(["arcane-backup-journal", "12 hours ago"])).toMatchObject({ spec: { target: "arcane" } });
+        expect(() => buildBackupRemote(["vzdump-run", "200"])).toThrow(/vmid/);
+        expect(() => buildBackupRemote(["restic-restore", "latest", "../etc"])).toThrow(/absolute/);
+        expect(() => buildBackupRemote(["restic-restore", "latest", "/etc/pve; rm -rf /"])).toThrow(/absolute/);
+        expect(() => buildBackupRemote(["restic-ls", "xyz"])).toThrow(/snapshot/);
+        expect(() => buildBackupRemote(["restic-snapshots", "a b"])).toThrow(/tag/);
+        expect(() => buildBackupRemote(["gcs-journal", "x; id"])).toThrow(/since/);
+        expect(() => buildBackupRemote(["restic-forget"])).toThrow(/unknown command/);
+    });
+
+    it("prints help without touching config", async () => {
+        const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        expect(await backupCommand(["--help"])).toBe(0);
+        expect(String(write.mock.calls[0][0])).toContain("restore-clean");
+        write.mockRestore();
+    });
+});
+
+describe("proxmox wrapper", () => {
+    it("validates vmids, paths, confirmation, and set keys", () => {
+        expect(parseVmid("106")).toBe(106);
+        expect(() => parseVmid("6")).toThrow(/vmid/);
+        expect(validatePvePath("/nodes/pulsar/status")).toBe("/nodes/pulsar/status");
+        expect(validatePvePath("/cluster/resources?type=storage")).toBe("/cluster/resources?type=storage");
+        expect(() => validatePvePath("nodes")).toThrow(UsageError);
+        expect(() => validatePvePath("/nodes/../access")).toThrow(UsageError);
+        expect(needsConfirm(["stop", "106", "--confirm"])).toEqual(["stop", "106"]);
+        expect(() => needsConfirm(["stop", "106"])).toThrow(/--confirm/);
+        expect(parseSetPairs("qemu", ["memory=4096", "cores=2", "net0=virtio,bridge=vmbr0"])).toEqual({ memory: "4096", cores: "2", net0: "virtio,bridge=vmbr0" });
+        expect(parseSetPairs("lxc", ["swap=512"])).toEqual({ swap: "512" });
+        expect(() => parseSetPairs("qemu", ["swap=512"])).toThrow(/may set/);
+        expect(() => parseSetPairs("lxc", ["scsi0=local-lvm:32"])).toThrow(/may set/);
+        expect(() => parseSetPairs("qemu", [])).toThrow(/key=value/);
+    });
+
+    it("maps host commands to fixed remote strings", () => {
+        expect(buildHostRemote(["host-status"])).toBe("host-status");
+        expect(buildHostRemote(["guest-exec", "101", "df"])).toBe("guest-exec 101 df");
+        expect(() => buildHostRemote(["guest-exec", "101", "rm"])).toThrow(/action/);
+        expect(() => buildHostRemote(["host-journal", "1 hour ago; id"])).toThrow(/since/);
+        expect(() => buildHostRemote(["shell"])).toThrow(/unknown host command/);
+    });
+
+    it("prints help without touching config", async () => {
+        const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        expect(await proxmoxCommand([])).toBe(0);
+        expect(String(write.mock.calls[0][0])).toContain("snapshot-rollback");
+        write.mockRestore();
+    });
+});
+
+describe("inference wrapper", () => {
+    it("maps commands to targets and enforces confirmation", () => {
+        expect(buildInferenceRemote(["nexus-status"])).toMatchObject({ remote: "nexus-status", spec: { target: "nexus" } });
+        expect(buildInferenceRemote(["nexus-log", "embed", "100"]).remote).toBe("nexus-log embed 100");
+        expect(buildInferenceRemote(["nexus-stop", "rerank", "--confirm"]).remote).toBe("nexus-stop rerank");
+        expect(buildInferenceRemote(["hermes-upgrade", "--confirm"])).toMatchObject({ remote: "hermes-upgrade", spec: { target: "pulsar" } });
+        expect(buildInferenceRemote(["hermes-journal", "1 hour ago"])).toMatchObject({ spec: { target: "hermes" } });
+        expect(() => buildInferenceRemote(["nexus-stop", "rerank"])).toThrow(/--confirm/);
+        expect(() => buildInferenceRemote(["hermes-upgrade"])).toThrow(/--confirm/);
+        expect(() => buildInferenceRemote(["nexus-restart", "server"])).toThrow(/service/);
+        expect(() => buildInferenceRemote(["nexus-log", "embed", "5000"])).toThrow(/lines/);
+        expect(() => buildInferenceRemote(["hermes-restart", "discord"])).toThrow(/service/);
+        expect(() => buildInferenceRemote(["europa-start"])).toThrow(/unknown command/);
+    });
+
+    it("compacts github releases", () => {
+        const releases = compactReleases([{ tag_name: "v2026.9.1", name: "Sept", published_at: "2026-09-10T00:00:00Z", html_url: "https://x/y", prerelease: false, body: "x".repeat(7000) }, {}]);
+        expect(releases[0]).toMatchObject({ tag: "v2026.9.1", name: "Sept", prerelease: false, url: "https://x/y" });
+        expect(releases[0].notes.length).toBe(6000);
+        expect(releases[1]).toEqual({ tag: "?", name: "", published: "", prerelease: false, url: "", notes: "" });
+    });
+
+    it("prints help without touching config", async () => {
+        const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        expect(await inferenceCommand(["help"])).toBe(0);
+        expect(String(write.mock.calls[0][0])).toContain("hermes-releases");
+        write.mockRestore();
+    });
+});
+
 describe("wrapper config errors", () => {
     let home: string;
     const originalHome = process.env.HOME;
@@ -279,5 +379,8 @@ describe("wrapper config errors", () => {
         await expect(dnsCommand(["technitium", "primary", "zones"])).rejects.toThrow(/dns\.json/);
         await expect(edgeCommand(["probe"])).rejects.toThrow(/edge\.json/);
         await expect(securityCommand(["attention"])).rejects.toThrow(/security\.json/);
+        await expect(backupCommand(["vzdump-tasks"])).rejects.toThrow(/backup\.json/);
+        await expect(proxmoxCommand(["guests"])).rejects.toThrow(/proxmox\.json/);
+        await expect(inferenceCommand(["nexus-status"])).rejects.toThrow(/inference\.json/);
     });
 });