@slugbugblue/trax-cli 0.12.1 → 0.13.0

package/src/cmds/import-export.js

@@ -1,19 +1,14 @@
-/* Copyright 2022-2025 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 import/export commands
+ * @copyright 2022-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// CLI import/export commands
+/**
+ * @typedef {import('../cli.js').CLIContext} CLIContext
+ * @typedef {import('../cli.js').TraxVariant} TraxVariant
+ * @typedef {import('../cli.js').GameNotes} GameNotes
+ */
 
 import fs from 'node:fs/promises'
 import process from 'node:process'
@@ -22,14 +17,17 @@ import { Trax } from '@slugbugblue/trax'
 import { puzzles, sources } from '@slugbugblue/trax-puzzles'
 
 const paths = envPaths('trax', { suffix: '' })
+/** @type {Record<string, string>} */
 const PATHS = {}
 
 // Store a copy of the CLI context object locally
+/** @type {Partial<CLIContext>} */
 let cli = {}
 
+/** @param {unknown} fsError */
 const fsOuch = (fsError) => {
   if (cli.out) {
-    cli.out(fsError, cli.COLORS.fatal)
+    cli.out(String(fsError))
   } else {
     console.log(fsError)
   }
@@ -37,18 +35,23 @@ const fsOuch = (fsError) => {
   throw fsError
 }
 
+/** @param {string} name @returns {string} */
 const expandPath = (name) => {
   // Expand home directory ... anything else?
-  if (name.includes('~')) name = name.replace('~', process.env.HOME)
+  if (name.includes('~')) name = name.replace('~', process.env.HOME ?? '~')
   return name
 }
 
 // Return the actual path on disk, creating it if necessary.
 // Path is one of cache, config, data, log, temp.
+/** @param {string} path @returns {Promise<string | false>} */
 const getPath = async (path) => {
   if (path in PATHS) return PATHS[path]
   if (path in paths) {
-    const realPath = paths[path]
+    const pathsRecord = /** @type {Record<string, string>} */ (
+      /** @type {unknown} */ (paths)
+    )
+    const realPath = pathsRecord[path]
     await fs.mkdir(realPath, { recursive: true })
     PATHS[path] = realPath
     return realPath
@@ -57,6 +60,7 @@ const getPath = async (path) => {
   return false
 }
 
+/** @returns {string} */
 const hexy = (length = 6) => {
   let hex = ''
   while (hex.length < length) {
@@ -66,6 +70,13 @@ const hexy = (length = 6) => {
   return hex
 }
 
+/**
+ * @param {string} filetype
+ * @param {string} filename
+ * @param {Record<string, unknown>} variable
+ * @param {(s: string) => Record<string, unknown>} decode
+ * @returns {Promise<Record<string, unknown>>}
+ */
 export const getFile = async (filetype, filename, variable, decode) => {
   const path = await getPath(filetype)
   if (path) {
@@ -82,7 +93,9 @@ export const getFile = async (filetype, filename, variable, decode) => {
         } else {
           console.log(error)
         }
-      } else if (fsError.code !== 'ENOENT') {
+      } else if (
+        /** @type {NodeJS.ErrnoException} */ (fsError).code !== 'ENOENT'
+      ) {
         fsOuch(fsError)
       }
     }
@@ -91,6 +104,12 @@ export const getFile = async (filetype, filename, variable, decode) => {
   return variable
 }
 
+/**
+ * @param {string} filetype
+ * @param {string} filename
+ * @param {string} data
+ * @returns {Promise<void>}
+ */
 export const saveFile = async (filetype, filename, data) => {
   const path = await getPath(filetype)
   if (path) {
@@ -118,6 +137,36 @@ export const importCmd = {
     'Load a ".trx" game file into memory. Once imported, it will be assigned',
     'a game id and automatically selected for future commands.',
   ],
+  /** @param {CLIContext} CLI @param {string} [filename] */
+  async fn(CLI, filename) {
+    cli = CLI
+    if (!filename) {
+      CLI.error('Missing filename.')
+      return CLI.do('help', 'import')
+    }
+
+    let content
+    try {
+      content = await fs.readFile(expandPath(filename), 'utf8')
+    } catch (fsError) {
+      if (
+        /** @type {NodeJS.ErrnoException} */ (fsError).code === 'ENOENT' &&
+        !filename.endsWith('.trx')
+      ) {
+        try {
+          content = await fs.readFile(expandPath(filename + '.trx'), 'utf8')
+        } catch {
+          content = null
+        }
+      }
+
+      if (!content) return CLI.error(String(fsError))
+    }
+
+    if (!interpretFile(CLI, content)) {
+      CLI.error(filename + ' does not appear to be formatted correctly.')
+    }
+  },
 }
 
 export const exportCmd = {
@@ -130,29 +179,95 @@ export const exportCmd = {
     'Export the current game to an external ".trx" file for safe-keeping or',
     'to share. Specify a game id to export a different game.',
   ],
+  /** @param {CLIContext} CLI @param {string} [id] @param {string} [filename] */
+  async fn(CLI, id, filename) {
+    cli = CLI
+    let game = CLI.GAME
+    if (id) {
+      const newid = id.replace(/^#/v, '')
+      game = CLI.GAMES[newid]
+      if (!game) {
+        filename = id
+        game = CLI.GAME
+      }
+    }
+
+    if (!game || !game.id) {
+      return CLI.error('No active game. Type "new" to start a game.')
+    }
+
+    const trax = new Trax(game.rules, game.moves, 'cli')
+
+    let content = Trax.names[game.rules].replace(' ', '') + '\n'
+    content += game.players?.[0] || 'white'
+    content += ' vs '
+    content += game.players?.[1] || 'black'
+    content += '\n; @slugbugblue/trax cli.js v' + CLI.version + '\n'
+    if (game.puzzle) {
+      const puzzle = puzzles.find((p) => p.id === game.puzzle)
+      if (puzzle) {
+        const source = sources[puzzle.src]
+        content += '; Puzzle ' + game.puzzle
+        if (source) {
+          content += source.copyright
+            ? ' ©' + source.copyright + ' by '
+            : ' provided courtesy of '
+          content += source.name
+          if (source.url) content += '\n; ' + source.url
+          if (source.license) {
+            content += '\n; Licensed under ' + source.license
+            content += source.licenseUrl ? ' ' + source.licenseUrl : ''
+          }
+        }
+
+        content += '\n'
+      }
+    }
+
+    content += interleaveNotation(trax.moves, game.notes)
+
+    filename &&= filename.replaceAll(/[^ a-z\d.~\/]/gv, '')
+    if (filename) {
+      const fname = filename.split('/').pop()
+      if (!fname) filename += game.rules + game.id
+      if (!fname || !fname.includes('.')) filename += '.trx'
+      CLI.out(CLI.color('Exporting #' + game.id + ' to ') + filename)
+      try {
+        fs.writeFile(expandPath(filename), content)
+      } catch (error) {
+        fsOuch(error)
+      }
+    } else {
+      CLI.out(content)
+    }
+  },
 }
 
 /** Interpret the rules string of a .trx file.
- * @arg {string} r - rules string in lower case
+ * @param {string} r - rules string in lower case
  * @returns {TraxVariant}
  */
 const getRules = (r) =>
   r.includes('loop') ? 'traxloop' : r.includes('8x8') ? 'trax8' : 'trax'
 
 /** Decode a .trx formatted string into a game, preserving players and comments.
- * @arg {any} CLI - the CLI object
- * @arg {string} content - the contents of the .trx file
+ * @param {CLIContext} CLI - the CLI object
+ * @param {string} content - the contents of the .trx file
  * @returns {boolean} - true if a game was created
  */
 const interpretFile = (CLI, content) => {
+  /** @type {TraxVariant | undefined} */
   let rules
   let trax
+  /** @type {string[]} */
   let players = []
+  /** @type {string[]} */
   const moves = []
+  /** @type {GameNotes} */
   const comments = []
   for (const line of content.split('\n')) {
     if (!line) continue
-    const [ln, ...comment] = line.split(/[#;]/)
+    const [ln, ...comment] = line.split(/[#;]/v)
     if (ln) {
       const lower = ln.toLowerCase()
       if (!rules && lower.includes('trax')) {
@@ -183,7 +298,7 @@ const interpretFile = (CLI, content) => {
 
     if (comment.length > 0) {
       const note = comment.map((c) => c.trim()).join(' ')
-      if (!/^@slugbugblue\/trax cli\.js v/.test(note)) {
+      if (!/^@slugbugblue\/trax cli\.js v/v.test(note)) {
         comments.push({
           note,
           move: trax?.move || 0,
@@ -205,36 +320,9 @@ const interpretFile = (CLI, content) => {
   return true
 }
 
-importCmd.fn = async (CLI, filename) => {
-  cli = CLI
-  if (!filename) {
-    CLI.error('Missing filename.')
-    return CLI.do('help', 'import')
-  }
-
-  let content
-  try {
-    content = await fs.readFile(expandPath(filename), 'utf8')
-  } catch (fsError) {
-    if (fsError.code === 'ENOENT' && !filename.endsWith('.trx')) {
-      try {
-        content = await fs.readFile(expandPath(filename + '.trx'), 'utf8')
-      } catch {
-        content = null
-      }
-    }
-
-    if (!content) return CLI.error(fsError.toString())
-  }
-
-  if (!interpretFile(CLI, content)) {
-    CLI.error(filename + ' does not appear to be formatted correctly.')
-  }
-}
-
 /** Get all the notes for a certain move.
- * @arg {number} move - The move number
- * @arg {GameNotes} notes? - The notes for a game
+ * @param {number} move - The move number
+ * @param {GameNotes} [notes] - The notes for a game
  * @returns {string} - Notes formatted for this move, or empty string if none
  */
 const gameNotes = (move, notes) => {
@@ -248,18 +336,18 @@ const gameNotes = (move, notes) => {
   )
 }
 
-/** Join two strings together with a character with the appropriate joining
- * character depending on the length of the strings.
- * @arg {string} a - the first string
- * @arg {string} b - the second string
+/** Join two strings together with the appropriate joining character
+ * depending on the combined length of the strings.
+ * @param {string} a - the first string
+ * @param {string} b - the second string
  * @returns {string} - both strings correctly joined
  */
 const join = (a, b) =>
   a.length === 0 ? b : a.length + b.length > 78 ? a + '\n' + b : a + ' ' + b
 
 /** Interleave the game moves with any notes, formatted for the export file.
- * @arg {string[]} moves - an array of move notations
- * @arg {GameNotes} notes? - The notes for a game
+ * @param {string[]} moves - an array of move notations
+ * @param {GameNotes} [notes] - The notes for a game
  * @returns {string} - A string that can be placed into an export file
  */
 const interleaveNotation = (moves, notes) => {
@@ -294,70 +382,10 @@ const interleaveNotation = (moves, notes) => {
   return content
 }
 
-exportCmd.fn = async (CLI, id, filename) => {
-  cli = CLI
-  let game = CLI.GAME
-  if (id) {
-    const newid = id.replace(/^#/, '')
-    game = CLI.GAMES[newid]
-    if (!game) {
-      filename = id
-      game = CLI.GAME
-    }
-  }
-
-  if (!game || !game.id) {
-    return CLI.error('No active game. Type "new" to start a game.')
-  }
-
-  const trax = new Trax(game.rules, game.moves, 'cli')
-
-  let content = Trax.names[trax.rules].replace(' ', '') + '\n'
-  content += game.players?.[0] || 'white'
-  content += ' vs '
-  content += game.players?.[1] || 'black'
-  content += '\n; @slugbugblue/trax cli.js v' + CLI.version + '\n'
-  if (game.puzzle) {
-    const puzzle = puzzles.find((p) => p.id === game.puzzle)
-    if (puzzle) {
-      const source = sources[puzzle.src]
-      content += '; Puzzle ' + game.puzzle
-      if (source) {
-        content += source.copyright
-          ? ' ©' + source.copyright + ' by '
-          : ' provided courtesy of '
-        content += source.name
-        if (source.url) content += '\n; ' + source.url
-        if (source.license) {
-          content += '\n; Licensed under ' + source.license
-          content += source.licenseUrl ? ' ' + source.licenseUrl : ''
-        }
-      }
-
-      content += '\n'
-    }
-  }
-
-  content += interleaveNotation(trax.moves, game.notes)
-
-  filename &&= filename.replaceAll(/[^ a-z\d.~/]/g, '')
-  if (filename) {
-    const fname = filename.split('/').pop()
-    if (!fname) filename += game.rules + game.id
-    if (!fname.includes('.')) filename += '.trx'
-    CLI.out(CLI.color('Exporting #' + game.id + ' to ') + filename)
-    try {
-      fs.writeFile(expandPath(filename), content)
-    } catch (error) {
-      fsOuch(error)
-    }
-  } else {
-    CLI.out(content)
-  }
-}
-
+/** @type {Record<string, string[]>} */
 const FOLDERS = {}
 
+/** @param {string} [path] @returns {string[]} */
 export const findFiles = (path) => {
   if (typeof path !== 'string') path = ''
   let folder = '.'
@@ -372,7 +400,6 @@ export const findFiles = (path) => {
   if (!FOLDERS[prefix]) {
     FOLDERS[prefix] = []
     fs.readdir(folder, { withFileTypes: true })
-      // eslint-disable-next-line promise/prefer-await-to-then
       .then((dir) => {
         // At this point, everything is happening asynchronously,
         // so we have to call findFiles at least twice before we
@@ -388,7 +415,6 @@ export const findFiles = (path) => {
 
         FOLDERS[prefix] = entries
       })
-      // eslint-disable-next-line promise/prefer-await-to-then
       .catch(() => {
         // Errors are unimportant and should be silently ignored
       })

package/src/cmds/index.js

@@ -0,0 +1,40 @@
+/**
+ * @copyright 2025-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
+ */
+
+// Load all the commands here and put them in a list.
+// This just keeps the main program a tiny bit cleaner.
+
+import { analyzeCmd } from './analyze.js'
+import { deleteCmd } from './delete.js'
+import { helpCmd } from './help.js'
+import { importCmd, exportCmd } from './import-export.js'
+import { listCmd } from './list.js'
+import { newCmd } from './new.js'
+import { notesCmd } from './notes.js'
+import { playCmd, tryCmd } from './play-try.js'
+import { puzzlesCmd } from './puzzles.js'
+import { selectCmd } from './select.js'
+import { suggestCmd } from './suggest.js'
+import { undoCmd } from './undo.js'
+import { viewCmd } from './view.js'
+
+export const allCmds = [
+  analyzeCmd,
+  deleteCmd,
+  helpCmd,
+  importCmd,
+  exportCmd,
+  listCmd,
+  newCmd,
+  notesCmd,
+  playCmd,
+  tryCmd,
+  puzzlesCmd,
+  selectCmd,
+  suggestCmd,
+  undoCmd,
+  viewCmd,
+]

package/src/cmds/list.js

@@ -1,19 +1,10 @@
-/* Copyright 2022 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 list command
+ * @copyright 2022-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// CLI list command
+/** @typedef {import('../cli.js').CLIContext} CLIContext */
 
 import process from 'node:process'
 import { Trax } from '@slugbugblue/trax'
@@ -39,8 +30,75 @@ export const listCmd = {
     "  <other text>: match a player's name or the latest game note",
     'Add the "reverse" option to reverse the sort order.',
   ],
+  /** @param {CLIContext} CLI @param {...string} filters */
+  fn(CLI, ...filters) {
+    if (Object.keys(CLI.GAMES).length === 0) {
+      return CLI.error('No games. Type "new" to start a new game.')
+    }
+
+    const puzzle = filters.find((f) => f.length > 1 && 'puzzles'.startsWith(f))
+    if (puzzle) return CLI.do('puzzles', ...filters.filter((f) => f !== puzzle))
+
+    /** @type {Array<Record<string, string | number | boolean | undefined>>} */
+    let list = []
+    const size = {
+      spacing: 13, // Amount of space taken up by fixed-length and between columns
+      id: 1,
+      name: 1,
+      moves: 1,
+      p1: 1,
+      p2: 1,
+    }
+    let noteSize = Number.POSITIVE_INFINITY
+
+    for (const game of Object.values(CLI.GAMES)) {
+      const moves = game.moves.length === 0 ? 0 : game.moves.split(' ').length
+      list.push({
+        sid: String(game.id).padStart(9, '0'),
+        id: (game.id === CLI.GAME.id ? '* #' : '#') + String(game.id),
+        name: game.name?.length || 0,
+        rules: game.rules,
+        moves: game.over ? 'game over' : CLI.plural(moves, 'move'),
+        smoves: game.over ? '9999' : String(moves).padStart(9, '0'),
+        sturn: String(game.turn),
+        p1: game.players?.[0] || 'white',
+        p2: game.players?.[1] || 'black',
+        turn: game.turn,
+        over: game.over,
+        note: game.notes?.at(-1)?.note || '',
+      })
+    }
+
+    list = listSort(list, filters)
+
+    for (const game of list) {
+      size.id = Math.max(size.id, String(game.id).length)
+      size.name = Math.max(size.name, Number(game.name))
+      size.moves = Math.max(size.moves, String(game.moves).length)
+      size.p1 = Math.max(size.p1, String(game.p1).length)
+      size.p2 = Math.max(size.p2, String(game.p2).length)
+      noteSize = Math.min(noteSize, leftover(size))
+    }
+
+    for (const game of list) {
+      CLI.out(
+        CLI.color(String(game.id).padStart(size.id) + ' ') +
+          Trax.names[
+            /** @type {import('../cli.js').TraxVariant} */ (String(game.rules))
+          ] +
+          ' '.repeat(size.name - Number(game.name) + 1) +
+          CLI.bubble(game.turn === 1 ? 'wh' : 'w', String(game.p1)) +
+          CLI.color('vs '.padStart(size.p1 - String(game.p1).length + 4)) +
+          CLI.bubble(game.turn === 2 ? 'bh' : 'b', String(game.p2)) +
+          CLI.color(' '.padStart(size.p2 - String(game.p2).length + 1)) +
+          CLI.color(String(game.moves).padEnd(size.moves)) +
+          CLI.color.help(' ' + String(game.note).slice(0, noteSize)),
+      )
+    }
+  },
 }
 
+/** @param {string} a @param {string} b @returns {number} */
 const alphaSort = (a, b) => {
   a = String(a).toLowerCase()
   b = String(b).toLowerCase()
@@ -49,6 +107,7 @@ const alphaSort = (a, b) => {
   return 0
 }
 
+/** @param {string | undefined} sort @returns {string} */
 const sortBy = (sort) => {
   if (!sort) return 'id'
   sort = sort.toLowerCase()
@@ -67,6 +126,11 @@ const sortBy = (sort) => {
   return sort
 }
 
+/**
+ * @param {Array<Record<string, string | number | boolean | undefined>>} list
+ * @param {string[]} filters
+ * @returns {Array<Record<string, string | number | boolean | undefined>>}
+ */
 const listSort = (list, filters) => {
   if (list.length === 0) return list
   let reverse = false
@@ -75,7 +139,7 @@ const listSort = (list, filters) => {
     if (by === 'reverse') {
       reverse = true
     } else if (list[0]?.[by]) {
-      list.sort((a, b) => alphaSort(a[by], b[by]))
+      list.sort((a, b) => alphaSort(String(a[by]), String(b[by])))
     } else if (by === 'trax') {
       list = list.filter((g) => g.rules === by)
     } else if (['over', 'active'].includes(by)) {
@@ -83,12 +147,16 @@ const listSort = (list, filters) => {
     } else {
       list = list.filter((g) => {
         return (
-          g.id.endsWith(by) ||
-          Trax.names[g.rules].toLowerCase().includes(by) ||
-          g.p1.toLowerCase().includes(by) ||
-          g.p2.toLowerCase().includes(by) ||
-          g.moves.startsWith(by + ' ') ||
-          g.note.includes(by)
+          String(g.id).endsWith(by) ||
+          Trax.names[
+            /** @type {import('../cli.js').TraxVariant} */ (String(g.rules))
+          ]
+            .toLowerCase()
+            .includes(by) ||
+          String(g.p1).toLowerCase().includes(by) ||
+          String(g.p2).toLowerCase().includes(by) ||
+          String(g.moves).startsWith(by + ' ') ||
+          String(g.note).includes(by)
         )
       })
     }
@@ -99,9 +167,9 @@ const listSort = (list, filters) => {
   return list
 }
 
-/** Find how many columns are left over after all the other columns arefilled.
- * @arg {Record<string, number>} sizes
- * @returns {number} number of columns left over
+/** Find how many columns are left over after all the other columns are filled.
+ * @param {Record<string, number>} sizes
+ * @returns {number}
  */
 const leftover = (sizes) => {
   let left = process.stdout.columns
@@ -111,66 +179,3 @@ const leftover = (sizes) => {
 
   return left
 }
-
-listCmd.fn = (CLI, ...filters) => {
-  if (Object.keys(CLI.GAMES).length === 0) {
-    return CLI.error('No games. Type "new" to start a new game.')
-  }
-
-  const puzzle = filters.find((f) => f.length > 1 && 'puzzles'.startsWith(f))
-  if (puzzle) return CLI.do('puzzles', ...filters.filter((f) => f !== puzzle))
-
-  let list = []
-  const size = {
-    spacing: 13, // Amount of space taken up by fixed-length and between columns
-    id: 1,
-    name: 1,
-    moves: 1,
-    p1: 1,
-    p2: 1,
-  }
-  let noteSize = Number.POSITIVE_INFINITY
-
-  for (const game of Object.values(CLI.GAMES)) {
-    const moves = game.moves.length === 0 ? 0 : game.moves.split(' ').length
-    list.push({
-      sid: String(game.id).padStart(9, '0'),
-      id: (game.id === CLI.GAME.id ? '* #' : '#') + String(game.id),
-      name: game.name?.length || 0,
-      rules: game.rules,
-      moves: game.over ? 'game over' : CLI.plural(moves, 'move'),
-      smoves: game.over ? '9999' : String(moves).padStart(9, '0'),
-      sturn: String(game.turn),
-      p1: game.players?.[0] || 'white',
-      p2: game.players?.[1] || 'black',
-      turn: game.turn,
-      over: game.over,
-      note: game.notes?.[game.notes.length - 1]?.note || '',
-    })
-  }
-
-  list = listSort(list, filters)
-
-  for (const game of list) {
-    size.id = Math.max(size.id, game.id.length)
-    size.name = Math.max(size.name, game.name)
-    size.moves = Math.max(size.moves, game.moves.length)
-    size.p1 = Math.max(size.p1, game.p1.length)
-    size.p2 = Math.max(size.p2, game.p2.length)
-    noteSize = Math.min(noteSize, leftover(size))
-  }
-
-  for (const game of list) {
-    CLI.out(
-      CLI.color(game.id.padStart(size.id) + ' ') +
-        Trax.names[game.rules] +
-        ' '.repeat(size.name - game.name + 1) +
-        CLI.bubble(game.turn === 1 ? 'wh' : 'w', game.p1) +
-        CLI.color('vs '.padStart(size.p1 - game.p1.length + 4)) +
-        CLI.bubble(game.turn === 2 ? 'bh' : 'b', game.p2) +
-        CLI.color(' '.padStart(size.p2 - game.p2.length + 1)) +
-        CLI.color(game.moves.padEnd(size.moves)) +
-        CLI.color.help(' ' + game.note.slice(0, noteSize)),
-    )
-  }
-}