@slugbugblue/trax-cli 0.12.1 → 0.14.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,61 @@ 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.')
+    }
+  },
+}
+
+/** Generate puzzle attribution comment lines for export.
+ * @param {CLIContext['GAME']} game - the current game
+ * @returns {string} - formatted attribution string, or empty if no puzzle
+ */
+const puzzleAttribution = (game) => {
+  if (!game.puzzle) return ''
+  const puzzle = puzzles.find((p) => p.id === game.puzzle)
+  if (!puzzle) return ''
+  const source = sources[puzzle.src]
+  let attr = '; Puzzle ' + game.puzzle
+  if (source) {
+    attr += source.copyright
+      ? ' ©' + source.copyright + ' by '
+      : ' provided courtesy of '
+    attr += source.name
+    if (source.url) attr += '\n; ' + source.url
+    if (source.license) {
+      attr += '\n; Licensed under ' + source.license
+      attr += source.licenseUrl ? ' ' + source.licenseUrl : ''
+    }
+  }
+
+  return attr + '\n'
 }
 
 export const exportCmd = {
@@ -130,29 +204,102 @@ 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 v' + CLI.version + '\n'
+    content += puzzleAttribution(game)
+    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
- * @returns {boolean} - true if a game was created
+/** Apply pending moves to the game, or record them as notes if the game is over.
+ * @param {string[]} moves - pending move tokens (mutated in place)
+ * @param {Trax} trax - the current game instance
+ * @param {GameNotes} notes - notes accumulator
  */
-const interpretFile = (CLI, content) => {
+const applyMoves = (moves, trax, notes) => {
+  if (trax.gameOver) {
+    notes.push({ note: moves.map((c) => c.trim()).join(' '), move: trax.move })
+  } else {
+    trax.playMoves(moves.filter(Boolean))
+    moves.splice(0)
+  }
+}
+
+/** Record a comment segment as a note, unless it is the generator attribution.
+ * @param {string[]} comment - comment tokens from after the # or ; delimiter
+ * @param {Trax | undefined} trax - the current game instance, if initialized
+ * @param {GameNotes} notes - notes accumulator
+ */
+const collectComment = (comment, trax, notes) => {
+  if (comment.length === 0) return
+  const note = comment.map((c) => c.trim()).join(' ')
+  if (!/^@slugbugblue\/trax-cli v/v.test(note)) {
+    notes.push({ note, move: trax?.move || 0 })
+  }
+}
+
+/** Parse a .trx formatted string into structured game data.
+ * @param {string} content - the contents of the .trx file
+ * @returns {{ rules: TraxVariant, players: string[], trax: Trax, notes: GameNotes } | null} - parsed game data, or null if invalid
+ */
+const parseFile = (content) => {
+  /** @type {TraxVariant | undefined} */
   let rules
+  /** @type {Trax | undefined} */
   let trax
+  /** @type {string[]} */
   let players = []
+  /** @type {string[]} */
   const moves = []
-  const comments = []
+  /** @type {GameNotes} */
+  const notes = []
   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')) {
@@ -169,33 +316,29 @@ const interpretFile = (CLI, content) => {
     }
 
     if (moves.length > 0) {
-      if (!trax) return false
-      if (trax.gameOver) {
-        comments.push({
-          note: moves.map((c) => c.trim()).join(' '),
-          move: trax.move,
-        })
-      } else {
-        trax.playMoves(moves.filter(Boolean))
-        moves.splice(0)
-      }
+      if (!trax) return null
+      applyMoves(moves, trax, notes)
     }
 
-    if (comment.length > 0) {
-      const note = comment.map((c) => c.trim()).join(' ')
-      if (!/^@slugbugblue\/trax cli\.js v/.test(note)) {
-        comments.push({
-          note,
-          move: trax?.move || 0,
-        })
-      }
-    }
+    collectComment(comment, trax, notes)
   }
 
-  if (!trax) return false
+  if (!trax || !rules) return null
+  return { rules, players, trax, notes }
+}
+
+/** Decode a .trx formatted string into a game, preserving players and comments.
+ * @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) => {
+  const parsed = parseFile(content)
+  if (!parsed) return false
 
+  const { rules, players, trax, notes } = parsed
   CLI.do('new', rules, ...players)
-  CLI.GAMES[String(CLI.GAME.id)].notes = comments
+  CLI.GAMES[String(CLI.GAME.id)].notes = notes
   if (trax.moves.length > 0) {
     CLI.do('play', ...trax.moves)
   } else {
@@ -205,36 +348,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 +364,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 +410,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 +428,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 +443,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,
+]