@astrofoundry/pi-astro 0.40.17 → 0.40.19

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/agents/dns.md CHANGED
@@ -16,7 +16,7 @@ Rules:
16
16
 
17
17
  - Read before you write: list the zone's records, then add, update, or delete exactly the record the task names. Never create duplicates.
18
18
  - Internal changes go to the Technitium primary only; the other nodes follow through the catalog zone and the cluster. After a write, read the same zone from every node with `node <fqdn>` and report whether each has caught up.
19
- - New internal zones are Primary zones in the configured catalog; confirm with `zone-options` afterwards.
19
+ - New internal zones are Primary zones in the cluster catalog; confirm with `zone-options` afterwards.
20
20
  - Public records for the front door point at the VPS address with TTL 300 and `proxied: false`. Add the hostname to the VPS nginx allowlist (edge specialist) before the public record exists.
21
21
  - Deleting a zone or a record is only for tasks that name it explicitly; state what would disappear before you do it.
22
22
  - Report facts from the JSON output, including the record ids Cloudflare returns.
@@ -35,8 +35,8 @@ export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
35
35
  // Every UniFi write, on either console.
36
36
  network: [/^unifi\s+\S+\s+write\b/],
37
37
  dns: [
38
- /^technitium\s+primary\s+(zone-create|zone-delete|record-add|record-update|record-delete|cluster-init|cluster-delete|cluster-remove|server-domain)\b/,
39
- /^technitium\s+node\s+\S+\s+server-domain\b/,
38
+ /^technitium\s+primary\s+(zone-create|zone-catalog|zone-delete|record-add|record-update|record-delete|cluster-init|cluster-delete|cluster-remove|server-domain)\b/,
39
+ /^technitium\s+node\s+\S+\s+(server-domain|stale-zone-delete)\b/,
40
40
  /^technitium\s+join\b/,
41
41
  /^cloudflare\s+record-(add|update|delete)\b/,
42
42
  ],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrofoundry/pi-astro",
3
- "version": "0.40.17",
3
+ "version": "0.40.19",
4
4
  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -5,7 +5,7 @@ description: How the dns specialist operates the Technitium cluster (internal re
5
5
 
6
6
  # DNS specialist
7
7
 
8
- The internal resolvers form one Technitium cluster, `dns.home.arpa`: the Primary node `technitium1` on Synapse (`10.0.40.53`), and the Secondary nodes `technitium2` (LXC 107 on Pulsar, `10.0.40.54`) and `technitium3` (LXC 100 on SPACE-X at Mira, `10.1.40.53`). The primary owns every zone; the configured catalog zone replicates them, and the cluster syncs settings, blocklists, allowed and blocked zones, apps, and users to the other nodes. Every call goes to the primary; `node <fqdn>` makes the primary run it on another node. Public names live in Cloudflare zones `37pla.net` and `monadeo.com`. The `dns` tool has two families; `["--help"]` lists everything.
8
+ The internal resolvers form one Technitium cluster, `dns.home.arpa`: the Primary node `technitium1` on Synapse (`10.0.40.53`), and the Secondary nodes `technitium2` (LXC 107 on Pulsar, `10.0.40.54`) and `technitium3` (LXC 100 on SPACE-X at Mira, `10.1.40.53`). The primary owns every zone; the cluster catalog zone `cluster-catalog.dns.home.arpa` replicates them, and the cluster syncs settings, blocklists, allowed and blocked zones, apps, and users to the other nodes. Every call goes to the primary; `node <fqdn>` makes the primary run it on another node. Public names live in Cloudflare zones `37pla.net` and `monadeo.com`. The `dns` tool has two families; `["--help"]` lists everything.
9
9
 
10
10
  ## `technitium primary <command>` and `technitium node <fqdn> <command>`
11
11
 
@@ -18,7 +18,8 @@ The internal resolvers form one Technitium cluster, `dns.home.arpa`: the Primary
18
18
  | `stats [LastHour\|LastDay\|LastWeek\|LastMonth\|LastYear]` | dashboard counters |
19
19
  | `cluster-state` | cluster domain, nodes with id, type, state, and last seen, and the server's addresses |
20
20
  | `settings` | all server settings; secrets are redacted |
21
- | `zone-create <zone>` (primary) | Primary zone in the catalog |
21
+ | `zone-create <zone>` (primary) | Primary zone in the cluster catalog |
22
+ | `zone-catalog <zone>` (primary) | make an existing Primary zone a member of the cluster catalog |
22
23
  | `zone-delete <zone>` (primary) | deletes the zone and every record |
23
24
  | `record-add <zone> <domain> <type> key=value...` (primary) | `/api/zones/records/add` |
24
25
  | `record-update <zone> <domain> <type> key=value...` (primary) | `/api/zones/records/update` |
@@ -27,6 +28,7 @@ The internal resolvers form one Technitium cluster, `dns.home.arpa`: the Primary
27
28
  | `cluster-delete` (primary) | remove the cluster from the primary; refused while Secondary nodes exist |
28
29
  | `cluster-remove <secondaryNodeId>` (primary) | ask a Secondary node (id from `cluster-state`) to leave |
29
30
  | `server-domain <name>` (primary or node) | set that node's DNS Server Domain |
31
+ | `stale-zone-delete <zone>` (node only) | delete a Secondary zone no catalog manages (checked first), so the cluster catalog recreates it |
30
32
 
31
33
  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.
32
34
 
@@ -73,7 +73,7 @@ Host: Cortex (macOS on Apple silicon; Homebrew git; the specialists' Node, trend
73
73
  "homelabRemote": "git@github.com:astronaute77/homelab.git", "homelabBranch": "main", "repoArea": "02-pulsar-proxmox/dmz", "pomeriumConfig": "02-pulsar-proxmox/dmz/config.yaml" }
74
74
  { "unifi37HostId": "<from: specialist-cli network -- unifi cloud /v1/hosts>", "unifi37LocalUrl": "https://10.0.10.1/proxy/network/integration", "unifi37CertSha256": "<from: specialist-cli network -- unifi 37 fingerprint>",
75
75
  "unifiMiraHostId": "<the same>", "unifiMiraLocalUrl": "https://192.168.1.1/proxy/network/integration", "unifiMiraCertSha256": "<the same>", "pulsarHost": "10.0.10.37", "pulsarUser": "root" }
76
- { "technitiumPrimaryUrl": "http://10.0.40.53:5380", "technitiumCatalog": "cluster-catalog.dns.home.arpa" }
76
+ { "technitiumPrimaryUrl": "http://10.0.40.53:5380" }
77
77
  { "gcloud": "/usr/local/libexec/specialist-gcloud/current/bin/gcloud", "gcloudPython": "/usr/local/libexec/specialist-python/current/bin/python3",
78
78
  "project": "frontdoor-1337", "zone": "us-east1-c", "instance": "frontdoor-1337", "serviceAccount": "spc-edge@frontdoor-1337.iam.gserviceaccount.com",
79
79
  "iapLocalPort": 22337, "sshUser": "spc-edge", "publicIp": "35.237.66.101", "probeHost": "auth.37pla.net",
@@ -11,11 +11,12 @@ const SERVICE = "dns";
11
11
  interface DnsConfig extends Record<string, string> {
12
12
  /** API of the cluster primary; every other node is reached through it with the `node` parameter. */
13
13
  technitiumPrimaryUrl: string;
14
- /** Catalog zone new primary zones join, so the other nodes receive them. */
15
- technitiumCatalog: string;
16
14
  }
17
15
 
18
- const SHAPE = { technitiumPrimaryUrl: "string", technitiumCatalog: "string" } as const;
16
+ const SHAPE = { technitiumPrimaryUrl: "string" } as const;
17
+
18
+ /** Commands that need the cluster catalog, which the primary's cluster state names. */
19
+ const CATALOG_COMMANDS = new Set(["zone-create", "zone-catalog"]);
19
20
 
20
21
  const CLOUDFLARE_API = "https://api.cloudflare.com/client/v4";
21
22
  const TIMEOUT_MS = 30_000;
@@ -47,7 +48,8 @@ export const TECHNITIUM_READS: Readonly<Record<string, { args: [number, number];
47
48
 
48
49
  /** Technitium writes; zone and cluster writes on the primary only, the other nodes follow through the catalog and the cluster. */
49
50
  export const TECHNITIUM_WRITES: Readonly<Record<string, { args: [number, number]; help: string }>> = {
50
- "zone-create": { args: [1, 1], help: "zone-create <zone> Primary zone, member of the configured catalog" },
51
+ "zone-create": { args: [1, 1], help: "zone-create <zone> Primary zone, member of the cluster catalog" },
52
+ "zone-catalog": { args: [1, 1], help: "zone-catalog <zone> make an existing Primary zone a member of the cluster catalog" },
51
53
  "zone-delete": { args: [1, 1], help: "zone-delete <zone> delete a zone and every record in it" },
52
54
  "record-add": { args: [3, 40], help: "record-add <zone> <domain> <type> <key=value>... e.g. ipAddress=10.0.40.99 ttl=300" },
53
55
  "record-update": { args: [3, 40], help: "record-update <zone> <domain> <type> <key=value>... e.g. ipAddress=10.0.40.99 newIpAddress=10.0.40.98" },
@@ -56,6 +58,7 @@ export const TECHNITIUM_WRITES: Readonly<Record<string, { args: [number, number]
56
58
  "cluster-delete": { args: [0, 0], help: "cluster-delete remove the cluster from the primary (only without Secondary nodes)" },
57
59
  "cluster-remove": { args: [1, 1], help: "cluster-remove <secondaryNodeId> ask a Secondary node to leave the cluster" },
58
60
  "server-domain": { args: [1, 1], help: "server-domain <name> DNS Server Domain of the target node (also with node)" },
61
+ "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" },
59
62
  };
60
63
 
61
64
  const HELP = `dns specialist
@@ -133,6 +136,8 @@ export function technitiumRequest(catalog: string, args: string[]): TechnitiumRe
133
136
  }
134
137
  case "zone-create":
135
138
  return { path: "/api/zones/create", params: { zone: assertName(rest[0], "zone"), type: "Primary", catalog }, primaryOnly: true };
139
+ case "zone-catalog":
140
+ return { path: "/api/zones/options/set", params: { zone: assertName(rest[0], "zone"), catalog }, primaryOnly: true };
136
141
  case "zone-delete":
137
142
  return { path: "/api/zones/delete", params: { zone: assertName(rest[0], "zone") }, primaryOnly: true };
138
143
  case "record-add":
@@ -164,6 +169,8 @@ export function technitiumRequest(catalog: string, args: string[]): TechnitiumRe
164
169
  case "cluster-remove":
165
170
  if (!NODE_ID.test(rest[0])) throw new UsageError("cluster-remove needs the numeric Secondary node id from cluster-state");
166
171
  return { path: "/api/admin/cluster/primary/removeSecondary", params: { secondaryNodeId: rest[0] }, primaryOnly: true };
172
+ case "stale-zone-delete":
173
+ return { path: "/api/zones/delete", params: { zone: assertName(rest[0], "zone") }, primaryOnly: false };
167
174
  case "server-domain":
168
175
  return { path: "/api/settings/set", params: { dnsServerDomain: assertName(rest[0], "server domain") }, primaryOnly: false };
169
176
  default:
@@ -255,6 +262,14 @@ async function join(config: DnsConfig, args: string[]): Promise<number> {
255
262
  return 0;
256
263
  }
257
264
 
265
+ /** The cluster catalog zone, `cluster-catalog.<clusterDomain>`, from the primary's cluster state. */
266
+ async function clusterCatalog(config: DnsConfig): Promise<string> {
267
+ const state = await technitiumCall(config.technitiumPrimaryUrl, "/api/admin/cluster/state", {}, readSecret(SERVICE, "TECHNITIUM_TOKEN"), "primary");
268
+ const domain = (state.response as { clusterDomain?: string } | undefined)?.clusterDomain;
269
+ if (domain === undefined) throw new ServiceError("the primary reports no initialized cluster");
270
+ return `cluster-catalog.${domain}`;
271
+ }
272
+
258
273
  /** Splits `primary <command>` or `node <fqdn> <command>` into the target node (undefined for the primary) and the command. */
259
274
  export function technitiumTarget(args: string[]): { node: string | undefined; rest: string[] } {
260
275
  if (args[0] === "primary") return { node: undefined, rest: args.slice(1) };
@@ -269,11 +284,21 @@ export function technitiumTarget(args: string[]): { node: string | undefined; re
269
284
  async function technitium(config: DnsConfig, args: string[]): Promise<number> {
270
285
  if (args[0] === "join") return join(config, args.slice(1));
271
286
  const { node, rest } = technitiumTarget(args);
272
- const request = technitiumRequest(config.technitiumCatalog, rest);
287
+ const catalog = CATALOG_COMMANDS.has(rest[0] ?? "") ? await clusterCatalog(config) : "";
288
+ const request = technitiumRequest(catalog, rest);
273
289
  if (node !== undefined && request.primaryOnly) throw new UsageError("zone and cluster writes go to the primary; the other nodes follow through the catalog zone and the cluster");
274
290
  const params = node === undefined ? request.params : { ...request.params, node };
275
291
  const target = node ?? "primary";
276
- const parsed = await technitiumCall(config.technitiumPrimaryUrl, request.path, params, readSecret(SERVICE, "TECHNITIUM_TOKEN"), target);
292
+ const token = readSecret(SERVICE, "TECHNITIUM_TOKEN");
293
+ if (rest[0] === "stale-zone-delete") {
294
+ if (node === undefined) throw new UsageError("stale-zone-delete needs node <fqdn>; delete a primary zone with zone-delete");
295
+ const options = await technitiumCall(config.technitiumPrimaryUrl, "/api/zones/options/get", { zone: params.zone, node }, token, target);
296
+ const zone = options.response as { type?: string; catalog?: string | null } | undefined;
297
+ if (!["Secondary", "SecondaryCatalog"].includes(zone?.type ?? "") || (zone?.catalog ?? null) !== null) {
298
+ throw new UsageError(`${params.zone} on ${node} is ${zone?.type ?? "unknown"} in catalog ${zone?.catalog ?? "none"}; only a Secondary zone outside any catalog is stale`);
299
+ }
300
+ }
301
+ const parsed = await technitiumCall(config.technitiumPrimaryUrl, request.path, params, token, target);
277
302
  printJson({ node: target, status: parsed.status, response: redactSecrets(parsed.response ?? null) });
278
303
  return 0;
279
304
  }
@@ -195,6 +195,12 @@ describe("dns wrapper", () => {
195
195
  primaryOnly: true,
196
196
  });
197
197
  expect(technitiumRequest("c", ["cluster-delete"]).params).toEqual({ forceDelete: "false" });
198
+ expect(technitiumRequest("c", ["stale-zone-delete", "pdf.37pla.net"])).toEqual({ path: "/api/zones/delete", params: { zone: "pdf.37pla.net" }, primaryOnly: false });
199
+ expect(technitiumRequest("cluster-catalog.dns.home.arpa", ["zone-catalog", "pdf.37pla.net"])).toEqual({
200
+ path: "/api/zones/options/set",
201
+ params: { zone: "pdf.37pla.net", catalog: "cluster-catalog.dns.home.arpa" },
202
+ primaryOnly: true,
203
+ });
198
204
  expect(technitiumRequest("c", ["cluster-remove", "811905692"]).params).toEqual({ secondaryNodeId: "811905692" });
199
205
  expect(technitiumRequest("c", ["server-domain", "technitium1"])).toEqual({ path: "/api/settings/set", params: { dnsServerDomain: "technitium1" }, primaryOnly: false });
200
206
  });