@astrofoundry/pi-astro 0.40.24 → 0.40.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -43,6 +43,8 @@ describe("approvals", () => {
43
43
  expect(isRisky("edge", ["vps", "reboot", "--confirm", "--help"])).toBe(false);
44
44
  expect(isRisky("proxmox", ["guests"])).toBe(false);
45
45
  expect(isRisky("proxmox", ["set", "107", "memory=768"])).toBe(true);
46
+ expect(isRisky("proxmox", ["space-x", "set", "105", "memory=768"])).toBe(true);
47
+ expect(isRisky("proxmox", ["space-x", "guests"])).toBe(false);
46
48
  expect(isRisky("proxmox", ["shutdown", "107", "--confirm"])).toBe(true);
47
49
  expect(isRisky("security", ["decisions"])).toBe(false);
48
50
  expect(isRisky("inference", ["nexus-restart", "embed"])).toBe(true);
@@ -42,7 +42,7 @@ export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
42
42
  ],
43
43
  edge: [/^vps\s+deploy-nginx\b/],
44
44
  backup: [/^(vzdump-run|host-backup-run|arcane-backup-run|gcs-run|restic-check-run|restic-restore|restore-clean)\b/],
45
- proxmox: [/^(set|snapshot-create|start)\b/],
45
+ proxmox: [/^(space-x\s+)?(set|snapshot-create|start)\b/],
46
46
  inference: [/^(nexus-restart|nexus-start)\b/],
47
47
  // media has no entry: trendarr cannot delete anything, and adds and queue toggles run on the caller's request.
48
48
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrofoundry/pi-astro",
3
- "version": "0.40.24",
3
+ "version": "0.40.26",
4
4
  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -90,6 +90,18 @@ Behavior learned on the live consoles:
90
90
  - A policy has exactly one source zone and one destination zone; several destination zones need one policy each. The `SYSTEM_DEFINED` policies show each zone pair's default (on 37: Vpn to Dmz allows, Vpn to Services blocks).
91
91
  - Traffic between 37 and Mira crosses two firewalls: `<zone> to Vpn` on the sending site and `Vpn to <zone>` on the receiving site. A subnet routes only if Site Magic shares it: `unifi cloud /v1/sd-wan-configs/<id>` lists the shared networks per site. 37 shares Services, Management, Trusted, and DMZ; Mira shares Trusted, IoT, Services, and Management.
92
92
 
93
+ ## `unifi <37|mira> app-get <path>` and `unifi <37|mira> device-network <deviceId> <json>`
94
+
95
+ `app-get` reads any path of the Network application's own API under `/api/s/default/` or `/v2/api/site/default/`, through the same connector and key. Use it to find the fields a change needs before adding a narrow write command. Useful reads: `/api/s/default/stat/device` (devices with `mgmt_network_id`, `config_network`, `port_table`, `port_overrides`, `uplink`), `/api/s/default/stat/sta` (clients with `ap_mac`, `sw_mac`, `sw_port`), `/api/s/default/rest/networkconf` (networks with their 24-hex ids, VLAN, subnet, DHCP range).
96
+
97
+ `device-network` changes only a device's management network and address: a PUT of `/api/s/default/rest/device/<deviceId>` whose body may hold just `mgmt_network_id` and `config_network`. Both sites use the same layout: the uplink port stays native Default with all VLANs tagged, and each device sits on Management with a static address and the local DNS nodes.
98
+
99
+ ```json
100
+ { "args": ["unifi", "mira", "device-network", "<24-hex deviceId>", "{\"mgmt_network_id\":\"<Management networkconf id>\",\"config_network\":{\"type\":\"static\",\"ip\":\"10.1.10.3\",\"netmask\":\"255.255.255.0\",\"gateway\":\"10.1.10.1\",\"dns1\":\"10.1.40.53\",\"dns2\":\"10.0.40.54\",\"dnssuffix\":\"\",\"bonding_enabled\":false}}"] }
101
+ ```
102
+
103
+ Change one device at a time, downstream devices and the AP serving the operator last, and wait until `devices` shows it `ONLINE` at the new address before the next. An AP takes the Management network and the static address in one step. A switch does not: on 2026-10-31 the Flex XG lost the controller after getting both at once, and reverted to its previous settings by itself about 10 minutes later. For a switch, first send `mgmt_network_id` with `config_network: {"type":"dhcp"}` and wait for `ONLINE`; then send the static address. If it stays in provisioning (`state` 5, `last_config_applied_successfully: false`), restart it. The official `RESTART` device action works only on an `ONLINE` device. A switch powered by PoE can be restarted from its upstream port: `write POST /v1/sites/<siteId>/devices/<upstreamId>/interfaces/ports/<n>/actions '{"action":"POWER_CYCLE"}'`. A restart interrupts everything behind the switch; at Mira that is SPACE-X and technitium3 on Flex XG port 2.
104
+
93
105
  ## `unifi <37|mira> nat` and `unifi <37|mira> nat-write ...`
94
106
 
95
107
  The gateway's NAT rules (Policy Table, type NAT), which the official API lacks. The wrapper calls the Network application's own path `/proxy/network/v2/api/site/default/nat` through the cloud connector with the account key `UNIFI_API_KEY`; `--local` uses the console's local key instead.
@@ -1,12 +1,14 @@
1
1
  ---
2
2
  name: proxmox
3
- description: How the proxmox specialist operates Proxmox VE on Pulsar through the proxmox tool.
3
+ description: How the proxmox specialist operates Proxmox VE on Pulsar (37) and SPACE-X (Mira) through the proxmox tool.
4
4
  ---
5
5
 
6
6
  # Proxmox specialist
7
7
 
8
8
  Pulsar (`10.0.10.37`, Proxmox VE 9 on Debian 13, node name `pulsar`) runs every guest: VM 100 `arcane` (Docker platform), LXC 101 `hermes` (being retired by the operator; no specialist operates it), LXC 102 `backup` (GCS pusher), VM 103 `identity` (Zitadel), VM 104 `dmz` (Pomerium), LXC 105 `tailscale`, VM 106 `observability`, LXC 107 `technitium2`, LXC 108 `radius`. Storage `local-lvm` holds the disks, `unas-backup` the vzdump archives. The `proxmox` tool talks to the API with a token whose role allows audit everywhere and, on guests, power, snapshots, and CPU/memory/option/network settings; nothing else. `["--help"]` lists the commands.
9
9
 
10
+ SPACE-X (`10.1.10.37`, Proxmox VE 9 at Mira, node name `space-x`) runs LXC 100 `technitium3` (DNS cluster node) and LXC 105 `tailscale` (Mira's subnet router). Put `space-x` before any command to run it there, for example `["space-x", "guests"]`; without it every command runs on Pulsar. SPACE-X has the same restricted user `spc-proxmox@pve!cortex` with its own token, and the same forced-command key as Pulsar. SPACE-X has no backup storage yet.
11
+
10
12
  ## API commands
11
13
 
12
14
  | Command | Effect |
@@ -23,6 +23,46 @@ interface ProxmoxConfig extends Record<string, string> {
23
23
 
24
24
  const SHAPE = { apiUrl: "string", certSha256: "string", node: "string", pulsarHost: "string", pulsarUser: "string" } as const;
25
25
 
26
+ interface SpaceXConfig extends Record<string, string> {
27
+ spacexApiUrl: string;
28
+ spacexCertSha256: string;
29
+ spacexNode: string;
30
+ spacexHost: string;
31
+ spacexUser: string;
32
+ }
33
+
34
+ const SPACEX_SHAPE = { spacexApiUrl: "string", spacexCertSha256: "string", spacexNode: "string", spacexHost: "string", spacexUser: "string" } as const;
35
+
36
+ /** Pulsar at 37 is the default host; a leading `space-x` selects Mira's host. */
37
+ export const HOSTS = ["pulsar", "space-x"] as const;
38
+ export type HostName = (typeof HOSTS)[number];
39
+
40
+ /** One Proxmox host: its API, token fields, and forced-command SSH target. */
41
+ interface Target {
42
+ name: HostName;
43
+ apiUrl: string;
44
+ certSha256: string;
45
+ node: string;
46
+ sshHost: string;
47
+ sshUser: string;
48
+ tokenIdField: string;
49
+ tokenSecretField: string;
50
+ }
51
+
52
+ export function splitHost(args: string[]): { host: HostName; rest: string[] } {
53
+ return args[0] === "space-x" ? { host: "space-x", rest: args.slice(1) } : { host: "pulsar", rest: args };
54
+ }
55
+
56
+ function readTarget(host: HostName): Target {
57
+ if (host === "space-x") {
58
+ const c = readConfig<SpaceXConfig>(SERVICE, SPACEX_SHAPE);
59
+ // SPACE-X trusts the same forced-command key as Pulsar (SSH_KEY_PULSAR); its API token is its own.
60
+ return { name: host, apiUrl: c.spacexApiUrl, certSha256: c.spacexCertSha256, node: c.spacexNode, sshHost: c.spacexHost, sshUser: c.spacexUser, tokenIdField: "PVE_SPACEX_TOKEN_ID", tokenSecretField: "PVE_SPACEX_TOKEN_SECRET" };
61
+ }
62
+ const c = readConfig<ProxmoxConfig>(SERVICE, SHAPE);
63
+ return { name: host, apiUrl: c.apiUrl, certSha256: c.certSha256, node: c.node, sshHost: c.pulsarHost, sshUser: c.pulsarUser, tokenIdField: "PVE_TOKEN_ID", tokenSecretField: "PVE_TOKEN_SECRET" };
64
+ }
65
+
26
66
  const TIMEOUT_MS = 30_000;
27
67
  const TASK_POLL_MS = 2_000;
28
68
  const VMID = /^\d{3,9}$/;
@@ -50,7 +90,9 @@ export const HOST_COMMANDS: Readonly<Record<string, { args: number; help: string
50
90
  export const GUEST_EXEC = ["status", "journal", "df", "updates"];
51
91
  const SINCE = /^[A-Za-z0-9 :\-+]{1,40}$/;
52
92
 
53
- const HELP = `proxmox specialist (Proxmox VE on Pulsar)
93
+ const HELP = `proxmox specialist (Proxmox VE on Pulsar at 37 and SPACE-X at Mira)
94
+
95
+ [space-x] <command> every command below runs on Pulsar, or on SPACE-X with the space-x prefix
54
96
 
55
97
  guests every VM and container: vmid, name, type, status, resources (JSON)
56
98
  guest <vmid> current status and configuration of one guest (JSON)
@@ -90,9 +132,9 @@ interface GuestResource {
90
132
  tags?: string;
91
133
  }
92
134
 
93
- async function api(config: ProxmoxConfig, method: string, path: string, form?: Record<string, string>): Promise<unknown> {
94
- const tokenId = readSecret(SERVICE, "PVE_TOKEN_ID");
95
- const secret = readSecret(SERVICE, "PVE_TOKEN_SECRET");
135
+ async function api(config: Target, method: string, path: string, form?: Record<string, string>): Promise<unknown> {
136
+ const tokenId = readSecret(SERVICE, config.tokenIdField);
137
+ const secret = readSecret(SERVICE, config.tokenSecretField);
96
138
  const body = form === undefined ? undefined : new URLSearchParams(form).toString();
97
139
  const response = await pinnedRequest(new URL(`/api2/json${path}`, config.apiUrl), {
98
140
  method,
@@ -147,7 +189,7 @@ export function needsConfirm(args: string[]): string[] {
147
189
  return args.filter((_, i) => i !== index);
148
190
  }
149
191
 
150
- async function guestResource(config: ProxmoxConfig, vmid: number): Promise<GuestResource> {
192
+ async function guestResource(config: Target, vmid: number): Promise<GuestResource> {
151
193
  const resources = (await api(config, "GET", "/cluster/resources?type=vm")) as GuestResource[];
152
194
  const guest = resources.find((r) => r.vmid === vmid);
153
195
  if (!guest) throw new UsageError(`no guest with vmid ${vmid}`);
@@ -166,7 +208,7 @@ interface TaskStatus {
166
208
  endtime?: number;
167
209
  }
168
210
 
169
- async function waitTask(config: ProxmoxConfig, upid: string, timeoutMs: number): Promise<TaskStatus> {
211
+ async function waitTask(config: Target, upid: string, timeoutMs: number): Promise<TaskStatus> {
170
212
  const deadline = Date.now() + timeoutMs;
171
213
  for (;;) {
172
214
  const status = (await api(config, "GET", `/nodes/${config.node}/tasks/${encodeURIComponent(upid)}/status`)) as TaskStatus;
@@ -176,7 +218,7 @@ async function waitTask(config: ProxmoxConfig, upid: string, timeoutMs: number):
176
218
  }
177
219
  }
178
220
 
179
- async function runTask(config: ProxmoxConfig, method: string, path: string, form: Record<string, string> | undefined, label: string): Promise<number> {
221
+ async function runTask(config: Target, method: string, path: string, form: Record<string, string> | undefined, label: string): Promise<number> {
180
222
  const upid = (await api(config, method, path, form)) as string;
181
223
  const status = await waitTask(config, upid, 300_000);
182
224
  printJson({ action: label, upid, exitstatus: status.exitstatus, endtime: status.endtime });
@@ -184,7 +226,7 @@ async function runTask(config: ProxmoxConfig, method: string, path: string, form
184
226
  return 0;
185
227
  }
186
228
 
187
- async function apiCommand(config: ProxmoxConfig, args: string[]): Promise<number> {
229
+ async function apiCommand(config: Target, args: string[]): Promise<number> {
188
230
  const [name, ...rest] = args;
189
231
  switch (name) {
190
232
  case "guests": {
@@ -293,12 +335,12 @@ export function buildHostRemote(args: string[]): string {
293
335
  return [name, ...rest].join(" ");
294
336
  }
295
337
 
296
- async function host(config: ProxmoxConfig, args: string[]): Promise<number> {
338
+ async function host(config: Target, args: string[]): Promise<number> {
297
339
  const remote = buildHostRemote(args);
298
340
  const result = await sshFixed(
299
341
  {
300
- host: config.pulsarHost,
301
- user: config.pulsarUser,
342
+ host: config.sshHost,
343
+ user: config.sshUser,
302
344
  keyFile: secretPath(SERVICE, "SSH_KEY_PULSAR"),
303
345
  knownHostsFile: join(specialistsHome(), "config", "known_hosts"),
304
346
  },
@@ -315,14 +357,15 @@ export async function command(args: string[]): Promise<number> {
315
357
  printRaw(HELP);
316
358
  return 0;
317
359
  }
318
- const config = readConfig<ProxmoxConfig>(SERVICE, SHAPE);
319
- if (args[0] === "fingerprint") {
360
+ const { host: hostName, rest } = splitHost(args);
361
+ const config = readTarget(hostName);
362
+ if (rest[0] === "fingerprint") {
320
363
  const probe = await pinnedRequest(new URL("/", config.apiUrl), { method: "GET", headers: {}, expectedFingerprint: null, timeoutMs: TIMEOUT_MS });
321
364
  printJson({ host: new URL(config.apiUrl).host, fingerprint256: probe.fingerprint });
322
365
  return 0;
323
366
  }
324
- if (args[0] in HOST_COMMANDS) return host(config, args);
325
- return apiCommand(config, args);
367
+ if (rest[0] !== undefined && rest[0] in HOST_COMMANDS) return host(config, rest);
368
+ return apiCommand(config, rest);
326
369
  }
327
370
 
328
371
  if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
@@ -12,7 +12,7 @@ import { MAX_ADD_IDS, MAX_EXCLUDE_IDS, buildTrendarrCall, interpretRun, parseImd
12
12
  import { ServiceError, UsageError } from "./lib/errors.ts";
13
13
  import { safeRepoPath, safeWritePath } from "./lib/repo.ts";
14
14
  import { appGetPath, buildPulsarRemote, cloudPath, deviceNetworkWrite, NAT_PATH, natWrite, parseQuery, parseSiteArgs, unifiPath, unifiWrite, command as networkCommand } from "./network/run.ts";
15
- import { buildHostRemote, needsConfirm, parseSetPairs, parseVmid, validateApiPath as validatePvePath, command as proxmoxCommand } from "./proxmox/run.ts";
15
+ import { buildHostRemote, splitHost, needsConfirm, parseSetPairs, parseVmid, validateApiPath as validatePvePath, command as proxmoxCommand } from "./proxmox/run.ts";
16
16
  import { banLength, buildObsRemote, compactDecisions, parseGoDuration, summariseAlerts, summariseVulns, summariseWazuh, vulnEvents, wazuhEvents, command as securityCommand } from "./security/run.ts";
17
17
 
18
18
  describe("arcane wrapper", () => {
@@ -600,6 +600,8 @@ describe("proxmox wrapper", () => {
600
600
  });
601
601
 
602
602
  it("maps host commands to fixed remote strings", () => {
603
+ expect(splitHost(["space-x", "guests"])).toEqual({ host: "space-x", rest: ["guests"] });
604
+ expect(splitHost(["guests"])).toEqual({ host: "pulsar", rest: ["guests"] });
603
605
  expect(buildHostRemote(["host-status"])).toBe("host-status");
604
606
  expect(buildHostRemote(["guest-exec", "101", "df"])).toBe("guest-exec 101 df");
605
607
  expect(() => buildHostRemote(["guest-exec", "101", "rm"])).toThrow(/action/);