@slugbugblue/trax-cli 0.12.1 → 0.14.0

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,86 @@ 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.
+ * First checks position-code keys (exact board-state match, O(1)), then
+ * falls back to wildcard notation keys for paths containing '*'.
+ * @param {import('@slugbugblue/trax-puzzles').Defense} defense
+ * @param {string} positionCode
+ * @param {string[]} moves
+ * @returns {string | undefined}
+ */
+const getDefenseMove = (defense, positionCode, moves) => {
+  if (Object.hasOwn(defense, positionCode)) return defense[positionCode]
+  const key = Object.keys(defense)
+    .filter((k) => k.includes('*'))
+    .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 +185,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 +194,22 @@ 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.positionCode(),
+          trax.moves.slice(offset),
+        )
+      }
+    }
+
+    move ??= suggest(trax)?.pick?.move
+
     const ms = Date.now() - start
     if (move) {
       CLI.out(
@@ -87,89 +224,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.')
-  }
+  },
 }

package/src/cmds/suggest.js

@@ -1,19 +1,10 @@
-/* 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 suggest command
+ * @copyright 2022-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// CLI suggest command
+/** @typedef {import('../cli.js').CLIContext} CLIContext */
 
 import { suggest } from '@slugbugblue/trax-analyst'
 import { timeString } from '@slugbugblue/trax-cli/utils'
@@ -23,33 +14,33 @@ export const suggestCmd = {
   alt: ['bot'],
   desc: 'suggest a move',
   help: ['Suggest a move in the current game.'],
-}
+  /** @param {CLIContext} CLI @param {string} [debug] */
+  fn(CLI, debug) {
+    if (!String(CLI.GAME?.id)) {
+      return CLI.error('No active game. Type "new" to start a game.')
+    }
 
-suggestCmd.fn = (CLI, debug) => {
-  if (!String(CLI.GAME?.id)) {
-    return CLI.error('No active game. Type "new" to start a game.')
-  }
+    const game = CLI.TRAX
+    const suggestion = suggest(game)
 
-  const game = CLI.TRAX
-  const suggestion = suggest(game)
+    if (!suggestion.best) return
 
-  if (!suggestion.best) return
+    CLI.out(
+      CLI.bubble(
+        game.turn === 1 ? 'w' : 'b',
+        String(game.move + 1) + '. ' + suggestion.pick.move,
+      ),
+    )
 
-  CLI.out(
-    CLI.bubble(
-      game.turn === 1 ? 'w' : 'b',
-      String(game.move + 1) + '. ' + suggestion.pick.move,
-    ),
-  )
+    if (debug && 'debug'.startsWith(debug)) {
+      const m = []
+      for (const move of suggestion.options) {
+        m.push(move.move + ' ' + move.score)
+      }
 
-  if ('debug'.startsWith(debug)) {
-    const m = []
-    for (const move of suggestion.options) {
-      m.push(move.move + ' ' + move.score)
+      CLI.out(
+        '[' + m.join(', ') + '] ' + CLI.color.black(timeString(suggestion.ms)),
+      )
     }
-
-    CLI.out(
-      '[' + m.join(', ') + '] ' + CLI.color.black(timeString(suggestion.ms)),
-    )
-  }
+  },
 }

package/src/cmds/undo.js

@@ -1,19 +1,12 @@
-/* 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 undo command
+ * @copyright 2022-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// CLI undo command
+/** @typedef {import('../cli.js').CLIContext} CLIContext */
+
+import { puzzles } from '@slugbugblue/trax-puzzles'
 
 export const undoCmd = {
   name: 'undo',
@@ -24,17 +17,29 @@ export const undoCmd = {
     'Backtrack one or more moves in a game. Type "undo" to take back the last',
     'move, or "undo 2" to undo the last two moves.',
   ],
-}
-
-undoCmd.fn = (CLI, n) => {
-  n = Math.max(1, Math.floor(Number(n) || 1)) // Get an integer 1 or higher
+  /** @param {CLIContext} CLI @param {string} [n] */
+  fn(CLI, n) {
+    const count = Math.max(1, Math.floor(Number(n) || 1))
+    const { moves } = CLI.TRAX
 
-  const { moves } = CLI.TRAX
-  const undo = moves.slice(0, 0 - n)
-  if (moves.length === undo.length) {
-    CLI.error('Unable to undo.')
-  } else {
-    CLI.setGame(undo)
-    CLI.do('view')
-  }
+    if (CLI.GAME?.puzzle) {
+      const puzzle = puzzles.find((p) => p.id === CLI.GAME.puzzle)
+      const offset = puzzle ? puzzle.notation.split(' ').length : 0
+      const undoTo = Math.max(offset, moves.length - count * 2)
+      if (undoTo === moves.length) {
+        CLI.error('Cannot undo before the start of the puzzle.')
+      } else {
+        CLI.setGame(moves.slice(0, undoTo))
+        CLI.do('view')
+      }
+    } else {
+      const undo = moves.slice(0, 0 - count)
+      if (moves.length === undo.length) {
+        CLI.error('Unable to undo.')
+      } else {
+        CLI.setGame(undo)
+        CLI.do('view')
+      }
+    }
+  },
 }