@astrofoundry/pi-astro 0.29.1 → 0.31.0

package/README.md

@@ -1,6 +1,6 @@
 # @astrofoundry/pi-astro
 
-Personal customizations for the [pi coding agent](https://github.com/earendil-works/pi): 25 subagents (8 general-purpose, 8 Flourish-pipeline, 9 homelab specialists) run by the bundled `astro-subagents` extension, a `grimoire` docs tool, a `caveman` compressed-output toggle, an `astro-footer` status bar, 14 skills, and an `astro` theme.
+Personal customizations for the [pi coding agent](https://github.com/earendil-works/pi): 26 subagents (8 general-purpose, 8 Flourish-pipeline, 10 homelab specialists) run by the bundled `astro-subagents` extension, a `grimoire` docs tool, a `caveman` compressed-output toggle, an `astro-footer` status bar, 15 skills, and an `astro` theme.
 
 ## Full setup
 
@@ -68,8 +68,8 @@ pi                # launch; confirm [Extensions] lists astro-subagents, grimoire
 - `multi-edit` - registers the enhanced `edit` tool
 - `gemini-image` - registers `gemini_image` tool (requires a Gemini API key; prompts and saves on first use)
 - `security-guard` - blocks/prompts destructive bash commands and sensitive file access; configure at `~/.pi/agent/security-guard.json` (example written on first run); `/security-guard status|reload|test`
-- `astro-discord` - Discord access to the specialists: in the configured channels, `<specialist> <task>` runs `astro.<specialist>` and posts the answer as a reply (⏳ running, 🔒 waiting for an owner's approval of a risky call, ✅ done, ❌ failed). Owners may use every specialist and approve risky calls with buttons; other users only the specialists listed for them; everyone else is ignored. Inert unless the headless host sets `ASTRO_DISCORD=1`; setup with `d=$(mktemp -d) && cp ~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro/extensions/astro-discord/*.ts "$d" && node --disable-warning=ExperimentalWarning "$d/setup.ts"` (Node refuses to strip types inside `node_modules`, hence the copy), which prompts for the bot token and ids, checks them against Discord, and writes the LaunchAgent. See [specialists/README.md](specialists/README.md#discord).
-- `specialist-gate` - gives each specialist agent (`astro.arcane`, `astro.identity`, `astro.network`, `astro.dns`, `astro.edge`, `astro.security`, `astro.backup`, `astro.proxmox`, `astro.inference`) its single tool, which runs the matching CLI wrapper as a dedicated macOS user through `sudo`, and blocks every other agent from calling those CLIs or reading their credentials. Inactive until the host has `~/.pi/agent/specialists.json`. `/specialists` prints the status. Host setup is described in [specialists/README.md](specialists/README.md).
+- `astro-discord` - Discord access to the specialists: in the configured channels, `<specialist> <task>` runs `astro.<specialist>` and posts the answer as a reply (⏳ running, 🔒 waiting for an owner's approval of a risky call, ✅ done, ❌ failed). Owners may use every specialist and approve risky calls with buttons; other users only the specialists listed for them; everyone else is ignored. Where the `media` specialist is present, `/trending`, `/search`, and `/downloads` answer without a model, with an Add button beside each title. Inert unless the headless host sets `ASTRO_DISCORD=1`; setup with `d=$(mktemp -d) && cp ~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro/extensions/astro-discord/*.ts "$d" && node --disable-warning=ExperimentalWarning "$d/setup.ts"` (Node refuses to strip types inside `node_modules`, hence the copy), which prompts for the bot token and ids, checks them against Discord, and writes the LaunchAgent. See [specialists/README.md](specialists/README.md#discord).
+- `specialist-gate` - gives each specialist agent (`astro.arcane`, `astro.identity`, `astro.network`, `astro.dns`, `astro.edge`, `astro.security`, `astro.backup`, `astro.proxmox`, `astro.inference`, `astro.media`) its single tool, which runs the matching CLI wrapper as a dedicated macOS user through `sudo`, and blocks every other agent from calling those CLIs or reading their credentials. Inactive until the host has `~/.pi/agent/specialists.json`. `/specialists` prints the status. Host setup is described in [specialists/README.md](specialists/README.md).
 - `notify-on-stop` - runs a shell command when the agent finishes a turn (sound, voice, desktop notification). **Default: off.** Enable with `/notify on` (state persists in `~/.pi/agent/notify-on-stop.json`); disable with `/notify off`. macOS default command: plays the Glass system sound and speaks "Agent done" via `say` using the **`Samantha (Enhanced)`** voice. Linux default: `notify-send "pi" "Agent done"`. Override the voice with `PI_STOP_NOTIFY_VOICE=<voice-name>` (macOS only; e.g. `Alex`, `Karen`, `Daniel (Enhanced)`). Replace the full command with `PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff && say "Done"'`. Hard-kill (overrides `/notify on`) with `PI_STOP_NOTIFY_OFF=1`. Commands: `/notify [on|off|status|test]`. See [extensions/notify-on-stop/README.md](extensions/notify-on-stop/README.md) for full details.
   - **macOS voice install (required once for the default):** open **System Settings, Accessibility, Spoken Content, System Voice, Manage Voices...**, expand **English**, check **Samantha (Enhanced)**, click **Done** to download (~500 MB to 1 GB). Verify with `say -v "Samantha (Enhanced)" hi`. If the voice is missing, `say` errors silently and you'll only hear the Glass sound.
 - `vscode-image` - only active inside VS Code's integrated terminal (`TERM_PROGRAM=vscode`). Switches pi-tui's image output to the **Kitty graphics protocol** so images returned by tools like `gemini_image` render as real pixels instead of the `[Image: ...]` text fallback. **Requires enabling `Terminal > Integrated: Enable Images` in VS Code settings** (off by default); restart the integrated terminal after flipping it. Disable with `PI_VSCODE_IMAGE_OFF=1`. `/vscode-image` prints current status.
@@ -80,11 +80,11 @@ pi                # launch; confirm [Extensions] lists astro-subagents, grimoire
 
 **Bundled subagents** (call them as `astro.<name>`):
 - General-purpose: `code-reviewer`, `google-tech-lead`, `spec-writer`, `tester-api`, `tester-ui`, `ui-architect`, `ui-design-system`, `ui-frontend-developer`
-- Specialists (one homelab area each, need the host setup in [specialists/README.md](specialists/README.md)): `arcane` (Arcane container platform, GitOps first), `identity` (Zitadel, Pomerium routes through the homelab repository, certificates), `network` (UniFi reads and firewall policies, FreeRADIUS, Tailscale), `dns` (Technitium resolvers, Cloudflare zones), `edge` (Frontdoor VPS over IAP, nginx SNI allowlist through the homelab repository), `security` (Wazuh, CrowdSec, log archive, read-only), `backup` (vzdump, Restic layers, GCS offsite, restore tests), `proxmox` (guest lifecycle, snapshots, resources; no create or destroy), `inference` (llama.cpp on Nexus, Hermes gateways and upgrades, Europa health)
+- Specialists (one homelab area each, need the host setup in [specialists/README.md](specialists/README.md)): `arcane` (Arcane container platform, GitOps first), `identity` (Zitadel, Pomerium routes through the homelab repository, certificates), `network` (UniFi reads and firewall policies, FreeRADIUS, Tailscale), `dns` (Technitium resolvers, Cloudflare zones), `edge` (Frontdoor VPS over IAP, nginx SNI allowlist through the homelab repository), `security` (Wazuh, CrowdSec, log archive, read-only), `backup` (vzdump, Restic layers, GCS offsite, restore tests), `proxmox` (guest lifecycle, snapshots, resources; no create or destroy), `inference` (llama.cpp on Nexus, Hermes gateways and upgrades, Europa health), `media` (trendarr: trending titles, Radarr and Sonarr adds, SABnzbd pause)
 - Flourish pipeline: `flourish-input-vision` (image to spec), `flourish-input-narrative` (text to spec), `flourish-input-codebase` (HTML to spec), `flourish-architect` (spec to plan), `flourish-template-developer` (plan to SDK template, needs `@flourish/sdk`), `flourish-example-builder` (template to realistic example), `flourish-preview-runner` (multi-breakpoint preview + screenshots, needs `@flourish/sdk`), `flourish-reviewer` (audit)
 
 **Skills** (loadable via `/skill:<name>`):
-- `playwright-cli`, `postman-cli`, `raycast-script-creator`, `caveman`, `flourish-chart-spec`, `arcane`, `identity`, `network`, `dns`, `edge`, `security`, `backup`, `proxmox`, `inference` (the last nine are injected into their specialist agents)
+- `playwright-cli`, `postman-cli`, `raycast-script-creator`, `caveman`, `flourish-chart-spec`, `arcane`, `identity`, `network`, `dns`, `edge`, `security`, `backup`, `proxmox`, `inference`, `media` (the last ten are injected into their specialist agents)
 
 **Theme:**
 - `astro` - dark, gold accent, GitHub-dark-inspired

package/agents/media.md

@@ -0,0 +1,24 @@
+---
+name: media
+description: Manages the movie and series library through the media tool (trendarr), covering weekly trending with IMDb ratings, title search, adds to Radarr and Sonarr, and the SABnzbd queue pause state. Use for what is trending, adding a movie or series by name, and pausing or resuming downloads.
+tools: read, media, subagent
+skills: media
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
+maxSubagentDepth: 1
+model: openai-codex/gpt-6-astra
+thinking: xhigh
+---
+You are the media specialist. The `media` tool, which runs the `trendarr` CLI, is your only way to reach TMDB, OMDb, Radarr, Sonarr, and SABnzbd. You have no shell, no web, and no file access; if a task needs anything else, say so and stop.
+
+Rules:
+
+- Search before you add, and add only IMDb IDs that a `search` or `trending` result returned in this conversation. Never invent or guess an ID.
+- Resolve the title with the rules in the skill. A named film or series with one clear match: add it without asking. Ask one short question only when several plausible works remain and the choice changes what gets added.
+- Movies go to `add-movies`, series to `add-series`; batch independent IDs in one call.
+- Success needs an explicit `added` or `already_exists` in `results`; `already_exists` means it was already there, not newly added. Report every ID of a batch.
+- Pause or resume downloads only when the task asks for it, then report the returned state. Adding never implies a queue change.
+- Keep replies short: canonical title and year, outcome, and the SABnzbd state an add returned. Mention `/trending` and `/search` when the user would rather click Add buttons.
+- Library settings, quality profiles, Radarr and Sonarr configuration, and deletions are operator tasks; say so and stop.
+- Delegate through `subagent` only to another specialist (`astro.arcane` for the media containers on the Arcane VM) and only for that specialist's own area.

package/extensions/astro-discord/admin.ts

@@ -32,6 +32,7 @@ export function describeConfig(config: DiscordConfig): string {
         access.length > 0 ? "Extra access:" : "Extra access: none",
         ...access,
         `Approval timeout: ${config.approvalTimeoutMinutes} min`,
+        config.dailyReport ? `Arcane daily report: ${config.dailyReport.time} ${config.dailyReport.timeZone} in <#${config.dailyReport.channelId}>` : "Arcane daily report: off",
     ].join("\n");
 }
 

package/extensions/astro-discord/commands.ts

@@ -59,6 +59,7 @@ export function helpText(allowed: readonly string[], present: readonly string[],
     if (present.length > 1) lines.push(...allowed.map((name) => `• \`${name}\``));
     lines.push("Reactions: ⏳ running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed.");
     lines.push("A reply to my answer, or another task for the same specialist within 30 minutes, continues that conversation; start the task with `new` for a fresh one.");
+    if (allowed.includes("media")) lines.push("Slash commands `/trending`, `/search`, and `/downloads` answer directly, without the agent; an Add button adds that title at once.");
     const commands = ["`help` this message", "`status` running tasks"];
     if (canConfig) commands.push("`config show`", "`config channel <#channel> <always|mention> <*|name,name>`", "`config access <specialist> add|remove <@user>`");
     lines.push(`Commands: ${commands.join(", ")}.`);

package/extensions/astro-discord/config.ts

@@ -26,6 +26,8 @@ export interface DiscordConfig {
     /** Extra users per specialist name (without the astro. prefix). */
     access: Record<string, string[]>;
     approvalTimeoutMinutes: number;
+    /** Optional scheduled Arcane version report. */
+    dailyReport?: { channelId: string; time: string; timeZone: string };
 }
 
 export const SNOWFLAKE = /^\d{17,20}$/;
@@ -90,6 +92,7 @@ export function validateConfig(raw: unknown, errors: string[]): DiscordConfig |
     }
     const timeout = r.approvalTimeoutMinutes;
     if (typeof timeout !== "number" || !Number.isInteger(timeout) || timeout < 1 || timeout > 240) errors.push("approvalTimeoutMinutes must be an integer from 1 to 240");
+    const dailyReport = r.dailyReport === undefined ? undefined : validateDailyReport(r.dailyReport, errors);
     if (errors.length > 0) return null;
     return {
         applicationId: r.applicationId as string,
@@ -99,9 +102,30 @@ export function validateConfig(raw: unknown, errors: string[]): DiscordConfig |
         owners,
         access,
         approvalTimeoutMinutes: timeout as number,
+        ...(dailyReport ? { dailyReport } : {}),
     };
 }
 
+function validateDailyReport(raw: unknown, errors: string[]): DiscordConfig["dailyReport"] | undefined {
+    const r = raw as Record<string, unknown> | null;
+    if (typeof r !== "object" || r === null) {
+        errors.push("dailyReport must be an object");
+        return undefined;
+    }
+    if (typeof r.channelId !== "string" || !SNOWFLAKE.test(r.channelId)) errors.push("dailyReport.channelId must be a Discord id");
+    if (typeof r.time !== "string" || !/^([01]\d|2[0-3]):[0-5]\d$/.test(r.time)) errors.push("dailyReport.time must be HH:MM");
+    let zoneOk = typeof r.timeZone === "string";
+    if (zoneOk) {
+        try {
+            new Intl.DateTimeFormat("en", { timeZone: r.timeZone as string });
+        } catch {
+            zoneOk = false;
+        }
+    }
+    if (!zoneOk) errors.push("dailyReport.timeZone must be an IANA time zone such as Europe/Madrid");
+    return errors.length > 0 ? undefined : { channelId: r.channelId as string, time: r.time as string, timeZone: r.timeZone as string };
+}
+
 export function validateChannel(raw: unknown, where: string, errors: string[]): ChannelSettings | null {
     if (typeof raw !== "object" || raw === null) {
         errors.push(`${where} must be an object`);

package/extensions/astro-discord/daily-report.test.ts

@@ -0,0 +1,109 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { validateConfig } from "./config.ts";
+import { displayVersion, failureMessage, formatDailyReport, isDue, readReportState, REPORT_PREFIX, writeReportState, zonedNow } from "./daily-report.ts";
+
+const settings = { channelId: "1549873938140499999", time: "06:00", timeZone: "Europe/Madrid" };
+
+describe("daily report schedule", () => {
+    it("follows Madrid's daylight-saving offsets", () => {
+        expect(zonedNow("Europe/Madrid", new Date("2026-01-15T05:00:00Z"))).toEqual({ date: "2026-01-15", minutes: 360 });
+        expect(zonedNow("Europe/Madrid", new Date("2026-07-15T04:00:00Z"))).toEqual({ date: "2026-07-15", minutes: 360 });
+        expect(zonedNow("Europe/Madrid", new Date("2026-10-25T05:00:00Z"))).toEqual({ date: "2026-10-25", minutes: 360 });
+    });
+
+    it("is due once per local date, from the configured time on", () => {
+        const before = new Date("2026-07-15T03:59:00Z");
+        const at = new Date("2026-07-15T04:00:00Z");
+        const later = new Date("2026-07-15T09:30:00Z");
+        expect(isDue(settings, null, before)).toEqual({ due: false, date: "2026-07-15" });
+        expect(isDue(settings, null, at)).toEqual({ due: true, date: "2026-07-15" });
+        expect(isDue(settings, null, later).due).toBe(true);
+        expect(isDue(settings, { date: "2026-07-15", status: "sending" }, later).due).toBe(false);
+        expect(isDue(settings, { date: "2026-07-14", status: "sent" }, later).due).toBe(true);
+    });
+
+    it("keeps its state across processes", () => {
+        const dir = mkdtempSync(join(tmpdir(), "astro-report-"));
+        process.env.ASTRO_DISCORD_DIR = dir;
+        try {
+            expect(readReportState()).toBeNull();
+            writeReportState({ date: "2026-10-19", status: "sent", messageId: "1" });
+            expect(readReportState()).toEqual({ date: "2026-10-19", status: "sent", messageId: "1" });
+        } finally {
+            delete process.env.ASTRO_DISCORD_DIR;
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+
+describe("daily report message", () => {
+    let base: Record<string, unknown>;
+    beforeEach(() => {
+        base = { checkedAt: "2026-10-19T04:00:05Z", stacks: 19, images: 44, privateImages: ["a", "b"], counts: {}, rows: [] };
+    });
+    afterEach(() => undefined);
+
+    it("lists each service as current to target, unresolved where no release tag matches", () => {
+        const report = {
+            ...base,
+            rows: [
+                { stack: "crawl4ai", service: "crawl4ai", running: "0.9.3", latest: "0.9.4", status: "update", action: "pull", note: "" },
+                { stack: "media", service: "sonarr", running: "4.0.20.3014-ls325", latest: "4.0.20.3014-ls326", status: "update", action: "pull", note: "" },
+                { stack: "qdrant", service: "volume-init", running: "older build", latest: "1.38.0", status: "update", action: "pull", note: "" },
+                { stack: "profiles", service: "profiles", running: "1.31.4-alpine", latest: "1.31.6-alpine", status: "release", action: "edit tag", note: "" },
+                { stack: "arcane", service: "arcane", running: "v2.16.1", latest: "v2.17.0", status: "update", action: "edit digest", note: "" },
+                { stack: "stirling-pdf", service: "stirling-pdf", running: "2.14.3", latest: "3.0.0", status: "update", action: "pull", note: "major version change: read its release notes before pulling" },
+                { stack: "bigcapital", service: "gotenberg", running: "7.10.2", latest: "7.10.2", status: "up-to-date", action: "", note: "newer major 8 available (tag change)" },
+                { stack: "x", service: "y", running: "?", latest: "?", status: "unknown", action: "", note: "stale" },
+            ],
+        };
+        const { content, attachment } = formatDailyReport(report, "Europe/Madrid");
+        expect(attachment).toBeUndefined();
+        expect(content.split("\n")).toEqual([
+            `${REPORT_PREFIX} 6 updates (44 public images, 2 private excluded, checked 06:00 CEST).`,
+            "• crawl4ai: 0.9.3 → 0.9.4",
+            "• media/sonarr: 4.0.20.3014-ls325 → 4.0.20.3014-ls326",
+            "• qdrant/volume-init: unresolved → 1.38.0",
+            "• profiles: 1.31.4-alpine → 1.31.6-alpine (tag change)",
+            "• arcane: v2.16.1 → v2.17.0 (digest change)",
+            "• stirling-pdf: 2.14.3 → 3.0.0; major version change",
+            "• bigcapital/gotenberg: newer major 8 available (tag change)",
+            "• x/y: unresolved (check failed)",
+            "Checks only; nothing was updated.",
+        ]);
+        expect(content).not.toMatch(/sha256/);
+    });
+
+    it("says so when nothing needs updating, and moves a long list to an attachment", () => {
+        expect(formatDailyReport(base, "Europe/Madrid").content).toBe(`${REPORT_PREFIX} no updates (44 public images, 2 private excluded, checked 06:00 CEST).\nChecks only; nothing was updated.`);
+        const rows = Array.from({ length: 60 }, (_, i) => ({ stack: `stack-${i}`, service: `service-${i}`, running: "1.0.0", latest: "1.0.1", status: "update", action: "pull", note: "" }));
+        const long = formatDailyReport({ ...base, rows }, "Europe/Madrid");
+        expect(long.content).toContain("The full list is attached.");
+        expect(long.attachment?.split("\n")).toHaveLength(61);
+        expect(formatDailyReport({ nonsense: true }, "Europe/Madrid").content).toBe(failureMessage());
+        expect(failureMessage().startsWith(REPORT_PREFIX)).toBe(true);
+    });
+
+    it("never prints anything that is not a release tag", () => {
+        expect(displayVersion("v1.2.3")).toBe("v1.2.3");
+        expect(displayVersion("17 (older build)")).toBe("unresolved");
+        expect(displayVersion("sha256:abcdef")).toBe("unresolved");
+        expect(displayVersion(undefined)).toBe("unresolved");
+    });
+});
+
+describe("daily report config", () => {
+    const valid = { applicationId: "123456789012345678", guildId: "123456789012345678", channels: { "123456789012345678": { trigger: "always", specialists: "*" } }, adminChannelId: "123456789012345678", owners: ["123456789012345678"], access: {}, approvalTimeoutMinutes: 30 };
+    it("accepts a valid schedule and rejects a bad zone or time", () => {
+        const errors: string[] = [];
+        expect(validateConfig({ ...valid, dailyReport: settings }, errors)?.dailyReport).toEqual(settings);
+        expect(validateConfig({ ...valid, dailyReport: { ...settings, timeZone: "Mars/Olympus" } }, errors)).toBeNull();
+        expect(errors.join(" ")).toMatch(/IANA/);
+        const more: string[] = [];
+        expect(validateConfig({ ...valid, dailyReport: { ...settings, time: "6:00" } }, more)).toBeNull();
+        expect(validateConfig(valid, [])?.dailyReport).toBeUndefined();
+    });
+});

package/extensions/astro-discord/daily-report.ts

@@ -0,0 +1,122 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir } from "./config.ts";
+
+/** Every scheduled report starts with this, so it stands apart from conversations in the same channel. */
+export const REPORT_PREFIX = "Arcane Daily Report:";
+const MESSAGE_LIMIT = 1900;
+
+/** `dailyReport` in config.json: where and when the bridge posts the Arcane version report. */
+export interface DailyReportSettings {
+    channelId: string;
+    /** Local wall-clock time, `HH:MM`, in `timeZone`. */
+    time: string;
+    /** IANA zone such as `Europe/Madrid`; daylight-saving changes follow from it. */
+    timeZone: string;
+}
+
+export interface DailyReportState {
+    /** Local date in the report's time zone, `YYYY-MM-DD`. */
+    date: string;
+    status: "sending" | "sent" | "failed";
+    messageId?: string;
+}
+
+/** Local date and minutes past midnight in a time zone. */
+export function zonedNow(timeZone: string, now: Date): { date: string; minutes: number } {
+    const parts = new Intl.DateTimeFormat("en-CA", { timeZone, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).formatToParts(now);
+    const get = (type: string) => parts.find((p) => p.type === type)?.value ?? "";
+    return { date: `${get("year")}-${get("month")}-${get("day")}`, minutes: Number(get("hour")) * 60 + Number(get("minute")) };
+}
+
+/**
+ * Due once per local date, from the configured time on: a bridge that was down
+ * at 06:00 reports when it comes back that day. Any record for today, even a
+ * failed or interrupted send, means no second message.
+ */
+export function isDue(settings: DailyReportSettings, state: DailyReportState | null, now: Date): { due: boolean; date: string } {
+    const { date, minutes } = zonedNow(settings.timeZone, now);
+    const [h, m] = settings.time.split(":").map(Number);
+    return { due: minutes >= h * 60 + m && state?.date !== date, date };
+}
+
+function statePath(): string {
+    return join(configDir(), "daily-report.json");
+}
+
+export function readReportState(): DailyReportState | null {
+    try {
+        const raw = JSON.parse(readFileSync(statePath(), "utf-8")) as Partial<DailyReportState>;
+        return typeof raw.date === "string" && typeof raw.status === "string" ? (raw as DailyReportState) : null;
+    } catch {
+        return null;
+    }
+}
+
+export function writeReportState(state: DailyReportState): void {
+    const tmp = `${statePath()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+    renameSync(tmp, statePath());
+}
+
+/** A release tag as reported, or "unresolved" for anything that is not one (`older build`, `new build`, `?`). Never a digest. */
+export function displayVersion(value: unknown): string {
+    return typeof value === "string" && /^v?[0-9][A-Za-z0-9.+_-]{0,100}$/.test(value) ? value : "unresolved";
+}
+
+interface ReportRow {
+    stack: string;
+    service: string;
+    running: unknown;
+    latest: unknown;
+    status: string;
+    action?: string;
+    note?: string;
+}
+
+interface UpdateReport {
+    checkedAt: string;
+    images: number;
+    privateImages: unknown[];
+    rows: ReportRow[];
+}
+
+function isReport(value: unknown): value is UpdateReport {
+    const r = value as Partial<UpdateReport> | null;
+    return !!r && typeof r.checkedAt === "string" && typeof r.images === "number" && Array.isArray(r.privateImages) && Array.isArray(r.rows);
+}
+
+function clock(iso: string, timeZone: string): string {
+    return new Intl.DateTimeFormat("en-GB", { timeZone, hour: "2-digit", minute: "2-digit", hourCycle: "h23", timeZoneName: "short" }).format(new Date(iso));
+}
+
+function name(row: ReportRow): string {
+    return row.service === row.stack ? row.stack : `${row.stack}/${row.service}`;
+}
+
+/** One line per service: current to target version, with how the update applies when it is not a plain pull. */
+function line(row: ReportRow): string | null {
+    const major = /newer major (\S+) available/.exec(row.note ?? "");
+    if (row.status === "up-to-date") return major ? `• ${name(row)}: newer major ${major[1]} available (tag change)` : null;
+    if (row.status === "unknown") return `• ${name(row)}: unresolved (check failed)`;
+    const how = row.status === "rebuild" ? " (rebuild)" : row.action === "edit tag" ? " (tag change)" : row.action === "edit digest" ? " (digest change)" : "";
+    const extra = major ? `; newer major ${major[1]} available` : /major version change/.test(row.note ?? "") ? "; major version change" : "";
+    return `• ${name(row)}: ${displayVersion(row.running)} → ${displayVersion(row.latest)}${how}${extra}`;
+}
+
+/** The Discord message for one `update-report` result; a list too long for one message moves to an attachment. */
+export function formatDailyReport(report: unknown, timeZone: string): { content: string; attachment?: string } {
+    if (!isReport(report)) return { content: failureMessage() };
+    const lines = report.rows.map(line).filter((l): l is string => l !== null);
+    const updates = report.rows.filter((r) => r.status === "update" || r.status === "release" || r.status === "rebuild").length;
+    const scope = `${report.images} public images${report.privateImages.length > 0 ? `, ${report.privateImages.length} private excluded` : ""}, checked ${clock(report.checkedAt, timeZone)}`;
+    const head = updates === 0 && lines.length === 0 ? `${REPORT_PREFIX} no updates (${scope}).` : `${REPORT_PREFIX} ${updates} update${updates === 1 ? "" : "s"} (${scope}).`;
+    const body = [head, ...lines, "Checks only; nothing was updated."].join("\n");
+    if (body.length <= MESSAGE_LIMIT) return { content: body };
+    return { content: `${head}\nThe full list is attached.\nChecks only; nothing was updated.`, attachment: [head, ...lines].join("\n") };
+}
+
+/** Sent when the check itself fails: no list, so nothing reads as up to date. */
+export function failureMessage(): string {
+    return `${REPORT_PREFIX} the version check failed today, so there is no update list. The bridge log on Cortex has the reason.`;
+}