@devdogsuga/devtools 0.1.26 → 0.1.28

package/dist/images/graphics.js

@@ -1,234 +0,0 @@
-import { loadOpenGraph } from "../repo/source.js";
-import { UsageError } from "../ui.js";
-const BRAND = "apps/platform/public/brand";
-/** The two renditions anything may need, because anything may reach the GDG platform. */
-const GDG = ["gdgc-wide", "gdgc-square"];
-const EVENT_FORMATS = ["og", ...GDG, "involvement-network"];
-const EMAIL = ["email-1x", "email-2x", "email-3x"];
-/* ------------------------------------------------------------------- brand */
-/**
- * The club lockup, on each of the two grounds it is ever set on.
- *
- * One subject, two grounds, and the rendition decides which template draws it:
- * the email densities want the signature's tight horizontal strip, everything
- * else wants the banner. That is why "the email signature" is not a graphic of
- * its own — it is this lockup at `email-2x`, and its GDG export is the same
- * lockup at `gdgc-square` rather than a second drawing that has to be kept in
- * step with the first.
- */
-function brandGraphics(og) {
-    return ["dark", "light"].map((ground) => ({
-        name: ground === "dark" ? "brand/club" : "brand/club-light",
-        group: "brand",
-        stem: ground === "dark" ? "club" : "club-light",
-        formats: [
-            "og",
-            ...GDG,
-            ...(ground === "dark" ? ["savvycal"] : []),
-            ...EMAIL,
-        ],
-        why: `The DevDogs lockup with the GDG chapter cobrand, on a ${ground} ground.`,
-        render: (format) => format.family === "email"
-            ? og.EmailSignature({ width: format.width, ground })
-            : og.Banner({ width: format.width, height: format.height, ground }),
-        destination: (format) => ({
-            dir: format.family === "email" ? `${BRAND}/email` : `${BRAND}/banners`,
-            file: format.family === "email"
-                ? `signature-${ground}${format.scale > 1 ? `@${format.scale}x` : ""}.png`
-                : `club-${ground === "dark" ? "" : "light-"}${format.name}.png`,
-        }),
-    }));
-}
-/* -------------------------------------------------------------------- pages */
-/**
- * One graphic per public page, keyed by the route it belongs to.
- *
- * The platform renders these live from `opengraph-image.tsx`, so the files
- * written here are for looking at — an Open Graph card is otherwise only
- * visible by deploying and pasting a link somewhere, which is a slow way to
- * find out that a title wrapped badly.
- */
-function pageGraphics(og) {
-    return Object.entries(og.PAGE_CARDS).map(([route, copy]) => {
-        const stem = route === "/" ? "home" : route.slice(1).replace(/\//g, "-");
-        return {
-            name: `page/${stem}`,
-            group: "page",
-            stem,
-            formats: ["og", ...GDG],
-            why: `The card ${route} unfurls as.`,
-            render: (format) => og.PageCard({
-                width: format.width,
-                height: format.height,
-                cobrand: true,
-                ...copy,
-            }),
-            // The format is in the filename, not just the directory: `og` and
-            // `gdgc-square` are the same page at two sizes, and without it the second
-            // silently overwrites the first.
-            destination: (format) => ({
-                dir: `${BRAND}/og`,
-                file: `${stem}-${format.name}.png`,
-            }),
-        };
-    });
-}
-/* --------------------------------------------------------------------- apps */
-/** Which app's icons go where, and which of them Next serves by convention. */
-const APP_HOME = {
-    platform: { icons: `${BRAND}/icons`, app: "apps/platform/src/app" },
-    dogdays: {
-        icons: "apps/schedule-builder/public/icons",
-        app: "apps/schedule-builder/src/app",
-    },
-    // Flutter, and nothing deployed yet, so its icons wait in the club's own
-    // brand folder rather than in an app directory that does not exist.
-    dogpack: { icons: `${BRAND}/icons` },
-};
-function appGraphics(og) {
-    return Object.keys(og.APPS).map((app) => {
-        // Non-null by construction: every real AppKey (`Object.keys(og.APPS)`)
-        // has an APP_HOME entry. `AppKey` itself is widened to `string` here
-        // (see `open-graph-types.ts`'s header on why), so TS can no longer see
-        // that closed correspondence the way it could against the real literal
-        // union.
-        const home = APP_HOME[app];
-        const sizes = [16, 32, 48, 64, 96, 128, 180, 192, 256, 384, 512, 1024];
-        // Non-null by construction, same reasoning as `home` above: every real
-        // AppKey this loop iterates came from `Object.keys(og.APPS)` itself.
-        const brand = og.APPS[app];
-        return {
-            name: `app/${app}`,
-            group: "app",
-            stem: app,
-            formats: [
-                ...sizes.map((size) => `icon-${size}`),
-                ...(home.app ? ["icon-favicon", "icon-apple"] : []),
-                "og",
-                ...GDG,
-            ],
-            why: `${brand.name} — its mark as an icon, and its card as a link.`,
-            render: (format) => format.family === "icon"
-                ? og.AppIcon({
-                    app,
-                    size: format.width,
-                    background: og.OPAQUE_FORMATS.has(format.name)
-                        ? og.THEME.background
-                        : undefined,
-                })
-                : og.PageCard({
-                    width: format.width,
-                    height: format.height,
-                    title: brand.name,
-                    description: brand.blurb,
-                    eyebrow: brand.tagline,
-                    accent: brand.ground,
-                    footer: brand.host,
-                    cobrand: true,
-                }),
-            destination: (format) => {
-                // The two Next reads by name, which have to land in `src/app` under
-                // exactly those filenames or the framework does not see them.
-                if (home.app && format.name === "icon-favicon") {
-                    return { dir: home.app, file: "icon.png" };
-                }
-                if (home.app && format.name === "icon-apple") {
-                    return { dir: home.app, file: "apple-icon.png" };
-                }
-                // The platform serves its own link cards per request, so only the apps
-                // WITHOUT a live renderer get a static `opengraph-image.png`.
-                if (home.app && app !== "platform" && format.name === "og") {
-                    return { dir: home.app, file: "opengraph-image.png" };
-                }
-                return format.family === "icon"
-                    ? {
-                        dir: home.icons,
-                        file: `${app}-${format.name.replace("icon-", "")}.png`,
-                    }
-                    : { dir: `${BRAND}/og`, file: `app-${app}-${format.name}.png` };
-            },
-        };
-    });
-}
-/**
- * One graphic per meeting.
- *
- * These are the reason the two axes were split at all: "this meeting" x "the
- * GDG platform's banner" is a pairing nobody could have enumerated in advance.
- *
- * Their default directory is the one that is NOT in the repo. Every other
- * graphic is a committed asset the club re-renders; an event poster is an
- * export headed somewhere else, made once for one night. Writing those into
- * `public/brand` would fill a tracked directory with a growing pile of
- * one-offs, so they go to {@link EVENT_SCRATCH_DIR}, which `.gitignore` covers.
- */
-export const EVENT_SCRATCH_DIR = ".images/events";
-export function eventGraphics(og, events) {
-    return events.flatMap((event) => {
-        const meeting = {
-            name: `event/${event.slug}/meeting`,
-            group: "event",
-            stem: event.slug,
-            formats: EVENT_FORMATS,
-            why: `The ${event.slug} meeting — ${event.hint}.`,
-            render: (format) => og.EventCard({
-                width: format.width,
-                height: format.height,
-                cobrand: true,
-                ...event.detail,
-            }),
-            destination: (format) => ({
-                dir: `${EVENT_SCRATCH_DIR}/${event.slug}`,
-                file: `meeting-${format.name}.png`,
-            }),
-        };
-        if ((event.items?.length ?? 0) < 2)
-            return [meeting];
-        const occurrences = new Map();
-        const items = event.items.map((item) => {
-            const occurrence = (occurrences.get(item.stem) ?? 0) + 1;
-            occurrences.set(item.stem, occurrence);
-            const path = occurrence === 1 ? item.stem : `${item.stem}-${occurrence}`;
-            return {
-                name: `event/${event.slug}/${path}`,
-                group: "event",
-                // `--out` is deliberately flat, so its private stem still carries
-                // the meeting even though default output can use nested folders.
-                stem: `${event.slug}-${path}`,
-                formats: EVENT_FORMATS,
-                why: `${item.detail.badge?.label ?? "Agenda item"}: ${item.detail.title} — ${event.hint}.`,
-                render: (format) => og.EventCard({
-                    width: format.width,
-                    height: format.height,
-                    cobrand: true,
-                    ...item.detail,
-                }),
-                destination: (format) => ({
-                    dir: `${EVENT_SCRATCH_DIR}/${event.slug}`,
-                    file: `${path}-${format.name}.png`,
-                }),
-            };
-        });
-        return [meeting, ...items];
-    });
-}
-/* --------------------------------------------------------------------- all */
-/** Everything that does not need a database. */
-export async function staticGraphics() {
-    const og = await loadOpenGraph();
-    return [...brandGraphics(og), ...pageGraphics(og), ...appGraphics(og)];
-}
-/**
- * Every leaf is unique, so a flat `--out` directory cannot silently overwrite
- * one graphic's file with another's.
- */
-export function assertUniqueStems(graphics) {
-    const seen = new Map();
-    for (const graphic of graphics) {
-        const clash = seen.get(graphic.stem);
-        if (clash) {
-            throw new UsageError(`${graphic.name} and ${clash} share the leaf "${graphic.stem}", so a flat --out would overwrite one with the other.`);
-        }
-        seen.set(graphic.stem, graphic.name);
-    }
-}

package/dist/images/open-graph-types.d.ts

@@ -1,75 +0,0 @@
-/**
- * Type-only surface for `@devdogsuga/open-graph` — a hand-maintained mirror
- * of what `images/*.ts` actually uses, not a full re-export.
- *
- * `@devdogsuga/open-graph` is `"private": true` and never published — it
- * stays in DevDogsUGA (see the ledger) and devtools resolves it FROM the
- * repo at runtime (`repo/source.ts`'s `loadOpenGraph()`), never as a
- * Backstage dependency. Backstage has no copy of the package to pull real
- * types from, so these are duplicated for editor/typecheck convenience only
- * and MUST be kept in sync by hand if the real shape changes. Runtime
- * values always come from `loadOpenGraph()`, never from here.
- *
- * `EventDetail` and the `THEME` shape are NOT duplicated here: both are
- * re-exported by open-graph from `@devdogsuga/brand`, which — unlike
- * open-graph — IS a real Backstage package (published; see the ledger), so
- * those two types are imported for real below.
- */
-import type { ReactElement } from "react";
-import type { EventDetail } from "@devdogsuga/brand/event";
-import type { LoadedFont } from "@devdogsuga/brand";
-export type { EventDetail, LoadedFont };
-export type FormatFamily = "card" | "email" | "icon";
-export interface Format {
-    name: string;
-    width: number;
-    height: number;
-    scale: number;
-    family: FormatFamily;
-    why: string;
-}
-/**
- * `@devdogsuga/open-graph`'s `AppKey` is a string-literal union
- * (`"platform" | "dogdays" | "dogpack"` as of this writing). Widened to
- * `string` here rather than duplicating the literal list, which would
- * silently drift the moment a fourth app gets an icon — `APPS`'s real keys
- * are what devtools actually iterates over at runtime.
- */
-export type AppKey = string;
-export interface AppBrand {
-    name: string;
-    tagline: string;
-    blurb: string;
-    host: string;
-    ground: string;
-    mark: string;
-}
-export interface PageCardCopy {
-    title: string;
-    description: string;
-    eyebrow?: string;
-    accent?: string;
-    footer?: string;
-}
-/**
- * The five JSX template components. Typed loosely (`(...args) =>
- * ReactElement`, props as `any`) rather than duplicating each one's exact
- * props interface — those are the deepest, most likely to drift part of
- * open-graph's surface, and devtools only ever calls them with object
- * literals built right next to the call site, where a real typo would show
- * up as a runtime prop-shape mismatch the same way it would with `any`.
- */
-export type TemplateComponent = (props: any) => ReactElement;
-export interface OpenGraphModule {
-    FORMATS: Record<string, Format>;
-    OPAQUE_FORMATS: ReadonlySet<string>;
-    loadFonts: () => LoadedFont[];
-    APPS: Record<AppKey, AppBrand>;
-    AppIcon: TemplateComponent;
-    Banner: TemplateComponent;
-    EmailSignature: TemplateComponent;
-    EventCard: TemplateComponent;
-    PageCard: TemplateComponent;
-    PAGE_CARDS: Record<string, PageCardCopy>;
-    THEME: Record<string, string>;
-}

package/dist/images/open-graph-types.js

@@ -1 +0,0 @@
-export {};

package/dist/images/prompts.d.ts

@@ -1,34 +0,0 @@
-import type { Graphic } from "./graphics.js";
-/**
- * What the command asks for when the command line did not say.
- *
- * Three questions, and each one is skipped entirely when a flag answered it, so
- * a scripted invocation never blocks. That is the whole contract: this command
- * has to be usable both as "make me the September 8 posters" typed by an
- * officer who does not remember the format names, and as a line in a build.
- *
- * {@link requireInteractive} is what keeps the second half true. Without it a
- * missing flag in CI would hang on a prompt nobody can answer until the job
- * times out, which is the least debuggable failure available.
- */
-/** Refuses, naming the flag, rather than prompting where nobody can answer. */
-export declare function requireInteractive(what: string, flag: string): void;
-/**
- * Which graphics.
- *
- * Autocomplete rather than a plain list: there are dozens once a semester of
- * meetings is loaded, and the useful interaction is typing "sep" or "dogdays"
- * rather than scrolling. Grouped by prefix in the label so the list reads as
- * the `group/name` vocabulary the flags use.
- */
-export declare function pickGraphics(graphics: readonly Graphic[]): Promise<Graphic[]>;
-/**
- * Which formats.
- *
- * Offered from the union of what the chosen graphics support, so the list never
- * contains a size that would be skipped — asking somebody to pick `savvycal`
- * for an event and then quietly not rendering it is worse than not offering it.
- */
-export declare function pickFormats(graphics: readonly Graphic[]): Promise<string[]>;
-/** `undefined` means "each graphic's own default directory". */
-export declare function pickOutput(graphics: readonly Graphic[]): Promise<string | undefined>;

package/dist/images/prompts.js

@@ -1,100 +0,0 @@
-import { autocompleteMultiselect, isTTY, multiselect, path, select, } from "@clack/prompts";
-import { loadOpenGraph } from "../repo/source.js";
-import { unwrap, UsageError } from "../ui.js";
-import { formatsFor } from "./select.js";
-/**
- * What the command asks for when the command line did not say.
- *
- * Three questions, and each one is skipped entirely when a flag answered it, so
- * a scripted invocation never blocks. That is the whole contract: this command
- * has to be usable both as "make me the September 8 posters" typed by an
- * officer who does not remember the format names, and as a line in a build.
- *
- * {@link requireInteractive} is what keeps the second half true. Without it a
- * missing flag in CI would hang on a prompt nobody can answer until the job
- * times out, which is the least debuggable failure available.
- */
-/** Refuses, naming the flag, rather than prompting where nobody can answer. */
-export function requireInteractive(what, flag) {
-    if (isTTY(process.stdout))
-        return;
-    throw new UsageError(`No terminal to ask which ${what} to use. Pass ${flag} — this is not an interactive shell.`);
-}
-/**
- * Which graphics.
- *
- * Autocomplete rather than a plain list: there are dozens once a semester of
- * meetings is loaded, and the useful interaction is typing "sep" or "dogdays"
- * rather than scrolling. Grouped by prefix in the label so the list reads as
- * the `group/name` vocabulary the flags use.
- */
-export async function pickGraphics(graphics) {
-    requireInteractive("graphics", "a graphic name, or `*` for all of them");
-    const chosen = unwrap(await autocompleteMultiselect({
-        message: "Which images?",
-        options: graphics.map((graphic) => ({
-            value: graphic.name,
-            label: graphic.name,
-            hint: graphic.why,
-        })),
-    }));
-    return graphics.filter((graphic) => chosen.includes(graphic.name));
-}
-/**
- * Which formats.
- *
- * Offered from the union of what the chosen graphics support, so the list never
- * contains a size that would be skipped — asking somebody to pick `savvycal`
- * for an event and then quietly not rendering it is worse than not offering it.
- */
-export async function pickFormats(graphics) {
-    requireInteractive("formats", "--format or --all-formats");
-    const available = await formatsFor(graphics);
-    return unwrap(await multiselect({
-        message: "Which formats?",
-        options: available.map((format) => ({
-            value: format.name,
-            label: format.name,
-            hint: format.why,
-        })),
-        // The link card is what most of these are for, and it is supported by
-        // every graphic that is not an icon.
-        initialValues: available.some((format) => format.name === "og")
-            ? ["og"]
-            : [],
-    }));
-}
-/** `undefined` means "each graphic's own default directory". */
-export async function pickOutput(graphics) {
-    requireInteractive("output directory", "--out or --default-out");
-    const { FORMATS } = await loadOpenGraph();
-    // Shown so the choice is concrete. One directory names itself; several are
-    // summarised, because listing eight paths in a prompt hint is unreadable.
-    const defaults = [
-        ...new Set(graphics.flatMap((graphic) => graphic.formats
-            .map((name) => FORMATS[name])
-            .filter((format) => format !== undefined)
-            .map((format) => graphic.destination(format).dir))),
-    ];
-    const choice = unwrap(await select({
-        message: "Where should these go?",
-        options: [
-            {
-                value: "default",
-                label: defaults.length === 1 ? defaults[0] : "Their default directories",
-                hint: defaults.length === 1
-                    ? "where this one belongs"
-                    : `${defaults.length} directories, one per graphic`,
-            },
-            { value: "other", label: "Other…", hint: "a directory of your own" },
-        ],
-    }));
-    if (choice === "default")
-        return undefined;
-    return unwrap(await path({
-        message: "Which directory?",
-        // Completes against the filesystem, and only offers directories — the
-        // answer is a folder, and offering files would invite naming one.
-        directory: true,
-    }));
-}

package/dist/images/render.d.ts

@@ -1,21 +0,0 @@
-import type { ReactElement } from "react";
-export interface RenderOptions {
-    /** The layout's own width. Every size in the template is against this. */
-    width: number;
-    height: number;
-    /**
-     * Output pixels per layout pixel. The layout is computed once at `width` and
-     * the vector result is rasterised larger, so 3x is genuinely three times the
-     * detail rather than an upscaled 1x — and the type stays on the same metrics
-     * at every scale, which is what makes @1x/@2x/@3x a set rather than three
-     * slightly different pictures.
-     */
-    scale?: number;
-}
-export interface Rendered {
-    png: Buffer;
-    svg: string;
-    width: number;
-    height: number;
-}
-export declare function render(element: ReactElement, { width, height, scale }: RenderOptions): Promise<Rendered>;

package/dist/images/render.js

@@ -1,61 +0,0 @@
-/**
- * Turning a template into a PNG on disk.
- *
- * Two libraries, and the choice of each is load-bearing:
- *
- *   * **Satori** lays the template out and emits SVG. It is the same engine
- *     `next/og` runs inside the platform, so a card exported here and a card
- *     unfurled from a URL are the same picture rather than two implementations
- *     of one design.
- *   * **resvg** rasterises it, for the same reason. The obvious alternative was
- *     sharp, which this package already depends on — but sharp rasterises
- *     through librsvg, and librsvg does not read `rgba()` in a gradient stop,
- *     which is exactly the notation Satori emits. The background washes came
- *     out as flat black, silently and only in the CLI's copy of an image the
- *     site rendered correctly. resvg is what `@vercel/og` itself uses.
- *
- * `@vercel/og` is deliberately NOT used here even though this mirrors it. Its
- * Node build is bundled for a CommonJS loader: imported as ESM it wants a
- * global `require`, then a global `__dirname`, and then an `hb.wasm` the
- * package does not ship. `next/og` cannot be imported outside Next's bundler at
- * all. Driving Satori directly is the same rendering, three hacks fewer.
- */
-import { Resvg } from "@resvg/resvg-js";
-import satori, {} from "satori";
-import { loadOpenGraph } from "../repo/source.js";
-let fonts;
-/** The embedded faces, in Satori's shape. Decoded once per process. */
-async function satoriFonts() {
-    if (fonts)
-        return fonts;
-    const { loadFonts } = await loadOpenGraph();
-    return (fonts = loadFonts().map((font) => ({
-        name: font.name,
-        data: font.data,
-        weight: font.weight,
-        style: font.style,
-    })));
-}
-export async function render(element, { width, height, scale = 1 }) {
-    const svg = await satori(element, {
-        width,
-        height,
-        fonts: await satoriFonts(),
-    });
-    const png = new Resvg(svg, {
-        fitTo: { mode: "width", value: Math.round(width * scale) },
-        // Satori has already turned every glyph into a path, so resvg never needs
-        // to resolve a family. Saying so keeps it from probing the host's fonts,
-        // which is the one thing here that could differ between a contributor's
-        // machine and CI.
-        font: { loadSystemFonts: false },
-    })
-        .render()
-        .asPng();
-    return {
-        png,
-        svg,
-        width: Math.round(width * scale),
-        height: Math.round(height * scale),
-    };
-}

package/dist/images/select.d.ts

@@ -1,64 +0,0 @@
-import type { Format } from "./open-graph-types.js";
-import type { Graphic } from "./graphics.js";
-/**
- * Turning what somebody typed into a list of (graphic, format) pairs.
- *
- * Kept apart from `commands.ts` because all of it is pure: given a registry and
- * some patterns, these answer the same way every time and can be tested
- * without a terminal, a database or a renderer.
- */
-/** One image to render: a subject, and the size to draw it at. */
-export interface Selection {
-    graphic: Graphic;
-    format: Format;
-}
-export interface GraphicMatch {
-    matched: Graphic[];
-    /** Patterns that named nothing, so the caller can say which. */
-    unmatched: string[];
-}
-/**
- * Resolves graphic patterns.
- *
- * Every graphic is `group/name`, and three shapes of pattern read against
- * that: a lone star (or a star over a star) is everything, `group/` plus a star
- * is a whole group, and anything else is an exact name. Deliberately not a
- * general glob — `event/2026-` plus a star looks like it should work and would
- * be one more thing to specify, and the picker covers the case where somebody
- * does not know the exact name.
- *
- * A bare group is accepted as shorthand for `group/*`, because `images icons`
- * is what people type and refusing it teaches nothing.
- */
-export declare function matchGraphics(patterns: readonly string[], graphics: readonly Graphic[]): GraphicMatch;
-/**
- * Pairs each graphic with each requested format it actually supports.
- *
- * The matrix is sparse, and silently dropping a pair is the wrong answer in one
- * direction only: asking for `*` at every format should quietly skip the
- * combinations that do not exist, while asking for one graphic at one format it
- * cannot do should say so. The caller decides which case it is; this reports
- * both halves.
- */
-export declare function pair(graphics: readonly Graphic[], formats: readonly string[]): Promise<{
-    selections: Selection[];
-    unsupported: {
-        graphic: string;
-        format: string;
-    }[];
-}>;
-/** Every format any of these graphics can be drawn at, in registry order. */
-export declare function formatsFor(graphics: readonly Graphic[]): Promise<Format[]>;
-/**
- * Splits `--flag=value` into two tokens.
- *
- * The rest of this CLI reads flags as `--flag value`, and `positionals()`
- * depends on that to tell a flag's value from a subcommand. `--format=a,b`
- * arrives as one token, so it would be read as a positional — that is, as a
- * graphic name — and `images --format=og` would try to render a graphic called
- * `--format=og` and report nothing matched. Normalising here lets both spellings
- * work without teaching the shared parser about either.
- */
-export declare function normalizeArgv(argv: readonly string[]): string[];
-/** A comma-separated flag value, trimmed and emptied of blanks. */
-export declare function commaList(value: string | undefined): string[];