@astrofoundry/pi-astro 0.34.1 → 0.36.0

package/specialists/lib/stack-update.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import type { UpdateRow } from "./image-updates.ts";
+import { commitMessage, containersProblem, crossesMajor, nextImageRef, parseHolds, pendingRows, replaceImageRef, type StackContainer } from "./stack-update.ts";
+
+const A = `sha256:${"a".repeat(64)}`;
+const B = `sha256:${"b".repeat(64)}`;
+
+function row(over: Partial<UpdateRow>): UpdateRow {
+    return { stack: "s", service: "svc", ref: "nginx:1.31.4-alpine", image: "nginx:1.31.4-alpine", kind: "fixed", running: "1.31.4-alpine", latest: "1.31.6-alpine", status: "release", action: "edit tag", note: "", ...over };
+}
+
+describe("update holds", () => {
+    it("reads stack names with a reason", () => {
+        expect(parseHolds('{"supabase": " coordinated release: review first "}')).toEqual({ supabase: "coordinated release: review first" });
+        expect(parseHolds("{}")).toEqual({});
+    });
+
+    it("refuses a malformed file instead of holding nothing", () => {
+        expect(() => parseHolds("not json")).toThrow(/not JSON/);
+        expect(() => parseHolds('["supabase"]')).toThrow(/object of stack name/);
+        expect(() => parseHolds('{"supabase": ""}')).toThrow(/non-empty reason/);
+        expect(() => parseHolds('{"../x": "why"}')).toThrow(/stack name/);
+    });
+});
+
+describe("pending updates", () => {
+    it("keeps the rows an update changes and spots a major version", () => {
+        const rows = [row({ status: "update" }), row({ status: "release" }), row({ status: "rebuild" }), row({ status: "up-to-date" }), row({ status: "unknown" })];
+        expect(pendingRows(rows).map((r) => r.status)).toEqual(["update", "release", "rebuild"]);
+        expect(crossesMajor("2.14.3", "3.0.0")).toBe(true);
+        expect(crossesMajor("v2.16.1", "v2.17.0")).toBe(false);
+        expect(crossesMajor("older build", "3.0.0")).toBe(false);
+    });
+
+    it("moves a pinned tag or digest and leaves pulls to the redeploy", () => {
+        expect(nextImageRef(row({}))).toBe("nginx:1.31.6-alpine");
+        expect(nextImageRef(row({ ref: "registry.local:5000/app:1.2", latest: "1.3" }))).toBe("registry.local:5000/app:1.3");
+        expect(nextImageRef(row({ ref: `ghcr.io/x/y@${A}`, action: "edit digest", latestDigest: B }))).toBe(`ghcr.io/x/y@${B}`);
+        expect(nextImageRef(row({ ref: `ghcr.io/x/y:v1@${A}`, action: "edit digest", latestDigest: B }))).toBe(`ghcr.io/x/y:v1@${B}`);
+        expect(nextImageRef(row({ action: "pull" }))).toBeNull();
+        expect(() => nextImageRef(row({ latest: "new build" }))).toThrow(/cannot move/);
+        expect(() => nextImageRef(row({ ref: `ghcr.io/x/y@${A}`, action: "edit digest", latestDigest: "sha256:short" }))).toThrow(/new digest/);
+    });
+});
+
+describe("Compose rewrite", () => {
+    const compose = [
+        "services:",
+        "  db:",
+        "    image: postgres:18",
+        "  quoted:",
+        '    image: "postgres:18" # pinned on purpose',
+        "  single:",
+        "    image: 'postgres:18'",
+        "  longer:",
+        "    image: postgres:18.1",
+        "  other:",
+        "    image: mypostgres:18",
+        "  mixed:",
+        "    image: \"postgres:18'",
+        "  env:",
+        "    environment:",
+        "      IMAGE: postgres:18",
+        "      image_note: image: postgres:18",
+        "",
+    ].join("\n");
+
+    it("changes only image lines that name exactly the reference", () => {
+        const next = replaceImageRef(compose, "postgres:18", "postgres:19").split("\n");
+        expect(next[2]).toBe("    image: postgres:19");
+        expect(next[4]).toBe('    image: "postgres:19" # pinned on purpose');
+        expect(next[6]).toBe("    image: 'postgres:19'");
+        expect(next.slice(7)).toEqual(compose.split("\n").slice(7));
+    });
+
+    it("treats the reference as text, not a pattern, and refuses a file without it", () => {
+        expect(replaceImageRef("    image: a.b:1+x\n    image: aXb:1+x\n", "a.b:1+x", "a.b:2")).toBe("    image: a.b:2\n    image: aXb:1+x\n");
+        expect(() => replaceImageRef(compose, "postgres:17", "postgres:18")).toThrow(/no "image: postgres:17" line/);
+    });
+});
+
+describe("stack health after a redeploy", () => {
+    const up = (name: string, over: Partial<StackContainer> = {}): StackContainer => ({ name, running: true, state: "running", exitCode: null, health: "healthy", ...over });
+
+    it("passes running containers and finished one-shot jobs", () => {
+        expect(containersProblem([up("db"), up("app", { health: "none" }), up("init", { running: false, state: "exited", exitCode: 0 })], 3)).toBeNull();
+    });
+
+    it("names missing, stopped, unhealthy, and starting containers", () => {
+        expect(containersProblem([up("db")], 2)).toBe("1 of 2 services have a container");
+        expect(containersProblem([up("db"), up("init", { running: false, state: "exited", exitCode: 1 })], 2)).toBe("not running: init");
+        expect(containersProblem([up("db", { health: "unhealthy" }), up("app", { health: "starting" })], 2)).toBe("health: db (unhealthy), app (starting)");
+    });
+});
+
+describe("commit message", () => {
+    it("names the stack and every moved reference on one short line", () => {
+        expect(commitMessage("media", [{ service: "sonarr", from: "a:1", to: "a:2" }, { service: "radarr", from: "b:1", to: "b:2" }])).toBe("media: sonarr a:1 -> a:2, radarr b:1 -> b:2");
+        expect(commitMessage("s", Array.from({ length: 20 }, () => ({ service: "x", from: "y:1", to: "y:2" }))).length).toBe(200);
+    });
+});

package/specialists/lib/stack-update.ts

@@ -0,0 +1,115 @@
+import { UsageError } from "./errors.ts";
+import { parseTag, type UpdateRow } from "./image-updates.ts";
+import { parseImageRef } from "./registry.ts";
+
+/** Stacks whose updates wait for a person, tracked in the root of the GitOps repository: `{ "<stack>": "<reason>" }`. */
+export const HOLDS_FILE = "update-holds.json";
+const STACK = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+
+/** The held stacks with their reasons; a malformed file is an error, never "nothing held". */
+export function parseHolds(text: string): Record<string, string> {
+    let value: unknown;
+    try {
+        value = JSON.parse(text);
+    } catch {
+        throw new UsageError(`${HOLDS_FILE} is not JSON`);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) throw new UsageError(`${HOLDS_FILE} must be an object of stack name to reason`);
+    const holds: Record<string, string> = {};
+    for (const [stack, reason] of Object.entries(value)) {
+        if (!STACK.test(stack) || typeof reason !== "string" || reason.trim().length === 0) throw new UsageError(`${HOLDS_FILE}: "${stack.slice(0, 40)}" needs a stack name and a non-empty reason`);
+        holds[stack] = reason.trim().slice(0, 200);
+    }
+    return holds;
+}
+
+/** True when the update moves to a newer major version, read from the first number of both release tags. */
+export function crossesMajor(running: string, latest: string): boolean {
+    const a = parseTag(running);
+    const b = parseTag(latest);
+    return a !== null && b !== null && b.nums[0] > a.nums[0];
+}
+
+/** The rows of one stack that an update changes. */
+export function pendingRows(rows: readonly UpdateRow[]): UpdateRow[] {
+    return rows.filter((r) => r.status === "update" || r.status === "release" || r.status === "rebuild");
+}
+
+/**
+ * The image reference a pinned row moves to: the newer tag for `edit tag`, the
+ * newer digest for `edit digest`; null for rows a redeploy with a pull applies.
+ */
+export function nextImageRef(row: UpdateRow): string | null {
+    if (row.action === "edit tag") {
+        const ref = parseImageRef(row.ref);
+        if (ref.digest || !ref.tag || !parseTag(row.latest)) throw new UsageError(`${row.service}: cannot move ${row.ref} to tag ${row.latest}`);
+        if (!row.ref.endsWith(`:${ref.tag}`)) throw new UsageError(`${row.service}: ${row.ref} does not end with its tag`);
+        return `${row.ref.slice(0, row.ref.length - ref.tag.length)}${row.latest}`;
+    }
+    if (row.action === "edit digest") {
+        const at = row.ref.indexOf("@");
+        if (at < 0 || !row.latestDigest || !/^sha256:[0-9a-f]{64}$/.test(row.latestDigest)) throw new UsageError(`${row.service}: cannot move ${row.ref} to a new digest`);
+        return `${row.ref.slice(0, at)}@${row.latestDigest}`;
+    }
+    return null;
+}
+
+function escapeRegExp(text: string): string {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * The Compose file with every `image:` line that names exactly `oldRef`
+ * (quoted or not, with an optional trailing comment) changed to `newRef`.
+ * Any other mention of the reference, or a longer reference that starts with
+ * it, stays as it is. Refuses a file without such a line.
+ */
+export function replaceImageRef(compose: string, oldRef: string, newRef: string): string {
+    const line = new RegExp(`^(\\s*image:\\s*)(["']?)${escapeRegExp(oldRef)}\\2(\\s*(?:#.*)?)$`, "gm");
+    let count = 0;
+    const next = compose.replace(line, (_all, head: string, quote: string, tail: string) => {
+        count++;
+        return `${head}${quote}${newRef}${quote}${tail}`;
+    });
+    if (count === 0) throw new UsageError(`the Compose file has no "image: ${oldRef}" line`);
+    return next;
+}
+
+export type StackStatus = "updated" | "rolled back" | "failed" | "nothing to do";
+
+export interface ServiceResult {
+    service: string;
+    ref: string;
+    from: string;
+    to: string;
+    /** `pull` (redeploy with a pull) or the reference written into the Compose file. */
+    applied: string;
+    /** After the update: current, still behind, or not checked. */
+    result: "current" | "behind" | "unchecked";
+}
+
+/** One container of the stack after a redeploy, as `containers get` reports it. */
+export interface StackContainer {
+    name: string;
+    running: boolean | null;
+    state: string | null;
+    exitCode: number | null;
+    health: string;
+}
+
+/**
+ * Why the stack is not healthy yet, or null when every container runs (or, as
+ * a one-shot job, exited with code 0) and none is unhealthy or still starting.
+ */
+export function containersProblem(containers: readonly StackContainer[], expected: number): string | null {
+    if (containers.length < expected) return `${containers.length} of ${expected} services have a container`;
+    const down = containers.filter((c) => c.running !== true && !(c.state === "exited" && c.exitCode === 0)).map((c) => c.name);
+    if (down.length > 0) return `not running: ${down.join(", ")}`;
+    const sick = containers.filter((c) => c.health === "unhealthy" || c.health === "starting").map((c) => `${c.name} (${c.health})`);
+    return sick.length > 0 ? `health: ${sick.join(", ")}` : null;
+}
+
+/** A commit subject that names the stack and every reference it changes. */
+export function commitMessage(stack: string, edits: readonly { service: string; from: string; to: string }[]): string {
+    return `${stack}: ${edits.map((e) => `${e.service} ${e.from} -> ${e.to}`).join(", ")}`.slice(0, 200);
+}

package/specialists/provision/provision.sh

@@ -12,8 +12,8 @@ client_file="$config_dir/client.env"
 password_file="$config_dir/master-password"
 root="$home/.specialists"
 collection_name="${SPECIALISTS_COLLECTION:-specialists}"
-BW=/opt/homebrew/bin/bw
-JQ=/opt/homebrew/bin/jq
+BW=/usr/local/libexec/specialist-bw/current/bw
+JQ=/usr/local/libexec/specialist-jq/current/jq
 
 for f in "$client_file" "$password_file"; do
   [ -f "$f" ] || { echo "missing $f" >&2; exit 2; }

package/specialists/wrappers.test.ts

@@ -7,7 +7,7 @@ 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, isTransientSshFailure, PUBLIC_ROUTES, routeProbe } 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 { buildInferenceRemote, command as inferenceCommand } from "./inference/run.ts";
 import { MAX_ADD_IDS, buildTrendarrCall, interpretRun, parseImdbIds, trendarrConfig, trendarrError, trendarrWarnings, command as mediaCommand } from "./media/run.ts";
 import { ServiceError, UsageError } from "./lib/errors.ts";
 import { safeRepoPath, safeWritePath } from "./lib/repo.ts";
@@ -44,6 +44,7 @@ describe("arcane wrapper", () => {
         expect(await arcaneCommand(["--help"])).toBe(0);
         expect(String(write.mock.calls[0][0])).toContain("git write");
         expect(String(write.mock.calls[0][0])).toContain("git show");
+        expect(String(write.mock.calls[0][0])).toContain("stack-update <stack> [--confirm]");
         expect(String(write.mock.calls[0][0])).not.toMatch(/^\s+gitops /m);
         write.mockRestore();
     });
@@ -189,7 +190,7 @@ describe("edge wrapper", () => {
         const curl = async (args: string[]) => {
             seen.push(args);
             const url = args.at(-1) ?? "";
-            return { stdout: url.includes("/auth/v1/settings") ? "401 0.12" : url.includes("studio") || url.includes("mealie") ? "302 0.10" : "200 0.05", code: 0 };
+            return { stdout: url.includes("/auth/v1/settings") ? "401 0.12" : url.includes("oauth-authorization-server") ? "404 0.08" : url.includes("studio") || url.includes("mealie") ? "302 0.10" : "200 0.05", code: 0 };
         };
         const all = await routeProbe([], curl);
         expect(all).toHaveLength(Object.keys(PUBLIC_ROUTES).length);
@@ -429,31 +430,21 @@ describe("proxmox wrapper", () => {
 });
 
 describe("inference wrapper", () => {
-    it("maps commands to targets and enforces confirmation", () => {
-        expect(buildInferenceRemote(["nexus-status"])).toMatchObject({ remote: "nexus-status", spec: { target: "nexus" } });
+    it("maps commands to fixed remote strings and enforces confirmation", () => {
+        expect(buildInferenceRemote(["nexus-status"]).remote).toBe("nexus-status");
         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: "" });
+        expect(() => buildInferenceRemote(["hermes-status"])).toThrow(/unknown command/);
     });
 
     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");
+        expect(String(write.mock.calls[0][0])).toContain("europa-health");
         write.mockRestore();
     });
 });

package/specialists/entry/remote/spc-inference-hermes-entry.sh

@@ -1,27 +0,0 @@
-#!/bin/sh
-# Forced command for the spc-inference key on LXC 101 (user hermes, no sudo).
-# authorized_keys line in /home/hermes/.ssh/authorized_keys:
-#   command="/usr/local/sbin/spc-inference-hermes-entry",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 AAAA... spc-inference-hermes@cortex
-set -eu
-export PATH="$HOME/.local/bin:$HOME/.hermes/hermes-agent/venv/bin:/usr/local/bin:/usr/bin:/bin"
-export XDG_RUNTIME_DIR="/run/user/$(id -u)"
-cmd="${SSH_ORIGINAL_COMMAND:-}"
-name="${cmd%% *}"
-rest=""
-[ "$cmd" != "$name" ] && rest="${cmd#* }"
-since_ok() { printf '%s' "$1" | grep -Eq '^[A-Za-z0-9 :+-]{1,40}$'; }
-units="hermes-gateway.service hermes-gateway-api.service"
-
-case "$name" in
-  hermes-status) systemctl --user status $units --no-pager --lines=5 || true ;;
-  hermes-journal) since_ok "$rest" || { echo "bad since" >&2; exit 2; }; journalctl --user -u hermes-gateway.service -u hermes-gateway-api.service --since "$rest" --no-pager -n 200 ;;
-  hermes-errors) hermes logs errors ;;
-  hermes-restart)
-    case "$rest" in gateway) u=hermes-gateway.service ;; api) u=hermes-gateway-api.service ;; *) echo "bad service" >&2; exit 2 ;; esac
-    systemctl --user restart "$u"; sleep 3; systemctl --user status "$u" --no-pager --lines=5 || true ;;
-  hermes-api-health)
-    printf 'health=%s\n' "$(curl -s -o /dev/null -w '%{http_code}' -m 5 http://localhost:8650/health || echo 000)"
-    printf 'models=%s (401 expected)\n' "$(curl -s -o /dev/null -w '%{http_code}' -m 5 http://localhost:8650/v1/models || echo 000)" ;;
-  hermes-version) hermes --version | head -1 ;;
-  *) echo "refused: $cmd" >&2; exit 2 ;;
-esac

package/specialists/entry/remote/spc-inference-pulsar-entry.sh

@@ -1,14 +0,0 @@
-#!/bin/sh
-# Forced command for the spc-inference key on Pulsar (root): Hermes guest operations.
-# authorized_keys line:
-#   command="/usr/local/sbin/spc-inference-pulsar-entry",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 AAAA... spc-inference-pulsar@cortex
-set -eu
-export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-cmd="${SSH_ORIGINAL_COMMAND:-}"
-
-case "$cmd" in
-  hermes-guest-status) pct status 101 ;;
-  hermes-snapshots) pct listsnapshot 101 ;;
-  hermes-upgrade) /usr/local/bin/hermes-upgrade ;;
-  *) echo "refused: $cmd" >&2; exit 2 ;;
-esac