From 3bbfe919d20c5077561796e6155d88f2268f9dd3 Mon Sep 17 00:00:00 2001 From: ddidderr Date: Thu, 20 Aug 2026 09:06:47 +0200 Subject: [PATCH] docs(build): document real-data workflows Clarify that `just build` is the production no-bundle launcher build, while fixture builds are explicit. Document package-directory generation, the `LANSPREAD_GAMES_DIR` and `--set GAMES_DIR` default-run forms, the metadata cache behavior, and the force-refresh override so the catalogue workflow is usable without consulting the recipe implementation. Test Plan: - `prettier --check --prose-wrap always --print-width 80 README.md CLAUDE.md` -- passed - `just --fmt --check` -- passed - `git diff --cached --check` -- passed --- CLAUDE.md | 10 ++++++++-- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 57 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 12c47db..b57aea6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,8 +27,14 @@ Top-level `Cargo.toml` pins workspace dependency versions; per-crate Never use normal cargo ... commands, use the just ... commands instead. -- `just run` — run the GUI in dev mode. -- `just build` — build the GUI without bundling (also dev mode). +- `just run` — run the fixture GUI, or real data when `LANSPREAD_GAMES_DIR` is + set. +- `just build` — validate production authority and build the launcher without + bundling. +- `just build-production PACKAGES_DIR` — generate/reuse production authority and + build. +- `just run-fixture` / `just build-fixture` — use the test-only catalogue + explicitly. - `just fmt` — format the workspace. - `just clippy` — lint the workspace. - `just test` — run the workspace unit tests. diff --git a/README.md b/README.md index dad0758..877defb 100644 --- a/README.md +++ b/README.md @@ -31,18 +31,43 @@ builds. ## Daily development -Run the desktop app with the checked-in development catalog: +Run the desktop app with the checked-in test catalog: ```bash just run ``` -Build without bundling: +Build a launcher from the already-published production catalog without creating +an installer: ```bash just build ``` +Generate the production catalog from a package tree when necessary, then build +the same no-bundle launcher: + +```bash +just build-production /srv/lanspread/packages +``` + +To make the default `just` command use a real package tree, set the directory +before invoking it. The command generates or reuses the production catalog and +then runs the launcher with the production resource map: + +```bash +LANSPREAD_GAMES_DIR=/srv/lanspread/packages just +# Equivalent Just-variable form: +just --set GAMES_DIR /srv/lanspread/packages +``` + +The fixture-only paths remain explicit: + +```bash +just run-fixture +just build-fixture +``` + Run the standard checks before committing: ```bash @@ -52,9 +77,10 @@ just test just frontend-test ``` -`just run` and `just build` first check the default development catalog. The -workspace Rust commands explicitly opt into that exact fixture resource map so -Tauri's build script does not mistake test data for production authority. +`just run` uses the fixture path only when `LANSPREAD_GAMES_DIR` is unset. +`just build` always uses the production resource map and production profile; use +`just build-fixture` when a fixture build is intended. Tauri's build script +still rejects fixture resources unless the explicit fixture opt-in is present. ## Catalog checksums and production manifests @@ -111,6 +137,18 @@ Generate the complete production manifest set: just catalog-generate-production /srv/lanspread/packages ``` +The `--all` recipe keeps a local metadata-only stamp in +`.lanspread/catalog-cache/production.json`. It compares the package tree's +paths, entry types, sizes, and nanosecond mtimes, plus the catalog database and +`unrar` metadata. If those values and the published output still match, the +expensive package hashing and extraction step is skipped. This is only a +performance cache: `catalog-check-production` and every production build still +validate the catalog authority. Force a refresh when needed: + +```bash +LANSPREAD_CATALOG_FORCE=1 just catalog-generate-production /srv/lanspread/packages +``` + The publisher first checks every selected package's `version.ini` against `game.db`, then independently reads and hashes each selected package twice before publication. Under a durable publication marker, it atomically replaces @@ -201,10 +239,13 @@ just peer-cli-charlie | Command | Purpose | | --------------------------------------------------- | ------------------------------------------------------------------------ | | `just setup` | Install the Tauri CLI and frontend dependencies. | -| `just run` | Check the default fixture catalog and run the GUI. | -| `just build` | Check the default fixture catalog and build without bundling. | +| `just` / `just run` | Run fixtures, or real data when `LANSPREAD_GAMES_DIR` is set. | +| `just run-fixture` | Check the default fixture catalog and run the GUI. | +| `just build` | Validate production authority and build without bundling. | +| `just build-production PACKAGES_DIR` | Generate/reuse production authority and build without bundling. | +| `just build-fixture` | Check the default fixture catalog and build without bundling. | | `just bundle` | Check production authority and build production bundles. | -| `just catalog-generate-production PACKAGES_DIR` | Hash and publish the complete production package corpus. | +| `just catalog-generate-production PACKAGES_DIR` | Hash, cache, and publish the complete production package corpus. | | `just catalog-generate-production-game DIR GAME_ID` | Safely regenerate one game in an already complete catalog. | | `just catalog-check-production` | Validate all production database/index/manifest artifacts. | | `just fixture-catalog-check` | Validate the default development fixture catalog. |