@astrofoundry/pi-astro 0.30.0 → 0.32.0

package/extensions/astro-discord/media.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, it, vi } from "vitest";
+import { helpText } from "./commands.ts";
+import { validateConfig } from "./config.ts";
+import {
+    IS_COMPONENTS_V2,
+    KeyedQueue,
+    LIST_ENTRIES,
+    MEDIA_COMMANDS,
+    type MediaEntry,
+    addOutcome,
+    applyOutcome,
+    commandArgs,
+    countComponents,
+    entryButton,
+    entryLine,
+    hasActiveButton,
+    listMessage,
+    mediaAccess,
+    mediaPointer,
+    parseAddButton,
+    parseAddReport,
+    parseMediaList,
+    parseQueueState,
+    queueLine,
+} from "./media.ts";
+import { DiscordRest, type MessageComponent } from "./rest.ts";
+
+const OWNER = "123456789012345678";
+const FRIEND = "223456789012345678";
+const STRANGER = "323456789012345678";
+const MEDIA_CHANNEL = "423456789012345678";
+const ADMIN_CHANNEL = "523456789012345678";
+const OTHER_CHANNEL = "623456789012345678";
+
+function entry(rank: number, extra: Partial<MediaEntry> = {}): MediaEntry {
+    return { rank, title: `Title ${rank}`, year: 2026, imdb_rating: "7.1", imdb_id: `tt${1000 + rank}`, in_library: false, popularity: 100.4, ...extra };
+}
+
+describe("media slash commands", () => {
+    it("declares valid commands", () => {
+        for (const command of MEDIA_COMMANDS) {
+            expect(command.name).toMatch(/^[-_\p{L}\p{N}]{1,32}$/u);
+            expect(command.name).toBe(command.name.toLowerCase());
+            expect(command.description.length).toBeLessThanOrEqual(100);
+            const required = command.options.map((o) => "required" in o && o.required === true);
+            expect(required.indexOf(false) === -1 || required.lastIndexOf(true) < required.indexOf(false)).toBe(true);
+            for (const option of command.options) {
+                expect(option.name).toMatch(/^[-_\p{L}\p{N}]{1,32}$/u);
+                expect(option.description.length).toBeLessThanOrEqual(100);
+            }
+        }
+    });
+
+    it("maps options to wrapper arguments", () => {
+        expect(commandArgs("trending", [])).toEqual({ view: "trending", args: ["trending", "--max-entries", "10"] });
+        expect(commandArgs("trending", [{ name: "type", type: 3, value: "series" }, { name: "min_rating", type: 10, value: 0 }, { name: "count", type: 4, value: 5 }])).toEqual({
+            view: "trending",
+            args: ["trending", "--max-entries", "5", "--type", "series", "--min-rating", "0"],
+            only: "series",
+        });
+        expect(commandArgs("trending", [{ name: "count", type: 4, value: 50 }])?.args).toEqual(["trending", "--max-entries", "10"]);
+        expect(commandArgs("search", [{ name: "title", type: 3, value: "  dune " }])).toEqual({ view: "search", args: ["search", "dune", "--max-entries", "10"], query: "dune" });
+        expect(commandArgs("search", [{ name: "title", type: 3, value: "  " }])).toBeNull();
+        expect(commandArgs("downloads", [{ name: "action", type: 3, value: "pause" }])).toEqual({ view: "downloads", args: ["sabnzbd", "pause"] });
+        expect(commandArgs("downloads", [{ name: "action", type: 3, value: "unpause" }])).toEqual({ view: "downloads", args: ["sabnzbd", "resume"] });
+        expect(commandArgs("downloads", [{ name: "action", type: 3, value: "delete" }])).toBeNull();
+        expect(commandArgs("ban", [])).toBeNull();
+    });
+
+    it("reads the wrapper's JSON defensively", () => {
+        expect(parseMediaList({ movies: [entry(1)], series: [], warnings: ["Radarr unreachable", 3] })).toEqual({ movies: [entry(1)], series: [], warnings: ["Radarr unreachable"] });
+        expect(parseMediaList({ movies: [{ rank: "1" }], series: [] })).toBeNull();
+        expect(parseMediaList({ results: [] })).toBeNull();
+        expect(parseAddReport({ results: [{ imdb_id: "tt1", title: "X", status: "added", detail: null }, { bad: 1 }], sabnzbd_paused: true })).toEqual({ results: [{ imdb_id: "tt1", title: "X", status: "added", detail: null }], sabnzbd_paused: true });
+        expect(parseAddReport({ results: [], sabnzbd_paused: "no" })).toEqual({ results: [], sabnzbd_paused: null });
+        expect(parseAddReport(null)).toBeNull();
+        expect(parseQueueState({ sabnzbd_paused: false })).toBe(false);
+        expect(parseQueueState({})).toBeNull();
+        expect(queueLine(true)).toBe("SABnzbd paused: yes");
+    });
+});
+
+describe("media list layout", () => {
+    it("writes trendarr's Discord line without the library flag", () => {
+        expect(entryLine(entry(1, { title: "Hope", imdb_rating: "6.9", popularity: 367.6, imdb_id: "tt1" }), "trending")).toBe("1. [Hope (2026)](<https://www.imdb.com/title/tt1/>) — 6.9 · 🔥368");
+        expect(entryLine(entry(2, { title: "Masterplan", imdb_rating: null, popularity: 222 }), "trending")).toBe("2. [Masterplan (2026)](<https://www.imdb.com/title/tt1002/>) — 🔥222");
+        expect(entryLine(entry(3, { title: "A*B_[x]", year: null, imdb_id: null }), "search")).toBe("3. A\\*B\\_\\[x\\] — 7.1");
+        expect(entryLine(entry(4, { imdb_rating: null }), "search")).toBe("4. [Title 4 (2026)](<https://www.imdb.com/title/tt1004/>)");
+    });
+
+    it("puts an Add, In library, or No IMDb ID button beside each entry", () => {
+        expect(entryButton("movie", entry(1))).toEqual({ type: 2, style: 1, label: "Add", custom_id: "media:add:movie:tt1001:1" });
+        expect(entryButton("series", entry(2, { in_library: null }))).toMatchObject({ label: "Add", custom_id: "media:add:series:tt1002:2" });
+        expect(entryButton("movie", entry(3, { in_library: true }))).toMatchObject({ label: "In library", disabled: true, custom_id: "media:lib:movie:tt1003:3" });
+        expect(entryButton("movie", entry(4, { imdb_id: null }))).toMatchObject({ label: "No IMDb ID", disabled: true });
+        expect(entryButton("movie", entry(5, { imdb_id: "nm123" }))).toMatchObject({ label: "No IMDb ID", disabled: true });
+    });
+
+    it("builds one message per list within Discord's limits", () => {
+        const many = Array.from({ length: 14 }, (_, i) => entry(i + 1));
+        const message = listMessage("movie", many, "trending", undefined, ["Radarr unreachable — in_library unknown"]);
+        expect(message[0]).toEqual({ type: 10, content: "**🎬 Movies** · trending this week" });
+        expect(message.filter((c) => c.type === 9)).toHaveLength(LIST_ENTRIES);
+        expect(countComponents(message)).toBe(1 + LIST_ENTRIES * 3 + 1);
+        expect(countComponents(message)).toBeLessThanOrEqual(40);
+        expect(message.at(-1)).toEqual({ type: 10, content: "-# ⚠️ Radarr unreachable — in_library unknown" });
+        const ids = message.flatMap((c) => (c.accessory?.custom_id ? [c.accessory.custom_id] : []));
+        expect(new Set(ids).size).toBe(ids.length);
+        expect(ids.every((id) => id.length <= 100)).toBe(true);
+        expect(listMessage("series", [], "search", "x_y", [])).toEqual([{ type: 10, content: "**📺 Series** · search “x\\_y”" }, { type: 10, content: "_none_" }]);
+        expect(IS_COMPONENTS_V2).toBe(32768);
+    });
+});
+
+describe("media add buttons", () => {
+    const message: MessageComponent[] = [
+        { type: 10, id: 1, content: "**🎬 Movies** · trending this week" },
+        { type: 9, id: 2, components: [{ type: 10, id: 3, content: "1. Hope" }], accessory: { type: 2, id: 4, style: 1, label: "Add", custom_id: "media:add:movie:tt1:1" } },
+        { type: 9, id: 5, components: [{ type: 10, id: 6, content: "2. Other" }], accessory: { type: 2, id: 7, style: 1, label: "Add", custom_id: "media:add:movie:tt2:2" } },
+    ];
+
+    it("parses only Add buttons", () => {
+        expect(parseAddButton("media:add:movie:tt1:1")).toEqual({ kind: "movie", imdbId: "tt1" });
+        expect(parseAddButton("media:add:series:tt0903747:10")).toEqual({ kind: "series", imdbId: "tt0903747" });
+        expect(parseAddButton("media:done:movie:tt1:1")).toBeNull();
+        expect(parseAddButton("media:add:movie:tt1;rm:1")).toBeNull();
+        expect(parseAddButton("media:add:music:tt1:1")).toBeNull();
+    });
+
+    it("turns each add result into a button state and a private note", () => {
+        const report = (status: string, paused: boolean | null = false, detail: string | null = null) => ({ results: [{ imdb_id: "tt1", title: "Hope", status, detail }], sabnzbd_paused: paused });
+        expect(addOutcome(report("added"), "movie", "tt1")).toEqual({ label: "Added", style: 3, disabled: true });
+        expect(addOutcome(report("added", true), "movie", "tt1").note).toMatch(/downloads are paused/);
+        expect(addOutcome(report("already_exists"), "movie", "tt1")).toEqual({ label: "In library", style: 2, disabled: true });
+        expect(addOutcome(report("not_found"), "series", "tt1")).toMatchObject({ label: "Not found", disabled: true, note: expect.stringMatching(/Sonarr/) });
+        expect(addOutcome(report("error", false, "quality profile missing"), "movie", "tt1")).toMatchObject({ label: "Retry", disabled: false, note: "Not added: quality profile missing." });
+        expect(addOutcome({ results: [], sabnzbd_paused: null }, "movie", "tt1")).toMatchObject({ label: "Retry", disabled: false, note: "Not added: no result for this ID." });
+        expect(addOutcome(null, "movie", "tt1", "media: secret RADARR_API_KEY for media is missing")).toMatchObject({ label: "Retry", disabled: false, note: expect.stringMatching(/RADARR_API_KEY/) });
+    });
+
+    it("replaces only the clicked button and keeps component ids", () => {
+        expect(hasActiveButton(message, "media:add:movie:tt1:1")).toBe(true);
+        const next = applyOutcome(message, "media:add:movie:tt1:1", { label: "Added", style: 3, disabled: true });
+        expect(next[1].accessory).toEqual({ type: 2, id: 4, style: 3, label: "Added", custom_id: "media:done:movie:tt1:1", disabled: true });
+        expect(next[2]).toEqual(message[2]);
+        expect(next[0]).toEqual(message[0]);
+        expect(hasActiveButton(next, "media:add:movie:tt1:1")).toBe(false);
+        expect(hasActiveButton(next, "media:add:movie:tt2:2")).toBe(true);
+        const retry = applyOutcome(message, "media:add:movie:tt2:2", { label: "Retry", style: 4, disabled: false });
+        expect(retry[2].accessory).toMatchObject({ label: "Retry", custom_id: "media:add:movie:tt2:2", disabled: false });
+        expect(hasActiveButton(retry, "media:add:movie:tt2:2")).toBe(true);
+        expect(message[1].accessory?.label).toBe("Add");
+    });
+});
+
+describe("media access", () => {
+    const config = validateConfig(
+        {
+            applicationId: OWNER,
+            guildId: OWNER,
+            channels: { [ADMIN_CHANNEL]: { trigger: "always", specialists: "*" }, [MEDIA_CHANNEL]: { trigger: "always", specialists: ["media"] }, [OTHER_CHANNEL]: { trigger: "always", specialists: ["arcane"] } },
+            adminChannelId: ADMIN_CHANNEL,
+            owners: [OWNER],
+            access: { media: [FRIEND] },
+            approvalTimeoutMinutes: 30,
+        },
+        [],
+    )!;
+    const names = ["arcane", "media"];
+
+    it("answers owners and access.media users in channels with the media specialist", () => {
+        expect(mediaAccess(config, config.channels[MEDIA_CHANNEL], names, OWNER)).toBe("ok");
+        expect(mediaAccess(config, config.channels[MEDIA_CHANNEL], names, FRIEND)).toBe("ok");
+        expect(mediaAccess(config, config.channels[MEDIA_CHANNEL], names, STRANGER)).toBe("user");
+        expect(mediaAccess(config, config.channels[OTHER_CHANNEL], names, OWNER)).toBe("channel");
+        expect(mediaAccess(config, null, names, OWNER)).toBe("channel");
+        expect(mediaAccess(config, config.channels[MEDIA_CHANNEL], ["arcane"], OWNER)).toBe("channel");
+        expect(mediaPointer(config, names)).toBe(`Media commands answer in <#${ADMIN_CHANNEL}>, <#${MEDIA_CHANNEL}>.`);
+        expect(mediaPointer(config, ["arcane"])).toBe("No channel has the media specialist yet.");
+    });
+
+    it("mentions the slash commands in help where media may be used", () => {
+        expect(helpText(["media"], ["media"], false, "always", false)).toContain("/trending");
+        expect(helpText(["arcane"], ["arcane"], true, "always", false)).not.toContain("/trending");
+    });
+});
+
+describe("keyed queue", () => {
+    it("runs tasks of one key in order and keeps going after a failure", async () => {
+        const queue = new KeyedQueue();
+        const order: string[] = [];
+        let release: () => void = () => undefined;
+        const gate = new Promise<void>((resolve) => {
+            release = resolve;
+        });
+        const first = queue.run("m1", async () => {
+            await gate;
+            order.push("first");
+            throw new Error("boom");
+        });
+        const second = queue.run("m1", async () => {
+            order.push("second");
+        });
+        const other = queue.run("m2", async () => {
+            order.push("other");
+        });
+        await other;
+        expect(order).toEqual(["other"]);
+        release();
+        await expect(first).rejects.toThrow("boom");
+        await second;
+        expect(order).toEqual(["other", "first", "second"]);
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(queue.size).toBe(0);
+    });
+});
+
+describe("media rest calls", () => {
+    it("defers, edits the original response, follows up, and registers commands", async () => {
+        const calls: { url: string; init: RequestInit }[] = [];
+        const fetchImpl = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+            calls.push({ url: String(url), init: init ?? {} });
+            return new Response(JSON.stringify({ id: "m1", channel_id: "c1" }), { status: 200 });
+        }) as unknown as typeof fetch;
+        const rest = new DiscordRest("tok", fetchImpl);
+        await rest.deferReply("i1", "t1");
+        await rest.deferUpdate("i2", "t2");
+        await rest.editOriginal("app", "t1", { content: null, flags: IS_COMPONENTS_V2, components: [{ type: 10, content: "x" }] });
+        await rest.followUp("app", "t1", { content: "note", flags: 64 });
+        await rest.overwriteGlobalCommands("app", MEDIA_COMMANDS);
+        expect(calls.map((c) => `${c.init.method} ${c.url}`)).toEqual([
+            "POST https://discord.com/api/v10/interactions/i1/t1/callback",
+            "POST https://discord.com/api/v10/interactions/i2/t2/callback",
+            "PATCH https://discord.com/api/v10/webhooks/app/t1/messages/@original",
+            "POST https://discord.com/api/v10/webhooks/app/t1",
+            "PUT https://discord.com/api/v10/applications/app/commands",
+        ]);
+        expect(JSON.parse(calls[0].init.body as string)).toEqual({ type: 5 });
+        expect(JSON.parse(calls[1].init.body as string)).toEqual({ type: 6 });
+        expect(JSON.parse(calls[2].init.body as string)).toEqual({ content: null, flags: 32768, components: [{ type: 10, content: "x" }], allowed_mentions: { parse: [] } });
+        expect(JSON.parse(calls[3].init.body as string)).toEqual({ content: "note", flags: 64, allowed_mentions: { parse: [] } });
+        expect((JSON.parse(calls[4].init.body as string) as { name: string }[]).map((c) => c.name)).toEqual(["trending", "search", "downloads"]);
+    });
+});

package/extensions/astro-discord/media.ts

@@ -0,0 +1,312 @@
+import { type ChannelSettings, type DiscordConfig, canUse, channelSpecialists } from "./config.ts";
+import type { MessageComponent } from "./rest.ts";
+
+/** The specialist behind the slash commands and Add buttons. */
+export const MEDIA = "media";
+/** Message flag for layout components (Section, Text Display); content and embeds are unavailable with it. */
+export const IS_COMPONENTS_V2 = 1 << 15;
+/** One list message: a header, ten sections of three components each, and a warning line stay within Discord's 40 components. */
+export const LIST_ENTRIES = 10;
+
+export type MediaKind = "movie" | "series";
+
+export interface MediaEntry {
+    rank: number;
+    title: string;
+    year: number | null;
+    imdb_rating: string | null;
+    imdb_id: string | null;
+    in_library: boolean | null;
+    popularity?: number;
+}
+
+export interface MediaList {
+    movies: MediaEntry[];
+    series: MediaEntry[];
+    warnings: string[];
+}
+
+export interface AddResult {
+    imdb_id: string;
+    title: string | null;
+    status: string;
+    detail: string | null;
+}
+
+export interface AddReport {
+    results: AddResult[];
+    sabnzbd_paused: boolean | null;
+}
+
+const STRING = 3;
+const INTEGER = 4;
+const NUMBER = 10;
+const GUILD_CONTEXT = 0;
+const TYPE_CHOICES = [
+    { name: "movies", value: "movies" },
+    { name: "series", value: "series" },
+];
+
+/** Slash commands of the bridge, registered as the application's global command list. */
+export const MEDIA_COMMANDS = [
+    {
+        name: "trending",
+        type: 1,
+        description: "Trending movies and series this week, with Add buttons",
+        contexts: [GUILD_CONTEXT],
+        options: [
+            { type: STRING, name: "type", description: "Only movies or only series", choices: TYPE_CHOICES },
+            { type: NUMBER, name: "min_rating", description: "Drop movies below this IMDb rating (default 6.5, 0 keeps all)", min_value: 0, max_value: 10 },
+            { type: INTEGER, name: "count", description: "Entries per list (default 10)", min_value: 1, max_value: LIST_ENTRIES },
+        ],
+    },
+    {
+        name: "search",
+        type: 1,
+        description: "Search movies and series by title, with Add buttons",
+        contexts: [GUILD_CONTEXT],
+        options: [
+            { type: STRING, name: "title", description: "Full or partial title", required: true, min_length: 1, max_length: 100 },
+            { type: STRING, name: "type", description: "Only movies or only series", choices: TYPE_CHOICES },
+        ],
+    },
+    {
+        name: "downloads",
+        type: 1,
+        description: "SABnzbd queue: status, pause, or resume (unpause)",
+        contexts: [GUILD_CONTEXT],
+        options: [
+            {
+                type: STRING,
+                name: "action",
+                description: "What to do with the download queue",
+                required: true,
+                choices: [
+                    { name: "status", value: "status" },
+                    { name: "pause", value: "pause" },
+                    { name: "resume", value: "resume" },
+                    { name: "unpause", value: "unpause" },
+                ],
+            },
+        ],
+    },
+];
+
+export interface CommandOption {
+    name: string;
+    type: number;
+    value?: string | number | boolean;
+}
+
+export type MediaCommand =
+    | { view: "trending"; args: string[]; only?: "movies" | "series" }
+    | { view: "search"; args: string[]; only?: "movies" | "series"; query: string }
+    | { view: "downloads"; args: string[] };
+
+function value(options: readonly CommandOption[], name: string): string | number | undefined {
+    const found = options.find((o) => o.name === name)?.value;
+    return typeof found === "string" || typeof found === "number" ? found : undefined;
+}
+
+function listType(options: readonly CommandOption[]): "movies" | "series" | undefined {
+    const type = value(options, "type");
+    return type === "movies" || type === "series" ? type : undefined;
+}
+
+/** Wrapper arguments for one slash command, or null for a command this bridge does not own. */
+export function commandArgs(name: string, options: readonly CommandOption[]): MediaCommand | null {
+    const only = listType(options);
+    const typeArgs = only ? ["--type", only] : [];
+    if (name === "trending") {
+        const count = value(options, "count");
+        const minRating = value(options, "min_rating");
+        const entries = typeof count === "number" && Number.isInteger(count) && count >= 1 && count <= LIST_ENTRIES ? count : LIST_ENTRIES;
+        const rating = typeof minRating === "number" ? ["--min-rating", String(minRating)] : [];
+        return { view: "trending", args: ["trending", "--max-entries", String(entries), ...typeArgs, ...rating], ...(only ? { only } : {}) };
+    }
+    if (name === "search") {
+        const title = value(options, "title");
+        if (typeof title !== "string" || title.trim().length === 0) return null;
+        return { view: "search", args: ["search", title.trim(), "--max-entries", String(LIST_ENTRIES), ...typeArgs], query: title.trim(), ...(only ? { only } : {}) };
+    }
+    if (name === "downloads") {
+        const action = value(options, "action");
+        if (action !== "status" && action !== "pause" && action !== "resume" && action !== "unpause") return null;
+        return { view: "downloads", args: ["sabnzbd", action === "unpause" ? "resume" : action] };
+    }
+    return null;
+}
+
+function isEntry(value: unknown): value is MediaEntry {
+    const e = value as Partial<MediaEntry> | null;
+    return !!e && typeof e.rank === "number" && typeof e.title === "string";
+}
+
+/** The `trending` or `search` JSON of the media wrapper, or null when it is not one. */
+export function parseMediaList(value: unknown): MediaList | null {
+    const r = value as { movies?: unknown; series?: unknown; warnings?: unknown } | null;
+    if (!r || !Array.isArray(r.movies) || !Array.isArray(r.series) || !r.movies.every(isEntry) || !r.series.every(isEntry)) return null;
+    const warnings = Array.isArray(r.warnings) ? r.warnings.filter((w): w is string => typeof w === "string") : [];
+    return { movies: r.movies, series: r.series, warnings };
+}
+
+export function parseAddReport(value: unknown): AddReport | null {
+    const r = value as { results?: unknown; sabnzbd_paused?: unknown } | null;
+    if (!r || !Array.isArray(r.results)) return null;
+    const results = r.results.filter((x): x is AddResult => typeof (x as AddResult | null)?.imdb_id === "string" && typeof (x as AddResult).status === "string");
+    return { results, sabnzbd_paused: typeof r.sabnzbd_paused === "boolean" ? r.sabnzbd_paused : null };
+}
+
+export function parseQueueState(value: unknown): boolean | null {
+    const paused = (value as { sabnzbd_paused?: unknown } | null)?.sabnzbd_paused;
+    return typeof paused === "boolean" ? paused : null;
+}
+
+const IMDB_ID = /^tt\d{1,12}$/;
+
+function escapeDiscord(text: string): string {
+    return text.replace(/([\\*_~`|[\]])/g, "\\$1");
+}
+
+/** Title with year, linked to IMDb without a preview, as trendarr's `--discord` output writes it. */
+function titleLink(entry: MediaEntry): string {
+    const label = escapeDiscord(`${entry.title}${entry.year === null ? "" : ` (${entry.year})`}`);
+    return entry.imdb_id !== null && IMDB_ID.test(entry.imdb_id) ? `[${label}](<https://www.imdb.com/title/${entry.imdb_id}/>)` : label;
+}
+
+/** trendarr's `--discord` line without the library flag, which the button beside it shows. */
+export function entryLine(entry: MediaEntry, view: "trending" | "search"): string {
+    if (view === "trending") {
+        const rating = entry.imdb_rating === null ? "" : `${entry.imdb_rating} · `;
+        return `${entry.rank}. ${titleLink(entry)} — ${rating}🔥${Math.round(entry.popularity ?? 0)}`;
+    }
+    return `${entry.rank}. ${titleLink(entry)}${entry.imdb_rating === null ? "" : ` — ${entry.imdb_rating}`}`;
+}
+
+const PRIMARY = 1;
+const SECONDARY = 2;
+const SUCCESS = 3;
+const DANGER = 4;
+
+export function entryButton(kind: MediaKind, entry: MediaEntry): MessageComponent {
+    const id = entry.imdb_id !== null && IMDB_ID.test(entry.imdb_id) ? entry.imdb_id : null;
+    if (id === null) return { type: 2, style: SECONDARY, label: "No IMDb ID", custom_id: `media:none:${kind}:${entry.rank}`, disabled: true };
+    if (entry.in_library === true) return { type: 2, style: SECONDARY, label: "In library", custom_id: `media:lib:${kind}:${id}:${entry.rank}`, disabled: true };
+    // `in_library: null` means the library could not be read; trendarr's add answers already_exists if it is there.
+    return { type: 2, style: PRIMARY, label: "Add", custom_id: `media:add:${kind}:${id}:${entry.rank}` };
+}
+
+/** One Components V2 message: header, one section per entry with its button, and trendarr's warnings. */
+export function listMessage(kind: MediaKind, entries: readonly MediaEntry[], view: "trending" | "search", query: string | undefined, warnings: readonly string[]): MessageComponent[] {
+    const title = kind === "movie" ? "**🎬 Movies**" : "**📺 Series**";
+    const scope = view === "trending" ? "trending this week" : `search “${escapeDiscord(query ?? "")}”`;
+    const components: MessageComponent[] = [{ type: 10, content: `${title} · ${scope}` }];
+    if (entries.length === 0) components.push({ type: 10, content: "_none_" });
+    for (const entry of entries.slice(0, LIST_ENTRIES)) {
+        components.push({ type: 9, components: [{ type: 10, content: entryLine(entry, view) }], accessory: entryButton(kind, entry) });
+    }
+    if (warnings.length > 0) components.push({ type: 10, content: `-# ⚠️ ${warnings.join(" · ").slice(0, 500)}` });
+    return components;
+}
+
+/** Every component in a message, nested ones and section accessories included. */
+export function countComponents(components: readonly MessageComponent[]): number {
+    return components.reduce((n, c) => n + 1 + countComponents(c.components ?? []) + (c.accessory ? countComponents([c.accessory]) : 0), 0);
+}
+
+const ADD_ID = /^media:add:(movie|series):(tt\d{1,12}):\d{1,3}$/;
+
+export function parseAddButton(customId: string): { kind: MediaKind; imdbId: string } | null {
+    const m = ADD_ID.exec(customId);
+    return m ? { kind: m[1] as MediaKind, imdbId: m[2] } : null;
+}
+
+export interface Outcome {
+    label: string;
+    style: number;
+    /** A finished button stays disabled; a failed one can be clicked again. */
+    disabled: boolean;
+    /** Shown only to the user who clicked. */
+    note?: string;
+}
+
+/** What the clicked button turns into after the add, from the wrapper's answer or its failure text. */
+export function addOutcome(report: AddReport | null, kind: MediaKind, imdbId: string, failure?: string): Outcome {
+    if (!report) return { label: "Retry", style: DANGER, disabled: false, note: `Not added: ${failure ?? "the media check failed"}.` };
+    const result = report.results.find((r) => r.imdb_id === imdbId);
+    const name = result?.title ? `**${escapeDiscord(result.title)}**` : imdbId;
+    if (result?.status === "added") {
+        return { label: "Added", style: SUCCESS, disabled: true, ...(report.sabnzbd_paused === true ? { note: `Added ${name}; the search started, but downloads are paused. \`/downloads resume\` starts them.` } : {}) };
+    }
+    if (result?.status === "already_exists") return { label: "In library", style: SECONDARY, disabled: true };
+    if (result?.status === "not_found") return { label: "Not found", style: DANGER, disabled: true, note: `${name} was not found ${kind === "movie" ? "in Radarr" : "on TMDB or in Sonarr"}; nothing was added.` };
+    return { label: "Retry", style: DANGER, disabled: false, note: `Not added: ${result?.detail ?? (result ? result.status : "no result for this ID")}.` };
+}
+
+function mapButtons(components: readonly MessageComponent[], customId: string, replace: (button: MessageComponent) => MessageComponent): MessageComponent[] {
+    return components.map((c) => {
+        if (c.type === 2 && c.custom_id === customId) return replace(c);
+        const next: MessageComponent = { ...c };
+        if (c.components) next.components = mapButtons(c.components, customId, replace);
+        if (c.accessory) next.accessory = mapButtons([c.accessory], customId, replace)[0];
+        return next;
+    });
+}
+
+/** True while the message still shows that button enabled, so a second click on it does nothing. */
+export function hasActiveButton(components: readonly MessageComponent[], customId: string): boolean {
+    return components.some((c) => (c.type === 2 && c.custom_id === customId && c.disabled !== true) || hasActiveButton(c.components ?? [], customId) || (c.accessory ? hasActiveButton([c.accessory], customId) : false));
+}
+
+/** The message components with only the clicked button replaced by its outcome. */
+export function applyOutcome(components: readonly MessageComponent[], customId: string, outcome: Outcome): MessageComponent[] {
+    return mapButtons(components, customId, (button) => ({
+        ...button,
+        style: outcome.style,
+        label: outcome.label,
+        disabled: outcome.disabled,
+        custom_id: outcome.disabled ? customId.replace(/^media:add:/, "media:done:") : customId,
+    }));
+}
+
+export type MediaAccess = "ok" | "channel" | "user";
+
+/** Media commands answer where the media specialist is present and for owners or users listed under `access.media`. */
+export function mediaAccess(config: DiscordConfig, settings: ChannelSettings | null, configured: readonly string[], userId: string): MediaAccess {
+    if (!settings || !channelSpecialists(settings, configured).includes(MEDIA)) return "channel";
+    return canUse(config, userId, MEDIA) ? "ok" : "user";
+}
+
+export function mediaPointer(config: DiscordConfig, configured: readonly string[]): string {
+    const channels = Object.entries(config.channels)
+        .filter(([, settings]) => channelSpecialists(settings, configured).includes(MEDIA))
+        .map(([id]) => `<#${id}>`);
+    return channels.length > 0 ? `Media commands answer in ${channels.join(", ")}.` : "No channel has the media specialist yet.";
+}
+
+export function queueLine(paused: boolean): string {
+    return `SABnzbd paused: ${paused ? "yes" : "no"}`;
+}
+
+/**
+ * Runs tasks for one key strictly one after another; a failure does not stop
+ * the next. Button clicks on the same message go through one key, so each
+ * edit starts from the state the previous one left.
+ */
+export class KeyedQueue {
+    private readonly tails = new Map<string, Promise<void>>();
+
+    run(key: string, task: () => Promise<void>): Promise<void> {
+        const next = (this.tails.get(key) ?? Promise.resolve()).then(task);
+        const tail = next.catch(() => undefined);
+        this.tails.set(key, tail);
+        void tail.then(() => {
+            if (this.tails.get(key) === tail) this.tails.delete(key);
+        });
+        return next;
+    }
+
+    get size(): number {
+        return this.tails.size;
+    }
+}

package/extensions/astro-discord/open-work.ts

@@ -6,7 +6,8 @@ import { configDir } from "./config.ts";
 export interface OpenTask {
     specialist: string;
     channelId: string;
-    messageId: string;
+    /** Absent for a slash command or button click, which has no user message to answer. */
+    messageId?: string;
     placeholderId?: string;
 }
 

package/extensions/astro-discord/rest.ts

@@ -2,13 +2,26 @@ export const API = "https://discord.com/api/v10";
 
 export interface MessageComponent {
     type: number;
+    /** Set by Discord on every component it returns; kept unchanged when a message is edited. */
+    id?: number;
     components?: MessageComponent[];
+    /** Text of a Text Display. */
+    content?: string;
+    /** The button or thumbnail beside a Section's text. */
+    accessory?: MessageComponent;
     style?: number;
     label?: string;
     custom_id?: string;
     disabled?: boolean;
 }
 
+/** A message body for interaction webhooks: plain `content`, or `components` with the IS_COMPONENTS_V2 flag. */
+export interface WebhookMessage {
+    content?: string | null;
+    components?: MessageComponent[];
+    flags?: number;
+}
+
 export interface CreateMessage {
     content: string;
     replyTo?: string;
@@ -99,6 +112,31 @@ export class DiscordRest {
         await this.call("POST", `/interactions/${interactionId}/${interactionToken}/callback`, JSON.stringify({ type: 4, data: { content, flags: 64, allowed_mentions: { parse: [] } } }), "application/json");
     }
 
+    /** Acknowledges a slash command; Discord shows "thinking" until the original response is edited (callback type 5). */
+    async deferReply(interactionId: string, interactionToken: string): Promise<void> {
+        await this.call("POST", `/interactions/${interactionId}/${interactionToken}/callback`, JSON.stringify({ type: 5 }), "application/json");
+    }
+
+    /** Acknowledges a component click without a loading state; the message is edited later through the original response (callback type 6). */
+    async deferUpdate(interactionId: string, interactionToken: string): Promise<void> {
+        await this.call("POST", `/interactions/${interactionId}/${interactionToken}/callback`, JSON.stringify({ type: 6 }), "application/json");
+    }
+
+    /** Edits the original response: the deferred reply of a command, or the message of a clicked component. */
+    async editOriginal(applicationId: string, interactionToken: string, message: WebhookMessage): Promise<void> {
+        await this.call("PATCH", `/webhooks/${applicationId}/${interactionToken}/messages/@original`, JSON.stringify({ ...message, allowed_mentions: { parse: [] } }), "application/json");
+    }
+
+    /** Another message for the same interaction; with flags 64 only the user who triggered it sees it. */
+    async followUp(applicationId: string, interactionToken: string, message: WebhookMessage): Promise<DiscordMessage> {
+        return (await this.call("POST", `/webhooks/${applicationId}/${interactionToken}`, JSON.stringify({ ...message, allowed_mentions: { parse: [] } }), "application/json")).json() as Promise<DiscordMessage>;
+    }
+
+    /** Replaces the application's global slash commands with this list. */
+    async overwriteGlobalCommands(applicationId: string, commands: readonly unknown[]): Promise<void> {
+        await this.call("PUT", `/applications/${applicationId}/commands`, JSON.stringify(commands), "application/json");
+    }
+
     async gatewayUrl(): Promise<string> {
         const data = (await (await this.call("GET", "/gateway/bot")).json()) as { url?: string };
         if (typeof data.url !== "string") throw new Error("Discord did not return a gateway url");

package/extensions/specialist-gate/approvals.test.ts

@@ -29,6 +29,8 @@ describe("approvals", () => {
         expect(isRisky("inference", ["hermes-restart", "api"])).toBe(true);
         expect(isRisky("backup", ["restic-snapshots"])).toBe(false);
         expect(isRisky("backup", ["vzdump-run", "107"])).toBe(true);
+        expect(isRisky("media", ["add-movies", "tt1160419"])).toBe(false);
+        expect(isRisky("media", ["sabnzbd", "pause"])).toBe(false);
     });
 
     it("creates a ticket and polls until decided", async () => {

package/extensions/specialist-gate/index.ts

@@ -35,6 +35,7 @@ export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
     backup: [/^(vzdump-run|host-backup-run|arcane-backup-run|gcs-run|restic-check-run|restic-restore|restore-clean)\b/],
     proxmox: [/^(set|snapshot-create|start)\b/],
     inference: [/^(nexus-restart|nexus-start|hermes-restart)\b/],
+    // media has no entry: trendarr cannot delete anything, and adds and queue toggles run on the caller's request.
 };
 
 export function isRisky(service: string, args: readonly string[]): boolean {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"