rack/README.md

# rack

A browser-based idle/incremental game about running a homelab. Start with a
single Raspberry Pi on a desk, incrementally expand into something that
vaguely justifies its electricity bill.

Dark terminal aesthetic, dry flavour text, numbers go up, occasionally
things go wrong.

## Running it

```bash
npm install
npm run dev      # dev server on http://localhost:5677
npm run build    # production build
npm run preview  # preview the build on http://localhost:4587
npm test         # vitest run - engine + balance tests
```

No backend. Game state lives entirely in `localStorage`, autosaved on every
render tick and on tab close/hide.

## How it works

- **Hardware** (`src/data/hardware.ts`) provides RAM slots and power budget,
  enforced per host (not a shared pool). You can either unlock the next
  tier, or buy another unit of a tier you already own as a cheaper bridge —
  each extra unit of the same tier costs 40% more than the last
  (`hardwareCost()` in `engine.ts`). The starter Pi 4 is a one-time freebie
  and can't be rebought.
- **Services** (`src/data/services.ts`) run on hardware, consume RAM/power,
  and produce points/sec. They age (production creeps up over time) and can
  crash (probability rises with age, mitigated by the Cooling upgrade). The
  deploy dropdown shows each service's RAM/power cost up front and disables
  anything that wouldn't fit the currently selected host.
- **Upgrades** (`src/data/upgrades.ts`) are one-time persistent purchases:
  UPS shortens outages, Backups tiers reduce/reverse crash losses,
  Monitoring reveals crash risk, Redundancy runs a second instance of every
  service, Documentation is a small passive multiplier.
- **Random events** (`src/engine.ts` `rollRandomEvent`) fire on a
  Poisson-ish interval that tightens as the game clock advances: disk-full
  crashes, power outages, kernel panics, fan-noise flavour-only events,
  optional updates, and a rare `rm -rf` that deletes a service outright
  (guarded once Backups I is bought).
- **Prestige**: once total lifetime earnings cross 50,000 pts, a banner
  offers to decommission the rack — wipes hardware/services/upgrades but
  grants a permanent production multiplier and carries forward.
- **Host nicknames** (`src/data/hostnames.ts`): every host is randomly
  christened on purchase from a pool of sci-fi/mythology/sysadmin-humour
  names (hal9000, shodan, the-basement, works-on-my-machine, ...), drawn
  without replacement so they double as unique identifiers wherever a host
  is named.
- **Quirks** (`src/data/quirks.ts`): each deploy has a 30% chance of rolling
  a per-instance trait (Overclocked, Chatty, Legacy, Well-documented,
  Flaky, Artisanal) that shifts that instance's production and crash risk.
  Shown as a badge on the service row and in the rack view's tooltip.
- **Rack view**: an ASCII-art strip above the two main columns, one line per
  owned host, showing which services (as 2-letter codes) are deployed where
  and free capacity as dots — a compact answer to "what's actually running
  on what."
- **Help & changelog**: click the `?` in the header, or press `?` anywhere
  outside a text input, to open an in-app overlay with a quick "how this
  works" list and the full version changelog (`src/data/version.ts`),
  mirroring `../adventure`'s help-modal pattern.

## Project layout

```
src/
  types.ts       game state & definition types
  state.ts       new game, save/load (localStorage), id allocation
  engine.ts      tick loop: production, aging, crashes, events, prestige
  ui.ts          DOM rendering, one full re-render per render tick
  help.ts        the ?-triggered help/changelog overlay
  data/          static definitions: hardware/services/upgrades/events/
                 quirks/version (VERSION + in-app CHANGELOG entries)
  style.css      terminal theme
```

The simulation tick runs on `requestAnimationFrame` and is time-delta based
(not frame-based), so offline/backgrounded tabs still catch up correctly
when they regain focus. The passive UI re-render runs on its own ~1s
interval, decoupled from the tick — user actions (buy, deploy, fix,
uninstall) re-render immediately via a direct callback instead of waiting
on that interval, and it's skipped entirely while a `<select>` has focus so
the service-picker dropdown doesn't get yanked shut mid-render.

## Deployment

rack is its own container — deployed independently of `goonk`/`goonk-cv`,
same pattern as every other project on this host: a `Dockerfile` builds
the static site and serves it via nginx, `.gitea/workflows/docker.yml`
builds and pushes that image to the Gitea registry on every push to
`main`, and `docker-compose.yml` is the host-side reference for running
it. The CI workflow needs a repo secret named `TKNTKN` (a Gitea PAT with
`packages:write`) — same requirement as `goonk`'s own workflow, set under
Settings → Secrets.

Served from its own subdomain (e.g. `rack.explewd.com`), not a subpath of
goonk.se — that keeps the build completely vanilla (root-relative asset
URLs work as-is, no `--base` flag needed) and means the edge nginx just
needs one new `server_name` block or NPM proxy host pointing at whichever
port `docker-compose.yml`'s `HOST_PORT` exposes (`5677` by default — no
`--base=/rack/`/path-prefix plumbing required, unlike a subpath
deployment would need).

```bash
docker build -t rack .
docker run -d -p 5677:80 rack   # or: docker compose up -d
```

`rack`'s own `localStorage` key (`rack-save-v1`) is namespaced regardless
of URL shape, so it won't collide with anything else on the same origin.

If a subpath deployment (`goonk.se/rack`) is wanted later instead, use
`npm run build:subpath` (`vite build --base=/rack/`) — it rewrites
`dist/index.html`'s asset URLs to `/rack/assets/...`. That requires the
edge proxy to forward the `/rack/...` path through *unchanged* (not
strip the prefix) and the container to serve files at that same
sub-path — more moving parts to keep in sync than the subdomain route
above, which is why subdomain is the current choice.

## Tests

`src/engine.test.ts` (Vitest) covers the core loop mechanics rather than UI:
deploy/capacity checks (including per-host isolation), hardware/upgrade
purchases and prerequisite gating, the fix-cooldown (per-service, not
global — see CHANGELOG for why that matters), uninstall refunds,
production/crash/outage ticking, and prestige. A separate `balance sanity`
block asserts properties of the static data in `src/data/` rather than
specific numbers — e.g. every service pays back its own deploy cost in
under 5 minutes at base rate, hardware cost/capacity strictly increases
with tier, and no service's crash risk has crept past the intended
ceiling. These are meant to catch a future data tweak that breaks the
early-game feel, not to lock the current numbers in stone — adjust the
thresholds deliberately if you retune the balance.

## Design decisions worth knowing

- **Vanilla TypeScript + DOM**, no framework — matches the rest of the
  homelab-project family (`waste-go`, `flit`) and keeps this dependency-light
  per `PLAN.md`.
- **Dev/preview ports are non-default** (`5677` / `4587` instead of Vite's
  `5173` / `4173`) because the other sibling projects on this machine claim
  the usual ports and everything within ±10 of them.
- **Starting balance is 15 pts**, not 0 — the cheapest service (Nginx)
  costs 10, so a brand-new game can bootstrap its first deploy immediately
  without an awkward zero-income deadlock.