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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Anurag Hazra, Abhijit Gupta, martin-mfg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @stats-forge/github-stats-forge-cli
+
+Render a [GitHub Stats Forge](https://github.com/stats-forge/github-stats-forge) card
+to a local SVG file, one prompt at a time.
+
+Run it without installing anything:
+
+```sh
+npx @stats-forge/github-stats-forge-cli
+```
+
+or keep it around as `github-stats-forge`:
+
+```sh
+pnpm add -g @stats-forge/github-stats-forge-cli
+github-stats-forge
+```
+
+Requires Node 24 or newer. The cards themselves come from
+[`@stats-forge/github-stats-forge-core`](https://www.npmjs.com/package/@stats-forge/github-stats-forge-core),
+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
+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.
+
+The menu stays open afterwards, with every answer still on it and the cursor where
+you left it, so tuning a card is: generate, look at it, change one option, generate
+again. `Quit` (or Ctrl-C) ends the session.
+
+```
+? Which card? Stats — commits, PRs, issues, reviews and a rank
+? GitHub username anuraghazra
+? Stats — wrote stats-anuraghazra.svg — edit an option and generate again
+❯ Generate the card
+  Quit
+  Extra stats to show                    reviews,prs_merged
+  Stats to hide                          —
+  Show the stat icons                    yes
+  Theme                                  tokyonight
+```
+
+## Saving a card
+
+`Save these options` in the menu writes the card and its params to a JSON file, and
+`--config` loads one back:
+
+```sh
+github-stats-forge --config my-stats.json      # picks up where the file left off
+```
+
+```json
+{
+  "card": "stats",
+  "params": {
+    "username": "anuraghazra",
+    "theme": "tokyonight",
+    "show_icons": "true"
+  }
+}
+```
+
+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,
+so the next `Save these options` writes back to it without asking.
+
+`--generate` skips the menu too, rendering exactly what the file holds:
+
+```sh
+github-stats-forge --config my-stats.json --generate
+```
+
+Nothing is asked, so this is the form for a script or a scheduled job — refresh a
+card on a cron, or regenerate a directory of them. It exits non-zero if the card
+could not be rendered, and needs its token from `--pat`, an env file or the
+environment, since there is nobody to ask.
+
+While it fetches, a spinner runs on stderr — so `github-stats-forge > card.svg` still
+pipes only the card, and a CI log gets one line instead of an animation.
+
+## The token
+
+Every card except WakaTime reads the GitHub API, so it needs a personal access token
+([how to create one](https://github.com/settings/personal-access-tokens)). It can come
+from any of these, in this order:
+
+```sh
+github-stats-forge --pat ghp_yourtoken      # the flag wins
+echo "PAT_1=ghp_yourtoken" > .env    # read from ./.env by default
+export PAT_1=ghp_yourtoken           # or straight from the environment
+```
+
+`PAT_1`, `PAT_2`, … are the names core reads, so an env file you already use with a
+self-hosted instance works unchanged. With none of them set, the CLI asks for the
+token and hides what you type.
+
+## Options
+
+```
+-c, --card <id>       Skip the card prompt: stats, top-langs, pin, gist, wakatime
+-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: .env)
+-h, --help            Show the help
+-v, --version         Show the version
+```
+
+A card that cannot be rendered prints why, including the code and the param at
+fault, and exits non-zero:
+
+```
+Could not render the stats card.
+  Something went wrong: Invalid number input for parameter "border_radius"
+  code: invalid_param, param: border_radius
+```

package/build/cards.d.ts

@@ -0,0 +1,47 @@
+import type { ApiResult, CardConfig } from '@stats-forge/github-stats-forge-core';
+/**
+ * @file What each card accepts, in the order the prompts walk it.
+ *
+ * The core schemas validate these params;
+ * this catalog is what makes them navigable, so it carries the prose and the choices a schema has no room for.
+ */
+/** How a param is asked for, and how the answer becomes a query string value. */
+type OptionKind = 'text' | 'boolean' | 'number' | 'list' | 'choice';
+/** One param of one card. */
+export interface CardOption {
+    /** Query param the answer is written to. */
+    name: string;
+    /** What the prompt asks. */
+    label: string;
+    kind: OptionKind;
+    /** The accepted values, for `choice`. */
+    choices?: ReadonlyArray<string>;
+    /** Shown under the prompt, for anything the label cannot say. */
+    hint?: string;
+}
+/** A card, its params, and the core handler that renders it. */
+export interface CardKind {
+    id: string;
+    label: string;
+    /** Whether rendering it calls the GitHub API, and so needs a token. */
+    needsToken: boolean;
+    /** Asked first: the card renders nothing without them. */
+    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.
+     */
+    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;
+export {};
+//# sourceMappingURL=cards.d.ts.map

package/build/cards.d.ts.map

@@ -0,0 +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"}

package/build/cards.js

@@ -0,0 +1,295 @@
+import { gist, pin, stats, themes, topLangs, wakatime } from '@stats-forge/github-stats-forge-core';
+const THEME_NAMES = Object.keys(themes);
+/** Colors and the theme, which every card accepts. */
+const COMMON_OPTIONS = [
+    {
+        name: 'theme',
+        label: 'Theme',
+        kind: 'choice',
+        choices: THEME_NAMES,
+        hint: 'An unknown name falls back to the default theme',
+    },
+    {
+        name: 'title_color',
+        label: 'Title color',
+        kind: 'text',
+        hint: 'Hex, no #',
+    },
+    { name: 'text_color', label: 'Text color', kind: 'text', hint: 'Hex, no #' },
+    { name: 'icon_color', label: 'Icon color', kind: 'text', hint: 'Hex, no #' },
+    {
+        name: 'bg_color',
+        label: 'Background color',
+        kind: 'text',
+        hint: 'Hex, no #, or a gradient: angle,color,color',
+    },
+    {
+        name: 'border_color',
+        label: 'Border color',
+        kind: 'text',
+        hint: 'Hex, no #',
+    },
+    { name: 'border_radius', label: 'Border radius', kind: 'number' },
+    { name: 'hide_border', label: 'Hide the border', kind: 'boolean' },
+];
+const LOCALE_OPTION = {
+    name: 'locale',
+    label: 'Locale',
+    kind: 'text',
+    hint: 'Two-letter code, e.g. es',
+};
+const CARDS = [
+    {
+        id: 'stats',
+        label: 'Stats — commits, PRs, issues, reviews and a rank',
+        needsToken: true,
+        required: [{ name: 'username', label: 'GitHub username', kind: 'text' }],
+        options: [
+            {
+                name: 'show',
+                label: 'Extra stats to show',
+                kind: 'list',
+                hint: 'e.g. reviews,discussions_started,prs_merged,contributions',
+            },
+            {
+                name: 'hide',
+                label: 'Stats to hide',
+                kind: 'list',
+                hint: 'e.g. stars,commits,prs,issues,contribs',
+            },
+            { name: 'show_icons', label: 'Show the stat icons', kind: 'boolean' },
+            { name: 'hide_rank', label: 'Hide the rank circle', kind: 'boolean' },
+            {
+                name: 'rank_icon',
+                label: 'Rank indicator',
+                kind: 'choice',
+                choices: stats.RANK_ICONS,
+            },
+            {
+                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',
+            },
+            {
+                name: 'exclude_repo',
+                label: 'Repositories to exclude',
+                kind: 'list',
+            },
+            {
+                name: 'repo',
+                label: 'Repositories the search-based stats are scoped to',
+                kind: 'list',
+            },
+            {
+                name: 'owner',
+                label: 'Owners the search-based stats are scoped to',
+                kind: 'list',
+            },
+            {
+                name: 'role',
+                label: 'Owner affiliations to include',
+                kind: 'list',
+                hint: 'OWNER, COLLABORATOR, ORGANIZATION_MEMBER',
+            },
+            {
+                name: 'contribs_include_own_repos',
+                label: 'Count contributions to your own repositories',
+                kind: 'boolean',
+            },
+            { 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: 'line_height', label: 'Line height', kind: 'number' },
+            { name: 'text_bold', label: 'Bold stat values', kind: 'boolean' },
+            {
+                name: 'number_format',
+                label: 'Number format',
+                kind: 'choice',
+                choices: ['short', 'long'],
+            },
+            {
+                name: 'number_precision',
+                label: 'Decimals kept when abbreviating',
+                kind: 'number',
+            },
+            {
+                name: 'disable_animations',
+                label: 'Disable the animations',
+                kind: 'boolean',
+            },
+            { name: 'ring_color', label: 'Rank ring color', kind: 'text' },
+            LOCALE_OPTION,
+        ],
+        render: (query, config) => stats(query, config),
+    },
+    {
+        id: 'top-langs',
+        label: 'Top languages — the languages you write most',
+        needsToken: true,
+        required: [{ name: 'username', label: 'GitHub username', kind: 'text' }],
+        options: [
+            {
+                name: 'layout',
+                label: 'Layout',
+                kind: 'choice',
+                choices: topLangs.LAYOUTS,
+            },
+            { name: 'langs_count', label: 'Languages to show', kind: 'number' },
+            { name: 'hide', label: 'Languages to hide', kind: 'list' },
+            { name: 'exclude_repo', label: 'Repositories to exclude', kind: 'list' },
+            {
+                name: 'size_weight',
+                label: "Weight given to a language's size",
+                kind: 'number',
+            },
+            {
+                name: 'count_weight',
+                label: 'Weight given to its repository count',
+                kind: 'number',
+            },
+            {
+                name: 'stats_format',
+                label: 'Show values as',
+                kind: 'choice',
+                choices: topLangs.STATS_FORMATS,
+            },
+            {
+                name: 'hide_progress',
+                label: 'Hide the progress bars',
+                kind: 'boolean',
+            },
+            { name: 'hide_values', label: 'Hide the values', kind: 'boolean' },
+            {
+                name: 'prog_bar_bg_color',
+                label: 'Progress bar background color',
+                kind: 'text',
+            },
+            { name: 'role', label: 'Owner affiliations to include', kind: 'list' },
+            { 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) => topLangs(query, config),
+    },
+    {
+        id: 'pin',
+        label: 'Repository pin — one repository',
+        needsToken: true,
+        required: [
+            { name: 'username', label: 'GitHub username', kind: 'text' },
+            { name: 'repo', label: 'Repository name', kind: 'text' },
+        ],
+        options: [
+            { name: 'show_owner', label: 'Show the owner', kind: 'boolean' },
+            {
+                name: 'show',
+                label: 'Extra stats to show',
+                kind: 'list',
+                hint: 'e.g. prs_authored,issues_commented',
+            },
+            { name: 'show_icons', label: 'Show the stat icons', kind: 'boolean' },
+            {
+                name: 'description_lines_count',
+                label: 'Lines the description wraps to',
+                kind: 'number',
+            },
+            {
+                name: 'browser_rendering',
+                label: 'Let the browser wrap the description',
+                kind: 'boolean',
+            },
+            { name: 'card_width', label: 'Card width', kind: 'number' },
+            { name: 'line_height', label: 'Line height', kind: 'number' },
+            { name: 'text_bold', label: 'Bold stat values', kind: 'boolean' },
+            {
+                name: 'number_format',
+                label: 'Number format',
+                kind: 'choice',
+                choices: ['short', 'long'],
+            },
+            LOCALE_OPTION,
+        ],
+        render: (query, config) => pin(query, config),
+    },
+    {
+        id: 'gist',
+        label: 'Gist pin — one gist',
+        needsToken: true,
+        required: [{ name: 'id', label: 'Gist ID', kind: 'text' }],
+        options: [
+            { name: 'show_owner', label: 'Show the owner', kind: 'boolean' },
+            {
+                name: 'browser_rendering',
+                label: 'Let the browser wrap the description',
+                kind: 'boolean',
+            },
+        ],
+        render: (query, config) => gist(query, config),
+    },
+    {
+        id: 'wakatime',
+        label: 'WakaTime — coding time per language',
+        needsToken: false,
+        required: [{ name: 'username', label: 'WakaTime username', kind: 'text' }],
+        options: [
+            {
+                name: 'layout',
+                label: 'Layout',
+                kind: 'choice',
+                choices: wakatime.LAYOUTS,
+            },
+            {
+                name: 'display_format',
+                label: 'Show values as',
+                kind: 'choice',
+                choices: wakatime.DISPLAY_FORMATS,
+            },
+            { name: 'langs_count', label: 'Languages to show', kind: 'number' },
+            { name: 'hide', label: 'Languages to hide', kind: 'list' },
+            {
+                name: 'hide_progress',
+                label: 'Hide the progress bars',
+                kind: 'boolean',
+            },
+            { 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: 'line_height', label: 'Line height', kind: 'number' },
+            {
+                name: 'disable_animations',
+                label: 'Disable the animations',
+                kind: 'boolean',
+            },
+            {
+                name: 'api_domain',
+                label: 'WakaTime instance',
+                kind: 'text',
+                hint: 'Defaults to wakatime.com',
+            },
+            LOCALE_OPTION,
+        ],
+        render: (query, config) => wakatime(query, config),
+    },
+];
+/** Every card, with the options every card shares appended to its own. */
+export const cards = CARDS.map((card) => ({
+    ...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.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}