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

package/src/prompts.ts

@@ -1,21 +1,19 @@
-import { confirm, input, password, select } from '@inquirer/prompts';
+import { checkbox, 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> => {
@@ -35,6 +31,16 @@ const askOption = async (option: CardOption, current: Answer): Promise<Answer> =
     return confirm({ message, default: current === true });
   }
 
+  if (option.kind === 'list' && option.choices) {
+    const chosen = new Set(Array.isArray(current) ? current : []);
+    const picked = await checkbox({
+      message,
+      pageSize: 15,
+      choices: option.choices.map((value) => ({ value, checked: chosen.has(value) })),
+    });
+    return picked.length > 0 ? picked : undefined;
+  }
+
   if (option.kind === 'choice') {
     const choices = [
       { name: '— leave unset —', value: undefined as Answer },
@@ -71,9 +77,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 +92,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 +121,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 +142,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,27 +2,26 @@ 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.
  */
 
 /** A card and the answers it was rendered from: the shape of the file. */
 interface SavedCard {
-  /** Which card: `stats`, `top-langs`, `pin`, `gist`, `wakatime`. */
+  /** Which card, by the id the catalog gives it. */
   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,77 +29,85 @@ 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.
+ * 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: 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]) => [
-      name,
-      kinds.get(name) === 'boolean' ? value === 'true' : value,
-    ]),
-  );
+  const toAnswer = (name: string, value: string): Answer => {
+    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/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 = (