feat: preflight - prerequisites checked and tool paths recorded before wikitool runs; launcher refuses without it (#151, POSIX half)

Files changed: - .claude/settings.json - .gitea/workflows/ci.yml - .gitea/workflows/nightly.yml - .gitea/workflows/release.yml - .gitea/workflows/tracker-live.yml - .github/hooks/wiki-trace.json - .gitignore - .vibe/hooks.toml - AGENTS.md - CHANGES.md - EVALS.md - INSTALL.md - README.md - VERSION - instructions/bootstrap.md - instructions/preflight.md - instructions/setup-instance.md - instructions/upgrade-instance.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/cli.py - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/migrate_cmd.py - tools/chemenu/config.py - tools/chemenu/corpus_cache.py - tools/chemenu/prerequisites.py - tools/chemenu/search/ripgrep.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/test_dist_upgrade.py - tools/chemenu/tests/test_doctor.py - tools/chemenu/tests/test_preflight.py - tools/chemenu/toolpaths.py - tools/preflight.sh - tools/prerequisites.txt - tools/run_wikitool.py - tools/trace-hook - tools/wikitool
2026-10-01 05:52:55 +02:00
1 parent 5a731729f6
commit e4b2b6d9b1
@@ -1,7 +1,7 @@
 ---
 type: types/instruction.md
 name: bootstrap
-description: Prepare a fresh clone for work - create the tools venv and publish the skills into the harness directories, which are generated and not committed.
+description: Prepare a fresh clone for work - run the preflight (tool paths and the tools venv) and publish the skills into the harness directories, which are generated and not committed.
 ---

 # Bootstrap a fresh clone
@@ -19,15 +19,16 @@ they are published: the agent harness will not offer `wiki-ingest`, `wiki-query`

 ## Steps

-1. **Create the tool environment** (once per clone):
+1. **Run the preflight** (once per clone, and again after moving it) - see
+   [preflight.md](preflight.md). It records the tool paths in `.wikitool-tools.json` and
+   creates `tools/.venv`; until it exits 0, `tools/wikitool` refuses to start:

   ```bash
-   cd tools
-   python3 -m venv .venv
-   .venv/bin/pip install -r requirements.txt
-   cd ..
+   tools/preflight.sh
   ```

+   On exit 42, show its output to the user verbatim and wait.
+
 2. **Publish the skills:**

   ```bash
@@ -0,0 +1,90 @@
+---
+type: types/instruction.md
+name: preflight
+description: Run the preflight before any wikitool command in a new, cloned, moved or updated checkout - it checks Python, git and ripgrep, records their paths in .wikitool-tools.json and sets up tools/.venv; on exit 42 show its output verbatim and wait for the user, never install or work around anything yourself.
+---
+# Check the machine before anything else runs
+
+`tools/wikitool` does not start in a checkout the preflight has not passed in. It stops with
+exit 42 and names this procedure instead - so there is no skipping it, only running it early
+or being sent back to it.
+
+The preflight is a shell script, not a `wikitool` command, because it has to work before
+Python is known to exist. It does three things, all inside the install folder:
+
+- checks the tools listed in `tools/prerequisites.txt` - Python 3.11 or newer, git, ripgrep
+  (`rg`) - and, on Windows, that the install folder is short enough for Windows' path limit;
+- records the absolute path of each tool in `.wikitool-tools.json`, which `wikitool` then starts
+  them from instead of trusting whatever `PATH` a session inherited;
+- creates `tools/.venv` from the recorded Python and installs `tools/requirements.txt` into it.
+
+## When to run
+
+- First step of every installation procedure: [setup-instance.md](setup-instance.md) and
+  [bootstrap.md](bootstrap.md) both start here.
+- After every stack update ([upgrade-instance.md](upgrade-instance.md)) - a release can change
+  what the machine needs, or the requirements the venv holds.
+- Whenever `tools/wikitool` exits 42 and names the preflight, and whenever `tools/wikitool doctor`
+  reports `tool-paths` or `install-dir` as `FAIL`.
+
+It is safe to run at any time: a second run on a ready checkout changes nothing and exits 0.
+
+## Steps
+
+1. **Run it** from the root of the checkout:
+
+   ```bash
+   tools/preflight.sh
+   ```
+
+   This covers Linux, macOS and Git Bash on Windows, which is where Claude Code runs its
+   commands there.
+
+2. **Read the exit code.**
+
+   | Exit | Meaning | What you do |
+   |---|---|---|
+   | 0 | Everything is in place | Continue with the procedure that sent you here |
+   | 42 | The user has to act | Step 3 |
+   | 1 | Called wrongly, or `tools/prerequisites.txt` is missing next to the script | Report the exact command and output to the user; do not retry blindly |
+
+3. **On exit 42, show the output to the user exactly as it is, then stop and wait.** It is
+   written for someone without an IT background: each numbered block says what is missing, why
+   it matters, the command that fixes it, and what happens next. When the user's language is not
+   the language of the output, add a translation below it - never instead of it, since the
+   commands inside have to reach them unchanged.
+
+   While you wait, **install nothing, and work around nothing** - not with the user's consent
+   either. No package manager call, no other Python, no WSL, no hand-written
+   `.wikitool-tools.json`, no `wikitool` command "to see whether it works anyway". The command in
+   the output is for the user to run; how their machine is administered is theirs to decide.
+
+4. **When the user says it is done, run the preflight again.** Repeat steps 2-4 until it exits 0.
+
+   When the user tells you where a tool is installed instead, pass the path on:
+
+   ```bash
+   tools/preflight.sh --set rg=/opt/ripgrep/rg
+   ```
+
+   `--set <tool>=<path>` may be given several times. A path that does not work is refused with
+   exit 42 and nothing is written; a working one is recorded and kept on later runs, even though
+   the tool is still not on `PATH`.
+
+## Decision points
+
+- **The output names a folder that is too long.** Only on Windows with long paths off: the
+  install folder may be at most 95 characters, because every file of the wiki below it has to
+  stay within 259. Moving the wiki to a shorter folder is the user's step; do not try to shorten
+  paths inside the wiki instead.
+- **The venv or its libraries could not be installed.** The output carries the last lines of
+  what Python or pip said. A network, proxy or security-product cause is for the user - or
+  whoever administers their machine - to resolve; do not retry with other flags.
+- **`.wikitool-tools.json` looks wrong.** Never edit it. Run the preflight again, with `--set` for
+  a path the user names; `doctor` reports whether the result holds.
+
+## Scope
+
+Not a wiki content procedure - it touches nothing under `kb/`, `raw/`, `work/` or `reports/`.
+It does not configure identity, remotes or the harness either; those are later steps of
+[setup-instance.md](setup-instance.md).
@@ -193,15 +193,17 @@ and ready for its first ingest.
   `FAIL`, and so is one still carrying the sentinel - a renamed template is not a filled-in
   one.

-7. **Create the tool environment** (details: [bootstrap.md](bootstrap.md)):
+7. **Run the preflight** ([preflight.md](preflight.md)). It checks Python, git and ripgrep,
+   records their paths in `.wikitool-tools.json` and creates `tools/.venv` - no `tools/wikitool`
+   call works before it has passed:

   ```bash
-   cd tools
-   python3 -m venv .venv
-   .venv/bin/pip install -r requirements.txt
-   cd ..
+   tools/preflight.sh
   ```

+   On exit 42, show its output to the user verbatim and wait; run it again once they have
+   acted. Continue here only after it exits 0.
+
 8. **Publish the skills:**

   ```bash
@@ -150,8 +150,19 @@ fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream

   It writes, and commits nothing.

-8. **Republish the skills.** `tools/wikitool instructions sync` - the published skill directories
-   are copies, so until this runs the harness is still offering the previous release's skills.
+8. **Run the preflight, then republish the skills.** The release may need other tools or
+   other libraries than the one it replaced, and `tools/wikitool` refuses to start (exit 42)
+   until the preflight has passed against the new `tools/` - an instance upgrading from a
+   release without one has never run it at all. On its exit 42, show the output verbatim and
+   wait ([preflight.md](preflight.md)):
+
+   ```bash
+   tools/preflight.sh
+   tools/wikitool instructions sync
+   ```
+
+   `instructions sync` is needed because the published skill directories are copies: until it
+   runs, the harness is still offering the previous release's skills.

 9. **Verify the machinery, and fix what the release said would need fixing:**