@stats-forge/github-stats-forge-cli 0.0.1

package/build/index.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { CardConfig } from '@stats-forge/github-stats-forge-core';
+import { cards, findCard } from './cards.js';
+import { askRequired, askSavePath, askToken, navigateOptions, pickCard } from './prompts.js';
+import { defaultFileName, toQuery } from './query.js';
+import { readSavedCard, savedCardExists, toAnswers, writeSavedCard } from './saved-card.js';
+import { withSpinner } from './spinner.js';
+import { DEFAULT_ENV_FILE, loadEnvFile, resolveTokens } from './tokens.js';
+const HELP = `github-stats-forge — render a GitHub stats card to a local SVG
+
+Usage
+  github-stats-forge [options]
+
+Options
+  -c, --card <id>       Skip the card prompt: ${cards.map((card) => card.id).join(', ')}
+  -o, --out <file>      Where to write the card (default: named after the card)
+      --config <file>   Options to load, and where "Save these options" writes
+  -g, --generate        Render what --config holds and exit, without the menu
+      --pat <token>     GitHub token; repeat for several
+      --env-file <file> Env file to read PAT_1, PAT_2, … from (default: ${DEFAULT_ENV_FILE})
+  -h, --help            Show this
+  -v, --version         Show the version
+
+The token can also come from PAT_1 in the environment, or be typed when asked.
+`;
+/**
+ * @returns The flags this run was given.
+ */
+const readFlags = () => parseArgs({
+    options: {
+        card: { type: 'string', short: 'c' },
+        out: { type: 'string', short: 'o' },
+        config: { type: 'string' },
+        generate: { type: 'boolean', short: 'g', default: false },
+        pat: { type: 'string', multiple: true, default: [] },
+        'env-file': { type: 'string' },
+        help: { type: 'boolean', short: 'h', default: false },
+        version: { type: 'boolean', short: 'v', default: false },
+    },
+    allowPositionals: false,
+}).values;
+/**
+ * Renders a card and writes it next to wherever the run was started.
+ *
+ * @param card The card to render.
+ * @param query Its params.
+ * @param config Tokens the fetchers use.
+ * @param out Where to write it; named after the card when absent.
+ * @returns The file written, or the code that says why nothing was.
+ */
+const renderAndWrite = async (card, query, config, out) => {
+    const result = await withSpinner(`Rendering the ${card.id} card`, () => card.render(query, config));
+    if (result.status === 'error') {
+        const { code, message, secondaryMessage, param } = result.error;
+        process.stderr.write([
+            `Could not render the ${card.id} card.`,
+            `  ${message}${secondaryMessage ? `: ${secondaryMessage}` : ''}`,
+            `  code: ${code}${param ? `, param: ${param}` : ''}`,
+            result.retryable ? '  This one may work on a retry.' : '',
+        ]
+            .filter(Boolean)
+            .join('\n') + '\n');
+        return { failed: code };
+    }
+    const file = resolve(process.cwd(), out ?? defaultFileName(card, query));
+    await writeFile(file, result.content, 'utf8');
+    const written = relative(process.cwd(), file);
+    process.stdout.write(`Wrote ${written}\n`);
+    return { written };
+};
+/**
+ * Renders one card and writes it next to wherever the run was started.
+ *
+ * @returns Nothing; the process exits non-zero when the card could not be rendered.
+ */
+const main = async () => {
+    const flags = readFlags();
+    if (flags.help) {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (flags.version) {
+        // Same relative position from `src/` and from `build/`.
+        const manifest = new URL('../package.json', import.meta.url);
+        const { version } = JSON.parse(await readFile(manifest, 'utf8'));
+        process.stdout.write(`${version}\n`);
+        return;
+    }
+    // An explicit `--env-file` must exist; the default one is a convenience.
+    const envFile = flags['env-file'];
+    loadEnvFile(envFile ?? DEFAULT_ENV_FILE, envFile !== undefined);
+    // A saved file names its own card and carries its answers, so it skips both prompts.
+    const saved = flags.config !== undefined && savedCardExists(flags.config)
+        ? await readSavedCard(flags.config)
+        : undefined;
+    if (flags.generate && !saved) {
+        throw new Error('--generate renders a saved card, so it needs --config pointing at one.');
+    }
+    /*
+     * Every other path asks something.
+     * Without a terminal the prompt would hang on a stdin that never answers,
+     * so say what to pass instead.
+     */
+    if (!flags.generate && !process.stdin.isTTY) {
+        throw new Error('github-stats-forge asks questions, so it needs a terminal. Render a saved card instead: --config <file> --generate');
+    }
+    if (saved && flags.card !== undefined && flags.card !== saved.card.id) {
+        throw new Error(`${flags.config ?? ''} holds a ${saved.card.id} card, but --card asked for ${flags.card}.`);
+    }
+    const card = saved?.card ?? (flags.card === undefined ? await pickCard() : findCard(flags.card));
+    if (!card) {
+        throw new Error(`No card called "${flags.card ?? ''}". Try one of: ${cards
+            .map((known) => known.id)
+            .join(', ')}`);
+    }
+    let tokens = resolveTokens(flags.pat, process.env);
+    if (card.needsToken && tokens.length === 0 && flags.generate) {
+        throw new Error(`The ${card.id} card reads the GitHub API, so it needs a token. Pass --pat, or put PAT_1 in ${DEFAULT_ENV_FILE}.`);
+    }
+    if (card.needsToken && tokens.length === 0) {
+        const typed = await askToken();
+        if (!typed) {
+            throw new Error(`The ${card.id} card reads the GitHub API, so it needs a token. Pass --pat, or put PAT_1 in ${DEFAULT_ENV_FILE}.`);
+        }
+        tokens = [{ name: 'prompt', value: typed }];
+    }
+    const config = new CardConfig({ pats: tokens });
+    // `--generate` renders what the file holds and stops: no menu, nothing to answer.
+    if (saved && flags.generate) {
+        const outcome = await renderAndWrite(card, saved.params, config, flags.out);
+        if ('failed' in outcome) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    const menu = {
+        answers: saved ? toAnswers(card, saved.params) : await askRequired(card),
+    };
+    let savePath = flags.config;
+    /*
+     * The menu stays open after a render:
+     * a card is rarely right the first time, and the whole point of the option
+     * list is to change one thing and look again.
+     */
+    let status;
+    let lastFailed = false;
+    for (;;) {
+        const action = await navigateOptions(card, menu, status);
+        if (action === 'quit') {
+            break;
+        }
+        const query = toQuery(menu.answers);
+        if (action === 'save') {
+            const path = savePath ?? (await askSavePath(defaultFileName(card, query).replace(/\.svg$/, '.json')));
+            if (path) {
+                savePath = path;
+                const written = await writeSavedCard(path, card, query);
+                status = `saved ${relative(process.cwd(), written)} — load it again with --config`;
+            }
+            continue;
+        }
+        const outcome = await renderAndWrite(card, query, config, flags.out);
+        if ('failed' in outcome) {
+            // Left on the menu, since a rejected param is one edit away from working.
+            status = `${outcome.failed} — fix it and generate again`;
+            lastFailed = true;
+            continue;
+        }
+        status = `wrote ${outcome.written} — edit an option and generate again`;
+        lastFailed = false;
+    }
+    // Leaving straight after a failure still reports one.
+    if (lastFailed) {
+        process.exitCode = 1;
+    }
+};
+try {
+    await main();
+}
+catch (err) {
+    // A cancelled prompt is a normal way to leave, not a crash.
+    if (err instanceof Error && err.name === 'ExitPromptError') {
+        process.exitCode = 130;
+    }
+    else {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+    }
+}

package/build/prompts.d.ts

@@ -0,0 +1,58 @@
+import type { CardKind, CardOption } from './cards.js';
+import type { Answer } from './query.js';
+/**
+ * @file The navigation itself.
+ *
+ * A card first, then its required params, then a menu of every other option:
+ * pick one, answer it, and land back on the menu with the answer beside it.
+ */
+/**
+ * @returns The card to render.
+ */
+export declare const pickCard: () => Promise<CardKind>;
+/** How a trip through the option menu ended. */
+export type MenuChoice = 'generate' | 'save' | 'quit';
+/** What the menu carries between trips through it. */
+export interface Menu {
+    /** Answers so far, edited in place. */
+    answers: Map<string, Answer>;
+    /**
+     * Where the cursor sat when the menu was last left.
+     * Reopening lands on it, so editing one option after another does not mean
+     * scrolling back down each time.
+     */
+    cursor?: CardOption | MenuChoice | undefined;
+}
+/**
+ * Walks a card's options until the run asks for the card, or to leave.
+ *
+ * The menu is edited in place, so reopening it after a render keeps every answer
+ * and the cursor exactly where they were.
+ *
+ * @param card The card being built.
+ * @param menu Answers so far, and where the cursor sat.
+ * @param status What happened last time round, shown in the menu's own line.
+ * @returns Whether to render the card or to stop.
+ */
+export declare const navigateOptions: (card: CardKind, menu: Menu, status?: string) => Promise<MenuChoice>;
+/**
+ * Asks for the params the card cannot render without.
+ *
+ * @param card The card being built.
+ * @returns The answers, one per required param.
+ */
+export declare const askRequired: (card: CardKind) => Promise<Map<string, Answer>>;
+/**
+ * Asks where to write the options, when no `--config` said.
+ *
+ * @param suggestion The path offered by default.
+ * @returns The path, or `undefined` when the run changed its mind.
+ */
+export declare const askSavePath: (suggestion: string) => Promise<string | undefined>;
+/**
+ * Asks for a token, when nothing supplied one.
+ *
+ * @returns The token, or `undefined` when the run declined to give one.
+ */
+export declare const askToken: () => Promise<string | undefined>;
+//# sourceMappingURL=prompts.d.ts.map

package/build/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,QAAQ,QAAa,OAAO,CAAC,QAAQ,CAI9C,CAAC;AA+BL,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtD,sDAAsD;AACtD,MAAM,WAAW,IAAI;IACnB,uCAAuC;IACvC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAC1B,MAAM,QAAQ,EACd,MAAM,IAAI,EACV,SAAS,MAAM,KACd,OAAO,CAAC,UAAU,CAkCpB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAU,MAAM,QAAQ,KAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAY7E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAU,YAAY,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAMhF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,QAAa,OAAO,CAAC,MAAM,GAAG,SAAS,CAM3D,CAAC"}

package/build/prompts.js

@@ -0,0 +1,125 @@
+import { confirm, input, password, select } from '@inquirer/prompts';
+import { cards } from './cards.js';
+import { describeAnswer } from './query.js';
+/**
+ * @file The navigation itself.
+ *
+ * A card first, then its required params, then a menu of every other option:
+ * pick one, answer it, and land back on the menu with the answer beside it.
+ */
+/**
+ * @returns The card to render.
+ */
+export const pickCard = async () => select({
+    message: 'Which card?',
+    choices: cards.map((card) => ({ name: card.label, value: card })),
+});
+/**
+ * Asks for one option, seeded with whatever it already holds.
+ *
+ * @param option The option to ask for.
+ * @param current What it holds now.
+ * @returns The answer, or `undefined` when it was cleared.
+ */
+const askOption = async (option, current) => {
+    const message = option.hint ? `${option.label} (${option.hint})` : option.label;
+    if (option.kind === 'boolean') {
+        return confirm({ message, default: current === true });
+    }
+    if (option.kind === 'choice') {
+        const choices = [
+            { name: '— leave unset —', value: undefined },
+            ...(option.choices ?? []).map((value) => ({ name: value, value })),
+        ];
+        return select({ message, choices, default: current });
+    }
+    const answer = await input({
+        message,
+        default: current === undefined ? undefined : String(current),
+    });
+    return answer.trim() === '' ? undefined : answer.trim();
+};
+/**
+ * Walks a card's options until the run asks for the card, or to leave.
+ *
+ * The menu is edited in place, so reopening it after a render keeps every answer
+ * and the cursor exactly where they were.
+ *
+ * @param card The card being built.
+ * @param menu Answers so far, and where the cursor sat.
+ * @param status What happened last time round, shown in the menu's own line.
+ * @returns Whether to render the card or to stop.
+ */
+export const navigateOptions = async (card, menu, status) => {
+    // The label carries a description after an em dash; the menu wants the name.
+    const [name = card.id] = card.label.split(' — ');
+    for (;;) {
+        const choice = await select({
+            message: status ? `${name} — ${status}` : `${name} — set an option, or generate`,
+            pageSize: 15,
+            // Matched by reference against the values below, so the option objects work.
+            default: menu.cursor,
+            choices: [
+                { name: 'Generate the card', value: 'generate' },
+                { name: 'Save these options', value: 'save' },
+                { name: 'Quit', value: 'quit' },
+                ...card.options.map((option) => ({
+                    name: `${option.label.padEnd(38)} ${describeAnswer(option, menu.answers.get(option.name))}`,
+                    value: option,
+                })),
+            ],
+        });
+        menu.cursor = choice;
+        if (choice === 'generate' || choice === 'save' || choice === 'quit') {
+            return choice;
+        }
+        const answer = await askOption(choice, menu.answers.get(choice.name));
+        if (answer === undefined) {
+            menu.answers.delete(choice.name);
+        }
+        else {
+            menu.answers.set(choice.name, answer);
+        }
+    }
+};
+/**
+ * Asks for the params the card cannot render without.
+ *
+ * @param card The card being built.
+ * @returns The answers, one per required param.
+ */
+export const askRequired = async (card) => {
+    const answers = new Map();
+    for (const option of card.required) {
+        answers.set(option.name, await input({
+            message: option.label,
+            validate: (value) => value.trim() !== '' || 'Required',
+        }));
+    }
+    return answers;
+};
+/**
+ * Asks where to write the options, when no `--config` said.
+ *
+ * @param suggestion The path offered by default.
+ * @returns The path, or `undefined` when the run changed its mind.
+ */
+export const askSavePath = async (suggestion) => {
+    const answer = await input({
+        message: 'Save the options to',
+        default: suggestion,
+    });
+    return answer.trim() === '' ? undefined : answer.trim();
+};
+/**
+ * Asks for a token, when nothing supplied one.
+ *
+ * @returns The token, or `undefined` when the run declined to give one.
+ */
+export const askToken = async () => {
+    const value = await password({
+        message: 'GitHub personal access token (input hidden)',
+        mask: '*',
+    });
+    return value.trim() === '' ? undefined : value.trim();
+};

package/build/query.d.ts

@@ -0,0 +1,37 @@
+import type { CardKind, CardOption } from './cards.js';
+/**
+ * @file Answers in, query params out.
+ *
+ * The core handlers take exactly what a query string carries — strings — so an
+ * answer becomes one here, and an unanswered option is simply absent.
+ */
+/** What a prompt answered, before it becomes a query param. */
+export type Answer = string | number | boolean | Array<string> | undefined;
+/**
+ * @param value What the prompt returned.
+ * @returns The query string form, or `undefined` when there is nothing to send.
+ */
+export declare const toParam: (value: Answer) => string | undefined;
+/**
+ * @param answers What each option was answered with.
+ * @returns The query the card handler is called with.
+ */
+export declare const toQuery: (answers: ReadonlyMap<string, Answer>) => Record<string, string>;
+/**
+ * How an answer reads back in the option menu.
+ *
+ * @param option The option it answers.
+ * @param value What it was answered with.
+ * @returns The value as the menu shows it.
+ */
+export declare const describeAnswer: (option: CardOption, value: Answer) => string;
+/**
+ * The file a card is written to when `--out` is not given.
+ * Named after the card and whoever it is about, so a directory of them stays readable.
+ *
+ * @param card The card being rendered.
+ * @param query The answers it was rendered from.
+ * @returns A file name, ending in `.svg`.
+ */
+export declare const defaultFileName: (card: CardKind, query: Record<string, string>) => string;
+//# sourceMappingURL=query.d.ts.map

package/build/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;GAKG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,MAAM,GAAG,SAQhD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,SAAS,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CASnF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,UAAU,EAAE,OAAO,MAAM,KAAG,MAMlE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,QAAQ,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAK/E,CAAC"}

package/build/query.js

@@ -0,0 +1,55 @@
+/**
+ * @param value What the prompt returned.
+ * @returns The query string form, or `undefined` when there is nothing to send.
+ */
+export const toParam = (value) => {
+    if (value === undefined || value === '') {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return value.length > 0 ? value.join(',') : undefined;
+    }
+    return String(value);
+};
+/**
+ * @param answers What each option was answered with.
+ * @returns The query the card handler is called with.
+ */
+export const toQuery = (answers) => {
+    const query = {};
+    for (const [name, value] of answers) {
+        const param = toParam(value);
+        if (param !== undefined) {
+            query[name] = param;
+        }
+    }
+    return query;
+};
+/**
+ * How an answer reads back in the option menu.
+ *
+ * @param option The option it answers.
+ * @param value What it was answered with.
+ * @returns The value as the menu shows it.
+ */
+export const describeAnswer = (option, value) => {
+    const param = toParam(value);
+    if (param === undefined) {
+        return '—';
+    }
+    return option.kind === 'boolean' ? (value === true ? 'yes' : 'no') : param;
+};
+/**
+ * The file a card is written to when `--out` is not given.
+ * Named after the card and whoever it is about, so a directory of them stays readable.
+ *
+ * @param card The card being rendered.
+ * @param query The answers it was rendered from.
+ * @returns A file name, ending in `.svg`.
+ */
+export const defaultFileName = (card, query) => {
+    const subject = query['username'] ?? query['id'] ?? 'card';
+    const repo = query['repo'];
+    const parts = [card.id, subject, repo].filter(Boolean).join('-');
+    return `${parts.replace(/[^\w.-]/g, '-')}.svg`;
+};

package/build/saved-card.d.ts

@@ -0,0 +1,39 @@
+import type { CardKind } from './cards.js';
+import type { Answer } from './query.js';
+/**
+ * @param path File to look for, relative to the working directory.
+ * @returns Whether there is something there to load.
+ */
+export declare const savedCardExists: (path: string) => boolean;
+/**
+ * Reads a card back off disk.
+ *
+ * @param path File to read, relative to the working directory.
+ * @returns The card it names, and its params.
+ * @throws {Error} When the file is not a card this version can render.
+ */
+export declare const readSavedCard: (path: string) => Promise<{
+    card: CardKind;
+    params: Record<string, string>;
+}>;
+/**
+ * Writes a card down, so the same one can be rendered again later.
+ *
+ * @param path File to write, relative to the working directory.
+ * @param card The card being rendered.
+ * @param params Its params, as they reach the endpoint.
+ * @returns The path written to.
+ */
+export declare const writeSavedCard: (path: string, card: CardKind, params: Record<string, string>) => Promise<string>;
+/**
+ * Turns saved params back into answers the menu can show and edit.
+ *
+ * Everything on a query string is a string;
+ * a boolean option becomes one again so its prompt opens on the right answer.
+ *
+ * @param card The card the params belong to.
+ * @param params The saved params.
+ * @returns The answers, ready for the menu.
+ */
+export declare const toAnswers: (card: CardKind, params: Record<string, string>) => Map<string, Answer>;
+//# sourceMappingURL=saved-card.d.ts.map

package/build/saved-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saved-card.d.ts","sourceRoot":"","sources":["../src/saved-card.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAiBzC;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,OAAmD,CAAC;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,KACX,OAAO,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAyB5D,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,MAAM,QAAQ,EACd,QAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC7B,OAAO,CAAC,MAAM,CAKhB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,QAAQ,EAAE,QAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAW5F,CAAC"}

package/build/saved-card.js

@@ -0,0 +1,68 @@
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { findCard } from './cards.js';
+/**
+ * @param path File to look for, relative to the working directory.
+ * @returns Whether there is something there to load.
+ */
+export const savedCardExists = (path) => existsSync(resolve(process.cwd(), path));
+/**
+ * Reads a card back off disk.
+ *
+ * @param path File to read, relative to the working directory.
+ * @returns The card it names, and its params.
+ * @throws {Error} When the file is not a card this version can render.
+ */
+export const readSavedCard = async (path) => {
+    const file = resolve(process.cwd(), path);
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`${file} is not readable as JSON`, { cause: err });
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error(`${file} does not hold a saved card`);
+    }
+    const { card: id, params } = parsed;
+    const card = typeof id === 'string' ? findCard(id) : undefined;
+    if (!card) {
+        throw new Error(`${file} names no card this version renders: ${id ?? '(nothing)'}`);
+    }
+    // A param that is not a string could not have come off a query string.
+    const entries = Object.entries(params ?? {}).filter((entry) => typeof entry[1] === 'string');
+    return { card, params: Object.fromEntries(entries) };
+};
+/**
+ * Writes a card down, so the same one can be rendered again later.
+ *
+ * @param path File to write, relative to the working directory.
+ * @param card The card being rendered.
+ * @param params Its params, as they reach the endpoint.
+ * @returns The path written to.
+ */
+export const writeSavedCard = async (path, card, params) => {
+    const file = resolve(process.cwd(), path);
+    const saved = { card: card.id, params };
+    await writeFile(file, `${JSON.stringify(saved, null, 2)}\n`, 'utf8');
+    return file;
+};
+/**
+ * Turns saved params back into answers the menu can show and edit.
+ *
+ * Everything on a query string is a string;
+ * a boolean option becomes one again so its prompt opens on the right answer.
+ *
+ * @param card The card the params belong to.
+ * @param params The saved params.
+ * @returns The answers, ready for the menu.
+ */
+export const toAnswers = (card, params) => {
+    const kinds = new Map([...card.required, ...card.options].map((option) => [option.name, option.kind]));
+    return new Map(Object.entries(params).map(([name, value]) => [
+        name,
+        kinds.get(name) === 'boolean' ? value === 'true' : value,
+    ]));
+};

package/build/spinner.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file The wait between the last prompt and the file.
+ *
+ * Rendering a card means fetching from GitHub, which takes long enough that a
+ * still terminal reads as a hung one.
+ */
+/** What the spinner writes to; `process.stderr`, or a fake in a test. */
+export interface SpinnerStream {
+    isTTY?: boolean | undefined;
+    write: (chunk: string) => unknown;
+}
+/**
+ * Runs `work`, spinning until it settles.
+ *
+ * Written to stderr, so stdout carries only the result.
+ * Without a TTY — a pipe, a CI log — the label is printed once and nothing animates.
+ *
+ * @param label What the wait is for.
+ * @param work The wait itself.
+ * @param stream Where the spinner is drawn.
+ * @returns Whatever `work` answered with.
+ */
+export declare const withSpinner: <T>(label: string, work: () => Promise<T>, stream?: SpinnerStream) => Promise<T>;
+//# sourceMappingURL=spinner.d.ts.map

package/build/spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../src/spinner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EACjC,OAAO,MAAM,EACb,MAAM,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,SAAQ,aAA8B,KACrC,OAAO,CAAC,CAAC,CAoBX,CAAC"}

package/build/spinner.js

@@ -0,0 +1,44 @@
+/**
+ * @file The wait between the last prompt and the file.
+ *
+ * Rendering a card means fetching from GitHub, which takes long enough that a
+ * still terminal reads as a hung one.
+ */
+/** Braille frames: one cell wide, so the line never reflows. */
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const INTERVAL_MS = 80;
+const HIDE_CURSOR = '\u001b[?25l';
+const SHOW_CURSOR = '\u001b[?25h';
+/** Return to the start of the line and wipe what was on it. */
+const CLEAR_LINE = '\r\u001b[K';
+/**
+ * Runs `work`, spinning until it settles.
+ *
+ * Written to stderr, so stdout carries only the result.
+ * Without a TTY — a pipe, a CI log — the label is printed once and nothing animates.
+ *
+ * @param label What the wait is for.
+ * @param work The wait itself.
+ * @param stream Where the spinner is drawn.
+ * @returns Whatever `work` answered with.
+ */
+export const withSpinner = async (label, work, stream = process.stderr) => {
+    if (!stream.isTTY) {
+        stream.write(`${label}…\n`);
+        return work();
+    }
+    let frame = 0;
+    stream.write(HIDE_CURSOR);
+    const tick = setInterval(() => {
+        stream.write(`${CLEAR_LINE}${FRAMES[frame % FRAMES.length] ?? ''} ${label}`);
+        frame += 1;
+    }, INTERVAL_MS);
+    try {
+        return await work();
+    }
+    finally {
+        clearInterval(tick);
+        // The line goes back to the shell as it was found, whichever way this ended.
+        stream.write(`${CLEAR_LINE}${SHOW_CURSOR}`);
+    }
+};