• WORK IN PROGRESS
  • description
  • Validation gates
  • Running the game
    • downloading and installing
    • to run the game
    • server hot reloading
  • exiting the game

WORK IN PROGRESS

description

rewrite of the famous game flaghack

Validation gates

Audit-remediation work should use the project gates documented in docs/testing-gates.md. The short version is:

  pnpm generated:guard
  pnpm format:check
  pnpm check
  pnpm test:unit
  pnpm test:charm
  pnpm test:perf
  pnpm test:api:bot
  pnpm test:e2e:tmux:bot

For the smoke aggregate, run pnpm verify:smoke. For the stricter readiness gate that also runs pnpm check, run pnpm verify:gates.

The full build/codegen lifecycle is still known to be fragile; this setup does not claim that pnpm run build is fixed. Do not edit generated build/, dist/, declaration, map, backup, or generated schema JavaScript files by hand.

Running the game

downloading and installing

  git clone git@github.com:htayj/flaghack.git
  cd flaghack
  corepack enable
  corepack prepare pnpm@9.10.0 --activate
  pnpm install

The default CLI uses the Go Charmbracelet frontend. Use the Nix development shell for the matching Node, pnpm, Go, Python, and tmux toolchain:

  nix develop

to run the game

in one terminal run (this starts the server):

  pnpm run serve

and then in a second terminal run:

  pnpm run cli

to start the default Charmbracelet terminal client

A fresh game starts with role selection; the only current role is virgin. The default client supports NetHack movement, , pickup, d drop, e eat, q quaff, M-l loot, ; look, and _ travel. Use o or c followed by a direction to open or close a door; moving into a closed door also opens it.

Use C-s or #save to save and exit. Use C-q or #quit and confirm with y to permanently quit without saving. The server lazily resumes an existing save on first access; the explicit restore endpoint consumes a successfully decoded save. Saves default to $XDG_STATE_HOME/flag-hack/save.json, ~/.local/state/flag-hack/save.json when XDG_STATE_HOME is unset, or .flaghack/save.json when no home is available. Override the location with FLAGHACK_SAVE_PATH.

For agent/bot testing while a human server is already running on port 3000, use the bot port commands:

  pnpm run bot:serve
  pnpm run bot:cli

These use port 3100.

server hot reloading

The development server watches both server and shared domain TypeScript sources. Start it with:

  pnpm run serve

Changes are coalesced for 200 milliseconds and then restart the server through its nodemon-aware graceful shutdown path, including the normal shutdown autosave.

exiting the game

Use C-s or #save for a resumable save-and-exit. Use C-q or #quit for confirmed permanent quit. C-c disconnects the terminal client without saving; use C-s for durable progress. Autosave runs only when the server itself shuts down cleanly.