blunderdb

command module

v0.0.0-...-faa641b Latest Latest Go to latest Published: Oct 26, 2026 License: MIT Imports: 21 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/kevung/blunderdb

README ¶

blunderDB

A backgammon blunder analysis tool. Import your matches from eXtreme Gammon, GnuBG and BGBlitz, store every position once, search them by structure and by mistake, measure your play, and study the positions you keep getting wrong — with an evaluator built in.

Documentation, in nine languages: https://kevung.github.io/blunderDB/

Features

A library of positions

Import matches from eXtreme Gammon (.xg, .xgp), GnuBG (.sgf), BGBlitz (.bgf) and Jellyfish (.mat), by file, by folder or by drag-and-drop. Positions are deduplicated across imports; imported analyses, comments, luck and XG flags travel with them.
Search by checker structure (including an except structure), pip count, score, cube, dice, equity and error thresholds, contact/no-contact, comments, flags, player, match or tournament. Every filter has a command-line token, and filter sets can be saved as a library.
Collections and tournaments to organise positions and matches; match navigation with the played move highlighted.
Export a match to Jellyfish/GnuBG .mat to replay it in another program; export positions, or selected parts of a database.

Measuring and studying

Stats panel, four tabs: Dashboard (PR, Snowie error rate, MWC cost, rolling PR, top blunders), Progression (per tournament and per match), Errors (checker vs. cube, direction of cube errors, magnitude histogram) and Players, which compares every player in the database (record, PR, error rate, blunders, luck). Indicators are aligned on XG and GnuBG, and each one drills down to the positions behind it.
Spaced repetition (Anki-style, FSRS scheduler) with study and cram modes, forecasts and parameter optimisation.
Eval panel with an embedded evaluator: gammonNet, ported to Go and compiled into the binary, evaluates any position offline — neural network, 0- to 2-ply search, Janowski cube decisions, match-aware search. The panel shows the facts of the position (win, gammon and backgammon chances, equity) and the one decision the board asks; match equities are normalised, and "too good to double" is a verdict you actually see. Races run in three regimes: exact from a two-sided bearoff table (up to 6 checkers embedded, up to 11 with an optional 1.2 GB download), evaluated by gammonNet beyond it, and estimated — a win probability with an error bound, never a cube verdict. A challenge mode hides the numbers until you click.
Batch analysis fills the positions that have no analysis, after an import or across an existing library (blunderdb analyze), without ever overwriting an imported analysis.

Eval panel (gammonNet)	Stats dashboard

Sharing a database

Origin watermark: a signed mark, verified on open, that says what a file is and where it came from — and records nothing on the recipient's side.
Password protection: an encrypted .dbx container (AES-256-GCM, Argon2id) with a readable header.

One binary, five modes, dispatched on the first argument:

Mode	Purpose
(no argument)	Desktop app (Wails: Go backend, Svelte frontend) — Linux, macOS, Windows
`create`, `import`, `export`, `search`, `list`, `edit`, `match`, `epc`, `analyze`, `vacuum`, `verify`, `identity`, `info`, …	Command-line interface over the same database — see CLI_USAGE.md
`serve`	Headless HTTP + JSON daemon on SQLite or multi-tenant PostgreSQL, meant to run behind an authenticating reverse proxy — see doc/source/mode_headless.rst
`migrate`	Copy a SQLite database into PostgreSQL under a tenant
`call`	Generic in-process dispatcher over the daemon's handlers, for scripting and tests

The interface is available in English, French, German, Italian, Spanish, Finnish, Japanese, Greek and Russian.

Installation

Every asset on the Releases page comes with a .sha256 file (or the consolidated SHA256SUMS); verify with sha256sum -c. Every asset also carries a build-provenance attestation, verifiable with gh attestation verify <asset> --repo kevung/blunderDB — no key to manage. A minisign signature over SHA256SUMS is opt-in and not yet enabled; see packaging/minisign/.

Platform	How
Debian, Ubuntu, Mint	`sudo apt install ./blunderdb_x.y.z_amd64.deb`
Fedora, openSUSE	`sudo dnf install ./blunderdb-x.y.z.x86_64.rpm`
Arch Linux	`yay -S blunderdb-bin` (AUR, updated on each release)
Any Linux with Flatpak	`flatpak install ./blunderDB-x.y.z.flatpak` (bundle attached to each release; not on Flathub yet)
Other Linux	`.tar.gz` or raw binary — `webkit2gtk-4.1` build for current distributions, `webkit2gtk-4.0` build for Ubuntu 22.04-era systems
macOS	Universal `.app` (unsigned — see the security appendix in the docs)
Windows	`.exe` (unsigned — see the security appendix in the docs)
Server (`serve` mode)	`docker pull ghcr.io/kevung/blunderdb-serve:x.y.z` (amd64 and arm64; also builds from `Dockerfile.serve`)

winget and Homebrew are not published yet: each release ships the rendered manifests (blunderDB-winget-manifests-x.y.z.zip, blunderdb-x.y.z.rb) — see packaging/winget/ and packaging/homebrew/ for the submission steps.

The full guide, per system and in nine languages: Download and install.

Build from source

Prerequisites: Go 1.27 (go.mod requires 1.26.0 at least), Node.js 22, Wails v2 CLI 2.15.

go install github.com/wailsapp/wails/v2/cmd/wails@v2.17.0
git clone https://github.com/kevung/blunderDB.git
cd blunderDB
make build            # wails build -tags webkit2_41 → build/bin/blunderDB
make dev              # hot-reload development build

make build targets webkit2gtk-4.1; plain wails build targets webkit2gtk-4.0. The daemon alone builds without Wails or CGO: go build ./cmd/serve.

Usage

./blunderDB                                                    # desktop app
./blunderDB import  --db my.db --type match --file game.xg      # import a match
./blunderDB search  --db my.db --error-min 0.05                 # search by error
./blunderDB list    --db my.db --type players                   # players table
./blunderDB analyze --db my.db                                  # fill missing analyses
./blunderDB serve   --db my.db --addr 127.0.0.1:8080            # headless daemon

In the desktop app, open or create a .db file, then import match files via the toolbar or drag-and-drop.

Tech stack

Layer	Technology
Backend	Go · pure-Go SQLite (modernc.org/sqlite) · PostgreSQL (server mode)
Evaluator	gammonNet ported to Go · GnuBG bearoff tables (one-sided and two-sided)
Frontend	Svelte 5 · Vite · two.js (board rendering)
Framework	Wails v2 (Go ↔ WebView bridge)
Docs	Sphinx, 9 languages (French source + 8 gettext translations)

Community

Discord: https://discord.gg/DA5PpzM9En — questions, feedback, a position to discuss, the quickest way to reach the author.
GitHub Discussions: https://github.com/kevung/blunderDB/discussions — release announcements and longer threads.
Issues: bugs and feature requests, with the match file that reproduces them. A security problem goes through SECURITY.md instead.

Everyone taking part is bound by the code of conduct.

Contributing

Contributions are welcome — see CONTRIBUTING.md: prerequisites, make check (everything CI enforces), the worktree workflow, and the two documentation rules — a user-visible change ships with its French documentation in the same branch, and a modified .rst ships with its eight .po in the same commit. ARCHITECTURE.md is a diagram-first tour of the system; the invariants that tests do not catch are listed in CLAUDE.md; design decisions are recorded in docs/adr/.

License

MIT

Documentation ¶

Overview ¶

Command blunderdb is the single binary for every mode this project ships: with no arguments it launches the Wails desktop GUI (internal/gui); its first argument otherwise selects `serve` (the headless HTTP+JSON daemon, internal/server), `migrate` (copy a SQLite database into PostgreSQL under a tenant, pkg/blunderdb/migrate), or a CLI subcommand (internal/cli, dispatched through cli.IsCommand against the single handlers() table it owns — never duplicate that list here). The GUI build embeds frontend/dist (go:embed all:frontend/dist) and the app icon; cmd/serve is the sibling entrypoint that builds the daemon alone, without Wails or the embedded frontend, for the container image.

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
blunderdb-loadtest command Command blunderdb-loadtest is a self-contained HTTP load generator for a running `blunderdb serve` daemon: it drives /v1/* with a scenario mix across many tenants and writes a JSON + Markdown latency report.	Command blunderdb-loadtest is a self-contained HTTP load generator for a running `blunderdb serve` daemon: it drives /v1/* with a scenario mix across many tenants and writes a JSON + Markdown latency report.
blunderdb-synthdb command Command blunderdb-synthdb builds a SQLite database of synthetic matches for scale benchmarks: no committed fixture comes near the million positions an imported corpus reaches, and the search, stats and listing paths only show their cost at that size.	Command blunderdb-synthdb builds a SQLite database of synthetic matches for scale benchmarks: no committed fixture comes near the million positions an imported corpus reaches, and the search, stats and listing paths only show their cost at that size.
calibrace command Command calibrace calibrates the win-probability correction of pkg/blunderdb/engine/race against a TS-06-11 two-sided bearoff oracle (the bearoff-data-1 release asset; never committed to git).	Command calibrace calibrates the win-probability correction of pkg/blunderdb/engine/race against a TS-06-11 two-sided bearoff oracle (the bearoff-data-1 release asset; never committed to git).
cli-doc-gen command Command cli-doc-gen captures every CLI subcommand's `--help` into CLI_USAGE.md between the generated markers; the hand-written prose above is untouched.	Command cli-doc-gen captures every CLI subcommand's `--help` into CLI_USAGE.md between the generated markers; the hand-written prose above is untouched.
extract_gnubg_stats command extract_gnubg_stats parses GS tags from a gnuBG SGF file and prints aggregated per-player statistics as JSON.	extract_gnubg_stats parses GS tags from a gnuBG SGF file and prints aggregated per-player statistics as JSON.
help-gen command Command help-gen builds the in-app help bundles (frontend/public/help/*.bin) from the documentation that already states the same facts.	Command help-gen builds the in-app help bundles (frontend/public/help/*.bin) from the documentation that already states the same facts.
likecorpus command Command likecorpus produces the human-judged corpus for `like`: N targets drawn from a real library, their k nearest neighbours, and a column for a player to write "same problem: yes / no" in.	Command likecorpus produces the human-judged corpus for `like`: N targets drawn from a real library, their k nearest neighbours, and a column for a player to write "same problem: yes / no" in.
openapi-gen command Command openapi-gen regenerates openapi.yaml, doc/source/api_reference.rst and clients/python/blunderdb/_generated.py from internal/server's route table (see internal/server/openapigen).	Command openapi-gen regenerates openapi.yaml, doc/source/api_reference.rst and clients/python/blunderdb/_generated.py from internal/server's route table (see internal/server/openapigen).
openingbook-gen command Command openingbook-gen computes the book of the first two moves at a match score (pkg/blunderdb/openingbook) and compiles it into the file the binary embeds.	Command openingbook-gen computes the book of the first two moves at a match score (pkg/blunderdb/openingbook) and compiles it into the file the binary embeds.
serve command Command serve is the headless entrypoint of the blunderDB engine.	Command serve is the headless entrypoint of the blunderDB engine.
train-analysis-dict command train-analysis-dict regenerates the zstd dictionary embedded at pkg/blunderdb/engine/analysis_bin_dict.bin (ADR-0030, ADR-0070); a dev-time tool.	train-analysis-dict regenerates the zstd dictionary embedded at pkg/blunderdb/engine/analysis_bin_dict.bin (ADR-0030, ADR-0070); a dev-time tool.
internal
applog Package applog is the desktop GUI's on-disk log file: location and size-based rotation.	Package applog is the desktop GUI's on-disk log file: location and size-based rotation.
cli Package cli implements the blunderDB command-line interface, one `blunderdb <command>` per file (cli_<cmd>.go).	Package cli implements the blunderDB command-line interface, one `blunderdb <command>` per file (cli_<cmd>.go).
cputime Package cputime reads the processor time the current process has consumed, for the tests that guard a cost.	Package cputime reads the processor time the current process has consumed, for the tests that guard a cost.
gui Package gui is the Wails desktop application: the bound App struct the frontend calls through wailsjs, and Run (run.go), the bootstrap.	Package gui is the Wails desktop application: the bound App struct the frontend calls through wailsjs, and Run (run.go), the bootstrap.
server Package server implements the `blunderdb serve` HTTP + JSON daemon.	Package server implements the `blunderdb serve` HTTP + JSON daemon.
server/handlers Package handlers holds the HTTP handlers for the blunderdb serve daemon.	Package handlers holds the HTTP handlers for the blunderdb serve daemon.
server/metrics Package metrics is a tiny, dependency-free Prometheus exposition for the blunderdb serve daemon.	Package metrics is a tiny, dependency-free Prometheus exposition for the blunderdb serve daemon.
server/middleware
server/openapigen Package openapigen builds a machine-readable model of blunderDB's /v1 API surface (method, pattern, request/response shape) by parsing the Go source of internal/server's handlers_*.go files — not by reflecting on a running Server, since the generic rpc[Req,Resp]/rpcVoid[Req]/rpcStream[Req,T] builders erase their type parameters from a compiled binary's runtime-visible function names (Go's dictionary-based generics render them as "rpc[...]", not the real instantiated types).	Package openapigen builds a machine-readable model of blunderDB's /v1 API surface (method, pattern, request/response shape) by parsing the Go source of internal/server's handlers_*.go files — not by reflecting on a running Server, since the generic rpc[Req,Resp]/rpcVoid[Req]/rpcStream[Req,T] builders erase their type parameters from a compiled binary's runtime-visible function names (Go's dictionary-based generics render them as "rpc[...]", not the real instantiated types).
server/webui Package webui embeds the built web front and serves it (ADR-0039).	Package webui embeds the built web front and serves it (ADR-0039).
pkg
blunderdb/anki Package anki holds the spaced-repetition scheduling every storage backend runs when a card is reviewed.	Package anki holds the spaced-repetition scheduling every storage backend runs when a card is reviewed.
blunderdb/apkg Package apkg writes a study deck or a collection as an Anki package (.apkg), to review it in Anki on a phone without the serve daemon.	Package apkg writes a study deck or a collection as an Anki package (.apkg), to review it in Anki on a phone without the serve daemon.
blunderdb/assistant
blunderdb/capture Package capture reads a backgammon position from a screen capture of another program's board, in pure Go, without a learned model: each known board is a theme — its geometry in units of the point width and the colours it draws — and Read looks for it at every scale.	Package capture reads a backgammon position from a screen capture of another program's board, in pure Go, without a learned model: each known board is a theme — its geometry in units of the point width and the colours it draws — and Read looks for it at every scale.
blunderdb/database Package database is the legacy SQLite-only persistence wrapper the Wails GUI and the CLI run against.	Package database is the legacy SQLite-only persistence wrapper the Wails GUI and the CLI run against.
blunderdb/direction Package direction runs a Tournament from inside blunderDB: it is the only place in the tree that knows the Nicomaque engine.	Package direction runs a Tournament from inside blunderDB: it is the only place in the tree that knows the Nicomaque engine.
blunderdb/direction/service Package service runs the Direction of a Tournament and the Rencontre it plays in (ADR-0047, ADR-0056) on the storage contract, so the desktop, the CLI and the serve daemon share one implementation over SQLite and PostgreSQL alike (ADR-0057 rule 2).	Package service runs the Direction of a Tournament and the Rencontre it plays in (ADR-0047, ADR-0056) on the storage contract, so the desktop, the CLI and the serve daemon share one implementation over SQLite and PostgreSQL alike (ADR-0057 rule 2).
blunderdb/domain Package domain holds the core backgammon domain types shared across the blunderDB engine, persistence layer, CLI and GUI.	Package domain holds the core backgammon domain types shared across the blunderDB engine, persistence layer, CLI and GUI.
blunderdb/duel Package duel is the Arbiter of a Duel: a match played inside blunderDB, the dice rolled here, the rules enforced, each Side deciding for itself (ADR-0072).	Package duel is the Arbiter of a Duel: a match played inside blunderDB, the dice rolled here, the rules enforced, each Side deciding for itself (ADR-0072).
blunderdb/engine Package engine holds what blunderDB computes ABOUT a position, as opposed to what it stores about one (pkg/blunderdb/storage) or what a position IS (pkg/blunderdb/domain, which this package imports and which never imports back).	Package engine holds what blunderDB computes ABOUT a position, as opposed to what it stores about one (pkg/blunderdb/storage) or what a position IS (pkg/blunderdb/domain, which this package imports and which never imports back).
blunderdb/engine/bearoffgen
blunderdb/engine/bearoffgen/bearofftest Package bearofftest hands tests a real bearoff table (the binary carries none since ADR-0027).	Package bearofftest hands tests a real bearoff table (the binary carries none since ADR-0027).
blunderdb/engine/gammonnet Package gammonnet is a Go port of the gammonNet evaluator's network, feature encoding, search and cube model (https://github.com/kevung/gammonNet, MIT).	Package gammonnet is a Go port of the gammonNet evaluator's network, feature encoding, search and cube model (https://github.com/kevung/gammonNet, MIT).
blunderdb/engine/race Package race computes race (bearoff) metrics shared by the GUI, the CLI and the serve daemon.	Package race computes race (bearoff) metrics shared by the GUI, the CLI and the serve daemon.
blunderdb/engine/rollout Package rollout plays a position out to settle what a search cannot: two plays a few thousandths apart, or a cube decision the cube model is unsure of.	Package rollout plays a position out to settle what a search cannot: two plays a few thousandths apart, or a cube decision the cube model is unsure of.
blunderdb/engine/training Package training makes the Training questions that need the neural evaluator (ADR-0040, ADR-0041).	Package training makes the Training questions that need the neural evaluator (ADR-0040, ADR-0041).