torben
210e0c8286
Files changed: - .gitea/workflows/ci.yml - CHANGES.md - INSTALL.md - README.md - VERSION - docs/why-gates-are-code.md - instructions/bootstrap.md - instructions/bug-report.md - instructions/preflight.md - instructions/setup-instance.md - instructions/upgrade-instance.md - tools/CONTRACT.md - tools/README.md - tools/bugreport.py - tools/chemenu/cli.py - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/doctor.py - tools/chemenu/prerequisites.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/test_bugreport.py - tools/chemenu/tests/test_doctor.py - tools/chemenu/tests/test_preflight.py - tools/chemenu/tests/test_preflight_pwsh.py - tools/chemenu/toolpaths.py - tools/preflight.ps1 - tools/wikitool - tools/wikitool.ps1
126 lines
6.4 KiB
Markdown
126 lines
6.4 KiB
Markdown
---
|
|
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 script, not a `wikitool` command, because it has to work before Python is
|
|
known to exist: `tools/preflight.sh` for POSIX shells, `tools/preflight.ps1` for PowerShell 7 on
|
|
Windows. The two answer the same questions from the same list and write the same
|
|
`.wikitool-tools.json`. 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 and
|
|
(PowerShell only) that the execution policy and the files' Mark of the Web let
|
|
`tools/wikitool.ps1` start;
|
|
- 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.
|
|
|
|
<!-- wikitool:toc -->
|
|
## Contents
|
|
|
|
- [When to run](#when-to-run)
|
|
- [Steps](#steps)
|
|
- [Decision points](#decision-points)
|
|
- [Scope](#scope)
|
|
<!-- /wikitool:toc -->
|
|
|
|
## 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`, `install-dir`, `execution-policy` or `script-marks` 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, with the script for the shell the session runs in:
|
|
|
|
```bash
|
|
tools/preflight.sh
|
|
```
|
|
|
|
This covers Linux, macOS and Git Bash on Windows, which is where Claude Code runs its
|
|
commands there. From PowerShell 7 on Windows (GitHub Copilot CLI, for one) use the twin, and
|
|
always with exactly this prefix:
|
|
|
|
```powershell
|
|
pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1
|
|
```
|
|
|
|
The bypass holds for that one process only and changes no setting; it is what lets the script
|
|
run at all when the checkout carries a Mark of the Web, so that it can report that itself.
|
|
Windows PowerShell 5.1 is not supported.
|
|
|
|
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
|
|
```
|
|
|
|
```powershell
|
|
pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1 --set rg=C:\Tools\rg\rg.exe
|
|
```
|
|
|
|
`--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 output names the PowerShell execution policy** (`Restricted` or `AllSigned`). The fix is a
|
|
line the user runs in a PowerShell 7 window; it changes a setting of their account, so it is
|
|
theirs to run. When a *group policy* sets it, nothing on this computer can override it: the
|
|
output says to ask whoever administers the machine - or to use `tools/wikitool` from Git Bash
|
|
instead. Do not suggest a workaround that evades the policy.
|
|
- **The output names scripts with a Mark of the Web.** The checkout was downloaded with a browser
|
|
and unpacked in Explorer, so Windows marks every file as coming from the internet. The command
|
|
in the output (`Unblock-File` over the folder) is the user's to run; a download by
|
|
`Invoke-WebRequest`, `git clone` or `tar` carries no mark.
|
|
- **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).
|