@stats-forge/github-stats-forge-cli 0.0.2 → 0.2.0

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;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,SAAU,QAAQ,WAAW,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAuB7F,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,49 +19,58 @@ 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.
+ * a boolean becomes one again, and a list splits back into its values,
+ * so each prompt opens on the answer it was saved with.
  *
- * @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]) => [
-        name,
-        kinds.get(name) === 'boolean' ? value === 'true' : value,
-    ]));
+    const toAnswer = (name, value) => {
+        switch (kinds.get(name)) {
+            case 'boolean': {
+                return value === 'true';
+            }
+            case 'list': {
+                return value
+                    .split(',')
+                    .map((item) => item.trim())
+                    .filter(Boolean);
+            }
+            default: {
+                return value;
+            }
+        }
+    };
+    return new Map(Object.entries(options).map(([name, value]) => [name, toAnswer(name, 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.2",
+  "version": "0.2.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.2"
+    "@inquirer/prompts": "8.7.0",
+    "@stats-forge/github-stats-forge-core": "^0.2.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,13 @@
-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 {
+  contributedTo,
+  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.
@@ -18,7 +26,7 @@ export interface CardOption {
   /** What the prompt asks. */
   label: string;
   kind: OptionKind;
-  /** The accepted values, for `choice`. */
+  /** The accepted values, for `choice` and for a `list` whose values are a closed set. */
   choices?: ReadonlyArray<string>;
   /** Shown under the prompt, for anything the label cannot say. */
   hint?: string;
@@ -34,11 +42,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>;
 }
 
@@ -77,6 +81,19 @@ const COMMON_OPTIONS: ReadonlyArray<CardOption> = [
   { name: 'hide_border', label: 'Hide the border', kind: 'boolean' },
 ];
 
+/**
+ * The two ends of a card's date range.
+ *
+ * @returns The pair, naming what it counts.
+ */
+const rangeOptions = (counted: string): ReadonlyArray<CardOption> => {
+  const hint = 'A year, a month or a day: 2024, 2024-03, 2024-03-15';
+  return [
+    { name: 'from', label: `Count ${counted} from`, kind: 'text', hint },
+    { name: 'to', label: `Count ${counted} up to`, kind: 'text', hint },
+  ];
+};
+
 const LOCALE_OPTION: CardOption = {
   name: 'locale',
   label: 'Locale',
@@ -95,13 +112,13 @@ const CARDS: ReadonlyArray<CardKind> = [
         name: 'show',
         label: 'Extra stats to show',
         kind: 'list',
-        hint: 'e.g. reviews,discussions_started,prs_merged,contributions',
+        choices: stats.OPTIONS.show,
       },
       {
         name: 'hide',
         label: 'Stats to hide',
         kind: 'list',
-        hint: 'e.g. stars,commits,prs,issues,contribs',
+        choices: stats.OPTIONS.hide,
       },
       { name: 'show_icons', label: 'Show the stat icons', kind: 'boolean' },
       { name: 'hide_rank', label: 'Hide the rank circle', kind: 'boolean' },
@@ -109,19 +126,14 @@ const CARDS: ReadonlyArray<CardKind> = [
         name: 'rank_icon',
         label: 'Rank indicator',
         kind: 'choice',
-        choices: stats.RANK_ICONS,
+        choices: stats.OPTIONS.rank_icon,
       },
       {
         name: 'include_all_commits',
         label: 'Count commits of all time',
         kind: 'boolean',
       },
-      {
-        name: 'commits_year',
-        label: 'Count commits for one year',
-        kind: 'number',
-        hint: 'Four digits, e.g. 2025',
-      },
+      ...rangeOptions('commits'),
       {
         name: 'exclude_repo',
         label: 'Repositories to exclude',
@@ -141,7 +153,7 @@ const CARDS: ReadonlyArray<CardKind> = [
         name: 'role',
         label: 'Owner affiliations to include',
         kind: 'list',
-        hint: 'OWNER, COLLABORATOR, ORGANIZATION_MEMBER',
+        choices: stats.OPTIONS.role,
       },
       {
         name: 'contribs_include_own_repos',
@@ -157,7 +169,7 @@ const CARDS: ReadonlyArray<CardKind> = [
         name: 'number_format',
         label: 'Number format',
         kind: 'choice',
-        choices: ['short', 'long'],
+        choices: stats.OPTIONS.number_format,
       },
       {
         name: 'number_precision',
@@ -172,7 +184,7 @@ const CARDS: ReadonlyArray<CardKind> = [
       { name: 'ring_color', label: 'Rank ring color', kind: 'text' },
       LOCALE_OPTION,
     ],
-    render: (query, config) => stats(query, config),
+    render: stats,
   },
   {
     id: 'top-langs',
@@ -184,7 +196,7 @@ const CARDS: ReadonlyArray<CardKind> = [
         name: 'layout',
         label: 'Layout',
         kind: 'choice',
-        choices: topLangs.LAYOUTS,
+        choices: topLangs.OPTIONS.layout,
       },
       { name: 'langs_count', label: 'Languages to show', kind: 'number' },
       { name: 'hide', label: 'Languages to hide', kind: 'list' },
@@ -203,7 +215,7 @@ const CARDS: ReadonlyArray<CardKind> = [
         name: 'stats_format',
         label: 'Show values as',
         kind: 'choice',
-        choices: topLangs.STATS_FORMATS,
+        choices: topLangs.OPTIONS.stats_format,
       },
       {
         name: 'hide_progress',
@@ -216,7 +228,12 @@ const CARDS: ReadonlyArray<CardKind> = [
         label: 'Progress bar background color',
         kind: 'text',
       },
-      { name: 'role', label: 'Owner affiliations to include', kind: 'list' },
+      {
+        name: 'role',
+        label: 'Owner affiliations to include',
+        kind: 'list',
+        choices: topLangs.OPTIONS.role,
+      },
       { name: 'custom_title', label: 'Card title', kind: 'text' },
       { name: 'hide_title', label: 'Hide the title', kind: 'boolean' },
       { name: 'card_width', label: 'Card width', kind: 'number' },
@@ -227,7 +244,7 @@ const CARDS: ReadonlyArray<CardKind> = [
       },
       LOCALE_OPTION,
     ],
-    render: (query, config) => topLangs(query, config),
+    render: topLangs,
   },
   {
     id: 'pin',
@@ -243,7 +260,7 @@ const CARDS: ReadonlyArray<CardKind> = [
         name: 'show',
         label: 'Extra stats to show',
         kind: 'list',
-        hint: 'e.g. prs_authored,issues_commented',
+        choices: pin.OPTIONS.show,
       },
       { name: 'show_icons', label: 'Show the stat icons', kind: 'boolean' },
       {
@@ -263,11 +280,48 @@ const CARDS: ReadonlyArray<CardKind> = [
         name: 'number_format',
         label: 'Number format',
         kind: 'choice',
-        choices: ['short', 'long'],
+        choices: pin.OPTIONS.number_format,
+      },
+      LOCALE_OPTION,
+    ],
+    render: pin,
+  },
+  {
+    id: 'contributed-to',
+    label: 'Contributed to — repositories you work on, ranked',
+    needsToken: true,
+    required: [{ name: 'username', label: 'GitHub username', kind: 'text' }],
+    options: [
+      { name: 'repos_count', label: 'Repositories to show', kind: 'number' },
+      {
+        name: 'include_own_repos',
+        label: 'Include your own repositories',
+        kind: 'boolean',
+      },
+      {
+        name: 'exclude_repo',
+        label: 'Repositories to exclude',
+        kind: 'list',
+        hint: 'Each one an owner/name, or just the name',
+      },
+      ...rangeOptions('contributions'),
+      {
+        name: 'hide_years',
+        label: 'Hide the year marks',
+        kind: 'boolean',
+        hint: 'One mark per contribution year, filled for the years that repo got one',
+      },
+      { name: 'custom_title', label: 'Card title', kind: 'text' },
+      { name: 'hide_title', label: 'Hide the title', kind: 'boolean' },
+      { name: 'card_width', label: 'Card width', kind: 'number' },
+      {
+        name: 'disable_animations',
+        label: 'Disable the animations',
+        kind: 'boolean',
       },
       LOCALE_OPTION,
     ],
-    render: (query, config) => pin(query, config),
+    render: contributedTo,
   },
   {
     id: 'gist',
@@ -281,8 +335,9 @@ const CARDS: ReadonlyArray<CardKind> = [
         label: 'Let the browser wrap the description',
         kind: 'boolean',
       },
+      LOCALE_OPTION,
     ],
-    render: (query, config) => gist(query, config),
+    render: gist,
   },
   {
     id: 'wakatime',
@@ -294,13 +349,13 @@ const CARDS: ReadonlyArray<CardKind> = [
         name: 'layout',
         label: 'Layout',
         kind: 'choice',
-        choices: wakatime.LAYOUTS,
+        choices: wakatime.OPTIONS.layout,
       },
       {
         name: 'display_format',
         label: 'Show values as',
         kind: 'choice',
-        choices: wakatime.DISPLAY_FORMATS,
+        choices: wakatime.OPTIONS.display_format,
       },
       { name: 'langs_count', label: 'Languages to show', kind: 'number' },
       { name: 'hide', label: 'Languages to hide', kind: 'list' },
@@ -326,7 +381,7 @@ const CARDS: ReadonlyArray<CardKind> = [
       },
       LOCALE_OPTION,
     ],
-    render: (query, config) => wakatime(query, config),
+    render: wakatime,
   },
 ];
 
@@ -337,7 +392,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;
   }
 }