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

package/README.md

@@ -21,7 +21,7 @@ Requires Node 24 or newer. The cards themselves come from
 so every option below is the one that package's api accepts — the prompts read the
 accepted values off it rather than keeping their own copy.
 
-It asks which card you want, then the params that card cannot render without, then
+It asks which card you want, then the options that card cannot render without, then
 puts you in a menu of every other option it accepts — pick one, answer it, and the
 menu comes back with the answer beside it. `Generate the card` writes the SVG.
 
@@ -43,7 +43,7 @@ again. `Quit` (or Ctrl-C) ends the session.
 
 ## Saving a card
 
-`Save these options` in the menu writes the card and its params to a JSON file, and
+`Save these options` in the menu writes the card and its options to a JSON file, and
 `--config` loads one back:
 
 ```sh
@@ -53,7 +53,7 @@ github-stats-forge --config my-stats.json      # picks up where the file left of
 ```json
 {
   "card": "stats",
-  "params": {
+  "options": {
     "username": "anuraghazra",
     "theme": "tokyonight",
     "show_icons": "true"
@@ -63,7 +63,7 @@ github-stats-forge --config my-stats.json      # picks up where the file left of
 
 The file holds what a query string holds, so it reads like the URL it stands for and
 can be edited by hand. Loading one skips both the card prompt and the required
-params, landing you straight on the menu — and `--config` doubles as the save target,
+options, landing you straight on the menu — and `--config` doubles as the save target,
 so the next `Save these options` writes back to it without asking.
 
 `--generate` skips the menu too, rendering exactly what the file holds:

package/build/cards.d.ts

@@ -1,4 +1,4 @@
-import type { ApiResult, CardConfig } from '@stats-forge/github-stats-forge-core';
+import type { ApiResult, CardConfig } from '@stats-forge/github-stats-forge-core/api';
 /**
  * @file What each card accepts, in the order the prompts walk it.
  *
@@ -29,17 +29,12 @@ export interface CardKind {
     required: ReadonlyArray<CardOption>;
     /** Everything else, navigable in any order. */
     options: ReadonlyArray<CardOption>;
-    /**
-     * @param query The answers, as a query string would carry them.
-     * @param config Tokens the fetchers use.
-     * @returns The rendered card, or the rendered error.
-     */
+    /** @returns The rendered card, or the rendered error. */
     render: (query: Record<string, string>, config: CardConfig) => Promise<ApiResult>;
 }
 /** Every card, with the options every card shares appended to its own. */
 export declare const cards: ReadonlyArray<CardKind>;
 /**
- * @param id The card's id, as `--card` takes it.
  * @returns The card, or `undefined` when nothing renders under that name.
  */
 export declare const findCard: (id: string) => CardKind | undefined;

package/build/cards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cards.d.ts","sourceRoot":"","sources":["../src/cards.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAElF;;;;;GAKG;AAEH,iFAAiF;AACjF,KAAK,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpE,6BAA6B;AAC7B,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,CAAC;IACjB,yCAAyC;IACzC,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChC,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACpC,+CAA+C;IAC/C,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACnC;;;;OAIG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;CACnF;AAkSD,0EAA0E;AAC1E,eAAO,MAAM,KAAK,EAAE,aAAa,CAAC,QAAQ,CAGvC,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,IAAI,MAAM,KAAG,QAAQ,GAAG,SAAiD,CAAC"}
+{"version":3,"file":"cards.d.ts","sourceRoot":"","sources":["../src/cards.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAEtF;;;;;GAKG;AAEH,iFAAiF;AACjF,KAAK,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpE,6BAA6B;AAC7B,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,CAAC;IACjB,yCAAyC;IACzC,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChC,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACpC,+CAA+C;IAC/C,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACnC,yDAAyD;IACzD,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;CACnF;AAkSD,0EAA0E;AAC1E,eAAO,MAAM,KAAK,EAAE,aAAa,CAAC,QAAQ,CAGvC,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,QAAQ,OAAQ,MAAM,KAAG,QAAQ,GAAG,SAAiD,CAAC"}

package/build/cards.js

@@ -1,4 +1,4 @@
-import { gist, pin, stats, themes, topLangs, wakatime } from '@stats-forge/github-stats-forge-core';
+import { gist, pin, stats, themes, topLangs, wakatime, } from '@stats-forge/github-stats-forge-core/api';
 const THEME_NAMES = Object.keys(themes);
 /** Colors and the theme, which every card accepts. */
 const COMMON_OPTIONS = [
@@ -289,7 +289,6 @@ export const cards = CARDS.map((card) => ({
     options: [...card.options, ...COMMON_OPTIONS],
 }));
 /**
- * @param id The card's id, as `--card` takes it.
  * @returns The card, or `undefined` when nothing renders under that name.
  */
 export const findCard = (id) => cards.find((card) => card.id === id);

package/build/index.js

@@ -2,7 +2,7 @@
 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 { CardConfig } from '@stats-forge/github-stats-forge-core/api';
 import { cards, findCard } from './cards.js';
 import { askRequired, askSavePath, askToken, navigateOptions, pickCard } from './prompts.js';
 import { defaultFileName, toQuery } from './query.js';
@@ -45,24 +45,20 @@ const readFlags = () => parseArgs({
 /**
  * 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([
+        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');
+            .join('\n')}\n`);
         return { failed: code };
     }
     const file = resolve(process.cwd(), out ?? defaultFileName(card, query));
@@ -73,6 +69,7 @@ const renderAndWrite = async (card, query, config, out) => {
 };
 /**
  * Renders one card and writes it next to wherever the run was started.
+ * Sets a non-zero exit code rather than throwing when it could not.
  *
  * @returns Nothing; the process exits non-zero when the card could not be rendered.
  */
@@ -130,14 +127,14 @@ const main = async () => {
     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);
+        const outcome = await renderAndWrite(card, saved.options, config, flags.out);
         if ('failed' in outcome) {
             process.exitCode = 1;
         }
         return;
     }
     const menu = {
-        answers: saved ? toAnswers(card, saved.params) : await askRequired(card),
+        answers: saved ? toAnswers(card, saved.options) : await askRequired(card),
     };
     let savePath = flags.config;
     /*
@@ -180,13 +177,13 @@ const main = async () => {
 try {
     await main();
 }
-catch (err) {
+catch (error) {
     // A cancelled prompt is a normal way to leave, not a crash.
-    if (err instanceof Error && err.name === 'ExitPromptError') {
+    if (error instanceof Error && error.name === 'ExitPromptError') {
         process.exitCode = 130;
     }
     else {
-        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
         process.exitCode = 1;
     }
 }

package/build/prompts.d.ts

@@ -1,14 +1,12 @@
-import type { CardKind, CardOption } from './cards.js';
-import type { Answer } from './query.js';
+import type { CardKind, CardOption } from './cards.ts';
+import type { Answer } from './query.ts';
 /**
  * @file The navigation itself.
  *
- * A card first, then its required params, then a menu of every other option:
+ * A card first, then its required options, 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.
- */
+/** @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';
@@ -29,23 +27,18 @@ export interface Menu {
  * 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.
+ * Asks for the options 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>;

package/build/prompts.d.ts.map

@@ -1 +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"}
+{"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,mCAAmC;AACnC,eAAO,MAAM,QAAQ,QAAO,OAAO,CAAC,QAAQ,CAIxC,CAAC;AA6BL,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;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,SACpB,QAAQ,QACR,IAAI,WACD,MAAM,KACd,OAAO,CAAC,UAAU,CAmCpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,SAAgB,QAAQ,KAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAY7E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,eAAsB,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

@@ -4,21 +4,17 @@ import { describeAnswer } from './query.js';
 /**
  * @file The navigation itself.
  *
- * A card first, then its required params, then a menu of every other option:
+ * A card first, then its required options, 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({
+/** @returns The card to render. */
+export const pickCard = () => 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) => {
@@ -45,9 +41,6 @@ const askOption = async (option, current) => {
  * 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) => {
@@ -58,7 +51,8 @@ export const navigateOptions = async (card, menu, status) => {
             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,
+            // `default` does not accept an explicit undefined, so an unset cursor omits it.
+            ...(menu.cursor !== undefined && { default: menu.cursor }),
             choices: [
                 { name: 'Generate the card', value: 'generate' },
                 { name: 'Save these options', value: 'save' },
@@ -83,9 +77,8 @@ export const navigateOptions = async (card, menu, status) => {
     }
 };
 /**
- * Asks for the params the card cannot render without.
+ * Asks for the options the card cannot render without.
  *
- * @param card The card being built.
  * @returns The answers, one per required param.
  */
 export const askRequired = async (card) => {
@@ -101,7 +94,6 @@ export const askRequired = async (card) => {
 /**
  * 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) => {

package/build/query.d.ts

@@ -1,4 +1,4 @@
-import type { CardKind, CardOption } from './cards.js';
+import type { CardKind, CardOption } from './cards.ts';
 /**
  * @file Answers in, query params out.
  *
@@ -8,29 +8,23 @@ import type { CardKind, CardOption } from './cards.js';
 /** 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.
+ * The `.svg` 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;

package/build/query.d.ts.map

@@ -1 +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"}
+{"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;;GAEG;AACH,eAAO,MAAM,OAAO,UAAW,MAAM,KAAG,MAAM,GAAG,SAQhD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,OAAO,YAAa,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CASnF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,WAAY,UAAU,SAAS,MAAM,KAAG,MAMlE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,SAAU,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAK/E,CAAC"}

package/build/query.js

@@ -1,5 +1,4 @@
 /**
- * @param value What the prompt returned.
  * @returns The query string form, or `undefined` when there is nothing to send.
  */
 export const toParam = (value) => {
@@ -12,7 +11,6 @@ export const toParam = (value) => {
     return String(value);
 };
 /**
- * @param answers What each option was answered with.
  * @returns The query the card handler is called with.
  */
 export const toQuery = (answers) => {
@@ -28,8 +26,6 @@ export const toQuery = (answers) => {
 /**
  * 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) => {
@@ -40,16 +36,14 @@ export const describeAnswer = (option, value) => {
     return option.kind === 'boolean' ? (value === true ? 'yes' : 'no') : param;
 };
 /**
- * The file a card is written to when `--out` is not given.
+ * The `.svg` 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 { repo } = query;
     const parts = [card.id, subject, repo].filter(Boolean).join('-');
-    return `${parts.replace(/[^\w.-]/g, '-')}.svg`;
+    return `${parts.replaceAll(/[^\w.-]/g, '-')}.svg`;
 };

package/build/saved-card.d.ts

@@ -1,39 +1,33 @@
-import type { CardKind } from './cards.js';
-import type { Answer } from './query.js';
+import type { CardKind } from './cards.ts';
+import type { Answer } from './query.ts';
 /**
- * @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.
+ *
+ * @returns The card it names, and its options.
  */
 export declare const readSavedCard: (path: string) => Promise<{
     card: CardKind;
-    params: Record<string, string>;
+    options: 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>;
+export declare const writeSavedCard: (path: string, card: CardKind, options: Record<string, string>) => Promise<string>;
 /**
- * Turns saved params back into answers the menu can show and edit.
+ * Turns saved options 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>;
+export declare const toAnswers: (card: CardKind, options: Record<string, string>) => Map<string, Answer>;
 //# sourceMappingURL=saved-card.d.ts.map

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

@@ -1 +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"}
+{"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;;GAEG;AACH,eAAO,MAAM,eAAe,SAAU,MAAM,KAAG,OAAmD,CAAC;AAEnG;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,KACX,OAAO,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAyB7D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,QACN,QAAQ,WACL,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC9B,OAAO,CAAC,MAAM,CAKhB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,SAAU,QAAQ,WAAW,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAW7F,CAAC"}

package/build/saved-card.js

@@ -3,16 +3,15 @@ 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.
+ *
+ * @returns The card it names, and its options.
  */
 export const readSavedCard = async (path) => {
     const file = resolve(process.cwd(), path);
@@ -20,48 +19,43 @@ export const readSavedCard = async (path) => {
     try {
         parsed = JSON.parse(await readFile(file, 'utf8'));
     }
-    catch (err) {
-        throw new Error(`${file} is not readable as JSON`, { cause: err });
+    catch (error) {
+        throw new Error(`${file} is not readable as JSON`, { cause: error });
     }
     if (typeof parsed !== 'object' || parsed === null) {
         throw new Error(`${file} does not hold a saved card`);
     }
-    const { card: id, params } = parsed;
+    const { card: id, options } = 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) };
+    // An option that is not a string could not have come off a query string.
+    const entries = Object.entries(options ?? {}).filter((entry) => typeof entry[1] === 'string');
+    return { card, options: 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) => {
+export const writeSavedCard = async (path, card, options) => {
     const file = resolve(process.cwd(), path);
-    const saved = { card: card.id, params };
+    const saved = { card: card.id, options };
     await writeFile(file, `${JSON.stringify(saved, null, 2)}\n`, 'utf8');
     return file;
 };
 /**
- * Turns saved params back into answers the menu can show and edit.
+ * Turns saved options 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) => {
+export const toAnswers = (card, options) => {
     const kinds = new Map([...card.required, ...card.options].map((option) => [option.name, option.kind]));
-    return new Map(Object.entries(params).map(([name, value]) => [
+    return new Map(Object.entries(options).map(([name, value]) => [
         name,
         kinds.get(name) === 'boolean' ? value === 'true' : value,
     ]));

package/build/spinner.d.ts

@@ -15,9 +15,6 @@ export interface SpinnerStream {
  * 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>;

package/build/spinner.d.ts.map

@@ -1 +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"}
+{"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;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,SAC1B,MAAM,QACP,MAAM,OAAO,CAAC,CAAC,CAAC,WACd,aAAa,KACpB,OAAO,CAAC,CAAC,CAoBX,CAAC"}

package/build/spinner.js

@@ -7,19 +7,16 @@
 /** 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';
+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';
+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) => {

package/build/tokens.d.ts

@@ -1,4 +1,4 @@
-import type { PersonalAccessToken } from '@stats-forge/github-stats-forge-core';
+import type { PersonalAccessToken } from '@stats-forge/github-stats-forge-core/api';
 /**
  * @file Where the GitHub token comes from.
  *
@@ -11,24 +11,21 @@ export declare const DEFAULT_ENV_FILE = ".env";
 /**
  * Loads an env file into `process.env`, the way `node --env-file` would.
  *
- * @param path File to load, relative to the working directory.
- * @param required Whether a missing file is an error.
- * @returns Whether anything was loaded.
  * @throws {Error} When `required` and the file is not there.
+ *
+ * @returns Whether anything was loaded.
  */
 export declare const loadEnvFile: (path: string, required: boolean) => boolean;
 /**
- * The tokens an env holds, under the `PAT_1`, `PAT_2`, … names core reads.
+ * The tokens an env holds, under the `PAT_1`, `PAT_2`, … names core reads,
+ * in name order and skipping any that are empty.
  *
- * @param env Environment to read.
  * @returns The tokens, in name order, skipping any that are empty.
  */
 export declare const tokensFromEnv: (env: Record<string, string | undefined>) => Array<PersonalAccessToken>;
 /**
  * The tokens a run will use.
  *
- * @param flags Tokens passed as `--pat`, which win over the environment.
- * @param env Environment to read, once any env file has been loaded into it.
  * @returns The tokens, empty when the run has none yet.
  */
 export declare const resolveTokens: (flags: ReadonlyArray<string>, env: Record<string, string | undefined>) => Array<PersonalAccessToken>;

package/build/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAEhF;;;;;;GAMG;AAEH,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAEvC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,UAAU,OAAO,KAAG,OAU7D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KACtC,KAAK,CAAC,mBAAmB,CAOtB,CAAC;AAEP;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,aAAa,CAAC,MAAM,CAAC,EAC5B,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KACtC,KAAK,CAAC,mBAAmB,CAO3B,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAEpF;;;;;;GAMG;AAEH,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,SAAU,MAAM,YAAY,OAAO,KAAG,OAU7D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QACnB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KACtC,KAAK,CAAC,mBAAmB,CAOtB,CAAC;AAEP;;;;GAIG;AACH,eAAO,MAAM,aAAa,UACjB,aAAa,CAAC,MAAM,CAAC,OACvB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KACtC,KAAK,CAAC,mBAAmB,CAO3B,CAAC"}

package/build/tokens.js

@@ -12,10 +12,9 @@ export const DEFAULT_ENV_FILE = '.env';
 /**
  * Loads an env file into `process.env`, the way `node --env-file` would.
  *
- * @param path File to load, relative to the working directory.
- * @param required Whether a missing file is an error.
- * @returns Whether anything was loaded.
  * @throws {Error} When `required` and the file is not there.
+ *
+ * @returns Whether anything was loaded.
  */
 export const loadEnvFile = (path, required) => {
     const absolute = resolve(process.cwd(), path);
@@ -29,14 +28,14 @@ export const loadEnvFile = (path, required) => {
     return true;
 };
 /**
- * The tokens an env holds, under the `PAT_1`, `PAT_2`, … names core reads.
+ * The tokens an env holds, under the `PAT_1`, `PAT_2`, … names core reads,
+ * in name order and skipping any that are empty.
  *
- * @param env Environment to read.
  * @returns The tokens, in name order, skipping any that are empty.
  */
 export const tokensFromEnv = (env) => Object.keys(env)
     .filter((name) => /^PAT_\d+$/.test(name))
-    .sort()
+    .toSorted()
     .flatMap((name) => {
     const value = env[name];
     return value ? [{ name, value }] : [];
@@ -44,8 +43,6 @@ export const tokensFromEnv = (env) => Object.keys(env)
 /**
  * The tokens a run will use.
  *
- * @param flags Tokens passed as `--pat`, which win over the environment.
- * @param env Environment to read, once any env file has been loaded into it.
  * @returns The tokens, empty when the run has none yet.
  */
 export const resolveTokens = (flags, env) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stats-forge/github-stats-forge-cli",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Render a GitHub stats card to a local SVG file, one prompt at a time",
   "keywords": [
     "cli",
@@ -19,7 +19,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/stats-forge/github-stats-forge.git",
+    "url": "git+https://github.com/stats-forge/github-stats-forge.git",
     "directory": "packages/cli"
   },
   "bin": {
@@ -40,20 +40,20 @@
     "access": "public"
   },
   "dependencies": {
-    "@inquirer/prompts": "8.6.0",
-    "@stats-forge/github-stats-forge-core": "^0.0.1"
+    "@inquirer/prompts": "8.7.0",
+    "@stats-forge/github-stats-forge-core": "^0.1.0"
   },
   "devDependencies": {
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "engines": {
-    "node": ">=24"
+    "node": "^24 || >=26"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "dev": "pnpm run build && node build/index.js",
+    "lint:publish": "attw --pack . --profile node16 --ignore-rules cjs-resolves-to-esm && publint --strict",
+    "dev": "node --conditions=@stats/source src/index.ts",
     "test": "vitest",
-    "lint": "eslint",
     "typecheck": "tsc -p tsconfig.typecheck.json"
   }
 }

package/src/cards.ts

@@ -1,5 +1,12 @@
-import { gist, pin, stats, themes, topLangs, wakatime } from '@stats-forge/github-stats-forge-core';
-import type { ApiResult, CardConfig } from '@stats-forge/github-stats-forge-core';
+import {
+  gist,
+  pin,
+  stats,
+  themes,
+  topLangs,
+  wakatime,
+} from '@stats-forge/github-stats-forge-core/api';
+import type { ApiResult, CardConfig } from '@stats-forge/github-stats-forge-core/api';
 
 /**
  * @file What each card accepts, in the order the prompts walk it.
@@ -34,11 +41,7 @@ export interface CardKind {
   required: ReadonlyArray<CardOption>;
   /** Everything else, navigable in any order. */
   options: ReadonlyArray<CardOption>;
-  /**
-   * @param query The answers, as a query string would carry them.
-   * @param config Tokens the fetchers use.
-   * @returns The rendered card, or the rendered error.
-   */
+  /** @returns The rendered card, or the rendered error. */
   render: (query: Record<string, string>, config: CardConfig) => Promise<ApiResult>;
 }
 
@@ -337,7 +340,6 @@ export const cards: ReadonlyArray<CardKind> = CARDS.map((card) => ({
 }));
 
 /**
- * @param id The card's id, as `--card` takes it.
  * @returns The card, or `undefined` when nothing renders under that name.
  */
 export const findCard = (id: string): CardKind | undefined => cards.find((card) => card.id === id);

package/src/index.ts

@@ -3,16 +3,16 @@ 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 { CardConfig } from '@stats-forge/github-stats-forge-core/api';
 
-import type { CardKind } from './cards.js';
-import { cards, findCard } from './cards.js';
-import type { Menu } from './prompts.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';
+import type { CardKind } from './cards.ts';
+import { cards, findCard } from './cards.ts';
+import type { Menu } from './prompts.ts';
+import { askRequired, askSavePath, askToken, navigateOptions, pickCard } from './prompts.ts';
+import { defaultFileName, toQuery } from './query.ts';
+import { readSavedCard, savedCardExists, toAnswers, writeSavedCard } from './saved-card.ts';
+import { withSpinner } from './spinner.ts';
+import { DEFAULT_ENV_FILE, loadEnvFile, resolveTokens } from './tokens.ts';
 
 const HELP = `github-stats-forge — render a GitHub stats card to a local SVG
 
@@ -32,10 +32,22 @@ Options
 The token can also come from PAT_1 in the environment, or be typed when asked.
 `;
 
+/** What the command line can carry. */
+interface Flags {
+  card?: string;
+  out?: string;
+  config?: string;
+  generate: boolean;
+  pat: Array<string>;
+  'env-file'?: string;
+  help: boolean;
+  version: boolean;
+}
+
 /**
  * @returns The flags this run was given.
  */
-const readFlags = () =>
+const readFlags = (): Flags =>
   parseArgs({
     options: {
       card: { type: 'string', short: 'c' },
@@ -53,10 +65,6 @@ const readFlags = () =>
 /**
  * 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 (
@@ -72,14 +80,14 @@ const renderAndWrite = async (
   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',
+        .join('\n')}\n`,
     );
     return { failed: code };
   }
@@ -93,6 +101,7 @@ const renderAndWrite = async (
 
 /**
  * Renders one card and writes it next to wherever the run was started.
+ * Sets a non-zero exit code rather than throwing when it could not.
  *
  * @returns Nothing; the process exits non-zero when the card could not be rendered.
  */
@@ -173,7 +182,7 @@ const main = async (): Promise<void> => {
 
   // `--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);
+    const outcome = await renderAndWrite(card, saved.options, config, flags.out);
     if ('failed' in outcome) {
       process.exitCode = 1;
     }
@@ -181,7 +190,7 @@ const main = async (): Promise<void> => {
   }
 
   const menu: Menu = {
-    answers: saved ? toAnswers(card, saved.params) : await askRequired(card),
+    answers: saved ? toAnswers(card, saved.options) : await askRequired(card),
   };
   let savePath = flags.config;
 
@@ -232,12 +241,12 @@ const main = async (): Promise<void> => {
 
 try {
   await main();
-} catch (err) {
+} catch (error) {
   // A cancelled prompt is a normal way to leave, not a crash.
-  if (err instanceof Error && err.name === 'ExitPromptError') {
+  if (error instanceof Error && error.name === 'ExitPromptError') {
     process.exitCode = 130;
   } else {
-    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     process.exitCode = 1;
   }
 }

package/src/prompts.ts

@@ -1,21 +1,19 @@
 import { confirm, input, password, select } from '@inquirer/prompts';
 
-import type { CardKind, CardOption } from './cards.js';
-import { cards } from './cards.js';
-import type { Answer } from './query.js';
-import { describeAnswer } from './query.js';
+import type { CardKind, CardOption } from './cards.ts';
+import { cards } from './cards.ts';
+import type { Answer } from './query.ts';
+import { describeAnswer } from './query.ts';
 
 /**
  * @file The navigation itself.
  *
- * A card first, then its required params, then a menu of every other option:
+ * A card first, then its required options, 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 (): Promise<CardKind> =>
+/** @returns The card to render. */
+export const pickCard = (): Promise<CardKind> =>
   select({
     message: 'Which card?',
     choices: cards.map((card) => ({ name: card.label, value: card })),
@@ -24,8 +22,6 @@ export const pickCard = async (): Promise<CardKind> =>
 /**
  * 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: CardOption, current: Answer): Promise<Answer> => {
@@ -71,9 +67,6 @@ export interface Menu {
  * 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 (
@@ -89,7 +82,8 @@ export const navigateOptions = async (
       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,
+      // `default` does not accept an explicit undefined, so an unset cursor omits it.
+      ...(menu.cursor !== undefined && { default: menu.cursor }),
       choices: [
         { name: 'Generate the card', value: 'generate' as const },
         { name: 'Save these options', value: 'save' as const },
@@ -117,9 +111,8 @@ export const navigateOptions = async (
 };
 
 /**
- * Asks for the params the card cannot render without.
+ * Asks for the options the card cannot render without.
  *
- * @param card The card being built.
  * @returns The answers, one per required param.
  */
 export const askRequired = async (card: CardKind): Promise<Map<string, Answer>> => {
@@ -139,7 +132,6 @@ export const askRequired = async (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 const askSavePath = async (suggestion: string): Promise<string | undefined> => {

package/src/query.ts

@@ -1,4 +1,4 @@
-import type { CardKind, CardOption } from './cards.js';
+import type { CardKind, CardOption } from './cards.ts';
 
 /**
  * @file Answers in, query params out.
@@ -11,7 +11,6 @@ import type { CardKind, CardOption } from './cards.js';
 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 const toParam = (value: Answer): string | undefined => {
@@ -25,7 +24,6 @@ export const toParam = (value: Answer): string | undefined => {
 };
 
 /**
- * @param answers What each option was answered with.
  * @returns The query the card handler is called with.
  */
 export const toQuery = (answers: ReadonlyMap<string, Answer>): Record<string, string> => {
@@ -42,8 +40,6 @@ export const toQuery = (answers: ReadonlyMap<string, Answer>): Record<string, st
 /**
  * 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: CardOption, value: Answer): string => {
@@ -55,16 +51,14 @@ export const describeAnswer = (option: CardOption, value: Answer): string => {
 };
 
 /**
- * The file a card is written to when `--out` is not given.
+ * The `.svg` 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: CardKind, query: Record<string, string>): string => {
   const subject = query['username'] ?? query['id'] ?? 'card';
-  const repo = query['repo'];
+  const { repo } = query;
   const parts = [card.id, subject, repo].filter(Boolean).join('-');
-  return `${parts.replace(/[^\w.-]/g, '-')}.svg`;
+  return `${parts.replaceAll(/[^\w.-]/g, '-')}.svg`;
 };

package/src/saved-card.ts

@@ -2,14 +2,14 @@ import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
-import type { CardKind } from './cards.js';
-import { findCard } from './cards.js';
-import type { Answer } from './query.js';
+import type { CardKind } from './cards.ts';
+import { findCard } from './cards.ts';
+import type { Answer } from './query.ts';
 
 /**
  * @file A card, written down.
  *
- * The file holds what a query string would hold — the card and its params as
+ * The file holds what a query string would hold — the card and its options as
  * strings — so it reads like the URL it stands for, and can be edited by hand.
  */
 
@@ -17,12 +17,11 @@ import type { Answer } from './query.js';
 interface SavedCard {
   /** Which card: `stats`, `top-langs`, `pin`, `gist`, `wakatime`. */
   card: string;
-  /** The params, exactly as they reach the endpoint. */
-  params: Record<string, string>;
+  /** The options, exactly as they reach the endpoint. */
+  options: Record<string, string>;
 }
 
 /**
- * @param path File to look for, relative to the working directory.
  * @returns Whether there is something there to load.
  */
 export const savedCardExists = (path: string): boolean => existsSync(resolve(process.cwd(), path));
@@ -30,75 +29,70 @@ export const savedCardExists = (path: string): boolean => existsSync(resolve(pro
 /**
  * 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.
+ *
+ * @returns The card it names, and its options.
  */
 export const readSavedCard = async (
   path: string,
-): Promise<{ card: CardKind; params: Record<string, string> }> => {
+): Promise<{ card: CardKind; options: Record<string, string> }> => {
   const file = resolve(process.cwd(), path);
   let parsed: unknown;
   try {
     parsed = JSON.parse(await readFile(file, 'utf8'));
-  } catch (err) {
-    throw new Error(`${file} is not readable as JSON`, { cause: err });
+  } catch (error) {
+    throw new Error(`${file} is not readable as JSON`, { cause: error });
   }
 
   if (typeof parsed !== 'object' || parsed === null) {
     throw new Error(`${file} does not hold a saved card`);
   }
 
-  const { card: id, params } = parsed as Partial<SavedCard>;
+  const { card: id, options } = parsed as Partial<SavedCard>;
   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(
+  // An option that is not a string could not have come off a query string.
+  const entries = Object.entries(options ?? {}).filter(
     (entry): entry is [string, string] => typeof entry[1] === 'string',
   );
 
-  return { card, params: Object.fromEntries(entries) };
+  return { card, options: 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: string,
   card: CardKind,
-  params: Record<string, string>,
+  options: Record<string, string>,
 ): Promise<string> => {
   const file = resolve(process.cwd(), path);
-  const saved: SavedCard = { card: card.id, params };
+  const saved: SavedCard = { card: card.id, options };
   await writeFile(file, `${JSON.stringify(saved, null, 2)}\n`, 'utf8');
   return file;
 };
 
 /**
- * Turns saved params back into answers the menu can show and edit.
+ * Turns saved options 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: CardKind, params: Record<string, string>): Map<string, Answer> => {
+export const toAnswers = (card: CardKind, options: Record<string, string>): Map<string, Answer> => {
   const kinds = new Map(
     [...card.required, ...card.options].map((option) => [option.name, option.kind]),
   );
 
   return new Map(
-    Object.entries(params).map(([name, value]) => [
+    Object.entries(options).map(([name, value]) => [
       name,
       kinds.get(name) === 'boolean' ? value === 'true' : value,
     ]),

package/src/spinner.ts

@@ -9,10 +9,10 @@
 const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 const INTERVAL_MS = 80;
 
-const HIDE_CURSOR = '\u001b[?25l';
-const SHOW_CURSOR = '\u001b[?25h';
+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';
+const CLEAR_LINE = '\r\u001B[K';
 
 /** What the spinner writes to; `process.stderr`, or a fake in a test. */
 export interface SpinnerStream {
@@ -26,9 +26,6 @@ export interface SpinnerStream {
  * 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 <T>(

package/src/tokens.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 
-import type { PersonalAccessToken } from '@stats-forge/github-stats-forge-core';
+import type { PersonalAccessToken } from '@stats-forge/github-stats-forge-core/api';
 
 /**
  * @file Where the GitHub token comes from.
@@ -17,10 +17,9 @@ export const DEFAULT_ENV_FILE = '.env';
 /**
  * Loads an env file into `process.env`, the way `node --env-file` would.
  *
- * @param path File to load, relative to the working directory.
- * @param required Whether a missing file is an error.
- * @returns Whether anything was loaded.
  * @throws {Error} When `required` and the file is not there.
+ *
+ * @returns Whether anything was loaded.
  */
 export const loadEnvFile = (path: string, required: boolean): boolean => {
   const absolute = resolve(process.cwd(), path);
@@ -35,9 +34,9 @@ export const loadEnvFile = (path: string, required: boolean): boolean => {
 };
 
 /**
- * The tokens an env holds, under the `PAT_1`, `PAT_2`, … names core reads.
+ * The tokens an env holds, under the `PAT_1`, `PAT_2`, … names core reads,
+ * in name order and skipping any that are empty.
  *
- * @param env Environment to read.
  * @returns The tokens, in name order, skipping any that are empty.
  */
 export const tokensFromEnv = (
@@ -45,7 +44,7 @@ export const tokensFromEnv = (
 ): Array<PersonalAccessToken> =>
   Object.keys(env)
     .filter((name) => /^PAT_\d+$/.test(name))
-    .sort()
+    .toSorted()
     .flatMap((name) => {
       const value = env[name];
       return value ? [{ name, value }] : [];
@@ -54,8 +53,6 @@ export const tokensFromEnv = (
 /**
  * The tokens a run will use.
  *
- * @param flags Tokens passed as `--pat`, which win over the environment.
- * @param env Environment to read, once any env file has been loaded into it.
  * @returns The tokens, empty when the run has none yet.
  */
 export const resolveTokens = (