torben
a6d07f97c4
Files changed: - .gitea/workflows/ci.yml - .gitea/workflows/release.yml - AGENTS.md - CHANGES.md - DEVELOPMENT.md - EVALS.md - INSTALL.md - README.md - VERSION - docs/ownership-and-templates.md - instructions/CONTRACT.md - instructions/bootstrap.md - instructions/dev/dev-setup.md - instructions/dev/stack-dev/SKILL.md - instructions/gates.md - instructions/ingest-large-tree.md - instructions/kb-profiles.md - instructions/mcp-read-server.md - instructions/migrations/3.0.0-authoring-conventions.md - instructions/preflight.md - instructions/private-instance.md - instructions/session-setup.md - instructions/setup-instance.md - instructions/upgrade-instance.md - tools/CONTRACT.md - tools/README.md - tools/chemenu/cli.py - tools/chemenu/cli_contract.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/upstream_cmd.py - tools/chemenu/commands/work_cmd.py - tools/chemenu/config.py - tools/chemenu/ownership.py - tools/chemenu/tests/test_cli.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_instructions_shell.py - tools/chemenu/tests/test_preflight.py - tools/chemenu/tests/test_preflight_pwsh.py - tools/chemenu/tests/test_run_budget.py - tools/chemenu/tests/test_upstream_cmd.py - tools/chemenu/toc.py - tools/preflight.ps1 - tools/preflight.sh
150 lines
8.4 KiB
Markdown
150 lines
8.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, a download or unpack failed (asset mode), or the stack tree next to the script is incomplete | 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 script is a release asset, not a tree script** - there is no `tools/prerequisites.txt`
|
|
beside it, because it was downloaded from a release into the empty folder the wiki is to live
|
|
in ([setup-instance.md](setup-instance.md) step 0). That is the *first* install, and the
|
|
script does one more thing before the steps above: it downloads the release tarball and its
|
|
`.sha256`, refuses unless the checksum matches, unpacks the stack into its own folder and
|
|
removes itself there; then it runs the preflight of the installed tree, passing `--set` and
|
|
its exit code through. Run it exactly as in step 1 (the path is the downloaded file, not
|
|
`tools/...`), and read the exit code the same way. After it, every later run - including the
|
|
retry after an exit 42 - is the tree's own `tools/preflight.sh` or `tools/preflight.ps1`.
|
|
- The folder has to be empty apart from the script and a `.git` (an empty clone of the
|
|
instance's own repository). Anything else is refused with exit 1 and nothing is touched -
|
|
which folder to use is the user's decision, not yours to resolve by deleting.
|
|
- `--into <path>` installs into another folder, under the same rule; the script then stays
|
|
where it is.
|
|
- `--archive <tarball>` uses a tarball already on disk, with its `<tarball>.sha256` beside it,
|
|
when the machine cannot download.
|
|
- A checksum that does not match, a failed download, and a copy of the script that carries no
|
|
download address (it was not taken from a release) exit 1 with nothing unpacked; report the
|
|
message, and do not fetch the tarball by another route.
|
|
- On POSIX, `curl`, `tar` and `sha256sum` (or `shasum`) have to exist; when one does not, the
|
|
script stops with exit 42 like any other missing tool. The PowerShell script needs nothing
|
|
beyond what Windows ships.
|
|
- **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. In asset mode the length is judged at the folder the stack
|
|
*would* be unpacked into, before anything is unpacked; the fix is a shorter folder (the
|
|
script downloaded there again, or a shorter `--into`).
|
|
- **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).
|