@slugbugblue/trax 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @slugbugblue/trax
 
+## 0.8.0 - 2022-04-08
+
+- Breaking change: `playMove()` now takes the _next_ move number instead of the
+  _last_ move number. It makes more sense to say "move number 1 is @0/" than to
+  say "the move following move number 0 is @0/".
+- Added variant name info to the engine as `Trax.name[rules]` as well as
+  `trax.name`
+- Restructured the repo to handle additional files, creating `src` and `hooks`
+  folders
+- Added a command-line interface (CLI) `cli.js` which npm will install using the
+  alias `trax`
+- The CLI usage is self-documenting; run `trax help` to get started
+- Initial commands available: `delete`, `export`, `help`, `import`, `list`,
+  `new`, `play`, `select`, `try`, `undo`, `view`
+
 ## 0.7.0 - 2022-03-28
 
 - Fixed a bug when including extra characters in a starting notation

package/README.md

@@ -9,7 +9,9 @@ information about Trax, including its rules and history, see the official
 website at [traxgame.com][traxgame].
 
 This goal of this javascript project is to allow Trax to be played
-programmatically. It can be used as an engine in a web browser or in nodejs.
+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.
 
 The Trax engine now enjoys automated testing with 100% code coverage. Any future
 changes to the engine should meet the same standard.
@@ -17,10 +19,81 @@ changes to the engine should meet the same standard.
 ## Installation
 
 ```bash
+# Install into a javascript project
 npm install @slugbugblue/trax
+
+# Or install globally to use the trax CLI
+npm install -g @slugbugblue/trax
+```
+
+## CLI Usage
+
+The command-line interface is provided as `trax`, available in your path if
+installed globally, or in the `node_modules/.bin` directory and runnable using
+`npx trax` if installed locally.
+
+The CLI can be used interactively by passing the `--interactive` or `-i` flag.
+When run interactively, you can 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 `#`.
+
+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
+to be the most common command used, you can simply omit the command name. For
+example, at the interactive prompt, entering `@0/` is the same as if you had
+entered `play 1. @0/`.
+
+Multiple games can be started at once, and the CLI will remember the currently
+active game and apply future actions to that game. Each game will retain its
+`#id` number until it is deleted, and you can use that number to switch between
+games. For example, to make game #1 active, enter `select 1` or `select #1` or
+simply `#1` at the interactive prompt.
+
+For ease of working at the command line, the symbols used as the last character
+of the Trax notation can optionally be replaced with letters. Use `s` for slash
+symbol (`/`), `b` for backslash (`\`), and `p` for plus (`+`). While there is no
+need to escape at the interactive prompt, these substitutions will be avilable
+there as well.
+
+The CLI uses standard Windows and Linux [XDG][xdg] file locations as provided by
+the [env-paths library][env-path], with current uses being the `config` and
+`data` folders.
+
+Examples:
+
+```text
+# Start a new Trax game with Chad playing as white
+> trax new Chad vs
+
+# Start a new Loop Trax game with Chad playing as black
+> trax new loop vs Chad
+
+# Start a new 8x8 Trax game with Chad as white and Another Player as black
+> trax new 8x8 Chad vs Another Player
+
+# Switch back to the first game. Note the quoting required at the command line.
+# This would not be necessary when running at the interactive prompt.
+> trax '#1'
+
+# Play two moves, using full notation
+> trax play 1. @0/ 2. A0/
+
+# Two more moves, using short notation and symbol substitution
+# B2/ => b2s and A0\ => a0b
+> trax b2s a0b
+
+# See the status of all games
+> trax ls
 ```
 
-## Usage
+## API Usage
 
 The main Trax engine is provided as `engine.js`, which can be used as follows:
 
@@ -46,8 +119,8 @@ For specifics, see the [engine.js documentation][engine-docs].
 
 ## Roadmap
 
-- Command line interface
-- Bot for solo games (?)
+- Game position analysis
+- Bot
 - Puzzles
 
 ## Support
@@ -103,8 +176,11 @@ David Smith and heirs, and are not to be used without permission.
 [ctrans]: mailto:chad@transtrum.net
 [dgb]: mailto:donald@traxgame.com
 [engine-docs]: docs/engine.md
+[env-path]: https://www.npmjs.com/package/env-paths
 [goldtoken]: https://goldtoken.com/
 [repo]: https://gitlab.com/slugbugblue/trax
 [sbb]: https://slugbugblue.com/
 [traxbook]: http://traxgame.com/shop_book.php
 [traxgame]: http://traxgame.com/
+[xdg]:
+  https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

package/docs/engine.md

@@ -35,7 +35,9 @@ class properties and methods:
 
 - `Trax.variants`: a Set of the different rule sets the engine supports. Try
   `Trax.variants.has(rule)` to see if your favorite rule set is supported. Or
-  `Trax.variants.forEach(s => { console.log(t) })` to list them all.
+  `Trax.variants.forEach((rule) => { console.log(rule) })` to list them all.
+
+- `Trax.names`: an object of variant rule set names to English names.
 
 - `Trax.point(x, y)`: quick access to the [Point class][point-docs], for
   two-dimensional locations used internally by the Trax engine and which are
@@ -121,6 +123,8 @@ unpredictable and invalid operations by the engine.
 
 #### calculated properties
 
+- `name`: string, a shortcut to get the actual name of the game from its variant
+  rule set code
 - `count`: number, the total number of tiles currently in play
 - `color`: string, the color (`'w'` or `'b'`) of the player whose turn it is
 - `gameOver`: boolean, `true` if the game is over
@@ -166,14 +170,25 @@ each move that can be played will be legal.
 Attempts to play the given `notation`. Updates the game instance if the notation
 is valid for the current position.
 
-##### `playMove(currentMoveNumber, nextMoveNotation)`
+Returns an object with at minimum the following key/value pair:
+
+- `valid`: `true` if the move is valid and results in a legal position
+
+If the move is valid, the following will also be part of the returned object:
+
+- `dropped`: a list of the tiles that were played by this move
+- `notation`: the resulting notation of the move
+
+##### `playMove(moveNumber, notation)`
 
 Used to play a move, but with an extra safeguard around the status of the game
 so that if this is called multiple times with the same values, it will ignore
 subsequent calls, which can be useful in the context of asynchronous
 communication and retries, such as when this engine is being used as the back
 end of a web interface. For example, if no moves have been made yet in a game,
-this can be called either as `playMove(0, '@0/')` or `playMove(0, '@0+')`.
+this can be called either as `playMove(1, '@0/')` or `playMove(1, '@0+')`.
+
+Returns the same object structure as the `play()` method.
 
 ##### `provisionalMove(from, to, via)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",
@@ -11,12 +11,15 @@
   "bugs": "https://gitlab.com/slugbugblue/trax/issues",
   "license": "Apache-2.0",
   "author": "Chad Transtrum <chad@transtrum.net>",
-  "exports": "./engine.js",
+  "exports": "./src/engine.js",
   "repository": "gitlab:slugbugblue/trax",
+  "bin": {
+    "trax": "./src/cli.js"
+  },
   "scripts": {
     "test": "xo && c8 ava",
     "preversion": "npm test",
-    "postversion": "git push && git push --tags"
+    "postversion": "hooks/postversion.sh src/version.js"
   },
   "dependencies": {
     "env-paths": "^3.0.0",
@@ -26,6 +29,7 @@
   "devDependencies": {
     "ava": "^4.1.0",
     "c8": "^7.11.0",
+    "genversion": "^3.0.2",
     "prettier": "^2.6.1",
     "xo": "^0.48.0"
   },