From 9dad83f50bb67de50d41ba30899cd388ea9ab923 Mon Sep 17 00:00:00 2001
From: Stephen Waits <steve@waits.net>
Date: Tue, 12 May 2026 10:26:30 -0600
Subject: [PATCH] chore(justfile): add `preview` recipe for local multi-version
 testing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`just build` produces a single-version site to ./book/ with no
versions.json, and `just build-site` produces the multi-version site
but viewing it via file:// makes the browser block
fetch('versions.json') for security reasons. Both cases leave the
version-picker stuck in label-only mode locally — which looked like
the picker was broken when it was actually doing the right thing
given the available data.

`just preview` is the recipe to test the picker end-to-end:

  1. Runs build-site (full _site/ with versions.json).
  2. Serves _site/ at http://localhost:8000/ via python -m http.server.
  3. Browser fetch() works, picker upgrades to a real dropdown,
     navigation between /latest/ and /v0.X.Y/ works.

Also restructured all recipe doc-comments to single-line summaries
(just --list only shows the immediately-preceding comment, and the
old multi-line comments were rendering as confusing fragments).
Background commentary moved to a file-level header.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 justfile | 31 +++++++++++++++++++++++--------
 1 file changed, 23 insertions(+), 8 deletions(-)

diff --git a/justfile b/justfile
index 42ee482..23fe302 100644
--- a/justfile
+++ b/justfile
@@ -1,9 +1,16 @@
 # meshcore-spec — task runner.
 #
-# Every recipe runs under `mise exec sh -c …`, so mise-pinned tools
+# Every recipe runs under `mise exec -- sh -c …`, so mise-pinned tools
 # (see mise.toml) are on PATH and we never accidentally use a system
 # mdbook of the wrong version. `sh` is intentional — keep recipes
 # POSIX-compatible.
+#
+# Background on `preview` vs the other build recipes:
+# `mdbook build` (used by `build` and `serve`) produces a single-
+# version site with no versions.json, so the version-picker stays in
+# its label-only fallback there. To see the picker as a dropdown
+# locally, run `just preview` — it builds the full multi-version site
+# AND serves it over HTTP, since browsers block fetch() under file://.
 
 set shell := ["mise", "exec", "--", "sh", "-c"]
 
@@ -15,20 +22,29 @@ _default:
 setup:
     mise install
 
-# Build the spec into ./book/ (single-version; for local dev).
+# Build a single-version site into ./book/ (mdbook output dir).
 build:
     mdbook build
 
-# Build the full multi-version site into ./_site/ (latest + every v* tag).
-# This is exactly what CI runs.
+# Build the full multi-version site into ./_site/ (same logic CI runs).
 build-site:
     sh scripts/build-site.sh
 
-# Live-preview the spec at http://localhost:3000 with auto-reload.
+# Build the multi-version site and serve it at http://localhost:8000/.
+preview: build-site
+    @echo ""
+    @echo "Serving ./_site/ at http://localhost:8000/"
+    @echo "  http://localhost:8000/latest/   - rolling main"
+    @echo "  http://localhost:8000/v0.1.0/   - frozen v0.1.0"
+    @echo "  Ctrl-C to stop."
+    @echo ""
+    cd _site && python3 -m http.server 8000
+
+# Live-preview a single-version build at http://localhost:3000 (auto-reload).
 serve:
     mdbook serve --open --port 3000
 
-# Remove all build outputs (single-version and multi-version).
+# Remove all build outputs (single- and multi-version).
 clean:
     rm -rf book _site
 
@@ -36,8 +52,7 @@ clean:
 validate:
     python3 tools/validate.py corpus/
 
-# Cut a frozen spec version: copy ./src/ to ./versions/<VERSION>/.
-# Usage: just cut-version v0.2.0
+# Snapshot ./src/ as ./versions/VERSION/. Usage: just cut-version v0.2.0
 cut-version VERSION:
     #!/usr/bin/env sh
     set -eu