@astrofoundry/pi-astro 0.35.0 → 0.36.0

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

@@ -1,96 +1,322 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseImageRef } from "../../specialists/lib/registry.ts";
+import { configDir } from "./config.ts";
+import { escapeDiscord } from "./media.ts";
 import type { MessageComponent } from "./rest.ts";
+import type { ReleaseNote } from "../../specialists/lib/releases.ts";
+import type { Review, Verdict } from "./tools-report.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;
-
-/** 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";
-}
 
+/** One row of the wrapper's `update-report` JSON, as far as the report reads it. */
 interface ReportRow {
     stack: string;
     service: string;
-    running: unknown;
-    latest: unknown;
+    ref: string;
+    running: string;
+    latest: string;
     status: string;
-    action?: string;
-    note?: string;
+    action: string;
+    note: string;
 }
 
-interface UpdateReport {
+interface UpdateReportJson {
     checkedAt: string;
     images: number;
     privateImages: unknown[];
     rows: ReportRow[];
+    holds?: Record<string, string>;
+    holdsError?: string;
 }
 
-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 isRow(value: unknown): value is ReportRow {
+    const r = value as Partial<ReportRow> | null;
+    return !!r && typeof r.stack === "string" && typeof r.service === "string" && typeof r.status === "string";
 }
 
-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 isReport(value: unknown): value is UpdateReportJson {
+    const r = value as Partial<UpdateReportJson> | null;
+    return !!r && typeof r.checkedAt === "string" && typeof r.images === "number" && Array.isArray(r.privateImages) && Array.isArray(r.rows) && r.rows.every(isRow);
 }
 
-function name(row: ReportRow): string {
-    return row.service === row.stack ? row.stack : `${row.stack}/${row.service}`;
+/** A release tag as reported (`1.2.3`, `v2.17.0`, `2.6.5.5623-ls164`); `new build`, `older build`, `?` and digests are not. */
+export function releaseTag(value: unknown): string | null {
+    return typeof value === "string" && /^v?[0-9][A-Za-z0-9.+_-]{0,100}$/.test(value) ? value : null;
 }
 
-/** 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}`;
+function numbers(tag: string): number[] {
+    return (/^v?(\d+(?:\.\d+)*)/.exec(tag)?.[1] ?? "").split(".").filter(Boolean).map(Number);
 }
 
-/** 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") };
+/** True when the second tag's first number is higher: an update across a major version. */
+export function crossesMajor(running: string | null, latest: string | null): boolean {
+    if (!running || !latest) return false;
+    const [a] = numbers(running);
+    const [b] = numbers(latest);
+    return a !== undefined && b !== undefined && b > a;
 }
 
-/** 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.`;
+const PENDING = new Set(["update", "release", "rebuild"]);
+
+export interface ServiceLine {
+    service: string;
+    status: string;
+    action: string;
+    running: string | null;
+    latest: string | null;
+    /** The tag the Compose file names (`latest`, `18`, `2.9.13`); what "new build of" refers to. */
+    tag: string;
+    major: boolean;
+    note: string;
+    review?: Review;
 }
 
-/** custom_id of the report's Upgrade Arcane button: `arcane:manager:<x.y.z>`. */
-export const MANAGER_BUTTON = /^arcane:manager:(\d{1,4}\.\d{1,4}\.\d{1,4})$/;
+export type StackState = "offered" | "running" | "updated" | "rolled back" | "failed" | "current";
 
-/** The newer Arcane manager release a report offers (`2.17.0`), from the row of stack and service `arcane`, or null. */
-export function managerOffer(report: unknown): string | null {
-    if (!isReport(report)) return null;
-    const row = report.rows.find((r) => r.stack === "arcane" && r.service === "arcane" && (r.status === "update" || r.status === "release"));
-    const m = row ? /^v?(\d{1,4}\.\d{1,4}\.\d{1,4})$/.exec(displayVersion(row.latest)) : null;
+export interface StackEntry {
+    stack: string;
+    lines: ServiceLine[];
+    /** Why the stack is held (`update-holds.json` in the GitOps repository); a held stack gets no button. */
+    held?: string;
+    /** The arcane stack only: the manager release its button upgrades to, `2.17.0`. */
+    manager?: string;
+    /** Whether the stack has an update its button applies. */
+    actionable: boolean;
+    state: StackState;
+    /** What the last update did, or why it failed. */
+    detail?: string;
+}
+
+/** One posted message of a report and the stacks it shows, so a click redraws exactly that message. */
+export interface PostedPage {
+    id: string;
+    stacks: string[];
+    head: boolean;
+}
+
+export interface ArcaneReport {
+    date: string;
+    checkedAt: string;
+    channelId: string;
+    timeZone: string;
+    images: number;
+    privateCount: number;
+    holdsError?: string;
+    stacks: StackEntry[];
+    messages: PostedPage[];
+}
+
+function tagOf(ref: string): string {
+    if (ref.length === 0) return "?";
+    try {
+        return parseImageRef(ref).tag ?? "digest pin";
+    } catch {
+        return "?";
+    }
+}
+
+function managerVersion(line: ServiceLine): string | null {
+    const m = line.latest ? /^v?(\d{1,4}\.\d{1,4}\.\d{1,4})$/.exec(line.latest) : null;
     return m ? m[1] : null;
 }
 
-export type ManagerButtonState = "offer" | "running" | "upgraded" | "failed";
+export interface ReportStacks {
+    stacks: StackEntry[];
+    images: number;
+    privateCount: number;
+    checkedAt: string;
+    holdsError?: string;
+}
+
+/**
+ * The report's stacks from one `update-report` answer: services with a
+ * pending update, a failed check, or a newer major tag, grouped by stack.
+ * The arcane stack is the manager, offered through manager-upgrade.
+ */
+export function buildStacks(report: unknown): ReportStacks | null {
+    if (!isReport(report)) return null;
+    const holds = report.holds ?? {};
+    const shown = report.rows.filter((r) => PENDING.has(r.status) || r.status === "unknown" || /newer major \S+ available/.test(r.note ?? ""));
+    const names = [...new Set(shown.map((r) => r.stack))].sort((a, b) => a.localeCompare(b));
+    const stacks = names.map((stack): StackEntry => {
+        const lines = shown
+            .filter((r) => r.stack === stack)
+            .map((r): ServiceLine => {
+                const running = releaseTag(r.running);
+                const latest = releaseTag(r.latest);
+                return { service: r.service, status: r.status, action: r.action ?? "", running, latest, tag: tagOf(r.ref ?? ""), major: PENDING.has(r.status) && crossesMajor(running, latest), note: r.note ?? "" };
+            });
+        const pending = lines.some((l) => PENDING.has(l.status));
+        const held = holds[stack];
+        if (stack === "arcane") {
+            const offer = lines.map((l) => (PENDING.has(l.status) ? managerVersion(l) : null)).find((v) => v !== null) ?? null;
+            return { stack, lines, actionable: offer !== null && !held, ...(offer ? { manager: offer } : {}), ...(held ? { held } : {}), state: "offered" };
+        }
+        return { stack, lines, actionable: pending && !held, ...(held ? { held } : {}), state: "offered" };
+    });
+    return { stacks, images: report.images, privateCount: report.privateImages.length, checkedAt: report.checkedAt, ...(report.holdsError ? { holdsError: report.holdsError } : {}) };
+}
+
+/** Services whose update crosses a major version; each gets a release-notes review before the report posts. */
+export function majorLines(stacks: readonly StackEntry[]): { stack: string; line: ServiceLine }[] {
+    return stacks.flatMap((s) => s.lines.filter((l) => l.major).map((line) => ({ stack: s.stack, line })));
+}
+
+const VERDICT_MARK: Record<Verdict, string> = { none: "🟢 nothing relevant", check: "🟡 check", breaking: "🔴 breaking" };
+
+/** One service in plain words: what runs, what is offered, and what kind of change it is. */
+export function serviceText(l: ServiceLine): string {
+    const name = escapeDiscord(l.service);
+    const tag = `\`${escapeDiscord(l.tag)}\``;
+    let text: string;
+    if (l.status === "unknown") {
+        text = `${name}: check failed${l.note ? ` (${escapeDiscord(l.note.slice(0, 160))})` : ""}`;
+    } else if (!PENDING.has(l.status)) {
+        const newer = /newer major (\S+) available/.exec(l.note)?.[1] ?? "?";
+        text = `${name}: ${escapeDiscord(l.running ?? l.tag)}, newer major ${escapeDiscord(newer)} available (a tag change by hand; Update does not apply it)`;
+    } else if (l.status === "rebuild") {
+        text = `${name}: rebuild of ${tag}`;
+    } else if (l.latest === null) {
+        text = `${name}: ${l.running ? `${escapeDiscord(l.running)} → ` : ""}new build of ${tag}`;
+    } else if (l.running !== null && l.running === l.latest) {
+        text = `${name}: ${escapeDiscord(l.latest)}, new build of ${tag}`;
+    } else {
+        const from = l.running ?? "older build";
+        const sameRelease = l.running !== null && numbers(l.running).join(".") === numbers(l.latest).join(".");
+        const kind = sameRelease ? `new build of ${tag}` : l.action === "edit tag" ? "new version (tag change)" : l.action === "edit digest" ? "new version (digest pin)" : "new version";
+        text = `${name}: ${escapeDiscord(from)} → ${escapeDiscord(l.latest)} · ${kind}`;
+    }
+    if (l.major) text += " · **major version**";
+    const newer = PENDING.has(l.status) ? /newer major (\S+) available/.exec(l.note)?.[1] : undefined;
+    if (newer) text += ` · newer major ${escapeDiscord(newer)} available`;
+    const review = l.review ? `\n-# ${l.review.verdict ? `${VERDICT_MARK[l.review.verdict]}: ` : "notes: "}${escapeDiscord(l.review.reason)}` : "";
+    return `• ${text}${review}`;
+}
+
+function stackText(s: StackEntry): string {
+    const held = s.held ? `\n-# ⏸ held: ${escapeDiscord(s.held)}` : "";
+    const detail = s.detail ? `\n-# ${escapeDiscord(s.detail)}` : "";
+    return `**${escapeDiscord(s.stack)}**\n${s.lines.map(serviceText).join("\n")}${held}${detail}`.slice(0, 1800);
+}
+
+const PRIMARY = 1;
+const SECONDARY = 2;
+const SUCCESS = 3;
+const DANGER = 4;
+const STACK = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,80}$/;
+
+/** custom_id of a stack's Update button. */
+export function stackId(stack: string): string {
+    return `arcane:stack:${stack}`;
+}
+
+/** custom_id of the arcane stack's button: `arcane:manager:<x.y.z>`. */
+export const MANAGER_BUTTON = /^arcane:manager:(\d{1,4}\.\d{1,4}\.\d{1,4})$/;
+
+export type ArcaneButton = { kind: "stack"; stack: string } | { kind: "manager"; version: string };
+
+export function parseArcaneButton(customId: string): ArcaneButton | null {
+    const stack = /^arcane:stack:(.+)$/.exec(customId);
+    if (stack) return STACK.test(stack[1]) && stack[1] !== "arcane" ? { kind: "stack", stack: stack[1] } : null;
+    const manager = MANAGER_BUTTON.exec(customId);
+    return manager ? { kind: "manager", version: manager[1] } : null;
+}
+
+function stackButton(s: StackEntry): MessageComponent {
+    const id = s.manager ? `arcane:manager:${s.manager}` : stackId(s.stack);
+    if (s.state === "running") return { type: 2, style: SECONDARY, label: s.manager ? `Upgrading Arcane to v${s.manager}…` : "Updating…", custom_id: id, disabled: true };
+    if (s.state === "updated") return { type: 2, style: SUCCESS, label: s.manager ? `Arcane v${s.manager} is running` : "Updated", custom_id: id, disabled: true };
+    if (s.state === "current") return { type: 2, style: SECONDARY, label: "Already current", custom_id: id, disabled: true };
+    if (s.state === "rolled back") return { type: 2, style: DANGER, label: "Rolled back", custom_id: id, disabled: true };
+    if (s.state === "failed") return s.manager ? { type: 2, style: DANGER, label: "Upgrade did not complete", custom_id: id, disabled: true } : { type: 2, style: DANGER, label: "Retry", custom_id: id };
+    return { type: 2, style: PRIMARY, label: s.manager ? `Upgrade Arcane to v${s.manager}` : "Update", custom_id: id };
+}
+
+/** A stack with an update its button applies is a Section with the button beside it; any other stack is text only. */
+export function stackComponent(s: StackEntry): MessageComponent {
+    const text: MessageComponent = { type: 10, content: stackText(s) };
+    return s.actionable ? { type: 9, components: [text], accessory: stackButton(s) } : text;
+}
+
+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));
+}
+
+type ReportView = Omit<ArcaneReport, "messages" | "date" | "channelId">;
+
+export function headText(report: ReportView): MessageComponent {
+    const withUpdates = report.stacks.filter((s) => s.lines.some((l) => PENDING.has(l.status))).length;
+    const scope = `${report.images} images${report.privateCount > 0 ? `, ${report.privateCount} private excluded` : ""}, checked ${clock(report.checkedAt, report.timeZone)}`;
+    const head =
+        report.stacks.length === 0
+            ? `**${REPORT_PREFIX}** no updates (${scope}).`
+            : `**${REPORT_PREFIX}** ${withUpdates} stack${withUpdates === 1 ? "" : "s"} with updates (${scope}).`;
+    const warning = report.holdsError ? `\n-# ⚠️ ${escapeDiscord(report.holdsError)}; Update still refuses held stacks` : "";
+    return { type: 10, content: `${head}${warning}` };
+}
+
+const MESSAGE_COMPONENTS = 40;
+/** Discord documents no total text limit for these messages; this keeps each one near a normal message's size. */
+const MESSAGE_TEXT = 3500;
+
+/** The components of one posted message, redrawn from the report's current state. */
+export function messageComponents(report: ReportView, page: Omit<PostedPage, "id">): MessageComponent[] {
+    const out: MessageComponent[] = [];
+    if (page.head) out.push(headText(report));
+    for (const name of page.stacks) {
+        const s = report.stacks.find((x) => x.stack === name);
+        if (s) out.push(stackComponent(s));
+    }
+    return out;
+}
+
+/** Splits the report into messages within 40 components and the text budget: header first. */
+export function layoutMessages(report: ReportView): Omit<PostedPage, "id">[] {
+    const pages: Omit<PostedPage, "id">[] = [];
+    let page: Omit<PostedPage, "id"> = { stacks: [], head: true };
+    let used = 1;
+    let text = (headText(report).content ?? "").length;
+    for (const s of report.stacks) {
+        const size = s.actionable ? 3 : 1;
+        const length = stackText(s).length;
+        if (used + size > MESSAGE_COMPONENTS || text + length > MESSAGE_TEXT) {
+            pages.push(page);
+            page = { stacks: [], head: false };
+            used = 0;
+            text = 0;
+        }
+        page.stacks.push(s.stack);
+        used += size;
+        text += length;
+    }
+    pages.push(page);
+    return pages;
+}
+
+/** 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.`;
+}
 
-/** The one button under the report; only the offer is clickable. */
-export function managerButton(version: string, state: ManagerButtonState): MessageComponent[] {
-    const label = { offer: `Upgrade Arcane to v${version}`, running: `Upgrading Arcane to v${version}…`, upgraded: `Arcane v${version} is running`, failed: `Upgrade to v${version} did not complete` }[state];
-    const style = { offer: 1, running: 2, upgraded: 3, failed: 4 }[state];
-    return [{ type: 1, components: [{ type: 2, style, label, custom_id: `arcane:manager:${version}`, ...(state === "offer" ? {} : { disabled: true }) }] }];
+/** The stack's state after `stack-update`, from its JSON answer, and one line for the report. */
+export function stackOutcome(out: Record<string, unknown>): { state: StackState; detail: string } {
+    const reason = typeof out.reason === "string" ? out.reason.slice(0, 300) : "";
+    const services = Array.isArray(out.services) ? (out.services as { service?: unknown; to?: unknown }[]) : [];
+    const moved = services.map((s) => `${String(s.service)} ${String(s.to)}`).join(", ");
+    if (out.status === "updated") return { state: "updated", detail: `updated: ${moved || "every service"}` };
+    if (out.status === "nothing to do") return { state: "current", detail: "nothing to update any more" };
+    if (out.status === "rolled back") return { state: "rolled back", detail: `rolled back: ${reason || "a check failed"}; the previous Compose file runs again` };
+    if (out.status === "failed") return { state: "failed", detail: `failed: ${reason || "no reason given"}` };
+    return { state: "failed", detail: "the update returned an unexpected answer; check the stack with the arcane specialist" };
 }
 
 function short(value: unknown): string {
     return typeof value === "string" ? value.replace(/^sha256:/, "").slice(0, 12) : "?";
 }
 
-/** The reply after an upgrade, from the wrapper's `manager-upgrade` answer. */
+/** The reply after a manager upgrade, from the wrapper's `manager-upgrade` answer. */
 export function managerSummary(out: Record<string, unknown>): string {
     const from = typeof out.from === "string" ? `v${out.from}` : "the previous version";
     const to = typeof out.to === "string" ? `v${out.to}` : "the new version";
@@ -105,3 +331,46 @@ export function managerSummary(out: Record<string, unknown>): string {
     if (out.status === "stopped") return `❌ The Arcane upgrade to ${to} stopped before the restart: ${reason}. The pin was reverted; ${from} keeps running.`;
     return `❌ The Arcane upgrade returned an unexpected answer; check the manager with the arcane specialist before retrying.`;
 }
+
+type StackNotes = { notes: Pick<ReleaseNote, "tag" | "published" | "notes">[]; omitted: string[] } | { notes: null; reason: string };
+
+function isNote(value: unknown): value is Pick<ReleaseNote, "tag" | "published" | "notes"> {
+    const n = value as Partial<ReleaseNote> | null;
+    return !!n && typeof n.tag === "string" && typeof n.published === "string" && typeof n.notes === "string";
+}
+
+/** The releases from the wrapper's `release-notes <stack>/<service>` answer, or why there are none to review. */
+export function releaseNotesFromJson(value: unknown): StackNotes {
+    const r = value as { releases?: unknown; omitted?: unknown; reason?: unknown } | null;
+    if (!r || typeof r !== "object" || !Array.isArray(r.releases) || !r.releases.every(isNote)) return { notes: null, reason: "release-notes returned an unexpected answer" };
+    if (r.releases.length === 0) return { notes: null, reason: typeof r.reason === "string" && r.reason.length > 0 ? r.reason.slice(0, 160) : "no release notes found" };
+    const omitted = Array.isArray(r.omitted) ? r.omitted.filter((o): o is string => typeof o === "string") : [];
+    return { notes: r.releases, omitted };
+}
+
+/** What the reviewer is told about a service of a stack, so it can tell what a release would break. */
+export function serviceUsage(stack: string, line: ServiceLine): string {
+    return `${line.service} is a service of the Docker Compose stack ${stack} on the Arcane VM, deployed through GitOps. The update replaces its image (tag ${line.tag}) from ${line.running ?? "an older build"} to ${line.latest ?? "a newer build"} and changes nothing else in the Compose file: no environment variables, volumes, ports, or companion services. Judge whether the release needs a configuration, data, or companion change before or after the swap.`;
+}
+
+// ---------------------------------------------------------------- posted report state
+
+function postedPath(): string {
+    return join(configDir(), "arcane-report-posted.json");
+}
+
+export function readPostedArcane(): ArcaneReport | null {
+    try {
+        const r = JSON.parse(readFileSync(postedPath(), "utf-8")) as Partial<ArcaneReport>;
+        return typeof r.date === "string" && Array.isArray(r.stacks) && Array.isArray(r.messages) ? (r as ArcaneReport) : null;
+    } catch {
+        return null;
+    }
+}
+
+export function writePostedArcane(report: ArcaneReport): void {
+    const path = postedPath();
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+}