@slugbugblue/trax-cli 0.12.1 → 0.13.0

package/src/cli.js

@@ -1,51 +1,141 @@
 #!/usr/bin/env node
-/* Copyright 2022-2023 Chad Transtrum
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+/** CLI for Trax, with a fallback REPL
+ * @copyright 2022-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// CLI for Trax, with a fallback REPL
-
 import process from 'node:process'
 import repl from 'node:repl'
 import YAML from 'yaml'
 import { Trax } from '@slugbugblue/trax'
-import { version as traxVersion } from '@slugbugblue/trax/version'
 import { version as analystVersion } from '@slugbugblue/trax-analyst'
 import * as tty from '@slugbugblue/trax-tty'
-// Load all the commands as individual plugins
-import { analyzeCmd } from './cmds/analyze.js'
-import { deleteCmd } from './cmds/delete.js'
-import { helpCmd } from './cmds/help.js'
-import {
-  importCmd,
-  exportCmd,
-  getFile,
-  saveFile,
-  findFiles,
-} from './cmds/import-export.js'
-import { listCmd } from './cmds/list.js'
-import { newCmd } from './cmds/new.js'
-import { notesCmd } from './cmds/notes.js'
-import { playCmd, tryCmd } from './cmds/play-try.js'
-import { puzzlesCmd } from './cmds/puzzles.js'
-import { selectCmd } from './cmds/select.js'
-import { suggestCmd } from './cmds/suggest.js'
-import { undoCmd } from './cmds/undo.js'
-import { viewCmd } from './cmds/view.js'
+import { allCmds } from './cmds/index.js'
+import { getFile, saveFile, findFiles } from './cmds/import-export.js'
 import { version } from './version.js'
 
-// Because typeof [] and null are both 'object'. is([], 'arr') => true
+/**
+ * @callback Colorize
+ * @param {string} text
+ * @param {string | number} [defaultColor]
+ * @returns {string}
+ */
+
+/**
+ * @typedef {Colorize & {
+ *   black: Colorize
+ *   command: Colorize
+ *   default: Colorize
+ *   error: Colorize
+ *   fatal: Colorize
+ *   help: Colorize
+ *   id: Colorize
+ *   optional: Colorize
+ *   short: Colorize
+ *   success: Colorize
+ *   variable: Colorize
+ *   white: Colorize
+ * }} Colorer
+ */
+
+/**
+ * @typedef {object} GameNote
+ * @property {number} move - the move number
+ * @property {string} note - the note text
+ */
+
+/** @typedef {GameNote[]} GameNotes */
+
+/** @typedef {'trax' | 'trax8' | 'traxloop'} TraxVariant */
+
+/**
+ * @typedef {object} GameData
+ * @property {string} id - game identifier
+ * @property {TraxVariant} rules - game variant
+ * @property {string} name - display name of the game variant
+ * @property {number} turn - current player (1 or 2)
+ * @property {string[]} players - player names [white, black]
+ * @property {string} moves - space-separated move notation
+ * @property {boolean} [over] - whether the game has ended
+ * @property {string} [puzzle] - puzzle ID if this is a puzzle game
+ * @property {number} [max] - max moves for puzzle win condition
+ * @property {GameNotes} [notes] - annotations
+ */
+
+/**
+ * @typedef {object} PuzzleStats
+ * @property {number} attempts - number of times started
+ * @property {number} solved - number of times solved
+ */
+
+/**
+ * @typedef {object} Command
+ * @property {string[]} alt - alternative names
+ * @property {string} args - argument syntax string
+ * @property {string[] | Function} comp - tab-completion hints
+ * @property {string} desc - short description
+ * @property {string[]} help - detailed help lines
+ * @property {boolean} [hide] - whether to hide from the help listing
+ * @property {Function} fn - command handler
+ */
+
+/**
+ * Plugin definition as supplied by a command module (looser than Command).
+ * @typedef {object} PluginDef
+ * @property {string} name
+ * @property {string | string[]} [alt]
+ * @property {string} [args]
+ * @property {string | string[] | Function} [comp]
+ * @property {string} desc
+ * @property {string | string[]} [help]
+ * @property {boolean} [hide]
+ * @property {string | string[]} [opts]
+ * @property {RegExp | RegExp[]} [rx]
+ * @property {Function} fn
+ */
+
+/**
+ * @typedef {object} CLIContext
+ * @property {Record<string, GameData>} GAMES - all stored games
+ * @property {GameData} GAME - currently selected game
+ * @property {string} ID - current game ID
+ * @property {number} puzzleLevel - current puzzle level
+ * @property {import('@slugbugblue/trax').Trax} TRAX - current Trax instance
+ * @property {Record<string, number>} COLORS - ANSI color codes by name
+ * @property {Colorer} color - colorizer function
+ * @property {(command: string) => Command} cmd - get a command object by name
+ * @property {string[]} commands - all registered command names
+ * @property {(id: string) => void} delete - delete a game by ID
+ * @property {(cmd: string, ...args: unknown[]) => void} do - invoke a command
+ * @property {(...parts: string[]) => Promise<void>} doNext - execute a command line
+ * @property {(text: string) => void} error - print an error to stdout
+ * @property {(move: string) => string} fixNotation - normalize move notation
+ * @property {(id?: string) => void} load - load a game by ID
+ * @property {(rules: string, players: string[], moves: string) => string} newGame - create a new game
+ * @property {(puzzle: object) => string} newPuzzle - start a new puzzle game
+ * @property {(text: string) => void} out - print to stdout
+ * @property {(n: number, noun: string, nouns?: string) => string} plural - pluralize a noun
+ * @property {(id: string) => PuzzleStats} puzzle - get puzzle stats
+ * @property {(id: string) => void} puzzleSolved - record a puzzle as solved
+ * @property {(word?: string) => string | string[] | undefined} resolveCommand - resolve abbreviation
+ * @property {() => void} save - persist data to disk
+ * @property {(moves: string[]) => void} setGame - update the current game's moves
+ * @property {() => void} updateGameData - sync TRAX state into stored game data
+ * @property {Function} bubble - tty bubble renderer
+ * @property {Function} display - tty board display
+ * @property {Function} name - tty name formatter
+ * @property {(variable: unknown, type: string) => boolean} is - type checker
+ * @property {string} version - CLI version string
+ * @property {string} CMD - command currently being evaluated
+ * @property {import('node:repl').REPLServer | undefined} repl - active REPL instance
+ */
+
+/** Check the type of a value, correctly handling arrays and null.
+ * @param {unknown} variable - value to check
+ * @param {string} type - expected type prefix (e.g. 'str', 'arr', 'func', 'undef')
+ * @returns {boolean}
+ */
 const is = (variable, type) =>
   Object.prototype.toString
     .call(variable)
@@ -59,10 +149,11 @@ const versionCmd = {
   opts: ['--version', '-v'],
   desc: 'display version number',
   help: 'Print out the current version of this program.',
+  /** @param {CLIContext} CLI */
   fn: (CLI) =>
     CLI.out(
       [
-        `Trax: engine v${traxVersion}`,
+        `Trax: engine v${Trax.version}`,
         `analyst v${analystVersion}`,
         `tty v${tty.version}`,
         `cli v${version}`,
@@ -87,26 +178,12 @@ const quitCmd = {
   },
 }
 
-const plugins = [
-  analyzeCmd,
-  deleteCmd,
-  exportCmd,
-  helpCmd,
-  importCmd,
-  listCmd,
-  newCmd,
-  notesCmd,
-  playCmd,
-  puzzlesCmd,
-  quitCmd,
-  selectCmd,
-  suggestCmd,
-  tryCmd,
-  undoCmd,
-  versionCmd,
-  viewCmd,
-]
+const plugins = [...allCmds, quitCmd, versionCmd]
 
+/** Generate a new unique game ID, filling gaps from the low end.
+ * @param {{ games?: Record<string, GameData> }} DATA
+ * @returns {string}
+ */
 const newId = (DATA) => {
   let max = 0
   let min = Number.POSITIVE_INFINITY
@@ -133,7 +210,9 @@ const color = (text, defaultColor) => {
   let quote = false
   let id = false
   const colors = [defaultColor]
-  const c = (t) => tty.color(t, colors.at(-1) || CLI.COLORS.default)
+  /** @param {string} [t] @returns {string} */
+  const c = (t = '') => tty.color(t, colors.at(-1) || CLI.COLORS.default)
+  /** @param {string} t @returns {string} */
   const short = (t) => tty.color(t, CLI.COLORS.short) + c()
   for (const char of text) {
     switch (char) {
@@ -186,7 +265,7 @@ const color = (text, defaultColor) => {
       }
 
       default: {
-        if (id && !/[\da-z]/.test(char)) {
+        if (id && !/[\da-z]/v.test(char)) {
           id = false
           colors.pop()
           out += c(char)
@@ -201,7 +280,9 @@ const color = (text, defaultColor) => {
 }
 
 // Internal representations of files
+/** @type {{ id: string, puzzleLevel: number }} */
 const CONFIG = { id: '', puzzleLevel: 0 }
+/** @type {{ games: Record<string, GameData>, puzzles: Record<string, PuzzleStats> }} */
 const DATA = { games: {}, puzzles: {} }
 
 // CLI context object for plugins
@@ -247,24 +328,27 @@ const CLI = {
   // CLI.color('hi') and CLI.color.default('hi') are equivalent
   color,
 
+  /** @param {string} command @returns {Command} */
   cmd(command) {
     // Return a command structure object or an empty object
     if (is(command, 'str') && command in commands) {
       return commands[command]
     }
 
-    return {}
+    return /** @type {Command} */ ({})
   },
 
   get commands() {
     return Object.keys(commands)
   },
 
+  /** @param {string} id */
   delete(id) {
     delete DATA.games[id]
     saveData()
   },
 
+  /** @param {string} cmd @param {...unknown} args */
   do(cmd, ...args) {
     // Call another plugin
     if (cmd in commands) {
@@ -274,17 +358,20 @@ const CLI = {
     }
   },
 
+  /** @param {...string} cmd */
   async doNext(...cmd) {
     // Execute another command line
     await evaluate(cmd.join(' '))
   },
 
+  /** @param {string} text */
   error(text) {
     // Prints an error to stdout
     CLI.out(CLI.color.error(text))
   },
 
   // Notation manipulation
+  /** @param {string} move @returns {string} */
   fixNotation(move) {
     if (move.endsWith('b')) return move.slice(0, -1) + '\\'
     if (move.endsWith('s')) return move.slice(0, -1) + '/'
@@ -292,6 +379,7 @@ const CLI = {
     return move
   },
 
+  /** @param {string} [id] */
   load(id) {
     id ||= Object.keys(DATA.games || {})[0]
     if (id && DATA.games?.[id] && DATA.games[id].rules) {
@@ -300,12 +388,18 @@ const CLI = {
         saveConfig()
       }
 
-      const game = CLI.GAME
+      const game = DATA.games[id]
       game.players ||= ['white', 'black']
       CLI.TRAX = new Trax(game.rules, game.moves, 'cli')
     }
   },
 
+  /**
+   * @param {TraxVariant} rules
+   * @param {string[]} players
+   * @param {string} moves
+   * @returns {string}
+   */
   newGame(rules, players, moves) {
     // Creates a new game
     const id = newId(DATA)
@@ -328,6 +422,7 @@ const CLI = {
     return id
   },
 
+  /** @param {import('@slugbugblue/trax-puzzles').Puzzle} puzzle @returns {string} */
   newPuzzle(puzzle) {
     // Starts a new puzzle
     const id = newId(DATA)
@@ -348,7 +443,7 @@ const CLI = {
       name: trax.name,
       turn: trax.turn,
       max: puzzle.max,
-      players: trax.turn === 1 ? players : players.reverse(),
+      players: trax.turn === 1 ? players : players.toReversed(),
       moves: trax.moves.join(' '),
       notes,
     }
@@ -369,30 +464,40 @@ const CLI = {
     return id
   },
 
+  /** @param {string} text */
   out(text) {
     // Prints to stdout
     console.info(text + tty.color(''))
   },
 
+  /**
+   * @param {number} n
+   * @param {string} noun
+   * @param {string} [nouns]
+   * @returns {string}
+   */
   plural(n, noun, nouns) {
     return String(n) + ' ' + (Math.abs(n) === 1 ? noun : nouns || noun + 's')
   },
 
+  /** @param {string} id @returns {PuzzleStats} */
   puzzle(id) {
     return DATA.puzzles?.[id] || { attempts: 0, solved: 0 }
   },
 
+  /** @param {string} id */
   puzzleSolved(id) {
     DATA.puzzles ||= {}
     DATA.puzzles[id] ||= { attempts: 1, solved: 0 }
     DATA.puzzles[id].solved += 1
   },
 
+  /** @param {string} [word] @returns {string | string[] | undefined} */
   resolveCommand(word) {
     // Determine if an entered word is a valid command.
     // Returns the command if a single match is found, an array if multiple
     // commands match, or undefined if nothing matches.
-    if (is(word, 'str') && word.length > 0) {
+    if (word && is(word, 'str')) {
       return abbreviations[word.toLowerCase()]
     }
 
@@ -404,9 +509,10 @@ const CLI = {
     saveData()
   },
 
+  /** @param {string[]} moves */
   setGame(moves) {
     // Updates the moves for the current game
-    const game = CLI.GAME
+    const game = DATA.games[CLI.ID]
     const trax = new Trax(game.rules, moves, 'cli')
     if (game.over || trax.over) game.over = trax.over
     game.moves = trax.moves.join(' ')
@@ -417,7 +523,7 @@ const CLI = {
   },
 
   updateGameData() {
-    const data = DATA.games[CLI.GAME.id]
+    const data = DATA.games[CLI.ID]
     const moves = CLI.TRAX.moves.join(' ')
     if (data.moves !== moves) {
       data.moves = moves
@@ -434,30 +540,41 @@ const CLI = {
 
   is,
   version,
+
+  // Dynamically assigned during evaluate() and main()
+  CMD: '',
+  /** @type {import('node:repl').REPLServer | undefined} */
+  repl: undefined,
 }
 
 let startRepl = false
 
+/** @returns {Promise<typeof CONFIG>} */
 const getConfig = async () => {
   await getFile('config', 'trax.yaml', CONFIG, YAML.parse)
   return CONFIG
 }
 
+/** @returns {Promise<typeof DATA>} */
 const getData = async () => {
   await getFile('data', 'trax.json', DATA, JSON.parse)
   return DATA
 }
 
+/** @returns {void} */
 const saveConfig = () => {
   saveFile('config', 'trax.yaml', YAML.stringify(CONFIG))
 }
 
+/** @returns {void} */
 const saveData = () => {
   saveFile('data', 'trax.json', JSON.stringify(DATA, null, 2) + '\n')
 }
 
+/** @type {Record<string, string>} */
 const OPTS = {}
 
+/** @returns {string} */
 const parseCommandLine = () => {
   let cmd = ''
   const args = process.argv.slice(2)
@@ -479,37 +596,61 @@ const parseCommandLine = () => {
 
 // Auto-populate the color functions
 for (const [name, value] of Object.entries(CLI.COLORS)) {
-  CLI.color[name] = (text) => color(text, value)
+  // @ts-ignore — dynamic string-keyed assignment onto the Colorer type
+  CLI.color[name] = (/** @type {string} */ text) => color(text, value)
 }
 
+/**
+ * @template T
+ * @param {T | T[] | undefined} item
+ * @returns {T[]}
+ */
 const forceArray = (item) =>
-  is(item, 'arr') ? item : is(item, 'undef') ? [] : [item]
+  Array.isArray(item) ? item : item === undefined ? [] : [item]
 
+/** @type {Record<string, string | string[]>} */
 const abbreviations = {}
+/** @type {Record<string, Command>} */
 const commands = {}
+/** @type {string[]} */
 const aliases = []
+/** @type {{rx: RegExp, name: string}[]} */
 const regexes = []
 
+/**
+ * @param {string[]} abbr
+ * @param {string} full
+ */
 const addAbbrev = (abbr, full) => {
   for (let abbrev of abbr) {
     while (abbrev.length > 0) {
-      const abbrSet = abbreviations[abbrev] || new Set()
-      abbrSet.add(full)
-      abbreviations[abbrev] = abbrSet
+      const existing = abbreviations[abbrev]
+      if (!existing) {
+        abbreviations[abbrev] = full
+      } else if (typeof existing === 'string') {
+        if (existing !== full) abbreviations[abbrev] = [existing, full]
+      } else if (!existing.includes(full)) {
+        existing.push(full)
+      }
+
       abbrev = abbrev.slice(0, -1)
     }
   }
 }
 
+/**
+ * @param {string | string[] | Function | undefined} comp
+ * @returns {string[] | Function}
+ */
 const makeComp = (comp) => {
-  if (is(comp, 'arr') || is(comp, 'func')) return comp
-  if (is(comp, 'str')) return comp.split(' ')
+  if (Array.isArray(comp) || typeof comp === 'function') return comp
+  if (typeof comp === 'string') return comp.split(' ')
   return []
 }
 
 const processPlugins = () => {
   // Process all the plugin command entries
-  for (const cmd of plugins) {
+  for (const cmd of /** @type {PluginDef[]} */ (plugins)) {
     if (cmd.opts) {
       for (const opt of forceArray(cmd.opts)) {
         OPTS[opt] = cmd.name
@@ -541,11 +682,15 @@ const processPlugins = () => {
   }
 
   for (const [abbr, value] of Object.entries(abbreviations)) {
-    const newValue = [...value]
-    abbreviations[abbr] = value.size > 1 ? newValue.sort() : newValue[0]
+    if (Array.isArray(value)) abbreviations[abbr] = value.toSorted()
   }
 }
 
+/**
+ * @param {string[]} completions
+ * @param {string} match
+ * @returns {string[]}
+ */
 const expand = (completions, match) => {
   completions = [...completions] // Do not modify in-place
   if (completions.includes('<cmd>')) {
@@ -590,8 +735,9 @@ const expand = (completions, match) => {
   return completions
 }
 
+/** @param {string} line @returns {[string[], string]} */
 const completer = (line) => {
-  const words = line.split(/\s+/).filter(Boolean)
+  const words = line.split(/\s+/v).filter(Boolean)
 
   let match = words.at(-1) || ''
   const previous = new Set(words.slice(1, -1).map((s) => s.toLowerCase()))
@@ -600,14 +746,16 @@ const completer = (line) => {
     match = ''
   }
 
+  /** @type {string[]} */
   let completions = []
   const cmd = abbreviations[String(words[0]).toLowerCase()]
 
-  if (is(cmd, 'str') && (line.endsWith(' ') || words.length > 1)) {
-    completions = commands[cmd].comp
-    if (is(completions, 'func')) {
-      completions = completions(CLI, words.slice(1), aliases)
-    }
+  if (typeof cmd === 'string' && (line.endsWith(' ') || words.length > 1)) {
+    const { comp } = commands[cmd]
+    completions =
+      typeof comp === 'function'
+        ? /** @type {string[]} */ (comp(CLI, words.slice(1), aliases))
+        : comp
 
     completions = expand(completions, match)
     if (words.length === 1 || (words.length === 2 && !line.endsWith(' '))) {
@@ -617,18 +765,12 @@ const completer = (line) => {
     completions = aliases
   }
 
-  for (let i = 0; i < completions.length; i++) {
-    const word = completions[i]
-    if (word.includes('|')) {
-      const comps = word.split('|')
-      completions[i] = comps.some((c) => previous.has(c.toLowerCase()))
-        ? ''
-        : comps
-    }
-  }
-
   completions = completions
-    .flat()
+    .flatMap((word) => {
+      if (!word.includes('|')) return word
+      const comps = word.split('|')
+      return comps.some((c) => previous.has(c.toLowerCase())) ? '' : comps
+    })
     .filter((c) => c && !previous.has(c.toLowerCase()))
 
   if (match && completions.length > 0) {
@@ -639,20 +781,17 @@ const completer = (line) => {
 
   if (!match && completions.length === 1) completions.push(' ')
 
-  completions = completions.map((c) => c + ' ').sort()
+  completions = completions.map((c) => c + ' ').toSorted()
 
   return [completions, match]
 }
 
+/** @param {string[]} cmd @returns {Set<string>} */
 const ambiguousSuggestions = (cmd) => {
-  const maybe = new Set()
+  const maybe = /** @type {Set<string>} */ (new Set())
   for (const alias of cmd) {
     if (alias.startsWith(CLI.CMD)) maybe.add(alias)
-
-    let alts = commands[alias].alt
-    alts = is(alts, 'arr') ? alts : [alts || '']
-
-    for (const alt of alts) {
+    for (const alt of commands[alias].alt) {
       if (alt.startsWith(CLI.CMD)) maybe.add(alt)
     }
   }
@@ -660,30 +799,31 @@ const ambiguousSuggestions = (cmd) => {
   return maybe
 }
 
+/** @param {string} command */
 const evaluate = async (command) => {
-  const [CMD, ...words] = command.split(/\s+/).filter(Boolean)
+  const [CMD, ...words] = command.split(/\s+/v).filter(Boolean)
   const cmdLower = CMD?.toLowerCase() || ''
   CLI.CMD = cmdLower
   let cmd = abbreviations[cmdLower]
 
   // If we are not in a REPL, let's remove hidden commands
-  if (!CLI.repl && is(cmd, 'arr')) {
+  if (!CLI.repl && Array.isArray(cmd)) {
     cmd = cmd.filter((c) => !commands[c].hide)
     if (cmd.length === 1) cmd = cmd[0]
   }
 
-  if (is(cmd, 'str')) {
+  if (typeof cmd === 'string') {
     if (words.length > 0 && abbreviations[words[0].toLowerCase()] === 'help') {
       commands.help.fn(CLI, cmd)
     } else {
       await commands[cmd].fn(CLI, ...words)
     }
-  } else if (is(cmd, 'arr')) {
+  } else if (Array.isArray(cmd)) {
     CLI.error('Ambiguous command. Perhaps you meant one of the following:')
     const maybe = ambiguousSuggestions(cmd)
 
     if (maybe.size > 0) {
-      for (const alias of [...maybe].sort()) {
+      for (const alias of [...maybe].toSorted()) {
         tty.outty(CLI.color.command('  ' + alias))
       }
     }
@@ -716,11 +856,11 @@ const main = async () => {
 
       CLI.repl = repl.start({
         prompt: 'trax❯ ',
-        async eval(cmd, ctx, fn, cb) {
+        async eval(cmd, _ctx, _fn, cb) {
           try {
             await evaluate(cmd)
           } catch (error) {
-            tty.outty(error, CLI.COLORS.fatal)
+            tty.outty(String(error), CLI.COLORS.fatal)
             throw error
           }