@slugbugblue/trax 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @slugbugblue/trax
 
+## 0.17.0 - 2022-12-29
+
+- The `import` CLI command now loads comments from a .trx file
+
+## 0.16.0 - 2022-12-27
+
+- Added a `notes` command to the CLI to add comments to a game
+
+  - all comments are included in the output generated by the `export` command
+  - the latest comment can be used as a text filter by the `list` command
+  - the latest comment is displayed by the `view` and `list` commands
+
+- Minor analysis improvements
+
 ## 0.15.0 - 2022-12-14
 
 - Added shared `puzzles` commands to the CLI:

package/README.md

@@ -13,7 +13,7 @@ Trax is a two-player boardless board game invented by David Smith. For more
 information about Trax, including its [rules][traxrules] and
 [history][traxhistory], see the official website at [traxgame.com][traxgame].
 
-This goal of this javascript project is to allow Trax to be played
+The goal of this javascript project is to allow Trax to be played
 programmatically. It can be used as an engine in a web browser, for example at
 [slugbugblue.com][sbb]; or in nodejs, for example by using the `trax` CLI
 provided as part of this project.
@@ -27,7 +27,7 @@ changes to the engine should meet the same standard.
 # Install into a javascript project
 npm install @slugbugblue/trax
 
-# Or install globally to use the trax CLI
+# Or install globally to use the trax CLI more easily
 npm install -g @slugbugblue/trax
 ```
 
@@ -43,11 +43,12 @@ avoid worries about the need to escape certain characters from the shell, and it
 can be easier to run multiple commands back to back.
 
 Help is available for the CLI through the use of the `help` command. Type
-`trax help` to see a list of the available commands, and `trax help play` to see
-information about the `play` command. Aliases and abbreviations are provided to
-minimize typing and to try to avoid the requirement of memorizing the commands.
-For example, the `list` command has an alias of `ls`, and the `select` command
-can be activated using `#`.
+`trax help` (or `npx trax help` with a local installation, or simply `help` if
+run interactively) to see a list of the available commands, and `trax help play`
+to see information about the `play` command. Aliases and abbreviations are
+provided to minimize typing and to try to avoid the requirement of memorizing
+the commands. For example, the `list` command has an alias of `ls`, and the
+`select` command can be activated using `#`.
 
 When you first launch the CLI, you can create a new game using the `new`
 command, and then enter moves for that game using `play`. Since `play` is likely

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",

package/src/analyst.js

@@ -379,7 +379,7 @@ export const Analysis = class {
       const calcLevel = level > 0 && defending ? level + threatLevel - 1 : level
       let points = attackScore(inactive, level, calc ? calcLevel : 0)
       if (level === threatLevel) points = passive ? Math.floor(points / 2) : 0
-      if (threatening) points = Math.floor(points / 2)
+      if (passive && threatening) points = Math.floor(points / 2)
       score += points
     }
 

package/src/cli.js

@@ -38,6 +38,7 @@ import {
 } 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'
@@ -87,6 +88,7 @@ const plugins = [
   importCmd,
   listCmd,
   newCmd,
+  notesCmd,
   playCmd,
   puzzlesCmd,
   quitCmd,
@@ -197,14 +199,6 @@ const DATA = { games: {}, puzzles: {} }
 
 // CLI context object for plugins
 const CLI = {
-  // Notation manipulation
-  fixNotation(move) {
-    if (move.endsWith('b')) return move.slice(0, -1) + '\\'
-    if (move.endsWith('s')) return move.slice(0, -1) + '/'
-    if (move.endsWith('p')) return move.slice(0, -1) + '+'
-    return move
-  },
-
   // Quick access to all stored games
   get GAMES() {
     return DATA.games || {}
@@ -283,6 +277,28 @@ const CLI = {
     CLI.out(CLI.color.error(text))
   },
 
+  // Notation manipulation
+  fixNotation(move) {
+    if (move.endsWith('b')) return move.slice(0, -1) + '\\'
+    if (move.endsWith('s')) return move.slice(0, -1) + '/'
+    if (move.endsWith('p')) return move.slice(0, -1) + '+'
+    return move
+  },
+
+  load(id) {
+    if (!id) id = Object.keys(DATA.games || {})[0]
+    if (id && DATA.games?.[id] && DATA.games[id].rules) {
+      if (id !== String(CONFIG.id)) {
+        CONFIG.id = id
+        saveConfig()
+      }
+
+      const game = CLI.GAME
+      if (!game.players) game.players = ['white', 'black']
+      CLI.TRAX = new Trax(game.rules, game.moves, 'cli')
+    }
+  },
+
   newGame(rules, players, moves) {
     // Creates a new game
     const id = newId(DATA)
@@ -367,6 +383,11 @@ const CLI = {
     return undefined
   },
 
+  /** Write out the current data to disk. */
+  save() {
+    saveData()
+  },
+
   setGame(moves) {
     // Updates the moves for the current game
     const game = CLI.GAME
@@ -390,20 +411,6 @@ const CLI = {
     }
   },
 
-  load(id) {
-    if (!id) id = Object.keys(DATA.games || {})[0]
-    if (id && DATA.games?.[id] && DATA.games[id].rules) {
-      if (id !== String(CONFIG.id)) {
-        CONFIG.id = id
-        saveConfig()
-      }
-
-      const game = CLI.GAME
-      if (!game.players) game.players = ['white', 'black']
-      CLI.TRAX = new Trax(game.rules, game.moves, 'cli')
-    }
-  },
-
   // Pass through functions
   bubble: tty.bubble,
   display: tty.display,

package/src/cmds/import-export.js

@@ -137,6 +137,79 @@ export const exportCmd = {
   ],
 }
 
+/** Interpret the rules string of a .trx file.
+ * @arg {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
+ */
+const interpretFile = (CLI, content) => {
+  let rules
+  let trax
+  let players = []
+  const moves = []
+  const comments = []
+  for (const line of content.split('\n')) {
+    if (!line) continue
+    const [ln, ...comment] = line.split(/[#;]/)
+    if (ln) {
+      const lower = ln.toLowerCase()
+      if (!rules && lower.includes('trax')) {
+        rules = getRules(lower)
+      } else if (players.length === 0 && lower.includes(' vs ')) {
+        players = ln.split(' ').filter(Boolean)
+      } else {
+        moves.push(...ln.split(' '))
+      }
+    }
+
+    if (!trax && rules && (players.length > 0 || moves.length > 0)) {
+      trax = new Trax(rules)
+    }
+
+    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, moves.length)
+      }
+    }
+
+    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,
+        })
+      }
+    }
+  }
+
+  if (!trax) return false
+
+  CLI.do('new', rules, ...players)
+  CLI.GAMES[String(CLI.GAME.id)].notes = comments
+  if (trax.moves.length > 0) {
+    CLI.do('play', ...trax.moves)
+  } else {
+    CLI.save()
+  }
+
+  return true
+}
+
 importCmd.fn = async (CLI, filename) => {
   cli = CLI
   if (!filename) {
@@ -156,36 +229,74 @@ importCmd.fn = async (CLI, filename) => {
       }
     }
 
-    if (!content) CLI.error(fsError.toString())
+    if (!content) return CLI.error(fsError.toString())
   }
 
-  if (content) {
-    let game
-    let players = []
-    const moves = []
-    for (const line of content.split('\n')) {
-      if (!line) continue
-      const ln = line.split(/[#;]/)[0]
-      if (!ln) continue
-      const lower = ln.toLowerCase()
-      if (!game && lower.includes('trax')) {
-        game = 'trax'
-        if (lower.includes('loop')) game = 'traxloop'
-        if (lower.includes('8x8')) game = 'trax8'
-      } else if (players.length === 0 && lower.includes(' vs ')) {
-        players = ln.split(' ').filter(Boolean)
-      } else {
-        moves.push(...ln.split(' '))
-      }
+  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
+ * @returns {string} - Notes formatted for this move, or empty string if none
+ */
+const gameNotes = (move, notes) => {
+  notes = notes || []
+  const moveNotes = notes.filter((n) => n.move === move)
+  if (moveNotes.length === 0) return ''
+  return (
+    '; ' +
+    moveNotes.map((n) => n.note.replaceAll('\n', '\n; ')).join('\n; ') +
+    '\n'
+  )
+}
+
+/** 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
+ * @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
+ * @returns {string} - A string that can be placed into an export file
+ */
+const interleaveNotation = (moves, notes) => {
+  let content = ''
+  let moveNumber = 0
+  let annotation = ''
+  for (const move of moves) {
+    const comments = gameNotes(moveNumber, notes)
+    if (comments) {
+      content += join(annotation, comments)
+      annotation = ''
     }
 
-    if (game) {
-      CLI.do('new', game, ...players)
-      CLI.do('play', ...moves.filter(Boolean))
+    moveNumber += 1
+    const notation = String(moveNumber) + '. ' + move
+    if (annotation.length + notation.length < 79) {
+      annotation += (annotation.length > 0 ? ' ' : '') + notation
     } else {
-      CLI.error(filename + ' does not appear to be formatted correctly.')
+      content += '\n' + annotation
+      annotation = notation
     }
   }
+
+  const comments = gameNotes(moveNumber, notes)
+  if (comments) {
+    content += join(annotation, comments)
+    annotation = ''
+  }
+
+  content += annotation
+  if (!content.endsWith('\n')) content += '\n'
+  return content
 }
 
 exportCmd.fn = (CLI, id, filename) => {
@@ -218,7 +329,7 @@ exportCmd.fn = (CLI, id, filename) => {
       content += '; Puzzle ' + game.puzzle
       if (source) {
         content += ' provided courtesy of ' + source.name
-        if (source.url) content += ' (' + source.url + ')'
+        if (source.url) content += '\n; ' + source.url
       }
 
       if (puzzle.title) content += '\n; ' + puzzle.title
@@ -230,7 +341,8 @@ exportCmd.fn = (CLI, id, filename) => {
     }
   }
 
-  content += trax.notation + '\n'
+  content += interleaveNotation(trax.moves, game.notes)
+
   if (filename) filename = filename.replace(/[^ a-z\d.~/]/g, '')
   if (filename) {
     const fname = filename.split('/').pop()

package/src/cmds/list.js

@@ -15,6 +15,8 @@
 
 // CLI list command
 
+import process from 'node:process'
+
 import { Trax } from '@slugbugblue/trax'
 
 export const listCmd = {
@@ -35,7 +37,7 @@ export const listCmd = {
     '  #id: match a game or a certain number of moves',
     '  "active" or "over": whether a game is in progress or not',
     '  "loop" or "8x8" or "trax": filter by game type',
-    "  <other text>: match a player's name",
+    "  <other text>: match a player's name or the latest game note",
     'Add the "reverse" option to reverse the sort order.',
   ],
 }
@@ -80,14 +82,16 @@ const listSort = (list, filters) => {
     } else if (['over', 'active'].includes(by)) {
       list = list.filter((g) => (by === 'over' ? g.over : !g.over))
     } else {
-      list = list.filter(
-        (g) =>
+      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.moves.startsWith(by + ' ') ||
+          g.note.includes(by)
+        )
+      })
     }
   }
 
@@ -96,6 +100,19 @@ 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
+ */
+const leftover = (sizes) => {
+  let left = process.stdout.columns
+  for (const size of Object.values(sizes)) {
+    left -= size
+  }
+
+  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.')
@@ -106,12 +123,14 @@ listCmd.fn = (CLI, ...filters) => {
 
   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
@@ -120,13 +139,14 @@ listCmd.fn = (CLI, ...filters) => {
       id: (game.id === CLI.GAME.id ? '* #' : '#') + String(game.id),
       name: game.name?.length || 0,
       rules: game.rules,
-      moves: CLI.plural(moves, 'move'),
+      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 || '',
     })
   }
 
@@ -138,6 +158,7 @@ listCmd.fn = (CLI, ...filters) => {
     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) {
@@ -149,7 +170,8 @@ listCmd.fn = (CLI, ...filters) => {
         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.over ? 'game over' : game.moves),
+        CLI.color(game.moves.padEnd(size.moves)) +
+        CLI.color.help(' ' + game.note.slice(0, noteSize)),
     )
   }
 }

package/src/cmds/notes.js

@@ -0,0 +1,34 @@
+/** Notes CLI command.
+ * @copyright 2022
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
+ */
+
+export const notesCmd = {
+  name: 'notes',
+  args: '[#id] <text>',
+  desc: 'add a note to a game',
+  help: [
+    '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)
+  if (!id) id = current
+  if (!/^#?\d+$/.test(id)) {
+    note.unshift(id)
+    id = current
+  }
+
+  if (id.startsWith('#')) id = id.slice(1)
+
+  const game = CLI.GAMES[id]
+  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()
+}

package/src/cmds/play-try.js

@@ -142,7 +142,7 @@ playCmd.fn = (CLI, ...moves) => {
 }
 
 tryCmd.fn = (CLI, move) => {
-  if (move.length === 0) {
+  if (!move || move.length === 0) {
     CLI.error('You must provide a move.')
     return CLI.do('help', 'try')
   }

package/src/cmds/view.js

@@ -39,7 +39,10 @@ viewCmd.fn = (CLI, move) => {
     show = Number(move)
   }
 
-  const players = CLI.GAME.players || ['white', 'black']
+  const game = CLI.GAME
+  const players = game.players || ['white', 'black']
+  const puzzle = game.puzzle || ''
+  const { note } = [...(game.notes || [{}])].pop()
 
   CLI.out(
     CLI.color('#' + CLI.ID + ' ') +
@@ -50,4 +53,6 @@ viewCmd.fn = (CLI, move) => {
       CLI.bubble('b' + (trax.turn === 2 ? 'h' : ''), players[1]),
   )
   CLI.display(trax, players, undefined, show)
+  if (puzzle) CLI.out(CLI.color('Puzzle ' + puzzle))
+  if (note) CLI.out(CLI.color.help(note))
 }

package/src/engine.js

@@ -617,7 +617,7 @@ export const Trax = class {
     return this.notation
       .replace(/\n/g, ' ')
       .split(' ')
-      .filter((n) => !n.endsWith('.'))
+      .filter((n) => Boolean(n) && !n.endsWith('.'))
   }
 
   /** Drop a tile onto the board. This is a lower level call. Use play() if possible instead.

package/src/threats.js

@@ -198,4 +198,5 @@ for (const one of Object.keys(corners)) {
 threats.add(3, 'ralbmrW') // Attack into a wide cave
 threats.add(3, 'Arlbmwr') // Reversed
 
+threats.add(4, 'rb¡c?w!br') // Connectable pair on an edge
 threats.add(4, 'ArlbmrW') // Wide cave ready for an attack

package/src/types.d.ts

@@ -62,6 +62,15 @@ type FoundThreats = Record<string, FoundThreat[]>
 /** All the threats found for both the white and black player. */
 type FoundThreatsCollection = { b: ColorThreats; w: ColorThreats }
 
+/** A note with a move number */
+type GameNote = {
+  move: number
+  note: string
+}
+
+/** Notes saved in the game object in the CLI. */
+type GameNotes = GameNote[]
+
 /** A point-like object has numerical x and y properties. */
 type PointLike = {
   x: number

package/src/version.js

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '0.15.0'
+export const version = '0.17.0'