@slugbugblue/trax-cli 0.12.0 → 0.13.0

package/src/cmds/new.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 new command
+ * @copyright 2022-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// CLI new command
+/** @typedef {import('../cli.js').CLIContext} CLIContext */
 
 export const newCmd = {
   name: 'new',
@@ -25,6 +16,51 @@ export const newCmd = {
     'Valid variants are "trax", "loop", and "8x8". Defaults to "trax" if not',
     'specified. Use the "vs" keyword to use specific names for the players.',
   ],
+  /** @param {CLIContext} CLI @param {string} [variant] @param {...string} names */
+  fn(CLI, variant, ...names) {
+    let rules = ''
+    if (variant) {
+      variant = variant.toLowerCase()
+      if (variant.length > 1 && 'puzzles'.startsWith(variant)) {
+        return CLI.do('puzzles', 'new', ...names)
+      }
+
+      if (['8x8', '8', 'trax8x8', '8trax', '8x8trax'].includes(variant)) {
+        rules = 'trax8'
+      }
+
+      if (['loop', 'l', 'looptrax'].includes(variant)) rules = 'traxloop'
+      if (variant === 't') rules = 'trax'
+      if (['trax', 'traxloop', 'trax8'].includes(variant)) rules = variant
+
+      if (!rules) {
+        if (names.includes('vs') || names.includes('VS')) {
+          // We don't have a variant, we have player names
+          names.unshift(variant)
+        } else {
+          CLI.error('Unknown Trax variant.')
+          return CLI.do('help', 'new')
+        }
+      }
+    }
+
+    const players = pairUp()
+    if (names.length > 0) {
+      let vs = names.indexOf('vs')
+      if (vs === -1) vs = names.indexOf('VS')
+      if (vs >= 0) {
+        players[0] = names.slice(0, vs).join(' ') || 'white'
+        players[1] = names.slice(vs + 1).join(' ') || 'black'
+      }
+    }
+
+    const id = CLI.newGame(
+      /** @type {import('../cli.js').TraxVariant} */ (rules || 'trax'),
+      players,
+      '',
+    )
+    CLI.out(CLI.color('Started new game #' + id))
+  },
 }
 
 // Okay, yes, this is silly
@@ -103,44 +139,3 @@ const pairUp = () => {
   if (duo[0].toLowerCase() !== duo[0] && Math.random() < 0.5) duo.reverse()
   return duo
 }
-
-newCmd.fn = (CLI, variant, ...names) => {
-  let rules = ''
-  if (variant) {
-    variant = variant.toLowerCase()
-    if (variant.length > 1 && 'puzzles'.startsWith(variant)) {
-      return CLI.do('puzzles', 'new', ...names)
-    }
-
-    if (['8x8', '8', 'trax8x8', '8trax', '8x8trax'].includes(variant)) {
-      rules = 'trax8'
-    }
-
-    if (['loop', 'l', 'looptrax'].includes(variant)) rules = 'traxloop'
-    if (variant === 't') rules = 'trax'
-    if (['trax', 'traxloop', 'trax8'].includes(variant)) rules = variant
-
-    if (!rules) {
-      if (names.includes('vs') || names.includes('VS')) {
-        // We don't have a variant, we have player names
-        names.unshift(variant)
-      } else {
-        CLI.error('Unknown Trax variant.')
-        return CLI.do('help', 'new')
-      }
-    }
-  }
-
-  const players = pairUp()
-  if (names.length > 0) {
-    let vs = names.indexOf('vs')
-    if (vs === -1) vs = names.indexOf('VS')
-    if (vs >= 0) {
-      players[0] = names.slice(0, vs).join(' ') || 'white'
-      players[1] = names.slice(vs + 1).join(' ') || 'black'
-    }
-  }
-
-  const id = CLI.newGame(rules, players, '')
-  CLI.out(CLI.color('Started new game #' + id))
-}

package/src/cmds/notes.js

@@ -1,9 +1,11 @@
 /** Notes CLI command.
- * @copyright 2022
+ * @copyright 2022-2026
  * @author Chad Transtrum <chad@transtrum.net>
  * @license Apache-2.0
  */
 
+/** @typedef {import('../cli.js').CLIContext} CLIContext */
+
 export const notesCmd = {
   name: 'notes',
   args: '[#id] <text>',
@@ -12,26 +14,26 @@ export const notesCmd = {
     'Add a short note to a game that will be shown when the game is',
     'displayed, listed, or exported.',
   ],
-}
-
-notesCmd.fn = (CLI, id, ...note) => {
-  const current = String(CLI.GAME.id)
-  id ||= current
-  if (!/^#?\d+$/.test(id)) {
-    note.unshift(id)
-    id = current
-  }
+  /** @param {CLIContext} CLI @param {string} [id] @param {...string} note */
+  fn(CLI, id, ...note) {
+    const current = String(CLI.GAME.id)
+    id ||= current
+    if (!/^#?\d+$/v.test(id)) {
+      note.unshift(id)
+      id = current
+    }
 
-  if (id.startsWith('#')) id = id.slice(1)
+    if (id.startsWith('#')) id = id.slice(1)
 
-  const game = CLI.GAMES[id]
+    const game = CLI.GAMES[id]
 
-  if (!game) return CLI.error('Game not found.')
+    if (!game) return CLI.error('Game not found.')
 
-  const notes = game.notes || []
-  const move = game.moves.length > 0 ? game.moves.split(' ').length : 0
+    const notes = game.notes || []
+    const move = game.moves.length > 0 ? game.moves.split(' ').length : 0
 
-  notes.push({ move, note: note.join(' ') })
-  game.notes = notes
-  CLI.save()
+    notes.push({ move, note: note.join(' ') })
+    game.notes = notes
+    CLI.save()
+  },
 }

package/src/cmds/play-try.js

@@ -1,25 +1,17 @@
-/* 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 play/try commands
+ * @copyright 2022-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// CLI play/try commands
+/** @typedef {import('../cli.js').CLIContext} CLIContext */
 
 import { suggest } from '@slugbugblue/trax-analyst'
+import { puzzles } from '@slugbugblue/trax-puzzles'
 import { timeString } from '@slugbugblue/trax-cli/utils'
 
-const moveRx = /^\d+\.?$/
-const notationRx = /^[@a-z]+\d+[bps/\\+]$/i
+const moveRx = /^\d+\.?$/v
+const notationRx = /^[@a-z]+\d+[bps\/\\+]$/iv
 
 export const playCmd = {
   name: 'play',
@@ -35,6 +27,65 @@ export const playCmd = {
     'Multiple moves can be submitted at once. Move numbers are optional,',
     'but if included, they will be checked for accuracy.',
   ],
+  /** @param {CLIContext} CLI @param {...string} moves */
+  fn(CLI, ...moves) {
+    if (moves.length === 0 || !moves[0]) {
+      CLI.error('You must provide a move.')
+      return CLI.do('help', 'play')
+    }
+
+    if (!CLI.GAME?.id) {
+      CLI.do('new')
+    }
+
+    const game = CLI.GAME
+    const trax = CLI.TRAX
+
+    if (trax.over) {
+      return CLI.error('The game is over.')
+    }
+
+    const start = trax.move
+    let checkMove
+
+    for (let move of moves) {
+      if (notationRx.test(move)) {
+        const moveNumber = trax.move
+        move = CLI.fixNotation(move)
+        if (checkMove) {
+          trax.play(checkMove, move)
+        } else {
+          trax.play(move)
+        }
+
+        if (trax.move === moveNumber) {
+          CLI.error(
+            'Move "' +
+              (checkMove ? checkMove + '. ' : '') +
+              move +
+              '" is invalid.',
+          )
+        }
+      } else if (moveRx.test(move)) {
+        checkMove = Number(move)
+      } else if (move) {
+        CLI.error('Move "' + move + '" is not in the correct notation.')
+      }
+    }
+
+    if (trax.move !== start) {
+      const result = bot(CLI)
+      CLI.updateGameData()
+      CLI.do('view')
+      if (result === 'lose') {
+        CLI.error('Failed to complete puzzle ' + game.puzzle)
+      } else if (result === 'win') {
+        CLI.out(CLI.color.success('You completed puzzle ' + game.puzzle))
+      } else if (result) {
+        CLI.out(result)
+      }
+    }
+  },
 }
 
 export const tryCmd = {
@@ -47,15 +98,80 @@ export const tryCmd = {
     'View a move without committing to it. This is useful for seeing the',
     'effects of forced tiles.',
   ],
+  /** @param {CLIContext} CLI @param {string} [move] */
+  fn(CLI, move) {
+    if (!move || move.length === 0) {
+      CLI.error('You must provide a move.')
+      return CLI.do('help', 'try')
+    }
+
+    if (!CLI.TRAX) {
+      CLI.do('new')
+    }
+
+    if (CLI.TRAX.over) {
+      return CLI.error('The game is over.')
+    }
+
+    if (notationRx.test(move)) {
+      move = CLI.fixNotation(move)
+      const play = CLI.TRAX.dropTile(move, undefined, 'tentative')
+      if (play.valid || play.dropped.length > 0) {
+        CLI.display(CLI.TRAX, CLI.GAME.players, move)
+      } else {
+        CLI.error('Move is invalid.')
+      }
+    } else {
+      CLI.error('Move is invalid.')
+    }
+  },
+}
+
+/**
+ * Check if a concrete move matches a defense key token.
+ * Handles the catch-all wildcard (*), column wildcards (@**, A**, etc.),
+ * and row wildcards (*0*, *5*, etc.).
+ * @param {string} move
+ * @param {string} token
+ * @returns {boolean}
+ */
+const matchesToken = (move, token) => {
+  if (token === '*') return true
+  if (!token.includes('*')) return token === move
+  const pattern =
+    '^' +
+    token
+      .replace('*', token.startsWith('*') ? '[@A-Za-z]+' : '[0-9]+')
+      .replace('*', String.raw`[+/\\]`) +
+    '$'
+  return new RegExp(pattern, 'v').test(move)
 }
 
+/**
+ * Find the defense move for the current puzzle state, if one exists.
+ * @param {import('@slugbugblue/trax-puzzles').Defense} defense
+ * @param {string[]} moves
+ * @returns {string | undefined}
+ */
+const getDefenseMove = (defense, moves) => {
+  const key = Object.keys(defense).find((k) => {
+    const tokens = k.split(' ')
+    return (
+      tokens.length === moves.length &&
+      tokens.every((token, i) => matchesToken(moves[i], token))
+    )
+  })
+  return key ? defense[key] : undefined
+}
+
+/** @param {CLIContext} CLI @returns {string} */
 const bot = (CLI) => {
   const game = CLI.GAME
   const trax = CLI.TRAX
   const players = game.players || ['a', 'b']
   const name = players[trax.turn - 1]
   if (trax.over && game.puzzle) {
-    if (trax.move <= game.max && name !== 'puzzlebot') {
+    if (trax.move <= (game.max ?? 0) && name !== 'puzzlebot') {
       CLI.puzzleSolved(game.puzzle)
       return 'win'
     }
@@ -63,8 +179,8 @@ const bot = (CLI) => {
     return 'lose'
   }
 
-  if (!trax.over && /bot\b/i.test(name)) {
-    if (game.puzzle && trax.move >= game.max) {
+  if (!trax.over && /bot\b/iv.test(name)) {
+    if (game.puzzle && game.max !== undefined && trax.move >= game.max) {
       trax.play('puzzled')
       return 'lose'
     }
@@ -72,7 +188,18 @@ const bot = (CLI) => {
     CLI.do('view')
     CLI.out(CLI.bubble(trax.color + 'd', `${name} thinking...`))
     const start = Date.now()
-    const move = suggest(trax)?.pick?.move
+
+    let move
+    if (game.puzzle) {
+      const puzzle = puzzles.find((p) => p.id === game.puzzle)
+      if (puzzle?.defense) {
+        const offset = puzzle.notation.split(' ').length
+        move = getDefenseMove(puzzle.defense, trax.moves.slice(offset))
+      }
+    }
+
+    move ??= suggest(trax)?.pick?.move
+
     const ms = Date.now() - start
     if (move) {
       CLI.out(
@@ -87,89 +214,3 @@ const bot = (CLI) => {
 
   return ''
 }
-
-playCmd.fn = (CLI, ...moves) => {
-  if (moves.length === 0 || !moves[0]) {
-    CLI.error('You must provide a move.')
-    return CLI.do('help', 'play')
-  }
-
-  if (!CLI.GAME?.id) {
-    CLI.do('new')
-  }
-
-  const game = CLI.GAME
-  const trax = CLI.TRAX
-
-  if (trax.over) {
-    return CLI.error('The game is over.')
-  }
-
-  const start = trax.move
-  let checkMove
-
-  for (let move of moves) {
-    if (notationRx.test(move)) {
-      const moveNumber = trax.move
-      move = CLI.fixNotation(move)
-      if (checkMove) {
-        trax.play(checkMove, move)
-      } else {
-        trax.play(move)
-      }
-
-      if (trax.move === moveNumber) {
-        CLI.error(
-          'Move "' +
-            (checkMove ? checkMove + '. ' : '') +
-            move +
-            '" is invalid.',
-        )
-      }
-    } else if (moveRx.test(move)) {
-      checkMove = Number(move)
-    } else if (move) {
-      CLI.error('Move "' + move + '" is not in the correct notation.')
-    }
-  }
-
-  if (trax.move !== start) {
-    const result = bot(CLI)
-    CLI.updateGameData()
-    CLI.do('view')
-    if (result === 'lose') {
-      CLI.error('Failed to complete puzzle ' + game.puzzle)
-    } else if (result === 'win') {
-      CLI.out(CLI.color.success('You completed puzzle ' + game.puzzle))
-    } else if (result) {
-      CLI.out(result)
-    }
-  }
-}
-
-tryCmd.fn = (CLI, move) => {
-  if (!move || move.length === 0) {
-    CLI.error('You must provide a move.')
-    return CLI.do('help', 'try')
-  }
-
-  if (!CLI.TRAX) {
-    CLI.do('new')
-  }
-
-  if (CLI.TRAX.over) {
-    return CLI.error('The game is over.')
-  }
-
-  if (notationRx.test(move)) {
-    move = CLI.fixNotation(move)
-    const play = CLI.TRAX.dropTile(move, undefined, 'tentative')
-    if (play.valid || play.dropped.length > 0) {
-      CLI.display(CLI.TRAX, CLI.GAME.players, move)
-    } else {
-      CLI.error('Move is invalid.')
-    }
-  } else {
-    CLI.error('Move is invalid.')
-  }
-}

package/src/cmds/puzzles.js

@@ -1,9 +1,11 @@
 /** @file Puzzles CLI
- * @copyright 2022-2023
+ * @copyright 2022-2026
  * @author Chad Transtrum <chad@transtrum.net>
  * @license Apache-2.0
  */
 
+/** @typedef {import('../cli.js').CLIContext} CLIContext */
+
 import { Trax } from '@slugbugblue/trax'
 import { levels, puzzles, sources } from '@slugbugblue/trax-puzzles'
 
@@ -29,13 +31,50 @@ export const puzzlesCmd = {
     'Practice your skills with puzzles. Use "list" to see the puzzle',
     'categories, or "start" to play a puzzle.',
   ],
+  /** @param {CLIContext} CLI @param {string} [action] @param {string} [id] */
+  fn(CLI, action, id) {
+    action = action?.toLowerCase() ?? 'list'
+    if (startAliases.some((alias) => alias.startsWith(action))) {
+      if (!id) return startNextPuzzle(CLI)
+
+      const puzzle = puzzles.find((p) => p.id === id)
+      if (puzzle) {
+        return startPuzzle(CLI, puzzle)
+      }
+
+      if (validLevels.includes(id)) {
+        return startNextPuzzle(CLI, levels.indexOf(id))
+      }
+
+      const possibles = puzzles.filter((p) => p.id.includes(id))
+      if (possibles.length === 1) {
+        return startPuzzle(CLI, possibles[0])
+      }
+
+      return CLI.error('Could not find puzzle ' + id)
+    }
+
+    if (action) {
+      const x = id || action
+      if (validLevels.includes(x)) return listLevel(CLI, x)
+      if (listAliases.some((alias) => alias.startsWith(x))) {
+        return listPuzzles(CLI)
+      }
+
+      return showPuzzle(CLI, x)
+    }
+
+    listPuzzles(CLI)
+  },
 }
 
+/** @param {string} [word] @returns {string} */
 const an = (word = '') => {
-  const a = /^[aeiou]/.test(word) ? 'an' : 'a'
+  const a = /^[aeiou]/v.test(word) ? 'an' : 'a'
   return a + ' ' + word
 }
 
+/** @param {CLIContext} CLI @param {string} id @param {boolean} [started] */
 const showPuzzle = (CLI, id, started = false) => {
   let puzzle = puzzles.find((p) => p.id === id)
   if (!puzzle) {
@@ -80,6 +119,7 @@ const showPuzzle = (CLI, id, started = false) => {
   )
 }
 
+/** @param {CLIContext} CLI */
 const listPuzzles = (CLI) => {
   let size = 1
   const data = []
@@ -112,6 +152,7 @@ const listPuzzles = (CLI) => {
   }
 }
 
+/** @param {CLIContext} CLI @param {string} levelName */
 const listLevel = (CLI, levelName) => {
   let size = 1
   const level = levels.indexOf(levelName)
@@ -134,55 +175,28 @@ const listLevel = (CLI, levelName) => {
   }
 }
 
+/** @param {CLIContext} CLI @param {import('@slugbugblue/trax-puzzles').Puzzle} puzzle */
 const startPuzzle = (CLI, puzzle) => {
   const id = CLI.newPuzzle(puzzle)
   CLI.out(CLI.color(`Started puzzle ${puzzle.id} as game #${id}`))
   showPuzzle(CLI, puzzle.id, true)
 }
 
+/** @param {CLIContext} CLI @param {number} [level] */
 const startNextPuzzle = (CLI, level) => {
   if (level === undefined) level = CLI.puzzleLevel
-  const unsolved = puzzles.filter((p) => !CLI.puzzle(p.id).solved)
+  const unsolved = puzzles
+    .filter((p) => !CLI.puzzle(p.id).solved)
+    .toSorted(
+      (a, b) =>
+        a.level - b.level ||
+        a.notation.split(' ').length - b.notation.split(' ').length,
+    )
   if (unsolved.length === 0) {
-    CLI.out(CLI.success('You have already completed all the puzzles.'))
+    CLI.out(CLI.color.success('You have already completed all the puzzles.'))
     return CLI.error('Specify a specific puzzle to try one again.')
   }
 
   const next = unsolved.find((p) => p.level >= level) || unsolved[0]
   startPuzzle(CLI, next)
 }
-
-puzzlesCmd.fn = (CLI, action, id) => {
-  action = action?.toLowerCase() ?? 'list'
-  if (startAliases.some((alias) => alias.startsWith(action))) {
-    if (!id) return startNextPuzzle(CLI)
-
-    const puzzle = puzzles.find((p) => p.id === id)
-    if (puzzle) {
-      return startPuzzle(CLI, puzzle)
-    }
-
-    if (validLevels.includes(id)) {
-      return startNextPuzzle(CLI, levels.indexOf(id))
-    }
-
-    const possibles = puzzles.filter((p) => p.id.includes(id))
-    if (possibles.length === 1) {
-      return startPuzzle(CLI, possibles[0])
-    }
-
-    return CLI.error('Could not find puzzle ' + id)
-  }
-
-  if (action) {
-    const x = id || action
-    if (validLevels.includes(x)) return listLevel(CLI, x)
-    if (listAliases.some((alias) => alias.startsWith(x))) {
-      return listPuzzles(CLI)
-    }
-
-    return showPuzzle(CLI, x)
-  }
-
-  listPuzzles(CLI)
-}

package/src/cmds/select.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 select command
+ * @copyright 2022-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// CLI select command
+/** @typedef {import('../cli.js').CLIContext} CLIContext */
 
 export const selectCmd = {
   name: 'select',
@@ -21,27 +12,27 @@ export const selectCmd = {
   args: '#id [command]',
   comp: '<id> <cmd>',
   desc: 'select a different game',
-  rx: /^#\d+$/,
+  rx: /^#\d+$/v,
   help: [
     'Make another game the default game of future commands. If another',
     'command is included, that command will be run immediately.',
   ],
-}
-
-selectCmd.fn = (CLI, id, ...cmds) => {
-  if (!id) {
-    CLI.error('Missing id.')
-    return CLI.do('help', 'select')
-  }
+  /** @param {CLIContext} CLI @param {string} [id] @param {...string} cmds */
+  fn(CLI, id, ...cmds) {
+    if (!id) {
+      CLI.error('Missing id.')
+      return CLI.do('help', 'select')
+    }
 
-  if (id.startsWith('#')) id = id.slice(1)
-  CLI.load(id)
-  if (String(CLI.GAME?.id) === id) {
-    CLI.out(CLI.color(`Game #${id} selected.`))
-    if (cmds.length > 0) {
-      CLI.doNext(cmds.join(' '))
+    if (id.startsWith('#')) id = id.slice(1)
+    CLI.load(id)
+    if (String(CLI.GAME?.id) === id) {
+      CLI.out(CLI.color(`Game #${id} selected.`))
+      if (cmds.length > 0) {
+        CLI.doNext(cmds.join(' '))
+      }
+    } else {
+      CLI.error('Invalid id. Type "list" to see available games.')
     }
-  } else {
-    CLI.error('Invalid id. Type "list" to see available games.')
-  }
+  },
 }