@astrofoundry/pi-astro 0.40.19 → 0.40.21

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrofoundry/pi-astro",
3
- "version": "0.40.19",
3
+ "version": "0.40.21",
4
4
  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -28,6 +28,7 @@ The internal resolvers form one Technitium cluster, `dns.home.arpa`: the Primary
28
28
  | `cluster-delete` (primary) | remove the cluster from the primary; refused while Secondary nodes exist |
29
29
  | `cluster-remove <secondaryNodeId>` (primary) | ask a Secondary node (id from `cluster-state`) to leave |
30
30
  | `server-domain <name>` (primary or node) | set that node's DNS Server Domain |
31
+ | `zone-resync <zone>` (primary or node) | re-fetch a Secondary or catalog zone; on a node's cluster catalog it recreates missing member zones |
31
32
  | `stale-zone-delete <zone>` (node only) | delete a Secondary zone no catalog manages (checked first), so the cluster catalog recreates it |
32
33
 
33
34
  Record parameters by type (the API's names): `A`/`AAAA` `ipAddress` (update: `newIpAddress`); `CNAME` `cname`; `TXT` `text`; `MX` `exchange`, `preference`; `SRV` `priority`, `weight`, `port`, `target`; `NS` `nameServer`; `PTR` `ptrName`. `ttl=<seconds>` and `comments=<text>` apply to all; `overwrite=true` replaces the record set on add.
@@ -39,9 +40,13 @@ Record parameters by type (the API's names): `A`/`AAAA` `ipAddress` (update: `ne
39
40
  { "args": ["technitium", "primary", "cluster-state"] }
40
41
  ```
41
42
 
42
- Every internal service name is its own Primary zone (`auth.37pla.net`, `kuma.37pla.net`, ...; 33 zones including `catalog.invalid` and the `orange.es` forwarder). There is no internal `37pla.net` zone: run `zones` first, then use the exact zone name, and create a new zone with `zone-create <fqdn>` before adding its records.
43
+ Every internal service name is its own Primary zone (`auth.37pla.net`, `kuma.37pla.net`, ...), plus the `orange.es` forwarder and the cluster zones. There is no internal `37pla.net` zone: run `zones` first, then use the exact zone name, and create a new zone with `zone-create <fqdn>` before adding its records.
43
44
 
44
- Zone, record, and cluster writes are refused with `node`. Replication is near-immediate; if a node still answers the old value after a minute, report it as a replication problem.
45
+ Zone, record, and cluster writes are refused with `node`. Record changes replicate within seconds. A new zone reaches the other nodes only when they refresh the cluster catalog: if a node does not answer it after a minute, run `zone-resync cluster-catalog.dns.home.arpa` on that node, then check again. If it still fails, report a replication problem.
46
+
47
+ Change users, passwords, settings, blocklists, and apps only on the primary. Joining replaced those sections on the other nodes, and the cluster copies them from the primary; the Technitium docs describe no sync in the other direction.
48
+
49
+ API reference: grimoire products `technitium-api` (HTTP API) and `technitium-dns`. The live cluster state lists nodes under `clusterNodes`; the docs call the field `nodes`.
45
50
 
46
51
  `technitium join <nodeUrl> <nodeIp>` adds a fresh node as a Secondary node: it refuses a node whose default `admin`/`admin` login was already changed, creates a one-time admin with a random password on the primary for the join, and deletes it afterwards. The join replaces the node's settings, blocklists, apps, and users with the primary's. Check `cluster-state` afterwards.
47
52
 
@@ -8,7 +8,7 @@ description: How the network specialist reads and changes the UniFi consoles of
8
8
  Two UniFi sites, each with its own console:
9
9
 
10
10
  - `37` (Madrid, console `10.0.10.1`): the homelab. Nine VLANs, inter-zone traffic denied unless a policy allows it, Wi-Fi `Ardilla-37` (EAP-TLS via FreeRADIUS on LXC 108), `Ardilla-IoT`, `Ardilla-GUEST`. LXC 105 runs the Tailscale subnet router for remote administration.
11
- - `mira` (console `192.168.1.1`): the second location. Wi-Fi `Astro` (192.168.1.0/24) and `AstroGuest` (192.168.40.0/24).
11
+ - `mira` (Cortex reaches its console at `10.1.60.1` over Site Magic): the second location, `10.1.0.0/16`, with the same zone model as 37 (Management 10, Services 40, Trusted 60, IoT 70, Guest 80). 37 and Mira are run as one network.
12
12
 
13
13
  The consoles are joined by Site Magic (SD-WAN). Never call either site "home". The `network` tool has three families.
14
14
 
@@ -27,7 +27,7 @@ Reads of that console's Network API. `<siteId>` is the UUID that `sites` returns
27
27
  | `device <siteId> <deviceId>` | one device with ports and radios |
28
28
  | `clients <siteId>` | connected clients |
29
29
  | `networks <siteId>` | networks and VLANs |
30
- | `firewall-policies <siteId>` | zone policies (filter with `--filter "name.like('%from Cortex')"`) |
30
+ | `firewall-policies <siteId>` | zone policies (filter with `--filter "name.like('*from Cortex')"`) |
31
31
  | `firewall-policy <siteId> <policyId>` | one policy, full object |
32
32
  | `firewall-zones <siteId>` | zones with ids and member networks |
33
33
  | `wans <siteId>` | WAN interfaces |
@@ -53,11 +53,41 @@ Procedure for every write:
53
53
  3. Write, then read the object back and report its id, name, and the fields that changed.
54
54
 
55
55
  ```json
56
- { "args": ["unifi", "37", "firewall-policies", "<siteId>", "--filter", "name.like('%from Cortex')"] }
56
+ { "args": ["unifi", "37", "firewall-policies", "<siteId>", "--filter", "name.like('*from Cortex')"] }
57
57
  { "args": ["unifi", "37", "write", "POST", "/v1/sites/<siteId>/firewall/policies", "{\"name\":\"Proxmox API - from Cortex\", ...}"] }
58
58
  { "args": ["unifi", "mira", "write", "DELETE", "/v1/sites/<siteId>/acl-rules/<aclRuleId>"] }
59
59
  ```
60
60
 
61
+ ## What the Network API can and cannot do
62
+
63
+ Both consoles run Network `10.6.109`. The console serves no `openapi.json` (404); the spec is at `https://developer.ui.com/network/v10.6.109/openapi.json` and in grimoire as `unifi-network-api` (11.0.97, same endpoints). Look a field up there before you report that the API cannot do something.
64
+
65
+ | Object (under `/v1/sites/<siteId>/`) | Methods | Notes |
66
+ |---|---|---|
67
+ | `networks`, `networks/{id}` | GET POST PUT DELETE | VLAN, zone, DHCP range and lease, DHCP DNS servers, gateway override, NTP, isolation, mDNS, internet access; `networks/{id}/references` shows what uses a network |
68
+ | `wifi/broadcasts` | GET POST PUT DELETE | SSIDs |
69
+ | `firewall/zones` | GET POST PUT DELETE | custom zones and their networks |
70
+ | `firewall/policies` | GET POST PUT PATCH DELETE | PATCH changes only `loggingEnabled` and `reportFlowEnabled`; `firewall/policies/ordering` GET PUT |
71
+ | `acl-rules` | GET POST PUT DELETE | switch ACLs; `acl-rules/ordering` GET PUT |
72
+ | `dns/policies` | GET POST PUT DELETE | gateway DNS records: `A_RECORD`, `AAAA_RECORD`, `CNAME_RECORD`, `MX_RECORD`, `SRV_RECORD`, `TXT_RECORD`, `FORWARD_DOMAIN` |
73
+ | `traffic-matching-lists` | GET POST PUT DELETE | IP and port lists for policies |
74
+ | `hotspot/vouchers` | GET POST DELETE | guest vouchers |
75
+ | `devices` | GET, POST (adopt), DELETE | `devices/{id}/actions`: `RESTART`; `devices/{id}/interfaces/ports/{idx}/actions`: `POWER_CYCLE`; `statistics/latest` |
76
+ | `clients` | GET | `clients/{id}/actions`: `AUTHORIZE_GUEST_ACCESS`, `UNAUTHORIZE_GUEST_ACCESS` |
77
+ | `wans`, `vpn/servers`, `vpn/site-to-site-tunnels`, `radius/profiles`, `switching/*`, `device-tags` | GET | read only |
78
+
79
+ No endpoint exists for these, so they stay owner tasks in the UniFi UI: Site Magic (read it with `unifi cloud`), switch port profiles and per-port settings (only power cycle), device settings (name, LEDs, uplink, management VLAN), client fixed IPs and names, port forwarding and NAT, static and traffic routes, VPN server and Teleport settings, admins, and console settings.
80
+
81
+ Behavior learned on the live consoles:
82
+
83
+ - A GET omits an optional field that is unset. A missing field is not proof that the API lacks it: `ipv4Configuration.dhcpConfiguration.dnsServerIpAddressesOverride` (the DHCP DNS servers) appears only once set. Check the schema.
84
+ - PUT replaces the whole object: send the full GET body without `id`, `metadata`, `default`, and `index`. To set DHCP DNS on a network, PUT it with `dnsServerIpAddressesOverride: ["<dns1>", "<dns2>"]`; remove the field to return to automatic.
85
+ - `like` uses `*` for any characters and `.` for one character; escape them with `\`. SQL `%` matches nothing and still returns `totalCount: 0` without an error.
86
+ - Lists return 25 items by default. 37 has about 390 firewall policies, mostly `SYSTEM_DEFINED` zone defaults and `DERIVED` return rules: page with `--offset`, or filter `metadata.origin.eq('USER_DEFINED')` (69 on 37 on 2026-10-31).
87
+ - Protocol filters: one protocol is `{"type":"NAMED_PROTOCOL","protocol":{"name":"TCP"},"matchOpposite":false}`; TCP and UDP together is `{"type":"PRESET","preset":{"name":"TCP_UDP"}}` with no `matchOpposite`. Omit `protocolFilter` to match every protocol.
88
+ - 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).
89
+ - 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.
90
+
61
91
  ## `unifi cloud <path>`
62
92
 
63
93
  Reads of the Site Manager API itself (`/v1/` or `/ea/`): `/v1/hosts` (consoles and their host ids), `/v1/sites`, `/v1/devices`, `/v1/sd-wan-configs` and `/v1/sd-wan-configs/{id}/status` (Site Magic), `/v1/isp-metrics/{type}`. Lists page with `pageSize` and `nextToken` in the query.
@@ -58,6 +58,7 @@ export const TECHNITIUM_WRITES: Readonly<Record<string, { args: [number, number]
58
58
  "cluster-delete": { args: [0, 0], help: "cluster-delete remove the cluster from the primary (only without Secondary nodes)" },
59
59
  "cluster-remove": { args: [1, 1], help: "cluster-remove <secondaryNodeId> ask a Secondary node to leave the cluster" },
60
60
  "server-domain": { args: [1, 1], help: "server-domain <name> DNS Server Domain of the target node (also with node)" },
61
+ "zone-resync": { args: [1, 1], help: "zone-resync <zone> re-fetch a Secondary or catalog zone from its primary (also with node)" },
61
62
  "stale-zone-delete": { args: [1, 1], help: "stale-zone-delete <zone> (node only) delete a Secondary zone that no catalog manages, so the cluster catalog recreates it" },
62
63
  };
63
64
 
@@ -169,6 +170,8 @@ export function technitiumRequest(catalog: string, args: string[]): TechnitiumRe
169
170
  case "cluster-remove":
170
171
  if (!NODE_ID.test(rest[0])) throw new UsageError("cluster-remove needs the numeric Secondary node id from cluster-state");
171
172
  return { path: "/api/admin/cluster/primary/removeSecondary", params: { secondaryNodeId: rest[0] }, primaryOnly: true };
173
+ case "zone-resync":
174
+ return { path: "/api/zones/resync", params: { zone: assertName(rest[0], "zone") }, primaryOnly: false };
172
175
  case "stale-zone-delete":
173
176
  return { path: "/api/zones/delete", params: { zone: assertName(rest[0], "zone") }, primaryOnly: false };
174
177
  case "server-domain":
@@ -195,6 +195,7 @@ describe("dns wrapper", () => {
195
195
  primaryOnly: true,
196
196
  });
197
197
  expect(technitiumRequest("c", ["cluster-delete"]).params).toEqual({ forceDelete: "false" });
198
+ expect(technitiumRequest("c", ["zone-resync", "cluster-catalog.dns.home.arpa"]).path).toBe("/api/zones/resync");
198
199
  expect(technitiumRequest("c", ["stale-zone-delete", "pdf.37pla.net"])).toEqual({ path: "/api/zones/delete", params: { zone: "pdf.37pla.net" }, primaryOnly: false });
199
200
  expect(technitiumRequest("cluster-catalog.dns.home.arpa", ["zone-catalog", "pdf.37pla.net"])).toEqual({
200
201
  path: "/api/zones/options/set",