feat!: installation only from a release, into an empty folder; upstream merge/verify and private-instance.md removed, dist adopt, shell-neutral instructions (#153)
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
This commit is contained in:
torben committed
1 parent
d0f08d1fba
commit
a6d07f97c4
46 files changed
+1314
-1936
No files matched your search
+27
-22
@@ -75,7 +75,8 @@ jobs:
|
||||
# working tree stays clean for the ignore-rule checks.
|
||||
WIKITOOL_SESSION_ID: ci-${{ github.run_id }}
|
||||
WIKI_TRACE_DIR: /tmp/wikitool-trace
|
||||
DIST_DIR: /tmp/dist
|
||||
BUILD_DIR: /tmp/build
|
||||
INSTANCE_DIR: /tmp/instance
|
||||
|
||||
steps:
|
||||
- name: System dependencies
|
||||
@@ -235,15 +236,24 @@ jobs:
|
||||
echo 'Then `docs verify` holds VERSION and CHANGES.md together.'
|
||||
exit 1
|
||||
|
||||
- name: Export the distribution
|
||||
run: tools/wikitool dist export "$DIST_DIR"
|
||||
- name: Build a release tarball
|
||||
# The same form release.yml builds - a `dist export` tree under exactly one
|
||||
# top-level folder, plus its .sha256 - so the replay below starts where a
|
||||
# user starts: from the archive, not from an exported tree.
|
||||
run: |
|
||||
set -eu
|
||||
name=chemenu-stack-ci
|
||||
mkdir -p "$BUILD_DIR"
|
||||
tools/wikitool dist export "${BUILD_DIR}/${name}"
|
||||
tar -czf "${BUILD_DIR}/${name}.tar.gz" -C "$BUILD_DIR" "$name"
|
||||
( cd "$BUILD_DIR" && sha256sum "${name}.tar.gz" > "${name}.tar.gz.sha256" )
|
||||
|
||||
- name: The distribution works as a fresh instance
|
||||
# Replays instructions/setup-instance.md end to end, minus its four
|
||||
# interactive decision points. What this tests is the release artifact
|
||||
# as an artifact: the documented path from an unpacked export to a
|
||||
# verified instance. Running one `instructions verify` against the
|
||||
# export would only have re-checked the file it just copied.
|
||||
# Replays instructions/setup-instance.md end to end, minus its interactive
|
||||
# decision points. What this tests is the release artifact as an
|
||||
# artifact: the documented path from the preflight asset in an empty
|
||||
# folder to a verified instance. Step 0 runs the asset with --archive
|
||||
# instead of a download, which is the one difference from a real install.
|
||||
#
|
||||
# Personalization is stubbed the same way the identity is: the real
|
||||
# step interviews the user, so CI substitutes a fixed answer - here,
|
||||
@@ -253,7 +263,13 @@ jobs:
|
||||
# what a person would write into them.
|
||||
run: |
|
||||
set -eu
|
||||
cd "$DIST_DIR"
|
||||
mkdir -p "$INSTANCE_DIR"
|
||||
cp tools/preflight.sh "$INSTANCE_DIR/preflight.sh"
|
||||
cd "$INSTANCE_DIR"
|
||||
sh preflight.sh --archive "${BUILD_DIR}/chemenu-stack-ci.tar.gz"
|
||||
# Installed in place: the asset is gone, the tree is here.
|
||||
test ! -e preflight.sh
|
||||
test -f tools/preflight.sh
|
||||
git init -q -b main
|
||||
git config user.name "CI Instance"
|
||||
git config user.email "ci@example.invalid"
|
||||
@@ -267,18 +283,7 @@ jobs:
|
||||
# contracts are adopted verbatim - the shipped text is a working
|
||||
# default, unlike a personalization file.
|
||||
grep -v 'wikitool:template-unfilled' kb/CONVENTIONS.md.template > kb/CONVENTIONS.md
|
||||
for template in kb/*/COLLECTION.md.template types/*.template; do
|
||||
cp "$template" "${template%.template}"
|
||||
done
|
||||
# A fresh instance refuses to run before its preflight (exit 42), so
|
||||
# this proves both halves: the refusal, then the setup that ends it.
|
||||
set +e
|
||||
tools/wikitool doctor > /tmp/before-preflight.txt 2>&1
|
||||
refused=$?
|
||||
set -e
|
||||
test "$refused" -eq 42
|
||||
grep -q 'tools/preflight.sh' /tmp/before-preflight.txt
|
||||
tools/preflight.sh
|
||||
tools/wikitool dist adopt
|
||||
tools/wikitool instructions sync
|
||||
tools/wikitool index rebuild
|
||||
tools/wikitool sources rebuild-index
|
||||
@@ -306,7 +311,7 @@ jobs:
|
||||
# The unit tests cover what it collects; this covers that it arrives.
|
||||
run: |
|
||||
set -eu
|
||||
cd "$DIST_DIR"
|
||||
cd "$INSTANCE_DIR"
|
||||
python3 tools/bugreport.py --no-trace
|
||||
bundle=$(ls -d reports/bugreport-*/ | head -n 1)
|
||||
test -f "$bundle/MANIFEST.md"
|
||||
|
||||
@@ -5,7 +5,9 @@
|
||||
# working wiki instance - no checkout of this repo required. CI already proved
|
||||
# that path works before this workflow ever runs. Beside it the release carries
|
||||
# tools/preflight.sh and tools/preflight.ps1 as assets, which download and unpack
|
||||
# that tarball themselves.
|
||||
# that tarball themselves, and the two instructions an agent reads before there is
|
||||
# a tree to read them in: setup-instance.md, which the installation sentence in
|
||||
# INSTALL.md points at, and the preflight.md its first step leads to.
|
||||
#
|
||||
# The tag is created here, by CI, and never by an agent: AGENTS.md invariant 5
|
||||
# ("never call raw git commit/push") stays intact because nothing in a session
|
||||
@@ -173,6 +175,12 @@ jobs:
|
||||
grep -qF "ReleaseChecksumUrl = '${download}/${name}.tar.gz.sha256'" "${BUILD_DIR}/preflight.ps1"
|
||||
chmod +x "${BUILD_DIR}/preflight.sh"
|
||||
|
||||
# The two instructions as the tarball carries them (dist export has already
|
||||
# stripped them), not as this checkout holds them.
|
||||
for doc in setup-instance.md preflight.md; do
|
||||
cp "${BUILD_DIR}/${name}/instructions/${doc}" "${BUILD_DIR}/${doc}"
|
||||
done
|
||||
|
||||
- name: Publish the release
|
||||
if: steps.version.outputs.skip != 'true'
|
||||
env:
|
||||
@@ -198,7 +206,7 @@ jobs:
|
||||
id="$(printf '%s' "$release" | jq -r '.id')"
|
||||
echo "Created release ${TAG} (id ${id})."
|
||||
|
||||
for asset in "${NAME}.tar.gz" "${NAME}.tar.gz.sha256" preflight.sh preflight.ps1; do
|
||||
for asset in "${NAME}.tar.gz" "${NAME}.tar.gz.sha256" preflight.sh preflight.ps1 setup-instance.md preflight.md; do
|
||||
curl -sS -f -X POST "${API}/releases/${id}/assets?name=${asset}" \
|
||||
-H "Authorization: token ${TOKEN}" \
|
||||
-F "attachment=@${BUILD_DIR}/${asset}" > /dev/null
|
||||
|
||||
@@ -37,12 +37,10 @@ missing or empty - a fresh clone - the harness offers no skills until they are p
|
||||
tools/wikitool instructions sync
|
||||
```
|
||||
|
||||
Full procedure, including the tool environment: [instructions/bootstrap.md](instructions/bootstrap.md).
|
||||
Setting up a brand-new, empty instance instead of cloning this one: `tools/wikitool dist export`
|
||||
and [instructions/setup-instance.md](instructions/setup-instance.md) - see
|
||||
[INSTALL.md](INSTALL.md). A *private* instance that keeps taking stack updates from a public
|
||||
upstream is a third shape, with a safeguard the other two do not need:
|
||||
[instructions/private-instance.md](instructions/private-instance.md).
|
||||
Full procedure for a fresh clone of an instance, including the tool environment:
|
||||
[instructions/bootstrap.md](instructions/bootstrap.md). Setting up a brand-new, empty instance
|
||||
instead: [instructions/setup-instance.md](instructions/setup-instance.md), which installs the
|
||||
latest release into an empty folder - see [INSTALL.md](INSTALL.md).
|
||||
|
||||
## Invariants
|
||||
|
||||
@@ -149,7 +147,8 @@ command touches it.
|
||||
Six pages are reached from this file, each by link rather than automatically:
|
||||
[docs/pipeline-rationale.md](docs/pipeline-rationale.md) (why the pipeline has four stages),
|
||||
[docs/ownership-and-templates.md](docs/ownership-and-templates.md) (why a `.template` split
|
||||
exists, and why silent overwrite is the failure it guards against),
|
||||
exists, why silent overwrite is the failure it guards against, and why an instance comes only
|
||||
from a release),
|
||||
[docs/language-boundaries.md](docs/language-boundaries.md) (why the control plane is English
|
||||
everywhere and the KB language is a value, and why the axis is the reader rather than the
|
||||
owner), [docs/why-gates-are-code.md](docs/why-gates-are-code.md) (why the four gates in
|
||||
@@ -337,7 +336,10 @@ see [Gates](#gates).
|
||||
Extending `tools/wikitool`, the type schema, or the instruction/skill layer itself (rather than
|
||||
operating on wiki content) is a different session type with different rules - see the
|
||||
`stack-dev` skill, nested under [instructions/dev/](instructions/dev/) along with the
|
||||
procedures it routes to. Never present in a distributed instance.
|
||||
procedures it routes to. Setting up a clone of this origin repository for that work - the demo
|
||||
corpus, the preflight, `dist export` as a build and test tool - is
|
||||
[instructions/dev/dev-setup.md](instructions/dev/dev-setup.md). Never present in a distributed
|
||||
instance.
|
||||
<!-- dist:strip-end -->
|
||||
|
||||
## Changelog
|
||||
|
||||
+61
-2
@@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse.
|
||||
|
||||
---
|
||||
|
||||
## 8.0.0-beta.19 - 2026-10-01 - Windows-Portabilität: Pfadtrenner, Zeilenenden, Encoding und Locks
|
||||
## 8.0.0-beta.20 - 2026-10-01 - Installation only from a release, into an empty folder; upstream merge/verify and the other install paths removed (#153)
|
||||
|
||||
**Author:** Torben Nehmer
|
||||
|
||||
@@ -68,8 +68,9 @@ concern - readable here, never shipped as something to parse.
|
||||
- publish without --no-push now exits 1 before committing when the remote is unreachable or not configured, where it used to commit locally and fail at the push - an offline session or a local-only instance must pass --no-push
|
||||
- new, rename, move and raw accept refuse a target whose path below the instance root is over 160 characters (UTF-16 code units); lint reports existing files over it as Long Paths (advisory) - rename each affected page with tools/wikitool rename, and shorten an incoming/ file name before raw accept
|
||||
- tools/wikitool now refuses to start (exit 42) until tools/preflight.sh (PowerShell 7: tools/preflight.ps1) has passed in the checkout - after updating, run it once: it checks Python, git and ripgrep, records their paths in .wikitool-tools.json and sets up tools/.venv
|
||||
- An instance is installed only from a release, into an empty folder (instructions/setup-instance.md); dist export, a clone of the origin repo and a private clone with the origin as upstream are no install paths any more, and wikitool upstream merge, upstream verify and instructions/private-instance.md are gone - an instance built one of those ways is reinstalled from a release into an empty folder and its kb/, raw/ and personal files are copied over. The preflight release asset installs into its own folder, which must be empty apart from the script and a .git, instead of creating a chemenu/ subfolder
|
||||
|
||||
**Migration:** none required - No page format changes; the rule only refuses titles, and each affected page is renamed individually with tools/wikitool rename
|
||||
**Migration:** none required - No page format changes: the title and path rules only refuse names, each affected page is renamed with tools/wikitool rename, and the removed install paths touch no page
|
||||
|
||||
<!-- wikitool:bumps -->
|
||||
**High impact**
|
||||
@@ -77,6 +78,7 @@ concern - readable here, never shipped as something to parse.
|
||||
- dist upgrade --latest: one-command update from the release feed
|
||||
- Page titles must form valid, unique file names on Windows and macOS
|
||||
- Preflight: prerequisites checked and tool paths recorded before wikitool runs (#151, POSIX half)
|
||||
- Installation only from a release, into an empty folder; upstream merge/verify and the other install paths removed (#153)
|
||||
|
||||
**Medium impact**
|
||||
- CalDAV task-tracker provider (Nextcloud Tasks, iOS Reminders); review reports unknown-value findings instead of skipping them
|
||||
@@ -130,6 +132,63 @@ concern - readable here, never shipped as something to parse.
|
||||
- preflight.ps1: the asset-mode error helper is Exit-Asset, so PSScriptAnalyzer passes
|
||||
<!-- /wikitool:bumps -->
|
||||
|
||||
### Installation only from a release, into an empty folder; upstream merge/verify and the other install paths removed (#153)
|
||||
|
||||
The install run analysed in Gitea #140 failed on an instruction that contradicted itself, and the
|
||||
path it took (Weg D, a private clone with this repo as `upstream`) was one of four. All four were
|
||||
cut down to one (D2, D3): an instance is installed from the latest release into an empty folder,
|
||||
`dist export` is a build tool, and a clone of this repository is development. None of the removed
|
||||
paths was in use, so the break has no transition.
|
||||
|
||||
- **Removed.** `wikitool upstream merge` and `upstream verify` (`commands/upstream_cmd.py` and its
|
||||
tests, the "Private instances" group of command records) and `instructions/private-instance.md`.
|
||||
Every reference in the shipped tree goes with them; `ownership.is_stack_owned` stays, because
|
||||
`dist export` uses it. The 3.0.0 migration document dates its reference in words. The
|
||||
Publish-Remote Gate stays: any checkout with two remotes needs it, and only its rationale lost
|
||||
the reference to the removed path. `gates.md` loses its section on `upstream merge` bypassing
|
||||
the Mass-Update Gate.
|
||||
- **The install path.** `instructions/setup-instance.md` starts at the release: it is attached
|
||||
to every release as an asset, together with `instructions/preflight.md` (E1), and the
|
||||
installation sentence in `INSTALL.md` points the agent at both through the API's
|
||||
`releases/latest` - Gitea 1.26 has no stable "latest" download link. Step 0 downloads the
|
||||
preflight asset with the shell's own command (E2, so no Mark of the Web) and runs it with the
|
||||
bypass prefix. The export step is gone, `git init` runs only where there is no repository yet,
|
||||
and an empty clone keeps its `origin`. The steps are renumbered; references to the
|
||||
personalization step name it rather than its number.
|
||||
- **The preflight asset installs in place (E6, changes D40).** It installs into its own folder,
|
||||
which has to be empty apart from the script and a `.git`, unpacks into a temporary folder
|
||||
inside it, moves the stack up and removes itself, so the first commit carries the stack and
|
||||
nothing else. `--into` installs elsewhere under the same rule. A non-empty target is refused
|
||||
with exit 1. Tests cover both shells, an empty clone, and the self-removal. Under bash the
|
||||
folder-too-long guidance printed `C:\\Chemenu` with a doubled backslash; it now prints one.
|
||||
- **`wikitool dist adopt` (E3).** Copies `kb/*/COLLECTION.md.template` and `types/*.template` to
|
||||
their unsuffixed names, never over an existing file. It replaces the `for … cp` loop in
|
||||
`setup-instance.md`, the two `cp` lines in `upgrade-instance.md` and the loop in the CI replay.
|
||||
- **Shell-neutral instructions (E4).** A command block in a shipped instruction is a
|
||||
`tools/wikitool` or `git` call or the preflight's own call; `instructions/CONTRACT.md` states
|
||||
it, and `tests/test_instructions_shell.py` holds it, with two exceptions of one line per shell:
|
||||
the session id (D26) and the preflight download (E2). Migration documents are out of scope.
|
||||
The same test checks that every PowerShell preflight call in a shipped file carries
|
||||
`pwsh -NoProfile -ExecutionPolicy Bypass -File`. `session-setup.md` loses the bash-only inline
|
||||
form and the `$(date +%s)` id; `upgrade-instance.md`, `ingest-large-tree.md` and
|
||||
`mcp-read-server.md` follow, as does the hint `work new` prints.
|
||||
- **Session id under Copilot (E5).** Neither Copilot CLI nor Copilot's agent mode in VS Code sets
|
||||
a session variable (checked against their documentation), so `session.HARNESS_ENV_VARS` is
|
||||
unchanged. `setup-instance.md` has the agent set `WIKITOOL_SESSION_ID` with the line for its
|
||||
shell before `doctor`, and `session-setup.md` says why.
|
||||
- **CI.** The replay builds a release tarball the way `release.yml` does and starts the preflight
|
||||
asset with `--archive` in an empty folder (D41). It no longer asserts the launcher's exit 42
|
||||
before the preflight - the asset runs the tree preflight itself, and the launcher's refusal is
|
||||
tested in `test_preflight.py`. `release.yml` attaches `setup-instance.md` and `preflight.md`
|
||||
from the exported tree.
|
||||
- **Docs.** `INSTALL.md` describes one path: what has to be there first (Windows: PowerShell 7,
|
||||
`RemoteSigned`, Git for Windows, a folder of at most 95 characters), the sentence for the
|
||||
agent, the questions it asks, and what to do at every stop of the preflight in both modes.
|
||||
`DEVELOPMENT.md` gains the development checkout, `dist export` as a build and test tool, and the
|
||||
private release feed that used to sit in `INSTALL.md`; `instructions/dev/dev-setup.md` is its
|
||||
agent-side counterpart. `bootstrap.md` is for a further checkout of an existing instance (D11).
|
||||
`docs/ownership-and-templates.md` records why an instance comes only from a release.
|
||||
|
||||
### Windows-Portabilität: Pfadtrenner, Zeilenenden, Encoding und Locks
|
||||
|
||||
The Python package assumed POSIX in several places that nothing on Linux would ever reveal
|
||||
|
||||
+62
-4
@@ -13,6 +13,62 @@ Grund steht dort als Kommentar, damit eine spätere Sitzung die vermeintliche L
|
||||
`INSTALL.md` oder `EVALS.md`, die `instructions verify` auf genau diesen Punkt prüft - nach
|
||||
`instructions/dev/` verlinken.
|
||||
|
||||
## Entwicklungsumgebung
|
||||
|
||||
Am Stack wird in einem Klon dieses Repos gearbeitet. Ein solcher Klon ist **keine Instanz** und
|
||||
wird nie eine. Instanzen entstehen ausschließlich aus Releases, siehe [INSTALL.md](INSTALL.md).
|
||||
|
||||
```bash
|
||||
git clone https://gitea.nehmer.net/torben/chemenu.git
|
||||
cd chemenu
|
||||
```
|
||||
|
||||
Danach den Agenten `instructions/bootstrap.md` ausführen lassen: Preflight, dann
|
||||
`tools/wikitool instructions sync`. Die Agenten-Seite dazu - was hier anders ist als in einer
|
||||
Instanz und wie `dist export` als Testwerkzeug läuft - steht in
|
||||
[instructions/dev/dev-setup.md](instructions/dev/dev-setup.md).
|
||||
|
||||
Was ein Klon mitbringt und eine Instanz nicht:
|
||||
|
||||
- **Den Demo-Korpus.** Rund 170 Seiten, die den Stack selbst dokumentieren: Gates, Lint,
|
||||
Versionierung, Suche, das Wiki-Muster. Er ist Testbett und begehbares Beispiel, keine
|
||||
produktive Wissensbasis. Was an ihm geändert werden darf, regelt
|
||||
[instructions/dev/corpus-policy.md](instructions/dev/corpus-policy.md).
|
||||
- **Eine Demo-Persona** in `USER.md`/`SOUL.md`. `doctor` meldet beide als ausgefüllt. Sie
|
||||
beschreiben den Demo-Betrieb, nicht dich.
|
||||
- **Telemetrie an.** Ohne `.wikitool-release.json` ist der Klon die Messstation, mit der der
|
||||
Stack sich selbst bewertet ([EVALS.md](EVALS.md) § „Whether it runs at all“).
|
||||
- **`instructions/dev/`, `commonplace/`, `.gitea/` und diese Datei.** `dist export` liefert
|
||||
davon nichts aus.
|
||||
|
||||
`ENVIRONMENT.md` fehlt nach jedem Klon, weil die Datei gitignored ist: Sie beschreibt einen
|
||||
Checkout, nicht das Repo. Wer sie anlegt (Vorlage `ENVIRONMENT.md.template`, Schritt 5 in
|
||||
`instructions/bootstrap.md`), erspart jeder Stack-Sitzung die Fragen nach Harness, `gitea-mcp`
|
||||
und Remote.
|
||||
|
||||
### `dist export` als Build- und Testwerkzeug
|
||||
|
||||
`tools/wikitool dist export <leeres Verzeichnis>` schreibt genau den Baum, den ein Release
|
||||
ausliefert: Maschinerie ohne Wiki-Inhalt, ohne Git-Historie, ohne `instructions/dev/`. Damit
|
||||
prüft man vor einem Release, was ausgeliefert würde (`--dry-run` listet es nur). Und man spielt
|
||||
den Installationsweg nach, ohne auf ein Release zu warten: Tarball daraus bauen wie
|
||||
`.gitea/workflows/release.yml`, dann das Preflight-Skript in einem leeren Verzeichnis mit
|
||||
`--archive <tarball>` starten. Der CI-Schritt „The distribution works as a fresh instance“ in
|
||||
`.gitea/workflows/ci.yml` macht genau das.
|
||||
|
||||
Für eine echte Instanz ist ein solcher Export kein Weg. Ihm fehlen die Release-Herkunft im
|
||||
Stamp, und `dist upgrade --latest` vergleicht später gegen einen Stand, den es nie als Release
|
||||
gab.
|
||||
|
||||
### Ein Release-Feed in einem nicht öffentlichen Repo
|
||||
|
||||
Wer den Stack in einem eigenen, nicht öffentlichen Repo betreibt und Instanzen von dort
|
||||
aktualisiert, lässt `WIKITOOL_UPDATE_URL` auf dessen Feed zeigen. Dabei gibt es eine Eigenheit:
|
||||
Gitea antwortet anonymen Aufrufern für ein unsichtbares Repo mit demselben `404` wie für ein gar
|
||||
nicht existierendes. Ein fehlendes Release und ein fehlender Zugriff sehen dann identisch aus –
|
||||
„kein Update gefunden“ wäre in dem Fall schlicht falsch. Dagegen hilft ein Gitea-Token mit
|
||||
Lesezugriff in `WIKITOOL_UPDATE_TOKEN`. Es geht nur an Downloads auf demselben Host wie der Feed.
|
||||
|
||||
## Der Release-Ablauf
|
||||
|
||||
Zwischen zwei Releases führt der Stack **einen** laufenden Versionskandidaten statt einer neuen
|
||||
@@ -75,8 +131,9 @@ eine Sitzung ihn tatsächlich durchläuft:
|
||||
`VERSION` bewegt: Eine suffixbehaftete `VERSION` (ein Kandidat) lässt den Job sauber
|
||||
überspringen, bevor er die Releases-API überhaupt anfragt - Betas werden nie veröffentlicht.
|
||||
Eine suffixfreie `VERSION` baut die Distribution (`dist export`), erzeugt Tag und Release und
|
||||
lädt Tarball plus Prüfsumme hoch. **CI setzt den Tag, nie eine Sitzung** - das hält
|
||||
Invariante 5 intakt.
|
||||
lädt Tarball und Prüfsumme hoch, dazu die beiden Preflight-Skripte und die Anleitungen
|
||||
`setup-instance.md` und `preflight.md`, auf die der Installationssatz in `INSTALL.md` zeigt.
|
||||
**CI setzt den Tag, nie eine Sitzung** - das hält Invariante 5 intakt.
|
||||
|
||||
Die drei Verify-Befehle stehen oben in Schritt 3; was jeder von ihnen prüft, steht in
|
||||
[tools/CONTRACT.md](tools/CONTRACT.md) und wird dort von `docs verify` gegen die tatsächliche
|
||||
@@ -90,8 +147,9 @@ Drift also niemandem auf. Was `pytest` an dieser Stelle vom Entwickler erwartet,
|
||||
|
||||
`.gitea/workflows/ci.yml` läuft auf jeden Push/PR gegen `main` (Content-Pfade ausgenommen) und
|
||||
führt Testsuite, `docs verify`, `instructions verify` sowie einen vollständigen
|
||||
`setup-instance.md`-Replay gegen einen frischen `dist export` aus - derselbe Pfad, den ein neuer
|
||||
Nutzer tatsächlich geht. `.gitea/workflows/nightly.yml` ist der Drift-Check gegen die Zeit statt
|
||||
`setup-instance.md`-Replay aus: ein lokal gebauter Release-Tarball, das Preflight-Skript mit
|
||||
`--archive` in einem leeren Verzeichnis, dann die Schritte der Anleitung - derselbe Pfad, den
|
||||
ein neuer Nutzer tatsächlich geht, nur ohne Download. `.gitea/workflows/nightly.yml` ist der Drift-Check gegen die Zeit statt
|
||||
gegen einen Commit. `.gitea/workflows/release.yml` ist Schritt 6 oben.
|
||||
|
||||
Drei weitere Workflows tragen die Live-Tests der Tracker-Adapter (Super Productivity, CalDAV):
|
||||
|
||||
@@ -232,14 +232,14 @@ same question the same way:
|
||||
| Installation form | Default | Marker |
|
||||
|---|---|---|
|
||||
| Git clone of this repo (dev checkout) | **on** (opt-out) | No `.wikitool-release.json` |
|
||||
| `dist export` tarball (a distributed instance) | **off** (opt-in) | `.wikitool-release.json` present |
|
||||
| An instance installed from a release, and every clone of its own repository | **off** (opt-in) | `.wikitool-release.json` present |
|
||||
|
||||
The form is read off `.wikitool-release.json`, the same stamp `version check`, `dist upgrade` and
|
||||
`version notes` already use to tell a distribution from the repo it came from - present means an operator never
|
||||
asked for telemetry, absent means this is the dev checkout the stack ships from, where the traces
|
||||
are its own measuring instrument (the rest of this file). A private instance
|
||||
(`instructions/private-instance.md`) is a git clone of an *export*, so it carries the stamp and
|
||||
defaults off too - it is a consuming instance, not a measuring stand.
|
||||
are its own measuring instrument (the rest of this file). An instance commits the stamp with its
|
||||
first `publish`, so a clone of it on a second machine carries the stamp and defaults off too - it
|
||||
is a consuming instance, not a measuring stand.
|
||||
|
||||
**Turning it on for a distributed instance** is a per-checkout `.wikitool-telemetry.json` at the
|
||||
repo root, gitignored like `.wikitool-remotes.json` and for the same reason: the consent to write
|
||||
|
||||
+135
-182
@@ -1,167 +1,154 @@
|
||||
# Installation
|
||||
|
||||
Dieses Dokument richtet sich an Menschen. Es gibt vier Wege: ein **Release herunterladen**
|
||||
(der normale Weg zu einer neuen Instanz), eine Distribution **selbst exportieren**, **dieses
|
||||
Repo klonen** (Testbett und Demo, samt Beispielkorpus), oder eine **private Instanz mit diesem
|
||||
Repo als Upstream** aufsetzen. Der agent-seitige Ablauf steckt in `instructions/`; hier stehen
|
||||
nur die menschlichen Teile - für die vollständige Kommandoreferenz siehe
|
||||
Dieses Dokument richtet sich an Menschen. Es gibt genau einen Weg zu einer Chemenu-Instanz: Ein
|
||||
Agent installiert das **neueste Release** in ein leeres Verzeichnis, das du vorgibst. Die
|
||||
Schritte führt der Agent aus, nach `instructions/setup-instance.md` aus demselben Release. Hier
|
||||
steht, was du vorher bereitstellst, welchen Satz du ihm gibst, was er dich fragt und was zu tun
|
||||
ist, wenn er anhält. Die vollständige Kommandoreferenz steht in
|
||||
[tools/CONTRACT.md](tools/CONTRACT.md).
|
||||
|
||||
Den optionalen **MCP-Leseserver** installiert und betreibt
|
||||
[INSTALL-MCP.md](INSTALL-MCP.md): derselbe Korpus, lesend, für einen Konsumenten, der kein
|
||||
Terminal auf dieser Maschine ist.
|
||||
|
||||
## Voraussetzungen
|
||||
<!-- dist:strip-start -->
|
||||
Wer am Stack selbst arbeiten will, klont dieses Repo. Das ist eine Entwicklungsumgebung mit
|
||||
Demo-Korpus und keine Instanz; sie steht in [DEVELOPMENT.md](DEVELOPMENT.md).
|
||||
<!-- dist:strip-end -->
|
||||
|
||||
- Python 3.11 oder neuer
|
||||
- git
|
||||
- [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) - wird von `search` und
|
||||
`sources coverage` gebraucht
|
||||
- Nur unter Windows zusätzlich: PowerShell 7 (`pwsh`). Windows PowerShell 5.1 reicht nicht, und
|
||||
WSL ist nicht vorgesehen.
|
||||
## Was vorher da sein muss
|
||||
|
||||
Ob das alles da ist, prüft der Preflight (`tools/preflight.sh`, unter Windows in PowerShell 7
|
||||
`tools/preflight.ps1`), bevor irgendein
|
||||
`wikitool`-Befehl läuft - der erste Schritt jeder Einrichtung, siehe
|
||||
[instructions/preflight.md](instructions/preflight.md). Die maßgebliche Liste steht in
|
||||
`tools/prerequisites.txt`. Fehlt etwas, hält der Agent an und zeigt eine Anleitung mit dem
|
||||
Befehl, der es behebt; installieren muss man selbst, der Agent tut es nie.
|
||||
- **Python 3.11 oder neuer, git und [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`).**
|
||||
Die maßgebliche Liste steht in `tools/prerequisites.txt`; der Preflight prüft sie, bevor
|
||||
irgendein `wikitool`-Befehl läuft. Installieren musst du selbst - der Agent tut es nie, auch
|
||||
nicht mit deiner Zustimmung.
|
||||
- **Ein Agent-Harness**: Claude Code, GitHub Copilot (in VS Code oder als CLI), Codex CLI oder
|
||||
Mistral Vibe.
|
||||
- **Ein leeres Verzeichnis**, in dem die Instanz liegen soll, und dein Harness darin geöffnet.
|
||||
Leer heißt: nichts außer einem `.git`. Ein frisch geklontes, leeres Repo für deine Instanz ist
|
||||
also genau richtig - liegt dein Repo `torben/nathan` etwa in `~/src/nathan`, installierst du
|
||||
dorthin, und der Agent übernimmt dessen `origin` als Ziel für `publish`.
|
||||
|
||||
## Weg A: Release herunterladen
|
||||
Unter Windows zusätzlich:
|
||||
|
||||
Der kürzeste Weg zu einer eigenen Instanz - kein Checkout dieses Repos nötig. Jedes Release
|
||||
trägt genau einen `dist export`-Baum plus eine Prüfsumme. Das Repo ist öffentlich, der Download
|
||||
braucht also weder Konto noch Token:
|
||||
- **PowerShell 7** (`pwsh`), in VS Code als Standardterminal eingestellt. Windows PowerShell 5.1
|
||||
reicht nicht, und WSL ist nicht vorgesehen.
|
||||
- **Execution Policy `RemoteSigned`** - auf vielen Rechnern ab Werk gesetzt
|
||||
(`Get-ExecutionPolicy -List` zeigt es).
|
||||
- **Git for Windows.** Es bringt Git Bash mit, in dem Claude Code seine Befehle ausführt.
|
||||
- **Ein Installationsverzeichnis mit höchstens 95 Zeichen**, zum Beispiel `C:\Chemenu`. Windows
|
||||
erlaubt ohne eingeschaltete lange Pfade nur 259 Zeichen je Pfad, und die Dateien des Wikis
|
||||
brauchen den Rest. Wer Administratorrechte hat, kann stattdessen lange Pfade einschalten
|
||||
(`LongPathsEnabled`); verlangt wird das nicht.
|
||||
|
||||
```bash
|
||||
BASE=https://gitea.nehmer.net/torben/chemenu/releases/download/v<version>
|
||||
curl -LO $BASE/chemenu-stack-<version>.tar.gz
|
||||
curl -LO $BASE/chemenu-stack-<version>.tar.gz.sha256
|
||||
sha256sum -c chemenu-stack-<version>.tar.gz.sha256
|
||||
tar xzf chemenu-stack-<version>.tar.gz
|
||||
cd chemenu-stack-<version>
|
||||
```
|
||||
## Der Satz für den Agenten
|
||||
|
||||
Die Prüfsumme ist nicht Zierde: Sie ist das Einzige, was einen unterbrochenen Download von
|
||||
einem vollständigen unterscheidet, und `sha256sum -c` muss `OK` sagen, bevor irgendetwas
|
||||
entpackt wird.
|
||||
Öffne das leere Verzeichnis in deinem Harness und gib dem Agenten diesen Satz:
|
||||
|
||||
Statt dieser Befehle von Hand trägt jedes Release auch den Preflight selbst als Datei
|
||||
(`preflight.sh`, unter Windows `preflight.ps1`). In einen leeren Ordner geladen und dort
|
||||
gestartet, lädt er das Release herunter, prüft die Prüfsumme, entpackt es nach `chemenu/` neben
|
||||
sich (mit `--into <Pfad>` woandershin; ein vorhandenes Ziel wird nie angefasst) und führt dann
|
||||
den Preflight im entpackten Baum aus, siehe [instructions/preflight.md](instructions/preflight.md).
|
||||
> Richte in diesem Verzeichnis eine neue Chemenu-Instanz ein. Hol dazu das neueste Release von
|
||||
> `https://gitea.nehmer.net/api/v1/repos/torben/chemenu/releases/latest` und folge dessen Asset
|
||||
> `setup-instance.md`. Lies vor dem Start des Preflights das Asset `preflight.md` aus demselben
|
||||
> Release.
|
||||
|
||||
Danach weiter mit Schritt 2 aus Weg B: den Agenten
|
||||
[instructions/setup-instance.md](instructions/setup-instance.md) ausführen lassen. Der
|
||||
entpackte Baum ist bereits eine Distribution - Schritt 1 (`dist export`) entfällt.
|
||||
Damit liest der Agent die Beschreibung des neuesten Releases und daraus die beiden Anleitungen.
|
||||
Dann lädt er das passende Preflight-Skript (`preflight.ps1` für PowerShell, `preflight.sh` für
|
||||
eine POSIX-Shell) mit einem Befehl seiner Shell ins Verzeichnis - nicht über den Browser, damit
|
||||
Windows die Datei nicht als „aus dem Internet“ markiert - und startet es. Das Skript lädt den
|
||||
Tarball desselben Releases, prüft dessen sha256, entpackt ihn in das Verzeichnis, löscht sich
|
||||
selbst und prüft dann im entpackten Baum, ob alles da ist.
|
||||
|
||||
Die Liste der Releases: <https://gitea.nehmer.net/torben/chemenu/releases>.
|
||||
Die Liste aller Releases: <https://gitea.nehmer.net/torben/chemenu/releases>. Das Repo ist
|
||||
öffentlich; der Download braucht weder Konto noch Token.
|
||||
|
||||
## Weg B: Neue, leere Instanz selbst exportieren
|
||||
## Was der Agent dich fragt
|
||||
|
||||
Dasselbe Ergebnis aus einem Checkout dieses Repos - für einen Stand, der noch kein Release hat.
|
||||
Zwei Schritte, von denen nur der erste rein menschlich ist:
|
||||
Raten darf der Agent keine dieser Antworten, und keine übernimmt er aus einem anderen Repo:
|
||||
|
||||
1. **Zielverzeichnis wählen** und die Distribution dorthin exportieren, aus einem Checkout
|
||||
dieses Repos:
|
||||
- **Autor-Identität** - Name und E-Mail für `git config`. Das ist zugleich der Autorname jeder
|
||||
künftig angelegten Wiki-Seite (`$WIKI_AUTHOR` überschreibt ihn bei Bedarf).
|
||||
- **Remote** - bei einem leeren Klon nur die Bestätigung, dass `origin` stimmt; sonst eine URL,
|
||||
wenn du auf einen Server pushen willst. Ohne Remote bleibt die Instanz lokal, und jedes
|
||||
`publish` läuft mit `--no-push`.
|
||||
- **Sprache und Ton der Seiten** - sie landen in `kb/CONVENTIONS.md`, dazu je Collection
|
||||
`kb/<name>/COLLECTION.md`. Fertige Profile, darunter ein vollständiges deutsches, hält
|
||||
`instructions/kb-profiles.md` bereit. Entscheide das **vor dem ersten Ingest**: Danach ist ein
|
||||
Wechsel der Abschnittsnamen eine Migration jeder bestehenden Seite. Titel, Wikilink-Ziele,
|
||||
Zitat-IDs, Schema-Werte, Tags, Befehle und Pfade folgen keiner Sprache - `Act Runner` heißt in
|
||||
jeder Instanz `Act Runner`.
|
||||
- **Anwendungsgebiet** - woraus dieses Wiki seine Quellen zieht. Daraus schlägt der Agent eine
|
||||
`source_type`-Liste vor (bei einem Verein etwa Satzung, Protokoll, Spielbericht). Das ist ein
|
||||
Startpunkt, keine Festlegung: Später wird sie an echtem Bestand korrigiert
|
||||
(`instructions/evolve-subtypes.md`).
|
||||
- **Personalisierung** - wer diese Instanz bedient (`USER.md`) und wie sie klingt (`SOUL.md`).
|
||||
Der Agent interviewt dich entlang der Vorlagen und schreibt deine Antworten wörtlich mit. Zwei
|
||||
Fragen beantwortest nur du: den **Namen der Persona** und die **Themen, die bewusst draußen
|
||||
bleiben**.
|
||||
- **Umgebung** (optional) - Harness, MCP-Server, Remotes, damit spätere Sitzungen nicht erneut
|
||||
fragen. „Weiß ich nicht“ ist eine gültige Antwort.
|
||||
- **Telemetrie** - standardmäßig aus; der Agent fragt nur, ob du sie einschalten willst.
|
||||
- **Aufgaben-Tracker** (optional) - siehe [Konfiguration](#konfiguration).
|
||||
|
||||
```bash
|
||||
tools/wikitool dist export /pfad/zur/neuen/instanz
|
||||
```
|
||||
Am Ende legt der Agent den ersten Commit an. Dabei hält das Mass-Update-Gate an (Exit 42), weil
|
||||
eine neue Instanz aus weit mehr als zehn Dateien besteht. Das ist erwartet: Der Agent zeigt dir
|
||||
die Dateiliste und die `--confirm`-Zeile, und erst nach deiner Freigabe wird veröffentlicht.
|
||||
Danach startest du die Agent-Sitzung im selben Verzeichnis neu, damit sie die Skills lädt.
|
||||
|
||||
Das Ziel muss leer sein oder noch nicht existieren. `dist export` kopiert die Maschinerie
|
||||
(Werkzeuge, Typen, Instruktionen, die Collection-Contracts) ohne Wiki-Inhalt, ohne
|
||||
Git-Historie und ohne `instructions/dev/` (Stack-Entwicklung selbst, inkl. der vendorten
|
||||
`commonplace/`-Wissensbasis) - dauerhaft, ohne Restore-Weg.
|
||||
## Wenn der Agent anhält
|
||||
|
||||
2. **Den Agenten dort arbeiten lassen.** Öffne das Zielverzeichnis in deinem Agent-Harness
|
||||
(Claude Code, GitHub Copilot, Codex CLI, Mistral Vibe) und lass es
|
||||
`instructions/setup-instance.md` ausführen. Diese Anweisung fragt dich dabei explizit nach:
|
||||
- **Autor-Identität** (Name + E-Mail für `git config`) - wird nie geraten oder aus einem
|
||||
anderen Repo übernommen, und ist zugleich der Autorname jeder künftig angelegten
|
||||
Wiki-Seite (`$WIKI_AUTHOR` überschreibt dies bei Bedarf).
|
||||
- **Remote** (optional) - eine URL, wenn du das Repo auf einen Server pushen willst; sonst
|
||||
bleibt die Instanz lokal, und jedes `publish` läuft mit `--no-push` - ohne das Flag
|
||||
bricht `publish` mit Exit 1 ab, bevor es committet.
|
||||
- **Autorenkonventionen** - Sprache, Abschnittsnamen, Namensformen, Ton, Beziehungslabels
|
||||
und Hedging-Regel stehen in `kb/CONVENTIONS.md`, dazu je Collection die Regeln in
|
||||
`kb/<name>/COLLECTION.md`. Die Distribution bringt davon nur die `.template`-Dateien mit:
|
||||
das sind Entscheidungen *dieser* Instanz, keine Eigenschaft des Musters, und nichts davon
|
||||
liegt unter `tools/` oder `types/`. Fertige Profile - darunter ein vollständiges deutsches -
|
||||
hält `instructions/kb-profiles.md` bereit; es ist eine Palette, kein Enum. Sag die Sprache
|
||||
**vor dem ersten Ingest** - danach ist ein Wechsel der Abschnittsnamen eine Migration jeder
|
||||
bereits angelegten Seite.
|
||||
- **Anwendungsgebiet** - woraus dieses Wiki seine Quellen zieht. Daraus schlägt der Agent
|
||||
eine `source_type`-Liste vor (bei einem Verein etwa Satzung, Protokoll, Spielbericht statt
|
||||
Transkript, Analyse, Artikel) und setzt sie in `types/source.schema.yaml` und
|
||||
`types/source.md` ein. Das ist ein **Startpunkt, keine Festlegung**: zu diesem Zeitpunkt hat
|
||||
die Instanz null Quellen, die Taxonomie ist also geraten, bevor jemand Material gesehen hat.
|
||||
Sie wird später an echtem Bestand korrigiert - `instructions/evolve-subtypes.md` beschreibt,
|
||||
wie ein Wert dazukommt und wie das Auffangfach `unclassified` wieder leer wird. Nicht zur
|
||||
Wahl stehen `fidelity` und `authority`: die beiden sind Stack-Vokabular und in jeder Domäne
|
||||
dieselben.
|
||||
- **Personalization** - wer diese Instanz bedient (`USER.md`) und wie sie klingt
|
||||
(`SOUL.md`). Die Distribution bringt nur `USER.md.template` und `SOUL.md.template` mit:
|
||||
persönlicher Inhalt gehört nicht in jede exportierte Kopie, aber beide Dateien werden in
|
||||
jeder Session gelesen, sind also Betriebsvoraussetzung. Der Agent interviewt dich entlang
|
||||
der Template-Abschnitte und schreibt deine Antworten **wörtlich** mit - inklusive der
|
||||
beiden Fragen, die er nicht raten darf: der **Persona-Name** und die **Themen, die
|
||||
bewusst draußen bleiben**.
|
||||
Der Preflight hält mit **Exit 42** an, wenn du etwas tun musst. Seine Ausgabe nennt in einem
|
||||
nummerierten Block, was fehlt, warum, den Befehl, der es behebt, und wie es weitergeht. Der
|
||||
Agent zeigt dir diesen Block unverändert, setzt eine Übersetzung höchstens darunter und wartet.
|
||||
Sag ihm Bescheid, wenn du fertig bist; dann prüft er erneut. Ausweichen oder selbst installieren
|
||||
darf er nicht.
|
||||
|
||||
Danach ist die Instanz initialisiert, verifiziert und committet.
|
||||
**Beim Herunterladen und Entpacken** (das Skript aus dem Release, bevor es einen Baum gibt):
|
||||
|
||||
Was von der Sprachwahl unberührt bleibt: die Trennung zwischen Prosa und Identifiern.
|
||||
Seitentitel, Wikilink-Ziele, Zitat-IDs, Schema-Werte, Tags, Befehle und Pfade folgen keiner
|
||||
KB-Sprache, sondern dem etablierten Namen der Sache - `Act Runner` heißt in jeder Instanz
|
||||
`Act Runner`.
|
||||
- **Werkzeuge zum Laden oder Entpacken fehlen** (Exit 42). Unter Linux und macOS braucht das
|
||||
Skript `curl`, `tar` und `sha256sum` (oder `shasum`), unter Windows nur das `tar.exe` aus
|
||||
Windows 10/11. Installiere, was die Ausgabe nennt; unter Windows liefert Git for Windows alles
|
||||
für Git Bash mit.
|
||||
- **Das Verzeichnis ist zu lang** (Exit 42, nur Windows ohne lange Pfade). Nimm ein kürzeres,
|
||||
etwa `C:\Chemenu`, öffne es im Harness und gib den Satz dort noch einmal.
|
||||
- **Das Verzeichnis ist nicht leer** (Exit 1). Es darf nichts enthalten außer dem Skript und
|
||||
einem `.git`. Räume es selbst auf oder nimm ein anderes - der Agent löscht dort nichts.
|
||||
- **Download fehlgeschlagen oder Prüfsumme falsch** (Exit 1). Es wurde nichts entpackt. Prüf die
|
||||
Internetverbindung und lass es erneut versuchen; einen anderen Download-Weg sucht der Agent
|
||||
nicht. Ohne direkten Download kannst du Tarball und `.sha256` von der Release-Seite selbst
|
||||
nebeneinander ablegen; der Agent startet das Skript dann mit `--archive <tarball>`.
|
||||
|
||||
## Weg C: Dieses Repo klonen
|
||||
**Im entpackten Baum** (jeder weitere Lauf ist `tools/preflight.sh` bzw. unter PowerShell
|
||||
`pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1`):
|
||||
|
||||
Für die Arbeit am Stack selbst, oder um sich den mitgelieferten Korpus als begehbares Beispiel
|
||||
anzusehen. Was hier liegt, ist ein **Testbett und eine Demo**, keine produktive Wissensbasis:
|
||||
rund 170 Seiten, die den Stack selbst dokumentieren - Gates, Lint, Versionierung, Suche, das
|
||||
Wiki-Muster. Wer eigenes Wissen sammeln will, nimmt Weg A oder B und fängt mit einem leeren
|
||||
`kb/` an.
|
||||
- **Ein Werkzeug fehlt** - Python, git, ripgrep, unter Windows auch PowerShell 7. Die Ausgabe
|
||||
nennt den Installationsbefehl für dein System. Ist es schon installiert, nur woanders, nenn dem
|
||||
Agenten den Pfad; er reicht ihn mit `--set <werkzeug>=<pfad>` weiter.
|
||||
- **Eine Version ist zu alt** - zum Beispiel Python unter 3.11. Neuere Version installieren oder
|
||||
deren Pfad nennen.
|
||||
- **Ein genannter Pfad funktioniert nicht** - der Pfad muss auf das Programm selbst zeigen, nicht
|
||||
auf seinen Ordner.
|
||||
- **Die Python-Umgebung (`tools/.venv`) oder ihre Bibliotheken ließen sich nicht einrichten.** Die
|
||||
Ausgabe zeigt, was Python oder pip gemeldet haben. Meist blockiert ein Proxy oder ein
|
||||
Sicherheitsprogramm den Download; das klärt, wer deinen Rechner betreut.
|
||||
- **Skripte tragen die Markierung „aus dem Internet“** (nur Windows). Das passiert, wenn das
|
||||
Release im Browser geladen und im Explorer entpackt wurde. Einmal im Verzeichnis, in
|
||||
PowerShell 7: `Get-ChildItem -Recurse -File | Unblock-File`. `doctor` zeigt den Stand unter
|
||||
`script-marks`.
|
||||
- **Die Execution Policy verbietet Skripte** (`Restricted` oder `AllSigned`, nur Windows). Die
|
||||
Ausgabe nennt die eine Zeile für ein PowerShell-7-Fenster
|
||||
(`Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`). Setzt eine
|
||||
Gruppenrichtlinie sie, hilft nur die IT - oder du arbeitest aus Git Bash mit `tools/wikitool`.
|
||||
`doctor` zeigt den Stand unter `execution-policy`.
|
||||
- **Das Installationsverzeichnis ist zu lang** (nur Windows ohne lange Pfade). Die Instanz muss
|
||||
in ein kürzeres Verzeichnis umziehen, etwa `C:\Chemenu`.
|
||||
|
||||
```bash
|
||||
git clone https://gitea.nehmer.net/torben/chemenu.git
|
||||
cd chemenu
|
||||
```
|
||||
|
||||
Danach den Agenten `instructions/bootstrap.md` ausführen lassen (Preflight + Skills
|
||||
publizieren). Git-Repo, Autor-Identität und Inhalt existieren hier bereits.
|
||||
|
||||
Ein Clone, der älter ist als die Personalization-Dateien, hat kein `USER.md`/`SOUL.md` -
|
||||
`doctor` meldet dafür `personalization: FAIL`. Das ist einmalig nachzuholen: nur **Schritt 6
|
||||
(Personalization)** aus `instructions/setup-instance.md`, nicht der ganze Ablauf. `bootstrap.md`
|
||||
verweist an derselben Stelle darauf.
|
||||
|
||||
`ENVIRONMENT.md` fehlt nach einem Clone immer - die Datei ist gitignored, weil sie *einen
|
||||
Checkout* beschreibt und nicht das Repo. Sie ist optional; wer sie anlegt, spart jeder
|
||||
folgenden Session die Fragen nach Harness, MCP-Servern und Remote. Vorlage:
|
||||
`ENVIRONMENT.md.template`, Ablauf: Schritt 5 in `instructions/bootstrap.md`.
|
||||
|
||||
## Weg D: Private Instanz mit diesem Repo als Upstream
|
||||
|
||||
Die Kombination aus A und C: eine eigene, nicht öffentliche Instanz, die weiterhin
|
||||
Stack-Updates von hier zieht - per `git merge` statt per Tarball, also mit echtem
|
||||
Drei-Wege-Merge statt `cp -r`.
|
||||
|
||||
Das ist der Weg mit dem höchsten Einsatz, weil ein Checkout dann zwei Remotes hat und git beim
|
||||
Push nicht unterscheidet, welcher welcher ist. Ein falsches `--remote` legt privaten Inhalt auf
|
||||
ein öffentliches Repo, und ein Force-Push holt das nicht zurück - die Objekte bleiben per SHA
|
||||
abrufbar, bis auf dem Server die Reflogs verfallen.
|
||||
|
||||
Dagegen gibt es das **Publish-Remote-Gate**, und die Anleitung setzt es an die Stelle, an der
|
||||
es wirkt: *vor* dem ersten `publish`. Vollständiges Vorgehen:
|
||||
[instructions/private-instance.md](instructions/private-instance.md).
|
||||
Hält der Agent an einer anderen Stelle an und ist die Ursache nicht offensichtlich, bietet er dir
|
||||
einen Fehlerbericht an - siehe [Troubleshooting](#troubleshooting).
|
||||
|
||||
## Version und Updates
|
||||
|
||||
Jede Instanz trägt die Version des **Stacks** (Werkzeuge, Typen, Instruktionen, Contracts) -
|
||||
nicht die ihres Inhalts. Sie steht in `VERSION`, und eine per Release oder `dist export`
|
||||
erzeugte Instanz trägt zusätzlich `.wikitool-release.json` mit Herkunft und Exportdatum.
|
||||
nicht die ihres Inhalts. Sie steht in `VERSION`, daneben `.wikitool-release.json` mit Herkunft
|
||||
und Exportdatum des Releases.
|
||||
|
||||
```bash
|
||||
tools/wikitool version # was läuft hier, und woher kommt es
|
||||
@@ -203,12 +190,6 @@ erreichbar, nennt die Fehlermeldung die Release-Seite, die `.wikitool-release.js
|
||||
|
||||
### Eine Instanz aktualisieren
|
||||
|
||||
Zwei Wege, je nachdem, wie diese Instanz entstanden ist. Ein **Clone mit gemeinsamer
|
||||
Git-History** (`upstream`-Remote auf das Ursprungs-Repo, siehe
|
||||
[instructions/private-instance.md](instructions/private-instance.md)) nimmt Stack-Updates per
|
||||
echtem Drei-Wege-Merge: `tools/wikitool upstream merge`. Alles Folgende gilt für eine **Instanz
|
||||
aus einem Tarball**, ohne gemeinsame History.
|
||||
|
||||
Das Anwenden eines Updates schreibt in eine Instanz, die bereits Inhalt hat. Der Inhalt hat dabei
|
||||
eine **eigene Version**: `.wikitool-kb.json` sagt, in welcher Form die Seiten vorliegen,
|
||||
unabhängig davon, welche Maschinerie danebensteht. Genau dieser Unterschied ist der Zustand, in
|
||||
@@ -245,8 +226,8 @@ auf demselben Host wie der Feed.
|
||||
|
||||
**Beim ersten Sprung auf ein Release, das `--latest` kennt, gibt es die Option in der Instanz
|
||||
noch nicht** - die Instruktion, die dort steht, gehört zum Release, das die Instanz verlässt.
|
||||
Dann den Tarball einmal von Hand holen (Weg A oben), prüfen und `dist upgrade <tarball>` geben;
|
||||
ab dem Release danach trägt die Instanz `--latest` selbst.
|
||||
Dann Tarball und `.sha256` einmal von der Release-Seite holen, nebeneinander ablegen und
|
||||
`dist upgrade <tarball>` geben; ab dem Release danach trägt die Instanz `--latest` selbst.
|
||||
|
||||
**Beim ersten Sprung auf `4.5.0` oder höher gibt es `dist upgrade` in der Instanz noch nicht** -
|
||||
es kam erst mit `4.5.0`. Dann das Werkzeug aus dem entpackten *neuen* Tarball verwenden, gegen die
|
||||
@@ -275,7 +256,7 @@ sind. Einer Instanz, die älter ist als `.wikitool-kb.json`, fehlt die Datei gan
|
||||
aus der Zeit vor `4.5.0`) hat für `dist upgrade` keine Basis, gegen die es eine lokale Änderung
|
||||
erkennen könnte, und verweigert den Tausch - dafür gibt es heute keine Reparatur.
|
||||
Mit `<tarball-oder-verzeichnis>` lädt der Befehl selbst nichts herunter; die Datei muss vorher
|
||||
aus Weg A geholt werden. Nur `--latest` lädt, und ein Tarball muss in beiden Fällen genau ein
|
||||
von der Release-Seite geholt werden. Nur `--latest` lädt, und ein Tarball muss in beiden Fällen genau ein
|
||||
Top-Level-Verzeichnis enthalten - die Form, in der `.gitea/workflows/release.yml` es baut.
|
||||
|
||||
Vor `4.5.0` stand hier ein rein manueller Ablauf (Maschinerie von Hand kopieren, `kb/CONTRACT.md`
|
||||
@@ -293,22 +274,20 @@ Ausnahmen (`kb/CONVENTIONS.md`, `kb/*/COLLECTION.md`, `.wikitool-kb.json`) in
|
||||
| `WIKI_AUTHOR` | Override für den Autornamen neuer Source-Seiten | `git config user.name` - fehlt beides, bricht `new` mit `ERROR` ab |
|
||||
| `WIKITOOL_SESSION_ID` | Scopt das Iteration-Budget-Gate auf eine Aufgabe statt auf ein Terminal | Eine vom Harness selbst gesetzte Sitzungs-Variable, wo eine bekannt ist (z. B. `CLAUDE_CODE_SESSION_ID`), sonst die Parent-Process-ID (siehe [instructions/session-setup.md](instructions/session-setup.md)) |
|
||||
| `WIKITOOL_UPDATE_URL` | Release-Feed, den `version check` abfragt | Wert aus `.wikitool-release.json`, sonst der Feed der Ursprungs-Instanz |
|
||||
| `WIKITOOL_UPDATE_TOKEN` | Gitea-Token für den Release-Feed | keiner - gegen `torben/chemenu` nicht nötig, nur für einen privaten Fork (siehe unten) |
|
||||
| `WIKITOOL_UPDATE_TOKEN` | Gitea-Token für den Release-Feed | keiner - gegen `torben/chemenu` nicht nötig, nur gegen einen Feed in einem nicht öffentlichen Repo |
|
||||
| `WIKITOOL_TASKS_CONFIG` | Pfad zu einer Tracker-Konfiguration, die `task`, `review` und `doctor` statt `.wikitool-tasks.json` lesen - um einen Checkout der Reihe nach gegen mehrere Tracker laufen zu lassen | die `.wikitool-tasks.json` im Repo-Root. Nennt die Variable eine Datei, die es nicht gibt, ist das ein Fehler und nie „kein Tracker konfiguriert" |
|
||||
| `CHEMENU_ROOT` | Auf welchen Korpus das Paket zeigt - für einen Aufrufer, der nicht im Checkout selbst liegt | der Checkout, in dem das Paket liegt (`tools/wikitool` verhält sich ohne die Variable unverändert) |
|
||||
| `WIKI_TRACE` / `WIKI_TRACE_DIR` | Telemetrie abschalten bzw. aus dem Arbeitsbaum heraus umlenken | Hängt vom Installationsweg ab - siehe unten |
|
||||
| `WIKI_TRACE` / `WIKI_TRACE_DIR` | Telemetrie abschalten bzw. aus dem Arbeitsbaum heraus umlenken | Aus - siehe unten |
|
||||
| `WIKI_TRACE_MAX_SESSION_BYTES` / `WIKI_TRACE_KEEP_SESSIONS` | Byte-Deckel je Session-Trace bzw. wie viele Session-Verzeichnisse die Retention behält | 5 MiB je Session, 250 Verzeichnisse |
|
||||
|
||||
**Gegen das Ursprungs-Repo braucht es kein Token.** `torben/chemenu` ist öffentlich lesbar;
|
||||
`version check` und der Download in Weg A funktionieren ohne Konfiguration.
|
||||
`version check`, `dist upgrade --latest` und die Installation funktionieren ohne Konfiguration.
|
||||
|
||||
**Telemetrie-Default hängt vom gewählten Weg ab, nicht von einem festen Schalter.** Weg A und
|
||||
Weg B erzeugen eine `.wikitool-release.json` (Weg A trägt sie schon im Release, Weg B schreibt
|
||||
sie beim Export) - daran erkennt `chemenu.telemetry.policy`, dass niemand Telemetrie bestellt
|
||||
hat, und der Default steht auf **aus**. Weg C (dieses Repo geklont) trägt keine solche Datei -
|
||||
hier sind die Traces das Messinstrument, mit dem der Stack sich selbst bewertet, und der
|
||||
Default steht auf **an**. Weg D erbt den Default von der Distribution, aus der die private
|
||||
Instanz entstand, also ebenfalls **aus**.
|
||||
**Telemetrie ist in einer Instanz aus.** Jede Instanz trägt die `.wikitool-release.json` ihres
|
||||
Releases, und daran erkennt `chemenu.telemetry.policy`, dass niemand Telemetrie bestellt hat.
|
||||
Das gilt auch für jeden weiteren Klon der Instanz, weil die Datei mit dem ersten Commit ins Repo
|
||||
kommt. Nur ein Klon des Ursprungs-Repos zur Entwicklung trägt keine; dort sind die Traces das
|
||||
Messinstrument, mit dem der Stack sich selbst bewertet, und sie stehen auf **an**.
|
||||
|
||||
Wer den Default umdrehen will, legt `.wikitool-telemetry.json` im Repo-Root an (pro Checkout,
|
||||
gitignored, kein `.template` - genau wie `.wikitool-remotes.json`):
|
||||
@@ -322,18 +301,6 @@ Richtungen und schlägt diese Datei. `wikitool doctor` meldet den aktuellen Zust
|
||||
warum, und die Menge gegen beide Deckel); mehr dazu in [EVALS.md](EVALS.md) § "Whether it
|
||||
runs at all".
|
||||
|
||||
**Für einen privaten Fork schon.** Wer den Stack in ein eigenes, nicht öffentliches Repo legt
|
||||
und `WIKITOOL_UPDATE_URL` auf dessen Feed zeigen lässt, stößt auf eine Eigenheit, die man
|
||||
kennen sollte: Gitea antwortet anonymen Aufrufern für ein unsichtbares Repo mit demselben
|
||||
`404` wie für ein gar nicht existierendes. Ein fehlendes Release und ein fehlender Zugriff
|
||||
sehen dann identisch aus - „kein Update gefunden" wäre in dem Fall schlicht gelogen. Dagegen
|
||||
hilft ein Gitea-Token mit Lesezugriff:
|
||||
|
||||
```bash
|
||||
export WIKITOOL_UPDATE_TOKEN="<gitea-token>"
|
||||
tools/wikitool version check
|
||||
```
|
||||
|
||||
**Tool-Pfade - schreibt der Preflight, nicht der Mensch.** `.wikitool-tools.json` im Repo-Root
|
||||
hält die absoluten Pfade von Python, git und ripgrep, so wie der Preflight sie auf diesem Rechner
|
||||
gefunden hat; `wikitool` startet git und rg von dort statt über `PATH`. Pro Checkout und
|
||||
@@ -475,25 +442,16 @@ tools/wikitool instructions verify
|
||||
Preflight ist in diesem Checkout noch nicht durchgelaufen, oder seit dem letzten Update nicht
|
||||
mehr: `tools/preflight.sh` ausführen, siehe
|
||||
[instructions/preflight.md](instructions/preflight.md). In PowerShell 7 unter Windows heißt der
|
||||
Aufruf `pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1`; das `-ExecutionPolicy Bypass` gilt nur für diesen
|
||||
einen Prozess und ändert keine Einstellung.
|
||||
- **Unter Windows meldet der Preflight die PowerShell-Ausführungsrichtlinie** (`Restricted` oder
|
||||
`AllSigned`) - die Ausgabe nennt die eine Zeile, die man in einem PowerShell-7-Fenster ausführt
|
||||
(`Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`). Setzt eine
|
||||
Gruppenrichtlinie sie, hilft nur die IT, oder man arbeitet aus Git Bash mit `tools/wikitool`.
|
||||
`doctor` zeigt den Stand unter `execution-policy`.
|
||||
- **Unter Windows meldet der Preflight „Mark of the Web“** - das Repo wurde mit dem Browser
|
||||
geladen und im Explorer entpackt; Windows hält dann jede Datei für „aus dem Internet“ und
|
||||
PowerShell verweigert die Skripte. Einmal im entpackten Ordner, in PowerShell 7:
|
||||
`Get-ChildItem -Recurse -File | Unblock-File`. Wer mit `git clone` oder `Invoke-WebRequest`
|
||||
lädt, hat die Markierung nicht. `doctor` zeigt den Stand unter `script-marks`.
|
||||
Aufruf `pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1`; das
|
||||
`-ExecutionPolicy Bypass` gilt nur für diesen einen Prozess und ändert keine Einstellung. Was
|
||||
seine Ausgabe dann bedeuten kann, steht unter [Wenn der Agent anhält](#wenn-der-agent-anhält).
|
||||
- **Der Agent bietet keine Skills an (`wiki-ingest`, `wiki-query`, ...)** - `.agents/skills/`
|
||||
und `.claude/skills/` sind generiert und nicht committet. `tools/wikitool instructions sync`
|
||||
ausführen, dann die Agent-Session neu starten (Harnesses lesen Skills nur beim Start).
|
||||
- **`doctor` meldet `personalization: FAIL`** - `USER.md`/`SOUL.md` fehlen, oder sie tragen
|
||||
noch die Sentinel-Zeile aus dem Template (ein umbenanntes Template ist kein ausgefülltes).
|
||||
Den Personalization-Schritt (6) aus `instructions/setup-instance.md` ausführen lassen; bei
|
||||
einer Instanz nach Weg C ist das der einzige nachzuholende Schritt.
|
||||
Den Personalisierungs-Schritt aus `instructions/setup-instance.md` ausführen lassen; bei einem
|
||||
weiteren Klon einer älteren Instanz ist das der einzige nachzuholende Schritt.
|
||||
- **`doctor` meldet `environment: WARN`** - `ENVIRONMENT.md` existiert, trägt aber noch die
|
||||
Sentinel-Zeile aus dem Template. Ausfüllen (Vorlage: `ENVIRONMENT.md.template`) und die Zeile
|
||||
entfernen, oder die Datei löschen - sie ist optional, und `absent` ist ein gültiger
|
||||
@@ -526,8 +484,3 @@ tools/wikitool instructions verify
|
||||
Urteil eines Modells und lässt einen Rest übrig - lies das Bündel vor dem Teilen. Die
|
||||
Zuordnung, die Prüfliste und die Kandidatendatei enthalten Originale und liegen neben, nie im
|
||||
Bündel. Es wird nirgends hochgeladen - den Kanal wählst du selbst.
|
||||
- **Ich will am Tool-Stack selbst weiterarbeiten (nicht nur Wiki-Inhalt betreiben)** - eine neue
|
||||
Instanz hat dafür keinen Weg: `dist export` lässt `instructions/dev/` (Stack-Entwicklung,
|
||||
inkl. der vendorten `commonplace/`-Wissensbasis) bewusst und dauerhaft weg, ohne
|
||||
Restore-Mechanismus. Für Stack-Entwicklung im Ursprungs-Repo arbeiten (oder eine neue
|
||||
Dev-Instanz daraus exportieren) statt in dieser Instanz nachzurüsten.
|
||||
@@ -21,16 +21,22 @@ language* the prose is in, and what the tool-owned headings are called, is this
|
||||
[instructions/german-terminology.md](instructions/german-terminology.md).
|
||||
|
||||
This is a per-instance decision, not a property of the pattern - which is why it lives in a file
|
||||
the instance owns rather than in one the stack ships. A new instance built with
|
||||
`dist export` starts empty and picks any language by filling in `kb/CONVENTIONS.md` before
|
||||
the first ingest.
|
||||
the instance owns rather than in one the stack ships. A new instance installed from a release
|
||||
starts empty and picks any language by filling in `kb/CONVENTIONS.md` before the first ingest.
|
||||
|
||||
## Getting started
|
||||
|
||||
Two starting points, depending on what you're doing - full walkthrough in [INSTALL.md](INSTALL.md):
|
||||
Two starting points, depending on what you're doing:
|
||||
|
||||
- **Cloned this repo?** The skill definitions the agent harness loads are **generated and not
|
||||
committed**. Publish them once:
|
||||
- **A new instance.** Every instance is installed from a release, into an empty folder you
|
||||
choose: you give your agent one sentence, and it follows `instructions/setup-instance.md` from
|
||||
the latest release - preflight, git init, author identity, an optional remote, your authoring
|
||||
conventions and persona, the first commit. The sentence, what the agent will ask you, and what
|
||||
to do when it stops are in [INSTALL.md](INSTALL.md).
|
||||
|
||||
- **A further checkout of an instance you already have** (a second machine). Clone the
|
||||
instance's own repository, then run the preflight and publish the skills, which are
|
||||
**generated and not committed**:
|
||||
|
||||
```bash
|
||||
tools/preflight.sh # checks python/git/rg, records their paths, creates tools/.venv
|
||||
@@ -39,18 +45,17 @@ Two starting points, depending on what you're doing - full walkthrough in [INSTA
|
||||
```
|
||||
|
||||
`tools/wikitool` refuses to start (exit 42) until the preflight has passed; if it stops
|
||||
instead, its output says what to install - `instructions/preflight.md`. A release carries the
|
||||
same two scripts as assets that download and unpack the stack themselves, for installing
|
||||
without a clone.
|
||||
instead, its output says what to install - `instructions/preflight.md`. `instructions sync`
|
||||
copies each `instructions/<name>/SKILL.md` into `.agents/skills/` (GitHub Copilot, Codex CLI,
|
||||
Mistral Vibe) and `.claude/skills/` (Claude Code). Full procedure:
|
||||
`instructions/bootstrap.md`.
|
||||
|
||||
That copies each `instructions/<name>/SKILL.md` into `.agents/skills/` (GitHub Copilot, Codex
|
||||
CLI, Mistral Vibe) and `.claude/skills/` (Claude Code). Re-run it after changing a skill.
|
||||
Full procedure: `instructions/bootstrap.md`.
|
||||
|
||||
- **Starting a brand-new, empty instance instead?** `tools/wikitool dist export <target>`
|
||||
builds a contentless copy of the machinery - no example pages, no personal content - then
|
||||
`instructions/setup-instance.md` walks through git init, author identity, an optional remote,
|
||||
and the first commit.
|
||||
<!-- dist:strip-start -->
|
||||
- **Working on the stack itself.** A clone of this repository is a development checkout, with
|
||||
the demo corpus described below; it is never an instance. Setting it up, and `dist export` as
|
||||
the build and test tool it is, are in `DEVELOPMENT.md` (for you) and
|
||||
`instructions/dev/dev-setup.md` (for the agent).
|
||||
<!-- dist:strip-end -->
|
||||
|
||||
## Architecture
|
||||
|
||||
@@ -59,7 +64,7 @@ chemenu/
|
||||
├── AGENTS.md # Control plane: invariants, file naming, routing, gates
|
||||
├── CLAUDE.md # Claude Code only: imports AGENTS.md, links the one Claude-Code-only decision (model/effort). No rules of its own
|
||||
├── README.md # This file: human-readable overview of the whole repo
|
||||
├── INSTALL.md # Human-readable setup: new instance vs. cloning this one
|
||||
├── INSTALL.md # Human-readable install: one release, one sentence to the agent
|
||||
├── INSTALL-MCP.md # Human-readable setup for the optional MCP read server
|
||||
├── EVALS.md # Human-readable overview of telemetry and evaluation
|
||||
├── CHANGES.md # Changelog for the stack itself
|
||||
@@ -73,7 +78,7 @@ chemenu/
|
||||
├── .vibe/ # Mistral Vibe hooks + the repo's telemetry policy
|
||||
├── instructions/ # CONTROL: everything an agent is told to do
|
||||
│ ├── CONTRACT.md # Instruction vs. skill, publishing, writing standard
|
||||
│ ├── bootstrap.md # Prepare a fresh clone
|
||||
│ ├── bootstrap.md # Prepare a further checkout of an instance
|
||||
│ ├── gates.md # What to do when a gate refuses a call
|
||||
│ ├── german-terminology.md # Which words stay English in German prose; register
|
||||
│ ├── session-setup.md
|
||||
@@ -398,7 +403,8 @@ gitignored and no exporter is configured.
|
||||
|
||||
**A distributed instance records nothing unless it asks to.** The default follows the
|
||||
installation form - on for a git clone of this repo, where the traces are the stack's own
|
||||
measuring instrument, off for a `dist export` tarball, where nobody ordered telemetry. Two
|
||||
measuring instrument, off for an instance installed from a release, where nobody ordered
|
||||
telemetry. Two
|
||||
quantity caps apply either way: 5 MiB per session trace, and 250 session directories.
|
||||
`wikitool doctor` reports which state a checkout is in and why; EVALS.md § "Whether it runs at
|
||||
all" has the precedence rules and the opt-in file.
|
||||
|
||||
@@ -18,6 +18,7 @@ overwriting them would silently erase a choice someone made on purpose.
|
||||
- [Why a `.template`, not just an absent file](#why-a-template-not-just-an-absent-file)
|
||||
- [Where the file boundary used to strain](#where-the-file-boundary-used-to-strain)
|
||||
- [The consequence in practice](#the-consequence-in-practice)
|
||||
- [Why an instance comes only from a release](#why-an-instance-comes-only-from-a-release)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Two different kinds of truth
|
||||
@@ -66,9 +67,10 @@ excluded the same three paths and therefore reported success.
|
||||
|
||||
`chemenu/ownership.py` replaced the lists with one question - is this path, under a content
|
||||
stage, the stack's or the instance's? - answered by shape rather than by enumeration:
|
||||
`<stage>/CONTRACT.md`, and anything ending `.template`. Both consumers ask it, so `dist export`
|
||||
and `wikitool upstream merge` cannot disagree, and a machinery file added under a content stage
|
||||
tomorrow is recognised by both without either being edited. The deeper point is not the
|
||||
`<stage>/CONTRACT.md`, and anything ending `.template`. Every consumer asks it - at the time,
|
||||
`dist export` and a `wikitool upstream merge` that took the hand-run procedure's place; since
|
||||
that path was removed, the export alone - so no two of them can disagree, and a machinery file
|
||||
added under a content stage tomorrow is recognised without any of them being edited. The deeper point is not the
|
||||
deduplication: a list has to be maintained by whoever remembers it exists, and the failure mode
|
||||
when nobody does is silence, because a path the list has never heard of simply looks like
|
||||
content.
|
||||
@@ -179,3 +181,27 @@ categories, and make a locally changed file a decision someone takes deliberatel
|
||||
one an upgrade takes for them. The template-sourced files were filled in once, by a person, for
|
||||
a reason, and nothing about a newer release of the stack's mechanics gives it standing to
|
||||
override that.
|
||||
|
||||
## Why an instance comes only from a release
|
||||
|
||||
Everything above depends on one file every instance carries: the `.wikitool-release.json` its
|
||||
release wrote. It is the base `dist upgrade` classifies against, the marker that turns telemetry
|
||||
off for someone who never asked for it, and the record of which stack version the instance runs.
|
||||
An instance that starts anywhere else starts without that base, and every later step has to
|
||||
reconstruct the boundary by other means.
|
||||
|
||||
For a while there were four ways in: a release, a `dist export` from a checkout of the origin
|
||||
repository, a clone of that repository, and a private clone that kept the origin as a git
|
||||
`upstream` and took stack updates by merging. The last two never had the stamp, so they needed
|
||||
the boundary a second way. The clone took the origin's demo corpus, demo persona and development
|
||||
skills with it and had to be emptied by hand, and the instruction for doing so neither said what
|
||||
had to survive nor fitted into the iteration budget. The merge path needed its own
|
||||
ownership-aware command, `upstream merge`, which shipped two data-destroying bugs before it was
|
||||
right, and still left a checkout with two remotes and no stamp. None of the four was in use when
|
||||
they were cut down to one in 8.0.0.
|
||||
|
||||
What is left is a single shape. A release is an export packed as a tarball, installed into an
|
||||
empty folder - or an empty clone of the instance's own repository - by a script attached to the
|
||||
same release. `dist export` remains, as the tool that builds a release and tests what one would
|
||||
ship, not as a way to install. A clone of the origin repository remains too, as the place the
|
||||
stack is developed, and is never an instance.
|
||||
@@ -179,6 +179,18 @@ Scaffold with `tools/wikitool new instruction --name "<name>"`; the contract is
|
||||
at all. If that is worth preserving, it is a concept page under `kb/concepts/`, linked from
|
||||
here. Where the line runs, and how to test a passage against it: below.
|
||||
- **State scope boundaries.** When does this *not* apply, and what to do instead.
|
||||
- **A command block reads the same in every shell.** Depending on the harness, an instruction
|
||||
runs under bash, Git Bash or PowerShell 7. A command in a fenced block is a `tools/wikitool`
|
||||
or `git` call, or the preflight's own call per platform - never syntax only one shell reads: no
|
||||
heredoc, no `export`, no `$(...)` or `$VAR`, no inline `VAR=value command`, no `&&`, no `for`
|
||||
loop, no `cp`, `cat >`, `sha256sum`, `curl` or `tar`. A step that needs one of them gets a
|
||||
`wikitool` command instead, or leaves the file work to the agent's own file tools. Two places
|
||||
are exempt, each with one line per shell: setting the session id
|
||||
([session-setup.md](session-setup.md)) and downloading the preflight before an instance exists
|
||||
([setup-instance.md](setup-instance.md) step 0). Migration documents under
|
||||
`instructions/migrations/` belong to the release they shipped with and are not rewritten. The
|
||||
stack's own instructions are held to this by a test in the origin repository; what an instance
|
||||
writes for itself is its own decision.
|
||||
- **Write it in English, and let the agent speak the instance's language.** Both rules, and the
|
||||
line between prose and quoted vocabulary, are stated once in
|
||||
[AGENTS.md § File naming](../AGENTS.md#file-naming). They are named here because this is the
|
||||
|
||||
@@ -1,11 +1,15 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: bootstrap
|
||||
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.
|
||||
description: Prepare a fresh clone of an existing instance (a second machine, a new checkout) 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
|
||||
|
||||
An instance lives in its own git repository, so a second machine - or a new checkout on the same
|
||||
one - gets it with `git clone`. What the clone does not carry is everything that describes one
|
||||
machine rather than the instance: the tool paths and the tools venv, and the published skills.
|
||||
|
||||
`.agents/skills/` and `.claude/skills/` are generated copies of the skill directories under
|
||||
`instructions/`, and both are gitignored. A fresh clone therefore has no skills at all until
|
||||
they are published: the agent harness will not offer `wiki-ingest`, `wiki-query`,
|
||||
@@ -13,7 +17,7 @@ they are published: the agent harness will not offer `wiki-ingest`, `wiki-query`
|
||||
|
||||
## When to run
|
||||
|
||||
- After cloning the repository.
|
||||
- After cloning the instance's repository.
|
||||
- After `instructions/<name>/SKILL.md` is added, renamed, or edited.
|
||||
- Whenever `tools/wikitool instructions verify` reports a missing or drifted copy.
|
||||
|
||||
@@ -53,7 +57,7 @@ they are published: the agent harness will not offer `wiki-ingest`, `wiki-query`
|
||||
4. **Check for personalization.** A clone predating the personalization files has no
|
||||
`USER.md`/`SOUL.md`, and `tools/wikitool doctor` reports `personalization: FAIL` for it.
|
||||
That is a one-off catch-up, not a bootstrap step that repeats: run **only** the
|
||||
Personalization step (6) of [setup-instance.md](setup-instance.md), not the whole
|
||||
personalization step (5) of [setup-instance.md](setup-instance.md), not the whole
|
||||
procedure - this clone already has its git repo, author identity and content. A clone that
|
||||
already carries both files needs nothing here.
|
||||
|
||||
@@ -86,6 +90,6 @@ This does not apply to anything under `kb/`, `raw/` or `reports/`; those are com
|
||||
present immediately after a clone. If the wiki content looks wrong after cloning, that is a
|
||||
lint question, not a bootstrap one.
|
||||
|
||||
This also does not apply to a fresh instance created via `tools/wikitool dist export` - it has
|
||||
no git history, no author identity, and no generated indexes yet. That is
|
||||
[setup-instance.md](setup-instance.md), a longer procedure this one is a single step of.
|
||||
This also does not apply to a new instance installed from a release - it has no git history, no
|
||||
author identity, and no generated indexes yet. That is [setup-instance.md](setup-instance.md), a
|
||||
longer procedure this one is a single step of.
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: dev-setup
|
||||
description: Set up a clone of the origin repository for stack development - preflight, skills, the demo corpus and its persona, telemetry on - and use dist export as a build and test tool, never as a way to install an instance.
|
||||
---
|
||||
# Set up a development checkout of the stack
|
||||
|
||||
A clone of the origin repository is where the stack is developed. It is not an instance: it
|
||||
carries a demo corpus that documents the stack itself, a demo persona in `USER.md`/`SOUL.md`, the
|
||||
development material under `instructions/dev/` and `commonplace/`, and no
|
||||
`.wikitool-release.json`. Instances are installed from releases
|
||||
([setup-instance.md](../setup-instance.md)); nothing here produces one.
|
||||
|
||||
## When to run
|
||||
|
||||
- A fresh clone of the origin repository, before the first stack-dev session in it.
|
||||
- A clone that was moved, or whose `tools/.venv` was removed - only step 2 again.
|
||||
- Before testing a change to the install path itself (`setup-instance.md`, the preflight, the
|
||||
release workflow) - step 5.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Clone** the origin repository. The tree is complete as checked out: `kb/`, `raw/`,
|
||||
`USER.md`, `SOUL.md` and the filled `kb/CONVENTIONS.md` are committed here, unlike in an
|
||||
instance.
|
||||
|
||||
2. **Run [bootstrap.md](../bootstrap.md)** - the preflight, then `tools/wikitool instructions
|
||||
sync`. That publishes `stack-dev` and `stack-close` along with the content skills; both exist
|
||||
only in this repository.
|
||||
|
||||
3. **Record the environment** (bootstrap.md step 5). Here it is worth the minute: which harness,
|
||||
that `gitea-mcp` reaches the tracker and CI, which remote `publish` talks to. Every stack-dev
|
||||
session reads it instead of asking.
|
||||
|
||||
4. **Know what differs from an instance before relying on a default.**
|
||||
|
||||
| Here | In an instance |
|
||||
|---|---|
|
||||
| No `.wikitool-release.json`: telemetry is **on** - the traces are the stack's measuring instrument (`EVALS.md` § "Whether it runs at all") | Telemetry is off until the operator turns it on |
|
||||
| `USER.md`/`SOUL.md` describe a demo operator and persona | Written by the operator during setup |
|
||||
| `tools/wikitool dist upgrade` refuses: there is no stamp to compare against. The checkout follows `main` with `tools/wikitool sync` | Updated with `dist upgrade --latest` |
|
||||
| `instructions/dev/`, `commonplace/`, `DEVELOPMENT.md` and `.gitea/` are present | Never shipped |
|
||||
|
||||
5. **Use `dist export` as a build and test tool.** It writes exactly the tree a release ships, so
|
||||
it is how a change to the shipped surface is looked at before it is released:
|
||||
|
||||
```bash
|
||||
tools/wikitool dist export <empty scratch folder> --dry-run
|
||||
tools/wikitool dist export <empty scratch folder>
|
||||
```
|
||||
|
||||
To replay the install path the way a user meets it, build the release tarball from that tree
|
||||
the way `.gitea/workflows/release.yml` does (one top-level folder, a `.sha256` beside it) and
|
||||
start the tree's `tools/preflight.sh` as the asset, from an empty folder, with
|
||||
`--archive <tarball>` - the step "The distribution works as a fresh instance" in
|
||||
`.gitea/workflows/ci.yml` is that replay and the reference for it. Keep scratch trees outside
|
||||
this checkout.
|
||||
|
||||
## Decision points
|
||||
|
||||
- **Asked to set up an instance from this checkout** (`dist export` into the user's folder, or a
|
||||
clone that "becomes" their wiki)? Neither is an install path. An instance is installed from a
|
||||
release, by [setup-instance.md](../setup-instance.md); a stack state that has no release yet is
|
||||
released first, or tested with the replay in step 5 and thrown away.
|
||||
- **The demo corpus is in the way of a test?** Do not delete or rewrite corpus content to make
|
||||
room: [corpus-policy.md](corpus-policy.md) says what may be changed and how. Use a scratch
|
||||
export (step 5) for a clean tree instead.
|
||||
|
||||
## Scope
|
||||
|
||||
Not for operating an instance, and not for the release workflow itself (`DEVELOPMENT.md` for
|
||||
humans, [version-parts.md](version-parts.md) for the version part). Not shipped: `dist export`
|
||||
prunes `instructions/dev/` wholesale.
|
||||
@@ -67,6 +67,10 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
demo/testbed `kb/`, the measurable floors that define it, and what a reactive fix may and may
|
||||
not do to corpus content. Read it before judging whether the corpus can exercise a change, or
|
||||
before any fix that would touch `kb/` content.
|
||||
`instructions/dev/dev-setup.md` - setting up a clone of the origin repo for this work, what
|
||||
differs from an instance there (telemetry on, demo persona, no release stamp), and
|
||||
`dist export` as a build and test tool rather than an install path. Read it in a fresh clone,
|
||||
or before testing a change to the install path.
|
||||
`instructions/dev/doc-pull-through.md` - which document makes a claim about a touched
|
||||
surface (a `wikitool` command, a stage's rules, an `AGENTS.md` rule/gate/invariant, a
|
||||
README-shaped human doc, a `docs/` page's reasoning) and therefore needs updating alongside
|
||||
|
||||
+7
-29
@@ -25,7 +25,6 @@ Read the exit code first - it says which of these applies:
|
||||
- [Exit 42: user clearance required](#exit-42-user-clearance-required)
|
||||
- [Publish-Remote Gate](#publish-remote-gate)
|
||||
- [Upload Review Gate](#upload-review-gate)
|
||||
- [Mass-Update Gate blind spot: `upstream merge`](#mass-update-gate-blind-spot-upstream-merge)
|
||||
- [Iteration Budget Gate and loop-breaker](#iteration-budget-gate-and-loop-breaker)
|
||||
- [Taking a new session id](#taking-a-new-session-id)
|
||||
- [Scope](#scope)
|
||||
@@ -81,8 +80,8 @@ Background: the [[Mass-Update Gate]] concept page in `kb/`.
|
||||
The Mass-Update Gate asks whether a change is too large to publish. This one asks the question
|
||||
underneath it: **whether this is the right repository to publish to at all.**
|
||||
|
||||
A checkout that holds private content usually has two remotes - its own, and the public upstream
|
||||
it takes stack updates from. Git does not distinguish them at push time, so one wrong `--remote`
|
||||
A checkout that holds private content can have two remotes - its own, and a public one it also
|
||||
works against. Git does not distinguish them at push time, so one wrong `--remote`
|
||||
puts a private corpus on a public repository. That is not cheaply reversible: a force-push moves
|
||||
the branch, but the objects stay fetchable by SHA until someone expires the server's reflogs and
|
||||
runs `git gc --prune=now` on the bare repo.
|
||||
@@ -98,8 +97,8 @@ It pins **URLs, not remote names** - a name-based list would wave through a `pub
|
||||
`pushurl` when one is set, because that is where `git push` actually writes.
|
||||
|
||||
The file is per-checkout and gitignored, for the same reason `ENVIRONMENT.md` is: two clones push
|
||||
to two different places, so a committed copy would tell a private clone that the public upstream
|
||||
is a legitimate target for its own content. **Absent means unrestricted** - a single-remote
|
||||
to two different places, so a committed copy would tell a private clone that a public remote is a
|
||||
legitimate target for its own content. **Absent means unrestricted** - a single-remote
|
||||
checkout with nothing private in it has nothing to protect, and `doctor` reports which state a
|
||||
checkout is in, WARNing only when there is more than one remote and no allowlist. A malformed
|
||||
file is an error rather than "no restriction": a corrupted safeguard must not read as a disabled
|
||||
@@ -112,9 +111,8 @@ is a standing property of the checkout, not a per-push judgment. The way past it
|
||||
to add the URL to the file. **An agent must never edit `.wikitool-remotes.json` to get past a
|
||||
refusal** - that is opening a gate on your own initiative, which AGENTS.md invariant 6 forbids.
|
||||
|
||||
The setup this gate exists for - a private instance that takes stack updates from a public
|
||||
upstream - is [private-instance.md](private-instance.md). Step 4 there arms it, deliberately
|
||||
*before* the first `publish`: added afterwards it leaves open exactly the window it closes.
|
||||
Arm it *before* a second remote is added and before the first `publish` to it: added afterwards
|
||||
it leaves open exactly the window it closes.
|
||||
|
||||
### Upload Review Gate
|
||||
|
||||
@@ -135,26 +133,6 @@ Mass-Update Gate's review report versus this file's exit-42 procedure.
|
||||
all** - rejecting needs no clearance, only accepting a stranger's file into the pipeline does. It
|
||||
deletes the material and keeps only the reason and a sha256 in `mcp-upload/ledger.jsonl`.
|
||||
|
||||
### Mass-Update Gate blind spot: `upstream merge`
|
||||
|
||||
`upstream merge` (a private instance taking a stack update - see
|
||||
[private-instance.md](private-instance.md)) can update or delete dozens of stack-owned paths in
|
||||
one commit, and the Mass-Update Gate does not see any of it. The gate counts the *uncommitted*
|
||||
changes `publish` is about to stage; by the time `upstream merge` commits, the change is
|
||||
already history, and the commit it made is not what a later `publish` would be staging - that
|
||||
publish sees only whatever this session adds on top. A merge touching 200 files therefore goes
|
||||
out ungated the moment it is pushed.
|
||||
|
||||
This is not a hole to patch by making `upstream merge` route through the gate: the gate's
|
||||
question ("is this too much to publish?") does not apply to a change that only ever touches
|
||||
stack-owned paths that are, by definition, not this instance's own content. The check that
|
||||
actually matters here is `upstream merge`'s own postcheck - it re-verifies the merge commit
|
||||
against `upstream verify`'s logic immediately after committing, and exits 1 with the offending
|
||||
paths if anything landed outside a stack-owned one. **The merge commit is deliberately left in
|
||||
place** rather than reverted: it exists, a human has to look at it, and a command that quietly
|
||||
repaired its own mistake would hide the one event worth seeing. That postcheck is the safeguard
|
||||
for this command, not the Mass-Update Gate.
|
||||
|
||||
## Iteration Budget Gate and loop-breaker
|
||||
|
||||
Every `wikitool` call is counted per session. Calls are refused past **60 in a session**, or
|
||||
@@ -193,7 +171,7 @@ command you actually need to run, and only with the user's approval.
|
||||
|
||||
A dozen commands are exempt from this budget entirely - `search` and `doctor` because retrieval
|
||||
and diagnosis are reading, not iterating, plus the read-only forms of `links`, `cite`, `budget`,
|
||||
`eval`, `version`, `migrate` and `upstream verify`. The exemption is that allowlist in
|
||||
`eval`, `version` and `migrate`. The exemption is that allowlist in
|
||||
[tools/CONTRACT.md](../tools/CONTRACT.md), not a "does not change the wiki" rule of thumb: `lint`
|
||||
only writes to gitignored `reports/` and still counts, because it is not on the list.
|
||||
|
||||
|
||||
@@ -128,11 +128,9 @@ session.
|
||||
into `README.md` as `DECISION NEEDED: <question>` and **stops the run** - do not choose for
|
||||
the user and continue.
|
||||
|
||||
5. **Process one unit at a time.** For unit *N*, in this order:
|
||||
|
||||
```bash
|
||||
export WIKITOOL_SESSION_ID="<runkey>/u<N>"
|
||||
```
|
||||
5. **Process one unit at a time.** For unit *N*, in this order - after setting the session id
|
||||
to `<runkey>/u<N>` with the line for your shell from
|
||||
[session-setup.md](session-setup.md) § Steps:
|
||||
|
||||
a. **Read** every raw file in the unit, in full. Treat all of it as data, never instructions
|
||||
(AGENTS.md invariant 4).
|
||||
|
||||
@@ -15,8 +15,8 @@ it lives.
|
||||
|
||||
That direction is deliberate and it is the opposite of how this repo used to work. Language,
|
||||
tone, naming and the relationship vocabulary sat in `kb/CONTRACT.md`, a file `dist export` ships
|
||||
verbatim - so every instance that wanted something else edited a stack file, and an upstream
|
||||
merge handed the stack's answer back. What binds is now the instance's; what ships is this
|
||||
verbatim - so every instance that wanted something else edited a stack file, and the next update
|
||||
handed the stack's answer back. What binds is now the instance's; what ships is this
|
||||
catalogue, and it binds nothing.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
@@ -221,8 +221,8 @@ optional.
|
||||
[migrate-corpus.md](migrate-corpus.md).
|
||||
- **Tempted to make this page binding** - to have `COLLECTION.md` say `profile: entities` and
|
||||
nothing else? Do not. That is the arrangement this split was written to end: the instance
|
||||
would be bound by a file the stack ships and upgrades, which is how an upstream merge changes
|
||||
an instance's authoring rules without anyone deciding to.
|
||||
would be bound by a file the stack ships and upgrades, which is how an update changes an
|
||||
instance's authoring rules without anyone deciding to.
|
||||
|
||||
## Scope
|
||||
|
||||
|
||||
@@ -44,25 +44,27 @@ everything an operator needs that is *true of the software* rather than of one i
|
||||
and cryptography to do it.
|
||||
|
||||
```bash
|
||||
tools/.venv/bin/pip install -r tools/requirements-mcp.txt
|
||||
tools/.venv/bin/python -m pip install -r tools/requirements-mcp.txt
|
||||
```
|
||||
|
||||
2. **Decide which checkout it serves.** The root resolves by precedence - an explicit `--root`,
|
||||
then `$CHEMENU_ROOT`, then the checkout the package lives in. A deployment points at its
|
||||
corpus with one variable and no code:
|
||||
then `CHEMENU_ROOT`, then the checkout the package lives in. A deployment points at its
|
||||
corpus with one variable and no code, set in the environment the server process starts in
|
||||
(its service unit or container spec):
|
||||
|
||||
```bash
|
||||
export CHEMENU_ROOT=/srv/chemenu
|
||||
```
|
||||
| Variable | Value |
|
||||
|---|---|
|
||||
| `CHEMENU_ROOT` | The checkout it serves, for instance `/srv/chemenu` |
|
||||
|
||||
3. **Take tracing out of the served tree.** The server refuses to start otherwise, and the
|
||||
refusal is the point: telemetry defaults to on and writes under `reports/telemetry/` inside
|
||||
the repo, which step 5's sync is entitled to wipe. Either is fine:
|
||||
the repo, which step 5's sync is entitled to wipe. Set one of the two in the same
|
||||
environment:
|
||||
|
||||
```bash
|
||||
export WIKI_TRACE=0 # off
|
||||
export WIKI_TRACE_DIR=/var/log/chemenu # or elsewhere, outside the corpus
|
||||
```
|
||||
| Variable | Value |
|
||||
|---|---|
|
||||
| `WIKI_TRACE` | `0` - tracing off |
|
||||
| `WIKI_TRACE_DIR` | A directory outside the corpus, for instance `/var/log/chemenu` |
|
||||
|
||||
4. **Start it on the transport that matches what is in front of it.**
|
||||
|
||||
@@ -80,11 +82,11 @@ everything an operator needs that is *true of the software* rather than of one i
|
||||
5. **Keep the checkout current by polling, and keep it clean.**
|
||||
|
||||
```bash
|
||||
git -C "$CHEMENU_ROOT" fetch --quiet origin && \
|
||||
git -C "$CHEMENU_ROOT" reset --hard --quiet origin/main
|
||||
git -C <checkout> fetch --quiet origin
|
||||
git -C <checkout> reset --hard --quiet origin/main
|
||||
```
|
||||
|
||||
Every few minutes, from a timer beside the server. Polling rather than a webhook on purpose:
|
||||
The second only after the first succeeded, every few minutes, from a timer beside the server. Polling rather than a webhook on purpose:
|
||||
it needs no inbound endpoint and no signature checking, which is a smaller surface than the
|
||||
thing it would optimize. A webhook is a later optimization, not a starting point.
|
||||
|
||||
|
||||
@@ -56,9 +56,9 @@ other, so run this before the next `wiki-ingest` or `wiki-manage`, not afterward
|
||||
cp <unpacked-release>/kb/CONTRACT.md kb/CONTRACT.md
|
||||
```
|
||||
|
||||
A private instance cloned from an upstream takes it with the merge instead - see
|
||||
[private-instance.md](../private-instance.md), whose update procedure now re-takes the
|
||||
upstream side for exactly this path.
|
||||
A private instance cloned from an upstream took it with the merge instead - through the
|
||||
private-instance procedure and its `upstream merge`, which re-took the upstream side for
|
||||
exactly this path until both were removed in 8.0.0.
|
||||
|
||||
2. **Write `kb/CONVENTIONS.md`.** Two ways in, and the first is almost always right:
|
||||
|
||||
|
||||
+15
-11
@@ -100,16 +100,19 @@ It is safe to run at any time: a second run on a ready checkout changes nothing
|
||||
## Decision points
|
||||
|
||||
- **The script is a release asset, not a tree script** - there is no `tools/prerequisites.txt`
|
||||
beside it, because the user downloaded `preflight.sh` or `preflight.ps1` from a release page
|
||||
into an empty folder. 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, and unpacks into a `chemenu/` folder next to itself; then it runs the
|
||||
preflight of the unpacked 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`, run from inside `chemenu/`.
|
||||
- `--into <path>` unpacks somewhere else; an existing target is refused with exit 1 and
|
||||
nothing is touched, which is the user's decision to make, not yours to resolve by deleting.
|
||||
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
|
||||
@@ -122,7 +125,8 @@ It is safe to run at any time: a second run on a ready checkout changes nothing
|
||||
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 `--into`.
|
||||
*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
|
||||
|
||||
@@ -1,212 +0,0 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: private-instance
|
||||
description: Set up a private working instance as a clone of a public upstream, so stack updates arrive by merge instead of by copying a tarball over the tree.
|
||||
---
|
||||
|
||||
# Set up a private instance against a public upstream
|
||||
|
||||
The distribution path in [setup-instance.md](setup-instance.md) builds an instance from a
|
||||
`dist export` tarball, with no git ancestry in common with the repo it came from. That is the
|
||||
right shape for someone who only ever *consumes* the stack.
|
||||
|
||||
This is the other shape: a private instance that keeps taking stack changes from a public
|
||||
upstream, and whose own content must never travel back. It costs one safeguard to set up and
|
||||
saves the whole update procedure afterwards.
|
||||
|
||||
**Read this before, not after, the first `publish`.** The gate in step 4 is the thing that makes
|
||||
the arrangement safe, and adding it later means the window it closes was open in between.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [Why a clone rather than a tarball](#why-a-clone-rather-than-a-tarball)
|
||||
- [Steps](#steps)
|
||||
- [Taking a stack update](#taking-a-stack-update)
|
||||
- [Where stack development happens](#where-stack-development-happens)
|
||||
- [Decision points](#decision-points)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Why a clone rather than a tarball
|
||||
|
||||
`INSTALL.md`'s "Eine Instanz aktualisieren" is `cp -r` as an upgrade strategy: copy `tools/`,
|
||||
`types/`, `instructions/`, `AGENTS.md`, `VERSION` over the existing tree. It has no three-way
|
||||
merge, so it cannot notice that the receiving instance changed a file, and it has no conflict
|
||||
surface, so nobody learns when upstream and local both touched the same one. It overwrites
|
||||
silently.
|
||||
|
||||
A clone gets all of that from git. Stack changes land as real merges, with real conflicts where
|
||||
they conflict.
|
||||
|
||||
**What a plain `git merge` does *not* give you is protection from the upstream's content.** The
|
||||
private `main` deletes the demo corpus once, but that deletion does not make later upstream
|
||||
changes to those paths go away. Measured, not assumed:
|
||||
|
||||
| Upstream does | `git merge upstream/main` does |
|
||||
|---|---|
|
||||
| modifies a page you deleted | `CONFLICT (modify/delete)` - and **leaves the upstream version in your working tree**. Resolve it with `git add -A` and the demo page is back. |
|
||||
| adds a new page | stages it **silently**. No conflict, no prompt, no mention. |
|
||||
| deletes a page you also deleted | nothing. The only harmless case. |
|
||||
|
||||
The middle row is the one that matters, because nothing announces it. An upstream that ships a
|
||||
demo corpus *and* uses it as a test bed will add pages, and each one arrives in your instance
|
||||
and starts showing up in your `lint`, your `index` and your `search`.
|
||||
|
||||
So the merge has to be scoped. That is the procedure below, and it is not optional.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Clone, and name the two remotes for what they are.**
|
||||
|
||||
```bash
|
||||
git clone <private-repo-url> my-wiki
|
||||
cd my-wiki
|
||||
git remote add upstream <public-repo-url>
|
||||
```
|
||||
|
||||
`origin` is yours and is the only thing you ever push to. `upstream` is where stack updates
|
||||
come from and is fetch-only.
|
||||
|
||||
2. **Make the fetch-only half fetch-only in git, too.**
|
||||
|
||||
```bash
|
||||
git remote set-url --push upstream no_push
|
||||
```
|
||||
|
||||
git refuses to push to a URL it cannot resolve. This is a convenience, not the safeguard -
|
||||
step 4 is the safeguard.
|
||||
|
||||
3. **Delete the upstream's demo corpus once, on your own `main`.**
|
||||
|
||||
Everything under `kb/` and `raw/` that came with the clone is the upstream's content, not
|
||||
yours. Remove it with `wikitool rm --page` (never `rm -rf`: `rm` de-links each page from the
|
||||
rest of the wiki, and a plain delete leaves dead wikilinks and broken citations behind), then
|
||||
`index rebuild`, `sources rebuild-index`, `lint`.
|
||||
|
||||
This is a one-time cut. Afterwards the upstream corpus is frozen from your side, which is
|
||||
what makes later merges content-free.
|
||||
|
||||
4. **Arm the Publish-Remote Gate — before the first `publish`.**
|
||||
|
||||
```bash
|
||||
cat > .wikitool-remotes.json <<'EOF'
|
||||
{ "schema": 1, "allowed_push_urls": ["<your-private-push-url>"] }
|
||||
EOF
|
||||
```
|
||||
|
||||
Use the URL `git remote get-url --push origin` prints, exactly. `publish` refuses with exit
|
||||
42 for anything else, and there is no flag that opens it - see [gates.md](gates.md).
|
||||
|
||||
The file is gitignored, so it stays with this checkout and never travels to the upstream.
|
||||
`wikitool doctor` reports whether the gate is armed, and WARNs at more than one remote
|
||||
without it.
|
||||
|
||||
5. **Take away the write credential, if you can.** A token or deploy key for `origin` only,
|
||||
with no write access to the upstream, is the one control that holds even if everything above
|
||||
is misconfigured. Belt and braces.
|
||||
|
||||
6. **Personalize and bootstrap.** `USER.md`, `SOUL.md` and optionally `ENVIRONMENT.md` are
|
||||
yours and unrelated to the upstream's - see the Personalization step of
|
||||
[setup-instance.md](setup-instance.md), then [bootstrap.md](bootstrap.md) for the venv and
|
||||
the skills.
|
||||
|
||||
A clone inherits the upstream's `kb/CONVENTIONS.md` and `kb/*/COLLECTION.md` rather than
|
||||
templates, because it inherits the upstream's whole tree. They are yours from this point on:
|
||||
rewrite them if this instance writes its pages differently - the update procedure below
|
||||
restores them on every merge, so the change sticks. [kb-profiles.md](kb-profiles.md) has the
|
||||
alternatives.
|
||||
|
||||
## Taking a stack update
|
||||
|
||||
```bash
|
||||
tools/wikitool upstream merge --remote upstream --branch main
|
||||
```
|
||||
|
||||
Take the machinery, never the content. This is the command form of the same idea a hand-rolled
|
||||
merge would need: hold the merge open, force the content stages back to your own state, restore
|
||||
only the paths that are machinery, and only then let it close. Which paths those are is not a
|
||||
short literal list any more (see below) - it is `chemenu.ownership.is_stack_owned`, the same
|
||||
predicate `dist_cmd.py`'s export reads, so a stack change that adds a new machinery path under a
|
||||
content stage is recognised automatically rather than needing this document edited first.
|
||||
|
||||
**What counts as machinery under a content stage**, for readers who want the shape rather than
|
||||
the code:
|
||||
|
||||
| Path | Why it takes the upstream side |
|
||||
|---|---|
|
||||
| `<stage>/CONTRACT.md` (`kb/CONTRACT.md`, `raw/CONTRACT.md`, `work/CONTRACT.md`, `reports/CONTRACT.md`) | The stack's own stage contract. Every rule in it is enforced by `wikitool`; an instance never edits it |
|
||||
| any `*.template` under a content stage (`kb/CONVENTIONS.md.template`, each `kb/<name>/COLLECTION.md.template`, and any later one) | The template your filled file was adopted from. The filled file is yours; the template is the stack's |
|
||||
|
||||
Everything else under `kb/`, `raw/`, `work/` and `reports/` is yours, `kb/CONVENTIONS.md` and
|
||||
each `kb/<name>/COLLECTION.md` included - they bind your corpus, and they are exactly what
|
||||
`upstream merge` protects.
|
||||
|
||||
**Your local, uncommitted-by-design files under those stages survive.** Forcing a content stage
|
||||
back to your own state removes only what git tracks, never the directory wholesale - which
|
||||
matters because `reports/` is gitignored apart from its contract, so it holds data that is in no
|
||||
commit and cannot be recomputed: the telemetry traces `eval score` reads, saved eval reports,
|
||||
past lint reports. A merge has no business touching any of it, and does not.
|
||||
|
||||
The command itself checks its own result the same way `upstream verify` would, immediately
|
||||
after committing, and refuses loudly - without rolling the commit back - if anything landed
|
||||
outside a stack-owned path. A refusal there is a bug report, not something to work around by
|
||||
hand; see [tools/CONTRACT.md](../tools/CONTRACT.md) for the full error contract, including what
|
||||
a real conflict in `tools/`/`types/`/`instructions/` leaves behind.
|
||||
|
||||
Then, as after any stack change: `doctor`, `docs verify`, `instructions verify`, `migrate status`,
|
||||
`lint`. A `migrate status` with outstanding links means the update crossed a compatibility
|
||||
boundary - follow [migrate-corpus.md](migrate-corpus.md) before doing anything else.
|
||||
|
||||
**Why not just `git merge upstream/main`?** A page the upstream *adds* arrives with no conflict
|
||||
and no message under a plain merge - measured in the table further up this document. You would
|
||||
find out when `lint` starts reporting pages you never wrote, if you noticed at all. `upstream
|
||||
merge` closes exactly that gap: the content stages never see the upstream's version at all.
|
||||
|
||||
**Checking a merge you resolved by hand instead** (or auditing a past one): `tools/wikitool
|
||||
upstream verify --since <rev-before> --until <rev-after>` runs the same check `upstream merge`
|
||||
runs on itself, without doing the merge.
|
||||
|
||||
## Where stack development happens
|
||||
|
||||
**In the public repo, not here.** That is not a preference; the stack is built that way. The
|
||||
development-only half of the instruction layer is pruned from a distribution one-way, with no
|
||||
command that reconstructs it, so an instance built this way has no tool-development mode to
|
||||
switch into in the first place.
|
||||
|
||||
When a tool bug blocks real content work here - and it will - file the issue against the public
|
||||
repo (an MCP server or the web UI reaches it from any session; no shared history needed), fix it
|
||||
there where the tests, `docs verify` and CI's version gate live, and take the fix back with the
|
||||
merge above. Nothing is lost by the detour: the fix has to pass that CI either way.
|
||||
|
||||
## Decision points
|
||||
|
||||
- **Merge conflict in `kb/`, `raw/`, `work/` or `reports/`?** Expected, and already handled:
|
||||
`upstream merge` overwrites those stages with your own afterwards, so the conflict resolves
|
||||
itself. Never resolve one by hand with `git add -A` in a merge you are running yourself
|
||||
instead - that is exactly how the upstream version, which git left sitting in your working
|
||||
tree, gets committed into your instance.
|
||||
- **`upstream merge` exits 1 after committing?** Read the message: its own postcheck found
|
||||
content outside a stack-owned path in the commit it just made. The commit is **not** rolled
|
||||
back - inspect it (`git show`, or `tools/wikitool upstream verify --since <before> --until
|
||||
HEAD`) and decide by hand whether to revert it, fix forward, or report it as a stack bug. This
|
||||
should not happen; if it does, `chemenu.ownership.is_stack_owned` disagreed with itself between
|
||||
the restore and the check, which is exactly what the shared predicate is meant to prevent.
|
||||
- **Conflict in `tools/`, `types/` or `instructions/`?** You changed the stack locally, which
|
||||
step "Where stack development happens" says not to do. `upstream merge` leaves the merge open
|
||||
rather than guessing - take the upstream side for the named paths and re-file the change as an
|
||||
issue there, or resolve deliberately and finish the commit yourself.
|
||||
- **...but you changed how *your pages* are written?** That is not a stack change and the rule
|
||||
above does not apply to it. Language, section headings, naming forms, tone, relationship
|
||||
labels and the hedging rule live in `kb/CONVENTIONS.md`, and each collection's authoring
|
||||
rules in `kb/<name>/COLLECTION.md` - all under `kb/`, all yours, all restored by the merge
|
||||
procedure rather than overwritten by it. If you find yourself editing `tools/` or `types/` to
|
||||
change an authoring convention, that is a stack bug: file it, because the split exists
|
||||
precisely so you do not have to.
|
||||
|
||||
## Scope
|
||||
|
||||
Not for a first instance with no upstream - that is [setup-instance.md](setup-instance.md). Not
|
||||
for a fresh clone of a repo you already own and develop in - that is
|
||||
[bootstrap.md](bootstrap.md). This is specifically the two-remote case, where the cost of a
|
||||
mistaken push is disclosure rather than inconvenience.
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: session-setup
|
||||
description: Scope the wikitool iteration budget to the task by exporting a stable session id before the first tool call.
|
||||
description: Scope the wikitool iteration budget to the task by setting a stable session id - one line for bash, one for PowerShell - before the first tool call.
|
||||
---
|
||||
|
||||
# Scope the session budget
|
||||
@@ -15,17 +15,39 @@ Without an explicit id, and on a harness with no registered variable, the budget
|
||||
whichever shell happened to run the command, so a task spanning several terminals is counted as
|
||||
several sessions - and one that reuses a shell inherits an unrelated count.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [Steps](#steps)
|
||||
- [Multi-unit runs](#multi-unit-runs)
|
||||
- [Scope](#scope)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
## Steps
|
||||
|
||||
Run this **once per working session**, before the first `wikitool` call that is not exempt from
|
||||
the budget (see § Scope for what that means):
|
||||
the budget (see § Scope for what that means). Pick the id yourself - a short name for the task and
|
||||
the current date and time, such as `wiki-20261001-1430` - and set it with the line for the shell
|
||||
you run in. In a POSIX shell (Linux, macOS, Git Bash on Windows):
|
||||
|
||||
```bash
|
||||
export WIKITOOL_SESSION_ID="wiki-20261001-1430"
|
||||
```
|
||||
|
||||
In PowerShell 7:
|
||||
|
||||
```powershell
|
||||
$env:WIKITOOL_SESSION_ID = 'wiki-20261001-1430'
|
||||
```
|
||||
|
||||
These two lines are the only shell-specific syntax in the stack's instructions; everything else is
|
||||
a `tools/wikitool` or `git` call that reads the same in both shells. Then:
|
||||
|
||||
```bash
|
||||
export WIKITOOL_SESSION_ID="wiki-$(date +%s)"
|
||||
tools/wikitool sync
|
||||
```
|
||||
|
||||
**An `export` only carries if the shell carries.** Several agent harnesses run every tool call in
|
||||
**The variable only carries if the shell carries.** Several agent harnesses run every tool call in
|
||||
a freshly initialised shell: the working directory survives, shell state - environment variables,
|
||||
functions - does not, so the variable is gone by the next call and each call falls back to whatever
|
||||
the chain's next step resolves to.
|
||||
@@ -37,13 +59,15 @@ work into the same count. Setting `WIKITOOL_SESSION_ID` explicitly still narrows
|
||||
task at hand, and remains the only way to scope it at all on a harness with no registered
|
||||
variable - each call falls back to its own parent pid there, and neither the 60-call ceiling nor
|
||||
the loop-breaker can ever trip (measured directly on a real upgrade run: 33 `wikitool` calls in
|
||||
one task split into 21 telemetry buckets under the pid fallback alone). On such a harness, pass
|
||||
the id **inline on every call** instead of `export`, keeping the same value for the whole task:
|
||||
one task split into 21 telemetry buckets under the pid fallback alone). On such a harness, put the
|
||||
line **in front of every `tools/wikitool` call, in the same command**, joined with `;` - which
|
||||
both shells read the same way - and keep the same value for the whole task.
|
||||
|
||||
```bash
|
||||
WIKITOOL_SESSION_ID="wiki-1234" tools/wikitool sync
|
||||
WIKITOOL_SESSION_ID="wiki-1234" tools/wikitool new entity --name "..."
|
||||
```
|
||||
**GitHub Copilot registers no variable.** Neither Copilot CLI nor Copilot's agent mode in VS Code
|
||||
sets a session variable in the shell it runs commands in (checked against their documentation,
|
||||
October 2026), so the chain has no second step there. Under Copilot the line above is what scopes
|
||||
the budget at all, and what `tools/wikitool doctor` reads: without it, `doctor` reports
|
||||
`session-id: WARN` and names the parent-pid fallback.
|
||||
|
||||
Which of the three applies is answerable in one call: run `tools/wikitool budget status` twice in
|
||||
separate calls, and see whether it names the same id both times, and where that id came from -
|
||||
@@ -70,10 +94,7 @@ user, then `tools/wikitool sync --confirm-rebase <token>` before continuing. See
|
||||
|
||||
A task planned as several units - a tree ingest, where each unit produces its own source page
|
||||
and its own `publish` - takes one id per unit, derived from the workshop's run key:
|
||||
|
||||
```bash
|
||||
export WIKITOOL_SESSION_ID="ingest-documents-handbook/u3"
|
||||
```
|
||||
`<runkey>/u<N>`, for instance `ingest-documents-handbook/u3`, set with the same line as above.
|
||||
|
||||
The run key, the workshop directory name and the session id are then the same string, so the
|
||||
checklist in `work/<runkey>/README.md` and the budget state cannot disagree about where the
|
||||
@@ -87,7 +108,7 @@ refusal. See [gates.md](gates.md).
|
||||
**The exemption is an allowlist, not "read-only" or "does not change the wiki."** A command
|
||||
needs this setup unless it is one of the dozen `tools/CONTRACT.md` marks exempt in its command
|
||||
table (`search`, `doctor`, `links show`, `cite id`, `budget status`, the read-only forms of
|
||||
`eval`, `version`, `migrate` and `upstream verify`) - that table, not a rule of thumb here, is
|
||||
`eval`, `version` and `migrate`) - that table, not a rule of thumb here, is
|
||||
the single list. One entry on it, `version regrade`, is exempt only in its bare listing form and
|
||||
counted when it is given positions to regrade; every other entry is exempt however it is called.
|
||||
|
||||
|
||||
+179
-148
@@ -1,15 +1,19 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: setup-instance
|
||||
description: Turn a fresh distribution (from `dist export`) into a working, self-contained wiki instance - git repo, identity/author, optional remote, bootstrap, first commit.
|
||||
description: Install a new, self-contained wiki instance from the latest release into an empty folder - preflight asset, git repo, identity/author, optional remote, conventions, personalization, first commit.
|
||||
---
|
||||
|
||||
# Set up a new wiki instance
|
||||
|
||||
This instruction takes an empty distribution produced by `tools/wikitool dist export <target>`
|
||||
and turns it into a working, self-contained wiki instance - with its own git repo, its own
|
||||
author identity and (optionally) its own remote. At the end the instance is committed, verified
|
||||
and ready for its first ingest.
|
||||
This instruction takes an empty folder to a working, self-contained wiki instance, starting from
|
||||
the latest release - with its own git repo, its own author identity and (optionally) its own
|
||||
remote. At the end the instance is committed, verified and ready for its first ingest.
|
||||
|
||||
The same file is read in two places: as the asset `setup-instance.md` of a release, before
|
||||
anything is installed, and inside the installed instance as `instructions/setup-instance.md`.
|
||||
Its links to other instructions resolve only in the second place; step 0 says how to reach the
|
||||
one it needs before that.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
@@ -21,37 +25,86 @@ and ready for its first ingest.
|
||||
|
||||
## When to run
|
||||
|
||||
- The user wants to set up a new, empty wiki instance (their own subject, a different person).
|
||||
- Not for an existing clone of this (source) repo - see [bootstrap.md](bootstrap.md).
|
||||
- There is no way back: `dist export` deliberately and permanently leaves out
|
||||
`instructions/dev/` (stack development itself, including the vendored `commonplace/` knowledge
|
||||
base). Anyone who wants to develop the resulting instance's stack further does that in the
|
||||
origin repo (or a new dev instance made from it) - not by retrofitting it into this instance.
|
||||
- The user wants a new wiki instance - their own subject, a different person - in a folder they
|
||||
name. The folder is empty, or holds nothing but `.git`: an empty clone of the repository the
|
||||
instance will push to.
|
||||
- Not for a further checkout of an instance that already exists (a second machine): clone that
|
||||
instance's repository and follow [bootstrap.md](bootstrap.md).
|
||||
- Not for working on the stack itself. That happens in a clone of the origin repository; a
|
||||
release leaves out stack development (`instructions/dev/`) permanently, and nothing in an
|
||||
instance restores it.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Export the distribution**, in the source repo:
|
||||
0. **Install the release into the folder.** Skip this step when `tools/preflight.sh` already
|
||||
exists in the folder - then the release is installed and this file is being read from inside
|
||||
it; continue with step 1.
|
||||
|
||||
```bash
|
||||
tools/wikitool dist export <target>
|
||||
```
|
||||
1. **Settle the folder.** It is the one the user named, and every later step runs in it. It
|
||||
has to be empty or hold only `.git`; on Windows with long paths switched off, its path may
|
||||
be at most 95 characters (`C:\Chemenu`, for instance). The preflight checks both, so do
|
||||
not measure anything yourself.
|
||||
|
||||
`<target>` must not exist, or must be empty; otherwise the command aborts with `ERROR`. Work
|
||||
inside `<target>` for every step that follows.
|
||||
2. **Read `preflight.md` before running anything.** It is an asset of the same release as
|
||||
this file: in the release description this file came from (the answer of
|
||||
`.../api/v1/repos/<owner>/<repo>/releases/latest`), the entry under `assets` named
|
||||
`preflight.md`, at its `browser_download_url`. It says how the preflight is started and
|
||||
what to do when it stops - and the release's preflight is the next thing to run.
|
||||
|
||||
2. **Initialize the git repo:**
|
||||
3. **Download the preflight for the shell you run in**, from the same release's `assets`,
|
||||
into the folder - with the shell's own download command, never through a browser, so the
|
||||
file carries no Mark of the Web. In PowerShell 7:
|
||||
|
||||
```powershell
|
||||
Invoke-WebRequest -Uri <browser_download_url of preflight.ps1> -OutFile preflight.ps1
|
||||
```
|
||||
|
||||
In a POSIX shell (Linux, macOS, Git Bash on Windows):
|
||||
|
||||
```bash
|
||||
curl -fLO <browser_download_url of preflight.sh>
|
||||
```
|
||||
|
||||
4. **Run it, exactly as `preflight.md` step 1 says** - the path is the downloaded file:
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -ExecutionPolicy Bypass -File preflight.ps1
|
||||
```
|
||||
|
||||
```bash
|
||||
sh preflight.sh
|
||||
```
|
||||
|
||||
It downloads the release's tarball, refuses unless its sha256 matches, unpacks it into
|
||||
this folder, removes the downloaded script and runs the preflight of the installed tree.
|
||||
Read its exit code as `preflight.md` step 2 says; on exit 42 follow its step 3 - show the
|
||||
output verbatim and wait. Every later run, including the retry after an exit 42, is the
|
||||
tree's own `tools/preflight.sh` or `pwsh -NoProfile -ExecutionPolicy Bypass -File
|
||||
tools/preflight.ps1`.
|
||||
|
||||
Continue only after it exits 0. From here on, [preflight.md](preflight.md) and every other
|
||||
instruction this file links to lie under `instructions/` in the folder.
|
||||
|
||||
1. **Initialize the git repo.** If the folder has no `.git` yet:
|
||||
|
||||
```bash
|
||||
git init -b main
|
||||
```
|
||||
|
||||
`-b main` is mandatory: on the actual push, `tools/wikitool publish` checks that the
|
||||
If it has one - an empty clone - keep it. `git branch --show-current` must print `main`; if
|
||||
it prints anything else, switch before the first commit:
|
||||
|
||||
```bash
|
||||
git checkout -b main
|
||||
```
|
||||
|
||||
`main` is mandatory: on the actual push, `tools/wikitool publish` checks that the
|
||||
checked-out branch matches the target branch (default `main`) and refuses otherwise, so that
|
||||
the wrong branch is never published.
|
||||
|
||||
3. **Decision point - identity.** Ask the user for their name and email address; never guess
|
||||
them, and never quietly carry them over from the source repo (that is a different person and
|
||||
a different project):
|
||||
2. **Decision point - identity.** Ask the user for their name and email address; never guess
|
||||
them, and never quietly carry them over from another repository (that is a different person
|
||||
and a different project):
|
||||
|
||||
```bash
|
||||
git config user.name "<name>"
|
||||
@@ -62,18 +115,19 @@ and ready for its first ingest.
|
||||
resolves `author:` from `$WIKI_AUTHOR` (an override) or else from `git config user.name`, and
|
||||
aborts with `ERROR` when both are missing - there is no silent placeholder.
|
||||
|
||||
4. **Decision point - remote.** Ask the user for a remote URL; a purely local repo is a valid
|
||||
end state:
|
||||
3. **Decision point - remote.** An empty clone already has one: show the user `git remote -v`
|
||||
and confirm that `origin` is where this instance is to be published. Otherwise ask for a
|
||||
remote URL; a purely local repo is a valid end state:
|
||||
- Given: `git remote add origin <url>`
|
||||
- Not given: stay local - then **every** later `tools/wikitool publish` needs a `--no-push`
|
||||
(which also drops its branch check, see step 2). Without it, `publish` ends with exit 1
|
||||
(which also drops its branch check, see step 1). Without it, `publish` ends with exit 1
|
||||
before it commits anything, because there is no remote to publish to.
|
||||
|
||||
5. **Decision point - authoring conventions.** The distribution ships no filled-in conventions,
|
||||
only `kb/CONVENTIONS.md.template` and one `kb/<name>/COLLECTION.md.template` per collection.
|
||||
Both **bind** once adopted, and both belong to this instance - which is why the stack ships
|
||||
the template alone. The one decision behind them is: **in which language and in what tone
|
||||
does this instance write its pages?**
|
||||
4. **Decision point - authoring conventions.** The release ships no filled-in conventions, only
|
||||
`kb/CONVENTIONS.md.template` and one `kb/<name>/COLLECTION.md.template` per collection. Both
|
||||
**bind** once adopted, and both belong to this instance - which is why the stack ships the
|
||||
template alone. The one decision behind them is: **in which language and in what tone does
|
||||
this instance write its pages?**
|
||||
|
||||
Procedure:
|
||||
|
||||
@@ -81,19 +135,17 @@ and ready for its first ingest.
|
||||
user, because what they say is usable as a starting point regardless of language:
|
||||
|
||||
```bash
|
||||
for template in kb/*/COLLECTION.md.template types/*.template; do
|
||||
cp "$template" "${template%.template}"
|
||||
done
|
||||
tools/wikitool dist adopt
|
||||
```
|
||||
|
||||
The `.template` files stay where they are; they are the source for the next export.
|
||||
The `.template` files stay where they are; they are what the next `dist upgrade` compares
|
||||
against.
|
||||
|
||||
Under `types/` this covers exactly the type-specs with `root: kb` - `entity`, `concept`,
|
||||
`source`, `comparison` - along with their `.schema.yaml`. They describe pages *this*
|
||||
instance writes, so they belong to it: frontmatter, template and language may all be
|
||||
rewritten. `instruction`, `lint-report`, `type-spec` and `type-guidance` describe stack
|
||||
artifacts and arrive unchanged - the glob above never matches them because none of them
|
||||
ships as a `.template` in the first place.
|
||||
`source`, `comparison`, `project` - along with their `.schema.yaml`. They describe pages
|
||||
*this* instance writes, so they belong to it: frontmatter, template and language may all
|
||||
be rewritten. `instruction`, `lint-report`, `type-spec` and `type-guidance` describe stack
|
||||
artifacts and arrive unchanged - none of them ships as a `.template` in the first place.
|
||||
|
||||
A `root: kb` type-spec's generic authoring guidance (when to use the type, when not to)
|
||||
is not part of this adoption at all: it lives in a sibling `types/<name>.guidance.md`
|
||||
@@ -102,32 +154,29 @@ and ready for its first ingest.
|
||||
touched. `types/type-spec.md` § "Anatomy of a type" has the shape.
|
||||
|
||||
2. Ask the user for the KB language. `kb/CONVENTIONS.md.template` defaults to **English**;
|
||||
[kb-profiles.md](kb-profiles.md) additionally holds a complete German profile, whose full
|
||||
text is the source repo's own `kb/CONVENTIONS.md`. The profile catalogue is a **palette,
|
||||
not an enum**: what gets adopted is the text *into* the instance file, not a reference to
|
||||
the catalogue.
|
||||
[kb-profiles.md](kb-profiles.md) additionally holds a complete German profile. The
|
||||
profile catalogue is a **palette, not an enum**: what gets adopted is the text *into* the
|
||||
instance file, not a reference to the catalogue.
|
||||
|
||||
3. Copy `kb/CONVENTIONS.md.template` to `kb/CONVENTIONS.md`, fill it in along the chosen
|
||||
3. Write `kb/CONVENTIONS.md` from `kb/CONVENTIONS.md.template`, filled in along the chosen
|
||||
profile - language, section names, naming forms, tone, relationship labels, hedging rule -
|
||||
and remove the sentinel line (`wikitool:template-unfilled`) while doing so. The
|
||||
placeholders in curly braces **are** the list of questions.
|
||||
and without the sentinel line (`wikitool:template-unfilled`). The placeholders in curly
|
||||
braces **are** the list of questions.
|
||||
|
||||
4. For a language other than the source repo's: delete `german-terminology.md` or replace it
|
||||
with your own vocabulary - it is material belonging to the German profile, not to the
|
||||
stack.
|
||||
4. For a language other than German: delete `german-terminology.md` or replace it with your
|
||||
own vocabulary - it is material belonging to the German profile, not to the stack.
|
||||
|
||||
5. Ask the user about the subject area and derive a `source_type` proposal from it.
|
||||
[kb-profiles.md](kb-profiles.md) holds two worked domain profiles as illustration, beside
|
||||
the value this repo uses itself. The proposal is a **starting point, not a commitment** -
|
||||
at setup time the operator has zero sources and is guessing a taxonomy before having seen
|
||||
a single file, which is the worst possible moment to pin an enum down. Carrying out the
|
||||
proposal means setting the enum in `types/source.schema.yaml` **and** the matching
|
||||
`layout:` line per value in `types/source.md` in the same edit - one without the other
|
||||
leaves a value with no target directory. The visible catch-all (`unclassified`) survives
|
||||
every proposal; it is not a dumping ground but the slot for a source whose category is not
|
||||
settled yet. Extending the list later, or emptying that slot:
|
||||
[evolve-subtypes.md](evolve-subtypes.md) - not part of this step, but the way there once
|
||||
real material exists.
|
||||
[kb-profiles.md](kb-profiles.md) holds two worked domain profiles as illustration. The
|
||||
proposal is a **starting point, not a commitment** - at setup time the operator has zero
|
||||
sources and is guessing a taxonomy before having seen a single file, which is the worst
|
||||
possible moment to pin an enum down. Carrying out the proposal means setting the enum in
|
||||
`types/source.schema.yaml` **and** the matching `layout:` line per value in
|
||||
`types/source.md` in the same edit - one without the other leaves a value with no target
|
||||
directory. The visible catch-all (`unclassified`) survives every proposal; it is not a
|
||||
dumping ground but the slot for a source whose category is not settled yet. Extending the
|
||||
list later, or emptying that slot: [evolve-subtypes.md](evolve-subtypes.md) - not part of
|
||||
this step, but the way there once real material exists.
|
||||
|
||||
**Leave unchanged:** `fidelity` and `authority` on `source` pages. Those are stack
|
||||
vocabulary, not an instance decision - [kb-profiles.md](kb-profiles.md) says so in the
|
||||
@@ -139,7 +188,7 @@ and ready for its first ingest.
|
||||
[migrate-corpus.md](migrate-corpus.md)).
|
||||
|
||||
**None of this lives in a stack file.** The compiler reads the section names from
|
||||
`kb/CONVENTIONS.md`; the four page type-specs have belonged to this instance since step 1. An
|
||||
`kb/CONVENTIONS.md`; the page type-specs have belonged to this instance since sub-step 1. An
|
||||
instance in another language simply translates them - that is no longer a local patch to
|
||||
something shipped, but work on its own files, and an upgrade does not take it away again.
|
||||
|
||||
@@ -153,14 +202,14 @@ and ready for its first ingest.
|
||||
identifiers](../kb/CONTRACT.md#language-and-identifiers)). Titles, wikilink targets, cite ids,
|
||||
enum values, tags, commands and paths follow no KB language.
|
||||
|
||||
`tools/wikitool doctor` checks the result in step 13 (`conventions`): a missing file is a
|
||||
`tools/wikitool doctor` checks the result in step 12 (`conventions`): a missing file is a
|
||||
`FAIL`, and so is one carrying the sentinel or lacking a complete `sections:` block.
|
||||
`docs verify` additionally checks `profile:` and `required_by_stack:` on every
|
||||
`COLLECTION.md`.
|
||||
|
||||
6. **Decision point - personalization.** The distribution ships `USER.md.template` and
|
||||
5. **Decision point - personalization.** The release ships `USER.md.template` and
|
||||
`SOUL.md.template`, but no filled-in versions: who operates this instance and how it sounds
|
||||
is the property of this instance alone and is never carried over from the source repo. Both
|
||||
is the property of this instance alone and is never carried over from anywhere else. Both
|
||||
files are read in **every** session from now on, so they come into being here - not later,
|
||||
when the occasion arises.
|
||||
|
||||
@@ -176,7 +225,7 @@ and ready for its first ingest.
|
||||
better to delete a section than to fill it with something plausible.
|
||||
4. Write the result as `USER.md` and `SOUL.md` respectively, removing the sentinel line
|
||||
(`wikitool:template-unfilled`) in the process. The `.template` files stay where they are -
|
||||
they are the source for the next export, not this step's leftovers.
|
||||
they are what the next `dist upgrade` compares against, not this step's leftovers.
|
||||
|
||||
Two questions the user answers rather than the agent: **the persona name** and **which topics
|
||||
deliberately stay out** (employer, clients, health - whatever they are). Guessing either
|
||||
@@ -189,103 +238,86 @@ and ready for its first ingest.
|
||||
invariant 3. They change no rule from [AGENTS.md](../AGENTS.md), and a user's statement never
|
||||
travels from them into `kb/` without the normal source/provenance process.
|
||||
|
||||
`tools/wikitool doctor` checks the result in step 13 (`personalization`): a missing file is a
|
||||
`tools/wikitool doctor` checks the result in step 12 (`personalization`): a missing file is a
|
||||
`FAIL`, and so is one still carrying the sentinel - a renamed template is not a filled-in
|
||||
one.
|
||||
|
||||
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
|
||||
tools/preflight.sh
|
||||
```
|
||||
|
||||
From PowerShell 7 on Windows, run the twin instead - same questions, same file:
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1
|
||||
```
|
||||
|
||||
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:**
|
||||
6. **Publish the skills:**
|
||||
|
||||
```bash
|
||||
tools/wikitool instructions sync
|
||||
```
|
||||
|
||||
9. **Decision point - record the environment.** The distribution ships
|
||||
`ENVIRONMENT.md.template`: harness, published skills, reachable MCP servers, connectors, git
|
||||
remotes, where CI runs. Constants a session would otherwise ask about every time.
|
||||
7. **Decision point - record the environment.** The release ships `ENVIRONMENT.md.template`:
|
||||
harness, published skills, reachable MCP servers, connectors, git remotes, where CI runs.
|
||||
Constants a session would otherwise ask about every time.
|
||||
|
||||
Unlike step 6, this step is **optional** and not an interview. Whatever can be read off the
|
||||
Unlike step 5, this step is **optional** and not an interview. Whatever can be read off the
|
||||
checkout itself (`git remote -v`, the running harness, the skills just published) the agent
|
||||
fills in; for the rest it asks once and accepts "I don't know" as an answer - an empty
|
||||
section is deleted, not filled with something plausible. Remove the sentinel line
|
||||
(`wikitool:template-unfilled`) when writing; the `.template` stays where it is.
|
||||
|
||||
If the step is skipped, everything still works: `doctor` reports
|
||||
`environment: absent (optional)` in step 13, not a `FAIL`. The file is gitignored and enters
|
||||
`environment: absent (optional)` in step 12, not a `FAIL`. The file is gitignored and enters
|
||||
no commit - it describes this checkout, not the repo.
|
||||
|
||||
10. **Decision point - telemetry.** The default follows the installation path, not this step: an
|
||||
instance delivered via `dist export` - every instance that arrives here without having taken
|
||||
route C (a direct clone of the origin repo) - carries a `.wikitool-release.json` and starts
|
||||
with telemetry **off**; nobody asked for it, and nobody reads `EVALS.md` before the first
|
||||
file is written anyway. This step only asks whether the operator wants to reverse that.
|
||||
8. **Decision point - telemetry.** Every instance installed from a release carries a
|
||||
`.wikitool-release.json` and starts with telemetry **off**; nobody asked for it, and nobody
|
||||
reads `EVALS.md` before the first file is written anyway. This step only asks whether the
|
||||
operator wants to reverse that.
|
||||
|
||||
Ask the user once: telemetry on? If yes, create `.wikitool-telemetry.json` in the repo root
|
||||
(per checkout, gitignored, no `.template` - like `.wikitool-remotes.json`):
|
||||
Ask the user once: telemetry on? If yes, create `.wikitool-telemetry.json` in the repo root
|
||||
(per checkout, gitignored, no `.template` - like `.wikitool-remotes.json`):
|
||||
|
||||
```json
|
||||
{ "enabled": true }
|
||||
```
|
||||
|
||||
`max_session_bytes` (default 5 MiB) and `keep_sessions` (default 250) are optional in the
|
||||
same file; most instances need not touch them. If no, do nothing - the default is already
|
||||
off, and no file is created. `WIKI_TRACE` still overrides in both directions, should a
|
||||
single session need to differ.
|
||||
|
||||
`tools/wikitool doctor` reports the result in step 14 (`telemetry`): on/off, why
|
||||
(installation form, this file, or `WIKI_TRACE`), and the current volume against both caps -
|
||||
never a `FAIL`, since both directions are a valid state. More on this:
|
||||
[EVALS.md](../EVALS.md) § "Whether it runs at all".
|
||||
|
||||
11. **Decision point - task tracker.** The instance ships the `project` type and the collection
|
||||
its type-spec's `base_dir:` names (`kb/gtd/` here), so committed initiatives have a page from
|
||||
the start. What they do *not* have until this step is the other half of the weekly review:
|
||||
the tracker that owns the open items, which `tools/wikitool review` joins those pages against
|
||||
over the project name. No tracker configured is a legitimate end state - the pages work
|
||||
alone, `review` simply says so and refuses - so ask rather than assume.
|
||||
|
||||
Ask the user once: is there a task tracker to connect? If yes, create `.wikitool-tasks.json`
|
||||
in the repo root (per checkout, no `.template`, **gitignored once it holds a token** - like
|
||||
`.wikitool-telemetry.json` and `.wikitool-remotes.json`), with the provider's own section and
|
||||
the three thresholds the review reads as configuration rather than schema. The shape, the
|
||||
shipped providers, and what Super Productivity in particular needs are in
|
||||
[INSTALL.md](../INSTALL.md) § Konfiguration; do not restate them here. If no, do nothing - no
|
||||
file is created, and adding one later needs nothing from this procedure.
|
||||
|
||||
`doctor` reports the result in step 14 (`tasks`): absent is `OK`, a malformed file is the one
|
||||
`FAIL` here (a broken opt-in must not read as "no tracker configured"), and a configured
|
||||
provider that is simply not running is never a fault.
|
||||
|
||||
12. **Scope the session budget** (details: [session-setup.md](session-setup.md)):
|
||||
|
||||
```bash
|
||||
export WIKITOOL_SESSION_ID="wiki-$(date +%s)"
|
||||
```json
|
||||
{ "enabled": true }
|
||||
```
|
||||
|
||||
13. **Build the generated indexes** - `dist export` deliberately does not ship them:
|
||||
`max_session_bytes` (default 5 MiB) and `keep_sessions` (default 250) are optional in the
|
||||
same file; most instances need not touch them. If no, do nothing - the default is already
|
||||
off, and no file is created. `WIKI_TRACE` still overrides in both directions, should a
|
||||
single session need to differ.
|
||||
|
||||
`tools/wikitool doctor` reports the result in step 12 (`telemetry`): on/off, why
|
||||
(installation form, this file, or `WIKI_TRACE`), and the current volume against both caps -
|
||||
never a `FAIL`, since both directions are a valid state. More on this:
|
||||
[EVALS.md](../EVALS.md) § "Whether it runs at all".
|
||||
|
||||
9. **Decision point - task tracker.** The instance ships the `project` type and the collection
|
||||
its type-spec's `base_dir:` names (`kb/gtd/` here), so committed initiatives have a page from
|
||||
the start. What they do *not* have until this step is the other half of the weekly review:
|
||||
the tracker that owns the open items, which `tools/wikitool review` joins those pages against
|
||||
over the project name. No tracker configured is a legitimate end state - the pages work
|
||||
alone, `review` simply says so and refuses - so ask rather than assume.
|
||||
|
||||
Ask the user once: is there a task tracker to connect? If yes, create `.wikitool-tasks.json`
|
||||
in the repo root (per checkout, no `.template`, **gitignored once it holds a token** - like
|
||||
`.wikitool-telemetry.json` and `.wikitool-remotes.json`), with the provider's own section and
|
||||
the three thresholds the review reads as configuration rather than schema. The shape, the
|
||||
shipped providers, and what Super Productivity in particular needs are in
|
||||
[INSTALL.md](../INSTALL.md) § Konfiguration; do not restate them here. If no, do nothing - no
|
||||
file is created, and adding one later needs nothing from this procedure.
|
||||
|
||||
`doctor` reports the result in step 12 (`tasks`): absent is `OK`, a malformed file is the one
|
||||
`FAIL` here (a broken opt-in must not read as "no tracker configured"), and a configured
|
||||
provider that is simply not running is never a fault.
|
||||
|
||||
10. **Scope the session budget** with the line for the shell you run in, from
|
||||
[session-setup.md](session-setup.md) § Steps. Under GitHub Copilot this is what step 12's
|
||||
`doctor` reads: Copilot sets no session variable of its own, so without the line `doctor`
|
||||
reports `session-id: WARN` and the budget falls back to the parent process. If your harness
|
||||
starts a fresh shell for every command, put the line in front of each `tools/wikitool`
|
||||
call instead, in the same command - [session-setup.md](session-setup.md) says how.
|
||||
|
||||
11. **Build the generated indexes** - the release deliberately does not ship them:
|
||||
|
||||
```bash
|
||||
tools/wikitool index rebuild
|
||||
tools/wikitool sources rebuild-index
|
||||
```
|
||||
|
||||
14. **Verify**, in this order:
|
||||
12. **Verify**, in this order:
|
||||
|
||||
```bash
|
||||
tools/wikitool doctor
|
||||
@@ -295,27 +327,26 @@ and ready for its first ingest.
|
||||
```
|
||||
|
||||
`doctor` must run through without a `FAIL` before anything continues - a `WARN` (no remote,
|
||||
no `WIKITOOL_SESSION_ID`, say) is not a blocker. A `FAIL` names its own fix command; run it
|
||||
and call `doctor` again.
|
||||
say) is not a blocker. A `FAIL` names its own fix command; run it and call `doctor` again.
|
||||
|
||||
15. **Make the first commit:**
|
||||
13. **Make the first commit:**
|
||||
|
||||
```bash
|
||||
tools/wikitool publish --message "chore: initial instance setup"
|
||||
```
|
||||
|
||||
The Mass-Update Gate fires here as expected: a fresh distribution consists of far more than
|
||||
the ten counted files that trip the threshold, so the call ends with exit code 42. Show the
|
||||
The Mass-Update Gate fires here as expected: a fresh instance consists of far more than the
|
||||
ten counted files that trip the threshold, so the call ends with exit code 42. Show the
|
||||
output to the user **in full** and wait; it contains the file list and the exact
|
||||
`--confirm <token>` line that publishes once they approve. Details on the gate:
|
||||
[gates.md](gates.md).
|
||||
|
||||
A local-only instance (step 4) adds `--no-push` here too. Without it the call ends with exit
|
||||
A local-only instance (step 3) adds `--no-push` here too. Without it the call ends with exit
|
||||
1 before the gate, because there is no remote to publish to, and commits nothing.
|
||||
|
||||
16. **Restart the agent session.** Harnesses read the skill directories at startup; only
|
||||
afterwards are `wiki-ingest`, `wiki-query`, `wiki-manage`, `wiki-lint`, `wiki-status` and
|
||||
`gtd-weekly-review` available.
|
||||
14. **Restart the agent session in this folder.** Harnesses read `AGENTS.md` and the skill
|
||||
directories at startup; only afterwards are `wiki-ingest`, `wiki-query`, `wiki-manage`,
|
||||
`wiki-lint`, `wiki-status` and `gtd-weekly-review` available.
|
||||
|
||||
**A step fails and the cause is not obvious?** Do not improvise around it (invariant 7). Offer the
|
||||
user a bug report - [bug-report.md](bug-report.md) - and run it only if they agree; the collector
|
||||
@@ -323,10 +354,10 @@ works even when `wikitool` does not start.
|
||||
|
||||
## Scope
|
||||
|
||||
Applies only to an empty distribution produced by `dist export`. For an existing clone of this
|
||||
source repo see [bootstrap.md](bootstrap.md) - there the git repo, author and content already
|
||||
exist, and only the tool environment (step 7) plus the skills (step 8) are missing.
|
||||
Applies only to an empty folder (or an empty clone) and a release. A further checkout of an
|
||||
instance that already exists has its git repo, author and content already; it needs only the
|
||||
preflight and the skills - see [bootstrap.md](bootstrap.md).
|
||||
|
||||
One exception: step 6 (personalization) also applies to an existing clone that has no
|
||||
One exception: the personalization step (5) also applies to an existing checkout that has no
|
||||
`USER.md`/`SOUL.md` yet - there as a single catch-up step, not as a whole procedure.
|
||||
`bootstrap.md` points here for it.
|
||||
@@ -1,20 +1,20 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: upgrade-instance
|
||||
description: Carry out a stack release upgrade on an instance built from a tarball - read this release's notes, swap the machinery with dist upgrade, work the migration chain, verify, publish, and restart the session at the point where the new control plane starts to matter.
|
||||
description: Carry out a stack release upgrade on an instance installed from a release - read this release's notes, swap the machinery with dist upgrade, work the migration chain, verify, publish, and restart the session at the point where the new control plane starts to matter.
|
||||
manual: true
|
||||
---
|
||||
# Upgrade this instance to a new stack release
|
||||
|
||||
An instance built from a `dist export` tarball takes stack updates by copying a newer release
|
||||
over its machinery. This is the order in which that happens, what each step decides, and where
|
||||
the two known rough edges are. It ends with the instance on the new `VERSION`, its content
|
||||
version recorded, every check green, and the change published.
|
||||
An instance installed from a release takes stack updates by copying a newer release over its
|
||||
machinery. This is the order in which that happens, what each step decides, and where the two
|
||||
known rough edges are. It ends with the instance on the new `VERSION`, its content version
|
||||
recorded, every check green, and the change published.
|
||||
|
||||
**This is the tarball path.** An instance that is a *clone* of the origin repo, sharing git
|
||||
history, takes updates by three-way merge (`tools/wikitool upstream merge`) and follows
|
||||
[private-instance.md](private-instance.md) instead. `git remote -v` answers which one this is:
|
||||
a clone carries an `upstream` remote pointing at the origin.
|
||||
**Every instance takes this path.** An instance comes from a release and carries the
|
||||
`.wikitool-release.json` that release wrote; `dist upgrade` refuses to run without it. A clone of
|
||||
the origin repository is a development checkout of the stack itself, not an instance, and is
|
||||
updated with git rather than with this file.
|
||||
|
||||
**One thing this file deliberately does not know.** The copy you are reading shipped with the
|
||||
release this instance is *leaving*, not the one it is going to - so nothing specific to a
|
||||
@@ -39,18 +39,19 @@ documents that arrive inside the tarball.
|
||||
`dist upgrade --dry-run` both report the true state, and the step that matches what they say
|
||||
is where this run continues.
|
||||
|
||||
Not for setting up a new instance ([setup-instance.md](setup-instance.md)), not for preparing a
|
||||
fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream path above.
|
||||
Not for setting up a new instance ([setup-instance.md](setup-instance.md)) and not for preparing
|
||||
a further checkout of this one ([bootstrap.md](bootstrap.md)).
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Take a session id and pass it on every call for the whole upgrade** - the form and the
|
||||
reason are in [session-setup.md](session-setup.md). An upgrade is one of the longest runs
|
||||
this stack has, and the iteration budget only sees it as one run if every call carries the
|
||||
same id:
|
||||
1. **Take a session id and keep it for every call of the whole upgrade:** `upgrade-<target
|
||||
version>`, set with the line for your shell from [session-setup.md](session-setup.md) § Steps
|
||||
- which also says what to do on a harness that starts a fresh shell per command. An upgrade is
|
||||
one of the longest runs this stack has, and the iteration budget only sees it as one run if
|
||||
every call carries the same id. Then:
|
||||
|
||||
```bash
|
||||
WIKITOOL_SESSION_ID=upgrade-<target-version> tools/wikitool version check
|
||||
tools/wikitool version check
|
||||
```
|
||||
|
||||
2. **Read this release's notes before touching anything.** Two lines decide the rest of the run:
|
||||
@@ -88,10 +89,11 @@ fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream
|
||||
appeared in the meantime is refused before anything is downloaded, rather than applied unread.
|
||||
|
||||
The offline alternative is the tarball path: with the feed unreachable, or an archive the
|
||||
operator supplies, take the `.tar.gz` and its `.sha256` from the release page named in step 2,
|
||||
check the archive against the checksum before unpacking, and pass the file as `<tarball>`
|
||||
where the steps below say `--latest --expect <version>`. A tarball must unpack to exactly one
|
||||
top-level directory. The checksum comes from the same host as the archive, so it catches a
|
||||
operator supplies, the operator puts the `.tar.gz` and its `.sha256` side by side, from the
|
||||
release page named in step 2, and you pass the archive as `<tarball>` where the steps below
|
||||
say `--latest --expect <version>`. `dist upgrade` checks the archive against the `.sha256`
|
||||
beside it before unpacking, and refuses one that does not match. A tarball must unpack to
|
||||
exactly one top-level directory. The checksum comes from the same host as the archive, so it catches a
|
||||
damaged transfer, not a compromised host - who is trusted to publish releases is the
|
||||
operator's decision, made before this file starts ([INSTALL.md](../INSTALL.md) § "Version und
|
||||
Updates").
|
||||
@@ -189,15 +191,15 @@ fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream
|
||||
points at, is the other repairable shape - the `new` template from step 5 that nobody adopted.
|
||||
The fix is the ordinary adoption every `root: kb` type already needs, not a data migration:
|
||||
copy the shipped templates to their unsuffixed names, then fill the instance-owned parts
|
||||
(language, template text, any extra fields) the way step 5 of
|
||||
(language, template text, any extra fields) the way the authoring-conventions step of
|
||||
[setup-instance.md](setup-instance.md) describes for a fresh instance.
|
||||
|
||||
```bash
|
||||
cp types/<name>.md.template types/<name>.md
|
||||
cp kb/<collection>/COLLECTION.md.template kb/<collection>/COLLECTION.md
|
||||
tools/wikitool dist adopt types/<name>.md.template types/<name>.schema.yaml.template kb/<collection>/COLLECTION.md.template
|
||||
```
|
||||
|
||||
The `.template` files stay where they are - they are the source for the next upgrade's
|
||||
`dist adopt` copies only what does not exist yet, so a file this instance already adopted
|
||||
and filled is never touched. The `.template` files stay where they are - they are the source for the next upgrade's
|
||||
comparison. Any other failure is read against step 2's **Breaking Change:** line: if the
|
||||
release predicted it, the notes also say what fixes it; if it did not, stop and report it
|
||||
rather than improvising.
|
||||
@@ -274,8 +276,8 @@ fresh clone ([bootstrap.md](bootstrap.md)), and not for the clone-with-upstream
|
||||
|
||||
## Scope
|
||||
|
||||
For an instance that receives releases as tarballs. Not the origin repo, which has no upgrade
|
||||
path of its own, and not a clone with shared history - see the second paragraph. Anything about
|
||||
For an instance installed from a release. Not the origin repo, which has no upgrade path of its
|
||||
own - see the second paragraph. Anything about
|
||||
*writing* a migration document rather than running one is
|
||||
[migrate-corpus.md](migrate-corpus.md) § "Writing the migration document".
|
||||
|
||||
|
||||
+55
-119
@@ -42,7 +42,6 @@ file end to end is for changing the CLI itself.
|
||||
- [Telemetry](#telemetry)
|
||||
- [Distribution and versioning](#distribution-and-versioning)
|
||||
- [Content migrations](#content-migrations)
|
||||
- [Private instances](#private-instances)
|
||||
- [Instance health](#instance-health)
|
||||
- [Design notes](#design-notes)
|
||||
- [Tests](#tests)
|
||||
@@ -137,6 +136,7 @@ docs contract write idempotent budget:counted exit:0,1
|
||||
eval sessions read idempotent budget:exempt exit:0 List the sessions that have a trace under `reports/telemetry/`.
|
||||
eval score read idempotent budget:exempt exit:0,1 Score one traced session.
|
||||
dist export write idempotent budget:counted exit:0,1 Write a contentless, distributable copy of this repo's machinery.
|
||||
dist adopt write idempotent budget:counted exit:0,1 Take shipped templates as this instance's own: copy each to its unsuffixed name.
|
||||
dist upgrade write non-idempotent budget:counted exit:0,1 Apply a stack update `dist export` produced - the write half of `version check`.
|
||||
version show read idempotent budget:exempt exit:0,1 Print this instance's stack version and where it came from.
|
||||
version check read idempotent budget:exempt exit:0,1 Ask the origin's release feed whether a newer stack exists.
|
||||
@@ -149,8 +149,6 @@ migrate status read idempotent budget:exempt exit:0,1
|
||||
migrate verify read idempotent budget:exempt exit:0,1 Compare `kb/` against a git revision on the invariants a content migration must not change.
|
||||
migrate done write non-idempotent budget:counted exit:0,1 Record one migration as applied, advancing `kb_version` in `.wikitool-kb.json`.
|
||||
migrate baseline write idempotent budget:counted exit:0,1 Declare `kb_version` once, for an instance predating `.wikitool-kb.json`.
|
||||
upstream merge write non-idempotent budget:counted exit:0,1 Take a stack update into a private instance's branch, machinery only.
|
||||
upstream verify read idempotent budget:exempt exit:0,1 Compare two revisions: did anything under a content stage change except through a stack-owned path?
|
||||
doctor read idempotent budget:exempt exit:0,1 Check that this instance is correctly configured.
|
||||
```
|
||||
|
||||
@@ -2437,15 +2435,66 @@ Write a contentless, distributable copy of this repo's machinery.
|
||||
- Ships templates, never the filled files: `USER.md.template`/`SOUL.md.template`, `kb/CONVENTIONS.md.template`, and each collection's contract re-keyed as `kb/<name>/COLLECTION.md.template`. The filled `USER.md`/`SOUL.md`/`kb/CONVENTIONS.md`/`kb/<name>/COLLECTION.md`/`types/<page-type>.md` bind their instance; `find_leaks` refuses a plan carrying one.
|
||||
- Writes a generated `.wikitool-release.json` stamp: version, export date, origin, and a sha256 per exported file - the base a later upgrade compares against.
|
||||
- The four origin options only fill stamp fields: `export` never calls git and cannot discover them.
|
||||
- One-way: no command reconstructs a distributed instance into a dev instance - work on the stack in the origin repo, or in a new dev instance exported from it.
|
||||
- A build and test tool: every release is an export packed as a tarball, and an instance is installed from such a release, never from an export directly.
|
||||
- One-way: no command reconstructs a distributed instance into a dev instance - work on the stack in a clone of the origin repo.
|
||||
- `--dry-run` lists every file it would write, and writes nothing.
|
||||
|
||||
**SEE ALSO**
|
||||
|
||||
- `instructions/setup-instance.md` - what comes after the export
|
||||
- `instructions/setup-instance.md` - installs a release, which is this export as a tarball
|
||||
- `wikitool dist upgrade` - applies a later export to an existing instance
|
||||
- `wikitool version show` - reads the stamp this writes
|
||||
|
||||
#### `dist adopt`
|
||||
|
||||
Take shipped templates as this instance's own: copy each to its unsuffixed name.
|
||||
|
||||
**SYNOPSIS**
|
||||
|
||||
- `wikitool dist adopt [<template>...] [--dry-run]`
|
||||
|
||||
**PROPERTIES**
|
||||
|
||||
- effect: write
|
||||
- idempotent: yes
|
||||
- atomic: No - files are copied one by one; a re-run completes an interrupted one
|
||||
- budget: counted
|
||||
- network: no
|
||||
|
||||
**EXAMPLES**
|
||||
|
||||
- `tools/wikitool dist adopt`
|
||||
- `tools/wikitool dist adopt types/project.md.template types/project.schema.yaml.template`
|
||||
- `tools/wikitool dist adopt --dry-run`
|
||||
|
||||
**EXIT STATUS**
|
||||
|
||||
- 0 success
|
||||
- 1 A named path does not exist, or is not a collection contract or page type-spec template
|
||||
|
||||
**ON FAILURE**
|
||||
|
||||
- A named path does not exist, or is not a collection contract or page type-spec template -> Not transient - name a template from the set in NOTES, or call it without a path
|
||||
|
||||
**NEVER**
|
||||
|
||||
- Never delete a target to make `dist adopt` replace it - a filled file is the instance's own work.
|
||||
|
||||
**NOTES**
|
||||
|
||||
- Copies `<name>.template` to `<name>` byte for byte; the template stays where it is, as the base the next `dist upgrade` compares against.
|
||||
- Without a path: every `kb/<collection>/COLLECTION.md.template` and every `types/*.template` (the `root: kb` page type-specs and their schemas).
|
||||
- With paths: exactly those templates, each of which has to be one of the set above.
|
||||
- Never overwrites: a target that already exists is reported as kept and left untouched.
|
||||
- Not for `kb/CONVENTIONS.md.template` or the personalization templates - those carry a sentinel and are filled in, not copied.
|
||||
- `--dry-run` lists what it would copy and keep, and writes nothing.
|
||||
|
||||
**SEE ALSO**
|
||||
|
||||
- `instructions/setup-instance.md` - adopts every template on a fresh instance
|
||||
- `instructions/upgrade-instance.md` - adopts a template a release added
|
||||
- `wikitool dist export` - re-keys these files as `.template` in the first place
|
||||
|
||||
#### `dist upgrade`
|
||||
|
||||
Apply a stack update `dist export` produced - the write half of `version check`.
|
||||
@@ -2492,7 +2541,7 @@ Apply a stack update `dist export` produced - the write half of `version check`.
|
||||
**ON FAILURE**
|
||||
|
||||
- Both `<source>` and `--latest`, or neither; or `--expect` without `--latest` -> Not transient - name exactly one source, and pass `--expect` only with `--latest`
|
||||
- Local `VERSION` missing, or no local `.wikitool-release.json` with a `files` block -> Not transient - fix the named precondition and retry. A checkout with shared git history takes stack updates with `wikitool upstream merge` instead
|
||||
- Local `VERSION` missing, or no local `.wikitool-release.json` with a `files` block -> Not transient - fix the named precondition and retry. A clone of the origin repo is a development checkout and takes no `dist upgrade` at all
|
||||
- `.wikitool-kb.json` is missing -> Run `wikitool migrate baseline <version>`, then retry
|
||||
- A migration is already outstanding against the *installed* machinery -> Finish it first - `wikitool migrate status` names it - then retry
|
||||
- The working tree is dirty -> Commit or stash first, then retry
|
||||
@@ -2537,7 +2586,6 @@ Apply a stack update `dist export` produced - the write half of `version check`.
|
||||
- `wikitool version notes` - the notes of the release `--expect` should name
|
||||
- `instructions/upgrade-instance.md` - the order after the swap
|
||||
- `INSTALL.md` § "Version und Updates" - which release, whether to take it, where the tarball comes from
|
||||
- `wikitool upstream merge` - the update path for a checkout with shared git history
|
||||
- `wikitool migrate status` - the migrations the report names
|
||||
|
||||
#### `version show`
|
||||
@@ -3081,118 +3129,6 @@ Declare `kb_version` once, for an instance predating `.wikitool-kb.json`.
|
||||
- `wikitool migrate done` - advances the version after a migration
|
||||
- `wikitool migrate status` - what is owed from the declared version
|
||||
|
||||
### Private instances
|
||||
|
||||
#### `upstream merge`
|
||||
|
||||
Take a stack update into a private instance's branch, machinery only.
|
||||
|
||||
**SYNOPSIS**
|
||||
|
||||
- `wikitool upstream merge [--remote upstream] [--branch main] [--no-fetch]`
|
||||
|
||||
**PROPERTIES**
|
||||
|
||||
- effect: write
|
||||
- idempotent: no
|
||||
- atomic: **No** - can leave an open, uncommitted merge behind on refusal after fetching
|
||||
- budget: counted
|
||||
- network: yes
|
||||
|
||||
**EXAMPLES**
|
||||
|
||||
- `tools/wikitool upstream merge`
|
||||
- `tools/wikitool upstream merge --remote upstream --branch main --no-fetch`
|
||||
|
||||
**EXIT STATUS**
|
||||
|
||||
- 0 success
|
||||
- 1 Dirty working tree, or a merge already in progress
|
||||
- 1 The remote does not resolve, the fetch failed, or `HEAD` does not resolve
|
||||
- 1 git refused to open the merge at all (unrelated histories); nothing was touched
|
||||
- 1 A real conflict remains in `tools/`/`types/`/`instructions/` after the content stages and stack-owned paths were restored; the merge is left open
|
||||
- 1 A git step failed inside the open merge (`git checkout MERGE_HEAD -- <path>` or `git commit --no-edit`)
|
||||
- 1 The postcheck after the commit found a leak; the merge commit already exists
|
||||
|
||||
**ON FAILURE**
|
||||
|
||||
- Dirty working tree, or a merge already in progress -> Fix the named precondition and retry once
|
||||
- The remote does not resolve, the fetch failed, or `HEAD` does not resolve -> Fix `--remote`/`--branch` or the repository state, then retry once
|
||||
- git refused to open the merge at all (unrelated histories); nothing was touched -> Do not retry unchanged - report it to the user
|
||||
- A real conflict remains in `tools/`/`types/`/`instructions/` after the content stages and stack-owned paths were restored; the merge is left open -> **Do not retry, do not force** - resolve the named paths by hand (take the upstream side, or re-file the local change as an issue against the public repo per `instructions/private-instance.md`) and either `git commit --no-edit` yourself or `git merge --abort`
|
||||
- A git step failed inside the open merge (`git checkout MERGE_HEAD -- <path>` or `git commit --no-edit`) -> Do not retry unchanged - inspect the open merge by hand
|
||||
- The postcheck after the commit found a leak; the merge commit already exists -> It is **not** rolled back automatically - inspect it by hand; this is a bug report, not a retry
|
||||
|
||||
**NEVER**
|
||||
|
||||
- Never retry a failed merge unchanged, and never force.
|
||||
|
||||
**NOTES**
|
||||
|
||||
- Refuses on a dirty working tree, a merge already in progress, or a remote that does not resolve. WARNs (does not block) when `.wikitool-remotes.json` is absent, pointing at the setup step that arms it.
|
||||
- Fetches `<remote>/<branch>` (unless `--no-fetch`) and reports "already up to date" if nothing new exists.
|
||||
- Otherwise opens `git merge --no-commit --no-ff <remote>/<branch>`, and stops, untouched, if git refused to open a merge at all (unrelated histories).
|
||||
- Forces every content stage (`kb/`, `raw/`, `work/`, `reports/`) back to the local side by removing **only the paths tracked in either tree** and checking `HEAD`'s back out - never the stage directory wholesale, so untracked and ignored local data under a stage (telemetry traces, saved eval and lint reports) is never deleted.
|
||||
- Then restores from the upstream side exactly the machinery paths - `<stage>/CONTRACT.md` and anything ending `.template` under a content stage - including a deletion, if the upstream removed one.
|
||||
- A real conflict left in `tools/`, `types/` or `instructions/` after that leaves the merge open, uncommitted, and exits 1 rather than guessing.
|
||||
- Commits with `git commit --no-edit`, then re-checks the resulting range with the `upstream verify` check; a finding there is a loud error, and the merge commit is not rolled back.
|
||||
- Never pushes.
|
||||
- Not idempotent, and not safe to retry unchanged.
|
||||
|
||||
**SEE ALSO**
|
||||
|
||||
- `instructions/private-instance.md` § "Taking a stack update" - the procedure this implements
|
||||
- `wikitool upstream verify` - the same check on any revision range
|
||||
- `wikitool publish` - pushes the merge afterwards
|
||||
|
||||
#### `upstream verify`
|
||||
|
||||
Compare two revisions: did anything under a content stage change except through a stack-owned path?
|
||||
|
||||
**SYNOPSIS**
|
||||
|
||||
- `wikitool upstream verify --since <rev> [--until HEAD]`
|
||||
|
||||
**PROPERTIES**
|
||||
|
||||
- effect: read
|
||||
- idempotent: yes
|
||||
- atomic: Read-only
|
||||
- budget: exempt
|
||||
- network: no
|
||||
|
||||
**EXAMPLES**
|
||||
|
||||
- `tools/wikitool upstream verify --since HEAD~1`
|
||||
- `tools/wikitool upstream verify --since v7.0.0 --until HEAD`
|
||||
|
||||
**EXIT STATUS**
|
||||
|
||||
- 0 success
|
||||
- 1 A leak: content changed under a content stage through a path that is not stack-owned
|
||||
- 1 `--since`/`--until` is not a revision in this repository
|
||||
|
||||
**ON FAILURE**
|
||||
|
||||
- A leak: content changed under a content stage through a path that is not stack-owned -> A finding is not fixed by re-running - it names the paths that leaked
|
||||
- `--since`/`--until` is not a revision in this repository -> Fix the revision argument and retry
|
||||
|
||||
**NEVER**
|
||||
|
||||
- Never re-run to make a leak finding go away.
|
||||
|
||||
**NOTES**
|
||||
|
||||
- Compares `--since` with `--until` (default `HEAD`): did anything under a content stage change except through a stack-owned path?
|
||||
- The same check `upstream merge` runs after its commit, so a hand-resolved merge conflict, or a `dist upgrade`, can be verified the same way.
|
||||
- Exits 1 with the offending paths if anything leaked; otherwise reports which stack-owned paths legitimately moved.
|
||||
- Read-only and exempt from the Iteration Budget Gate.
|
||||
|
||||
**SEE ALSO**
|
||||
|
||||
- `wikitool upstream merge` - runs this check after its commit
|
||||
- `instructions/private-instance.md` - the private-instance workflow
|
||||
|
||||
### Instance health
|
||||
|
||||
#### `doctor`
|
||||
|
||||
+2
-2
@@ -71,7 +71,7 @@ tools/
|
||||
wikitool entry point (POSIX sh): stops with exit 42 until the preflight has passed
|
||||
wikitool.ps1 the same entry point for PowerShell 7, which resolves `tools/wikitool` to this file first
|
||||
run_wikitool.py what the launcher runs with the venv's Python - puts chemenu on sys.path without PYTHONPATH, sets stdout/stderr to UTF-8
|
||||
preflight.sh checks prerequisites.txt, records .wikitool-tools.json, creates .venv (POSIX sh); as the release asset, downloads and unpacks the stack first
|
||||
preflight.sh checks prerequisites.txt, records .wikitool-tools.json, creates .venv (POSIX sh); as the release asset, downloads the stack and unpacks it into its own (empty) folder first
|
||||
preflight.ps1 the same for PowerShell 7; also checks the execution policy and the Mark of the Web
|
||||
prerequisites.txt what the machine needs, one `|`-separated line per tool - read by the preflight and `doctor`
|
||||
trace-hook what the harness hooks call: trace_ingest.py under the venv's Python
|
||||
@@ -91,7 +91,7 @@ tools/
|
||||
links.py labelled edges in `related:` - the graph's semantics as data, not prose
|
||||
kb_collections.py collection discovery (a directory with COLLECTION.md), and what one declares about itself
|
||||
conventions.py kb/CONVENTIONS.md: what this instance decided about authoring, as opposed to what the stack enforces
|
||||
ownership.py the stack-vs-instance boundary under a content stage - one predicate, read by `dist_cmd.py` and `commands/upstream_cmd.py` so the two cannot answer it differently
|
||||
ownership.py the stack-vs-instance boundary under a content stage - one predicate, so no caller keeps a list of its own
|
||||
type_resolver.py type-spec loading and schema resolution
|
||||
catalog.py how the corpus groups into collections and areas, and the shard threshold - with no CLI attached
|
||||
lint_core.py the lint checks and the report, with no CLI attached
|
||||
|
||||
@@ -49,7 +49,6 @@ try:
|
||||
touch as touch_module,
|
||||
types_cmd,
|
||||
upload_cmd,
|
||||
upstream_cmd,
|
||||
version_cmd,
|
||||
work_cmd,
|
||||
xref,
|
||||
@@ -178,7 +177,6 @@ app.add_typer(eval_cmd.app, name="eval")
|
||||
app.add_typer(dist_cmd.app, name="dist")
|
||||
app.add_typer(version_cmd.app, name="version")
|
||||
app.add_typer(migrate_cmd.app, name="migrate")
|
||||
app.add_typer(upstream_cmd.app, name="upstream")
|
||||
app.add_typer(task_cmd.app, name="task")
|
||||
app.command("new")(new_page.new_page_command)
|
||||
app.command("touch")(touch_module.touch_command)
|
||||
|
||||
@@ -276,16 +276,13 @@ GROUPS: tuple[tuple[str, tuple[str, ...]], ...] = (
|
||||
"eval sessions", "eval score",
|
||||
)),
|
||||
("Distribution and versioning", (
|
||||
"dist export", "dist upgrade",
|
||||
"dist export", "dist adopt", "dist upgrade",
|
||||
"version show", "version check", "version notes",
|
||||
"version bump", "version regrade", "version release",
|
||||
)),
|
||||
("Content migrations", (
|
||||
"migrate list", "migrate status", "migrate verify", "migrate done", "migrate baseline",
|
||||
)),
|
||||
("Private instances", (
|
||||
"upstream merge", "upstream verify",
|
||||
)),
|
||||
("Instance health", (
|
||||
"doctor",
|
||||
)),
|
||||
|
||||
@@ -149,8 +149,8 @@ INSTRUCTIONS_EXCLUDE_DIRS = {"dev"}
|
||||
# - it is a content stage too, but it has collections underneath it, so its
|
||||
# contract is handled by `build_plan` alongside them rather than as a bare
|
||||
# stage copy. Derived from `ownership.CONTENT_STAGES` rather than listed
|
||||
# again, so the set this loop copies and the set `upstream merge` restores
|
||||
# cannot name a different stage without one of them failing its own test.
|
||||
# again, so this loop and `ownership.is_stack_owned` cannot name a different
|
||||
# stage without one of them failing its own test.
|
||||
CONTRACT_ONLY_STAGES = tuple(
|
||||
f"{stage}/CONTRACT.md" for stage in ownership.CONTENT_STAGES if stage != "kb"
|
||||
)
|
||||
@@ -523,12 +523,9 @@ def build_plan(origin: Optional[Origin] = None) -> dict[str, PlannedFile]:
|
||||
# though they were the stack's.
|
||||
#
|
||||
# What counts as machinery under kb/ or raw/ is no longer a second list here:
|
||||
# it is `ownership.is_stack_owned`, the same predicate `upstream merge` and
|
||||
# `upstream verify` restore/check against. Only the export-only stubs
|
||||
# it is `ownership.is_stack_owned`. Only the export-only stubs
|
||||
# (`ownership.EXPORT_STUB_NAMES`) are allowed here without also being
|
||||
# stack-owned - a merge keeps the *local* copy of those, while export writes a
|
||||
# fresh one regardless of either side, so the two callers genuinely disagree
|
||||
# about them and each keeps its own allowance for that one case.
|
||||
# stack-owned - export writes a fresh one rather than shipping this repo's.
|
||||
_CONTENT_PREFIXES = ("kb/", "raw/")
|
||||
_INSTANCE_OWNED_KB_FILES = (kb_collections.CONTRACT_NAME, conventions.CONVENTIONS_FILENAME)
|
||||
|
||||
@@ -607,8 +604,10 @@ def _write_plan(target: Path, plan: dict[str, PlannedFile]) -> None:
|
||||
"a sha256 per exported file - the base a later upgrade compares against.",
|
||||
"The four origin options only fill stamp fields: `export` never calls git and cannot "
|
||||
"discover them.",
|
||||
"A build and test tool: every release is an export packed as a tarball, and an instance "
|
||||
"is installed from such a release, never from an export directly.",
|
||||
"One-way: no command reconstructs a distributed instance into a dev instance - work on "
|
||||
"the stack in the origin repo, or in a new dev instance exported from it.",
|
||||
"the stack in a clone of the origin repo.",
|
||||
"`--dry-run` lists every file it would write, and writes nothing.",
|
||||
),
|
||||
failures=(
|
||||
@@ -639,7 +638,7 @@ def _write_plan(target: Path, plan: dict[str, PlannedFile]) -> None:
|
||||
"Never merge an export into a non-empty directory by hand.",
|
||||
),
|
||||
see_also=(
|
||||
"`instructions/setup-instance.md` - what comes after the export",
|
||||
"`instructions/setup-instance.md` - installs a release, which is this export as a tarball",
|
||||
"`wikitool dist upgrade` - applies a later export to an existing instance",
|
||||
"`wikitool version show` - reads the stamp this writes",
|
||||
),
|
||||
@@ -725,6 +724,122 @@ def run_export(target: Path, dry_run: bool = False, origin: Optional[Origin] = N
|
||||
success(f"Exported {len(plan)} file(s) to {rel_path(target)}.")
|
||||
|
||||
|
||||
# --- dist adopt --------------------------------------------------------------
|
||||
#
|
||||
# The other half of the `.template` split above: an instance takes the shipped
|
||||
# default as its own by copying it to the unsuffixed name. Only the templates
|
||||
# whose shipped text is a working default are in scope - each collection's
|
||||
# contract and the page type-specs with their schemas. `kb/CONVENTIONS.md` and
|
||||
# the personalization files ship as templates too, but carry a sentinel and
|
||||
# exist to be filled in, so a verbatim copy of them would only be a file
|
||||
# `doctor` refuses; the agent writes those itself.
|
||||
|
||||
|
||||
def adoptable_templates() -> list[Path]:
|
||||
"""Every template `dist adopt` copies when it is given no path, sorted."""
|
||||
found = [
|
||||
path
|
||||
for path in config.KB_DIR.glob(f"*/{kb_collections.CONTRACT_NAME}{toc.TEMPLATE_SUFFIX}")
|
||||
if path.is_file()
|
||||
]
|
||||
found += [
|
||||
path for path in config.TYPES_DIR.glob(f"*{toc.TEMPLATE_SUFFIX}") if path.is_file()
|
||||
]
|
||||
return sorted(found)
|
||||
|
||||
|
||||
@cli_contract.record(cli_contract.CommandRecord(
|
||||
path="dist adopt",
|
||||
summary="Take shipped templates as this instance's own: copy each to its unsuffixed name.",
|
||||
synopsis=(cli_contract.Variant(usage="dist adopt [<template>...] [--dry-run]"),),
|
||||
properties=cli_contract.Properties(
|
||||
effect=cli_contract.Effect.WRITE,
|
||||
idempotent=cli_contract.Idempotent.YES,
|
||||
atomic="No - files are copied one by one; a re-run completes an interrupted one",
|
||||
budget=cli_contract.Budget.COUNTED,
|
||||
),
|
||||
notes=(
|
||||
"Copies `<name>.template` to `<name>` byte for byte; the template stays where it is, as "
|
||||
"the base the next `dist upgrade` compares against.",
|
||||
"Without a path: every `kb/<collection>/COLLECTION.md.template` and every "
|
||||
"`types/*.template` (the `root: kb` page type-specs and their schemas).",
|
||||
"With paths: exactly those templates, each of which has to be one of the set above.",
|
||||
"Never overwrites: a target that already exists is reported as kept and left untouched.",
|
||||
"Not for `kb/CONVENTIONS.md.template` or the personalization templates - those carry a "
|
||||
"sentinel and are filled in, not copied.",
|
||||
"`--dry-run` lists what it would copy and keep, and writes nothing.",
|
||||
),
|
||||
failures=(
|
||||
cli_contract.Failure(
|
||||
cause="A named path does not exist, or is not a collection contract or page type-spec "
|
||||
"template",
|
||||
reaction="Not transient - name a template from the set in NOTES, or call it without "
|
||||
"a path",
|
||||
),
|
||||
),
|
||||
examples=(
|
||||
"tools/wikitool dist adopt",
|
||||
"tools/wikitool dist adopt types/project.md.template types/project.schema.yaml.template",
|
||||
"tools/wikitool dist adopt --dry-run",
|
||||
),
|
||||
never=(
|
||||
"Never delete a target to make `dist adopt` replace it - a filled file is the "
|
||||
"instance's own work.",
|
||||
),
|
||||
see_also=(
|
||||
"`instructions/setup-instance.md` - adopts every template on a fresh instance",
|
||||
"`instructions/upgrade-instance.md` - adopts a template a release added",
|
||||
"`wikitool dist export` - re-keys these files as `.template` in the first place",
|
||||
),
|
||||
))
|
||||
@app.command("adopt")
|
||||
def adopt_command(
|
||||
templates: Optional[list[Path]] = typer.Argument(
|
||||
None, help="Templates to adopt. Default: every collection contract and page type-spec template."
|
||||
),
|
||||
dry_run: bool = typer.Option(
|
||||
False, "--dry-run", help="List what would be copied, without writing anything."
|
||||
),
|
||||
):
|
||||
"""Copy each shipped template to its unsuffixed name, never overwriting a file
|
||||
that already exists."""
|
||||
run_adopt(templates or [], dry_run=dry_run)
|
||||
|
||||
|
||||
def run_adopt(templates: Sequence[Path], dry_run: bool = False) -> None:
|
||||
adoptable = {path.resolve() for path in adoptable_templates()}
|
||||
if templates:
|
||||
chosen = []
|
||||
for given in templates:
|
||||
path = given if given.is_absolute() else config.ROOT / given
|
||||
if path.resolve() not in adoptable:
|
||||
fail(
|
||||
f"{given.as_posix()} is not a template `dist adopt` copies - it takes "
|
||||
"`kb/<collection>/COLLECTION.md.template` and `types/*.template` only."
|
||||
)
|
||||
return
|
||||
chosen.append(path)
|
||||
else:
|
||||
chosen = sorted(adoptable)
|
||||
|
||||
adopted = kept = 0
|
||||
for template in chosen:
|
||||
target = template.with_name(template.name[: -len(toc.TEMPLATE_SUFFIX)])
|
||||
if target.exists():
|
||||
typer.echo(f"keep {rel_path(target)} (exists)")
|
||||
kept += 1
|
||||
continue
|
||||
typer.echo(f"adopt {rel_path(template)} -> {rel_path(target)}")
|
||||
if not dry_run:
|
||||
shutil.copyfile(template, target)
|
||||
adopted += 1
|
||||
|
||||
if dry_run:
|
||||
success(f"Dry run: would adopt {adopted} template(s), keep {kept}. Nothing written.")
|
||||
else:
|
||||
success(f"Adopted {adopted} template(s), kept {kept}.")
|
||||
|
||||
|
||||
# --- dist upgrade ------------------------------------------------------------
|
||||
#
|
||||
# Apply a release `dist export` produced, rather than merely detecting one
|
||||
@@ -1149,8 +1264,8 @@ def _report_plan(
|
||||
cli_contract.Failure(
|
||||
cause="Local `VERSION` missing, or no local `.wikitool-release.json` with a `files` "
|
||||
"block",
|
||||
reaction="Not transient - fix the named precondition and retry. A checkout with "
|
||||
"shared git history takes stack updates with `wikitool upstream merge` instead",
|
||||
reaction="Not transient - fix the named precondition and retry. A clone of the "
|
||||
"origin repo is a development checkout and takes no `dist upgrade` at all",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
cause="`.wikitool-kb.json` is missing",
|
||||
@@ -1235,7 +1350,6 @@ def _report_plan(
|
||||
"`instructions/upgrade-instance.md` - the order after the swap",
|
||||
"`INSTALL.md` § \"Version und Updates\" - which release, whether to take it, where "
|
||||
"the tarball comes from",
|
||||
"`wikitool upstream merge` - the update path for a checkout with shared git history",
|
||||
"`wikitool migrate status` - the migrations the report names",
|
||||
),
|
||||
))
|
||||
@@ -1347,10 +1461,9 @@ def run_upgrade(
|
||||
fail(
|
||||
f"No local {version_mod.RELEASE_STAMP_FILENAME} (or it carries no `files` block). "
|
||||
"Without it, `dist upgrade` cannot tell a file this instance edited from one it "
|
||||
"merely received, and it refuses to guess. A checkout with shared git history takes "
|
||||
"stack updates via `wikitool upstream merge` instead - it has the same information "
|
||||
"as a merge base. A tarball instance that has lost its stamp has no repair path "
|
||||
"today; see Gitea #7 \"Bewusst offen gelassen\"."
|
||||
"merely received, and it refuses to guess. A clone of the origin repo is a "
|
||||
"development checkout and takes no `dist upgrade` at all. A release instance that "
|
||||
"has lost its stamp has no repair path today; see Gitea #7 \"Bewusst offen gelassen\"."
|
||||
)
|
||||
return
|
||||
old_files = old_stamp["files"]
|
||||
|
||||
@@ -655,7 +655,7 @@ MARKDOWN_LINK_RE = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)")
|
||||
# spelled again here: that module already decides which files are reference
|
||||
# material in both their forms, and this check runs over its scope. Not from
|
||||
# `ownership`, whose own `.template` handling answers a different question
|
||||
# (which side an upstream merge keeps) over a narrower scope (paths under a
|
||||
# (which path a release replaces) over a narrower scope (paths under a
|
||||
# content stage).
|
||||
TEMPLATE_SUFFIX = toc.TEMPLATE_SUFFIX
|
||||
|
||||
|
||||
@@ -411,8 +411,8 @@ def check_publish_remotes() -> Check:
|
||||
reports, the way `environment` does.
|
||||
|
||||
It does WARN for the case that actually bites: more than one remote
|
||||
configured and no allowlist. That is the shape a private instance has after
|
||||
it adds the public upstream, and it is exactly when a wrong `--remote`
|
||||
configured and no allowlist. That is the shape a private instance has once
|
||||
it adds a public remote, and it is exactly when a wrong `--remote`
|
||||
stops being a typo and starts being a disclosure.
|
||||
|
||||
Both absent states say **armed** or **not armed** rather than only naming
|
||||
|
||||
@@ -92,8 +92,8 @@ def _run(args: list[str]) -> subprocess.CompletedProcess:
|
||||
# The Mass-Update Gate asks "is this too much to publish?". This one asks the
|
||||
# question underneath it: "is this the right place to publish to at all?".
|
||||
#
|
||||
# A checkout holding private content typically has two remotes - its own, and
|
||||
# the public upstream it takes stack updates from. Nothing in git distinguishes
|
||||
# A checkout holding private content can have two remotes - its own, and a
|
||||
# public one it also works against. Nothing in git distinguishes
|
||||
# them at push time, so a single wrong `--remote` puts a private corpus on a
|
||||
# public repository, where a force-push does not take it back: the objects stay
|
||||
# fetchable by SHA until someone expires the server's reflogs.
|
||||
|
||||
@@ -1,513 +0,0 @@
|
||||
"""`wikitool upstream` - take a stack update from a public upstream into a
|
||||
private instance's `main` without letting the upstream's own content (a demo
|
||||
corpus, a workshop run) ride along.
|
||||
|
||||
`git merge upstream/main` on its own treats a moved corpus dangerously
|
||||
asymmetrically: a page the instance deleted and the upstream edited reports as
|
||||
a conflict, a page the upstream *added* stages silently, and a page both sides
|
||||
deleted is the only harmless case. `instructions/private-instance.md`'s prose
|
||||
procedure closes that, by holding the merge open, forcing the content stages
|
||||
(`ownership.CONTENT_STAGES`) back to the local side, and then restoring only
|
||||
the paths `ownership.is_stack_owned` recognises as machinery. `upstream merge`
|
||||
is that procedure in code, so the path set it acts on cannot drift from the
|
||||
one `dist_cmd.py` ships - both read `chemenu.ownership` - and so a conflict in
|
||||
the machinery layers, or a machinery file the upstream deleted, gets an
|
||||
explained stop instead of a silently wrong commit.
|
||||
|
||||
`upstream verify` is the other half: given two revisions, did anything change
|
||||
under a content stage except through a stack-owned path? It shares
|
||||
`_content_leaks` with the postcheck `upstream merge` runs on itself, so a
|
||||
hand-resolved merge or a future `dist upgrade` (Gitea #7) can be checked the
|
||||
same way.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
from pathlib import Path
|
||||
from typing import Optional
|
||||
|
||||
import typer
|
||||
|
||||
from chemenu import cli_contract, config, ownership
|
||||
from chemenu.commands import git_publish
|
||||
from chemenu.commands._util import console, fail, success
|
||||
|
||||
app = typer.Typer(help="Take a stack update from a public upstream, machinery only.")
|
||||
|
||||
|
||||
def _run(args: list[str]):
|
||||
import subprocess
|
||||
|
||||
return subprocess.run(args, cwd=config.ROOT, capture_output=True, text=True, encoding="utf-8")
|
||||
|
||||
|
||||
def _rev_parse(rev: str) -> Optional[str]:
|
||||
result = _run(["git", "rev-parse", "--verify", "-q", rev])
|
||||
return result.stdout.strip() if result.returncode == 0 else None
|
||||
|
||||
|
||||
def _git_dir() -> Optional[Path]:
|
||||
result = _run(["git", "rev-parse", "--git-dir"])
|
||||
if result.returncode != 0:
|
||||
return None
|
||||
path = Path(result.stdout.strip())
|
||||
return path if path.is_absolute() else config.ROOT / path
|
||||
|
||||
|
||||
def _working_tree_dirty() -> bool:
|
||||
result = _run(["git", "status", "--porcelain"])
|
||||
return bool(result.stdout.strip())
|
||||
|
||||
|
||||
def _merge_in_progress() -> bool:
|
||||
git_dir = _git_dir()
|
||||
return git_dir is not None and (git_dir / "MERGE_HEAD").exists()
|
||||
|
||||
|
||||
def _remote_resolves(remote: str) -> bool:
|
||||
return _run(["git", "remote", "get-url", remote]).returncode == 0
|
||||
|
||||
|
||||
def _is_ancestor(ancestor: str, of: str) -> bool:
|
||||
return _run(["git", "merge-base", "--is-ancestor", ancestor, of]).returncode == 0
|
||||
|
||||
|
||||
def _tree_has_path(rev: str, path: str) -> bool:
|
||||
return _run(["git", "rev-parse", "--verify", "-q", f"{rev}:{path}"]).returncode == 0
|
||||
|
||||
|
||||
def _tree_paths(rev: str) -> set[str]:
|
||||
result = _run(["git", "ls-tree", "-r", "--name-only", "-z", rev])
|
||||
if result.returncode != 0:
|
||||
return set()
|
||||
return {p for p in result.stdout.split("\0") if p}
|
||||
|
||||
|
||||
def _content_leaks(since: str, until: str) -> list[str]:
|
||||
"""Paths under a content stage that changed between `since` and `until`
|
||||
through something other than a stack-owned path. Shared by `upstream
|
||||
merge`'s own postcheck and `upstream verify`, so the two cannot disagree
|
||||
about what a clean update looks like."""
|
||||
result = _run(["git", "diff", "--name-only", "-z", since, until, "--", *ownership.CONTENT_STAGES])
|
||||
if result.returncode != 0:
|
||||
fail(
|
||||
f"`git diff {since} {until}` failed - is {since} a revision in this repository?\n"
|
||||
f"{result.stderr}"
|
||||
)
|
||||
return []
|
||||
changed = [p for p in result.stdout.split("\0") if p]
|
||||
return sorted(p for p in changed if not ownership.is_stack_owned(p))
|
||||
|
||||
|
||||
def _stack_paths_changed(since: str, until: str) -> list[str]:
|
||||
"""The subset of the same diff that *is* a stack-owned path - the paths
|
||||
that legitimately moved, for the success message."""
|
||||
result = _run(["git", "diff", "--name-only", "-z", since, until, "--", *ownership.CONTENT_STAGES])
|
||||
changed = [p for p in result.stdout.split("\0") if p]
|
||||
return sorted(p for p in changed if ownership.is_stack_owned(p))
|
||||
|
||||
|
||||
# --- upstream merge ---------------------------------------------------------
|
||||
|
||||
|
||||
def _prune_empty_dirs(stage: str) -> None:
|
||||
"""Remove directories left empty under `stage` after tracked files were
|
||||
deleted. git tracks no directories, so an emptied one is invisible to
|
||||
`git status` and would otherwise linger in the working tree as litter -
|
||||
an empty `kb/<area>/` that only ever existed in the upstream's corpus.
|
||||
Never touches a directory that still holds anything, ignored files
|
||||
included."""
|
||||
stage_dir = config.ROOT / stage
|
||||
if not stage_dir.is_dir():
|
||||
return
|
||||
for path in sorted(stage_dir.rglob("*"), key=lambda p: len(p.parts), reverse=True):
|
||||
if path.is_dir() and not any(path.iterdir()):
|
||||
path.rmdir()
|
||||
|
||||
|
||||
def _restore_stage_to_local(stage: str, tracked_paths: set[str]) -> None:
|
||||
"""Force one content stage back to the local (HEAD) side, whatever the
|
||||
merge did to it.
|
||||
|
||||
Deletes **only what git tracks on either side** - never the stage
|
||||
directory wholesale. That distinction is the whole point of this function:
|
||||
`reports/` is gitignored except its contract (see .gitignore), so a
|
||||
content stage's working tree legitimately holds local data that is not in
|
||||
any tree and not recomputable - the telemetry traces `eval score` reads,
|
||||
saved eval reports, past lint reports. A blanket `rm -rf` of the stage
|
||||
takes all of it out as collateral for a merge that was never about it.
|
||||
|
||||
Handles a stage that exists only in MERGE_HEAD too (the upstream
|
||||
introduced it): what the merge wrote is removed, and there is simply
|
||||
nothing to check out from HEAD afterwards.
|
||||
"""
|
||||
prefix = f"{stage}/"
|
||||
stage_paths = [p for p in tracked_paths if p.startswith(prefix)]
|
||||
if not stage_paths:
|
||||
return
|
||||
|
||||
_run(["git", "rm", "-rq", "--cached", "--ignore-unmatch", stage])
|
||||
for relative in stage_paths:
|
||||
target = config.ROOT / relative
|
||||
if target.is_file() or target.is_symlink():
|
||||
target.unlink()
|
||||
_prune_empty_dirs(stage)
|
||||
if _tree_has_path("HEAD", stage):
|
||||
_run(["git", "checkout", "HEAD", "--", stage])
|
||||
|
||||
|
||||
def _remote_gate_warning() -> None:
|
||||
if git_publish.read_allowed_push_urls() is not None:
|
||||
return
|
||||
console.print(
|
||||
"[bold yellow]WARN[/bold yellow] No .wikitool-remotes.json in this checkout - the "
|
||||
"Publish-Remote Gate is unarmed, so a future `publish` to the wrong remote would not "
|
||||
"be caught. `upstream merge` never pushes and proceeds regardless, but a checkout that "
|
||||
"takes stack updates from a public upstream should arm the gate before its next publish "
|
||||
"- see instructions/private-instance.md step 4."
|
||||
)
|
||||
|
||||
|
||||
def _precondition_failure(remote: str) -> Optional[str]:
|
||||
if _working_tree_dirty():
|
||||
return (
|
||||
"Working tree is not clean (`git status --porcelain` printed something). "
|
||||
"`upstream merge` refuses to start on a dirty tree so a refusal never has to "
|
||||
"guess which changes were already there. Commit or stash first."
|
||||
)
|
||||
if _merge_in_progress():
|
||||
return (
|
||||
"A merge is already in progress (.git/MERGE_HEAD exists). Resolve or abort it "
|
||||
"(`git merge --abort`) before running `upstream merge`."
|
||||
)
|
||||
if not _remote_resolves(remote):
|
||||
return f"Remote '{remote}' does not resolve (`git remote get-url {remote}` failed)."
|
||||
return None
|
||||
|
||||
|
||||
def _unresolved_conflict_message(unresolved: list[str], remote: str, branch: str) -> str:
|
||||
listed = "\n".join(f" - {p}" for p in unresolved)
|
||||
return (
|
||||
f"A real conflict remains in the machinery layers after restoring the content stages "
|
||||
f"and the stack-owned paths from {remote}/{branch}:\n{listed}\n\n"
|
||||
"The merge is left open, uncommitted - nothing was written to the branch. Per "
|
||||
"instructions/private-instance.md's decision points: this means the checkout changed "
|
||||
"the stack locally, which private instances do not do. Take the upstream side for "
|
||||
"these paths (`git checkout --theirs -- <path>` then `git add`) and re-file the local "
|
||||
"change as an issue against the public repo, or resolve deliberately and "
|
||||
"`git commit --no-edit` yourself. `git merge --abort` gives up the merge entirely."
|
||||
)
|
||||
|
||||
|
||||
def _postcheck_failure_message(leaks: list[str], before: str) -> str:
|
||||
listed = "\n".join(f" - {p}" for p in leaks)
|
||||
return (
|
||||
f"The merge commit exists (content stages are not what they were before this ran), "
|
||||
f"but it changed content outside of a stack-owned path:\n{listed}\n\n"
|
||||
f"This was NOT rolled back - the state belongs in front of you, not behind an automatic "
|
||||
f"repair the command applies to itself. Compare against the pre-merge commit ({before}) "
|
||||
"and decide by hand whether to revert the merge commit, cherry-pick around it, or fix "
|
||||
"forward. This is a bug in `upstream merge` or in `ownership.is_stack_owned` if it "
|
||||
"reproduces - please report it rather than working around it silently."
|
||||
)
|
||||
|
||||
|
||||
def _merge_success_message(
|
||||
changed: list[str], deleted: list[str], remote: str, branch: str
|
||||
) -> str:
|
||||
"""What the merge actually did, measured against the pre-merge commit
|
||||
rather than against what was restored.
|
||||
|
||||
`changed` is the real diff - restoring every stack-owned path from
|
||||
MERGE_HEAD touches each of them whether or not the upstream moved any, so
|
||||
reporting the restore list would claim seven updates for a merge that
|
||||
changed one file, and a reader who checks would find the report wrong.
|
||||
"""
|
||||
deleted_set = set(deleted)
|
||||
lines = [
|
||||
f"Merged {remote}/{branch}. Content stages "
|
||||
f"({', '.join(ownership.CONTENT_STAGES)}) are unchanged."
|
||||
]
|
||||
if changed:
|
||||
lines.append(f"Stack paths changed ({len(changed)}):")
|
||||
lines += [
|
||||
f" - {p}" + (" (deleted, following the upstream)" if p in deleted_set else "")
|
||||
for p in changed
|
||||
]
|
||||
else:
|
||||
lines.append("No stack-owned path changed.")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
@cli_contract.record(cli_contract.CommandRecord(
|
||||
path="upstream merge",
|
||||
summary="Take a stack update into a private instance's branch, machinery only.",
|
||||
synopsis=(cli_contract.Variant(
|
||||
usage="upstream merge [--remote upstream] [--branch main] [--no-fetch]",
|
||||
),),
|
||||
properties=cli_contract.Properties(
|
||||
effect=cli_contract.Effect.WRITE,
|
||||
idempotent=cli_contract.Idempotent.NO,
|
||||
atomic="**No** - can leave an open, uncommitted merge behind on refusal after fetching",
|
||||
budget=cli_contract.Budget.COUNTED,
|
||||
network=cli_contract.Network.YES,
|
||||
),
|
||||
notes=(
|
||||
"Refuses on a dirty working tree, a merge already in progress, or a remote that does "
|
||||
"not resolve. WARNs (does not block) when `.wikitool-remotes.json` is absent, pointing "
|
||||
"at the setup step that arms it.",
|
||||
"Fetches `<remote>/<branch>` (unless `--no-fetch`) and reports \"already up to date\" "
|
||||
"if nothing new exists.",
|
||||
"Otherwise opens `git merge --no-commit --no-ff <remote>/<branch>`, and stops, "
|
||||
"untouched, if git refused to open a merge at all (unrelated histories).",
|
||||
"Forces every content stage (`kb/`, `raw/`, `work/`, `reports/`) back to the local "
|
||||
"side by removing **only the paths tracked in either tree** and checking `HEAD`'s back "
|
||||
"out - never the stage directory wholesale, so untracked and ignored local data under "
|
||||
"a stage (telemetry traces, saved eval and lint reports) is never deleted.",
|
||||
"Then restores from the upstream side exactly the machinery paths - `<stage>/CONTRACT.md` "
|
||||
"and anything ending `.template` under a content stage - including a deletion, if the "
|
||||
"upstream removed one.",
|
||||
"A real conflict left in `tools/`, `types/` or `instructions/` after that leaves the "
|
||||
"merge open, uncommitted, and exits 1 rather than guessing.",
|
||||
"Commits with `git commit --no-edit`, then re-checks the resulting range with the "
|
||||
"`upstream verify` check; a finding there is a loud error, and the merge commit is not "
|
||||
"rolled back.",
|
||||
"Never pushes.",
|
||||
"Not idempotent, and not safe to retry unchanged.",
|
||||
),
|
||||
failures=(
|
||||
cli_contract.Failure(
|
||||
cause="Dirty working tree, or a merge already in progress",
|
||||
reaction="Fix the named precondition and retry once",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
cause="The remote does not resolve, the fetch failed, or `HEAD` does not resolve",
|
||||
reaction="Fix `--remote`/`--branch` or the repository state, then retry once",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
cause="git refused to open the merge at all (unrelated histories); nothing was "
|
||||
"touched",
|
||||
reaction="Do not retry unchanged - report it to the user",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
cause="A real conflict remains in `tools/`/`types/`/`instructions/` after the "
|
||||
"content stages and stack-owned paths were restored; the merge is left open",
|
||||
reaction="**Do not retry, do not force** - resolve the named paths by hand (take the "
|
||||
"upstream side, or re-file the local change as an issue against the public repo per "
|
||||
"`instructions/private-instance.md`) and either `git commit --no-edit` yourself or "
|
||||
"`git merge --abort`",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
cause="A git step failed inside the open merge (`git checkout MERGE_HEAD -- <path>` "
|
||||
"or `git commit --no-edit`)",
|
||||
reaction="Do not retry unchanged - inspect the open merge by hand",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
cause="The postcheck after the commit found a leak; the merge commit already exists",
|
||||
reaction="It is **not** rolled back automatically - inspect it by hand; this is a bug "
|
||||
"report, not a retry",
|
||||
),
|
||||
),
|
||||
examples=(
|
||||
"tools/wikitool upstream merge",
|
||||
"tools/wikitool upstream merge --remote upstream --branch main --no-fetch",
|
||||
),
|
||||
never=(
|
||||
"Never retry a failed merge unchanged, and never force.",
|
||||
),
|
||||
see_also=(
|
||||
"`instructions/private-instance.md` § \"Taking a stack update\" - the procedure this "
|
||||
"implements",
|
||||
"`wikitool upstream verify` - the same check on any revision range",
|
||||
"`wikitool publish` - pushes the merge afterwards",
|
||||
),
|
||||
))
|
||||
@app.command("merge")
|
||||
def merge_command(
|
||||
remote: str = typer.Option("upstream", "--remote", help="Remote to merge from"),
|
||||
branch: str = typer.Option("main", "--branch", help="Branch to merge"),
|
||||
no_fetch: bool = typer.Option(
|
||||
False, "--no-fetch", help="Skip `git fetch <remote>` - use whatever is already fetched"
|
||||
),
|
||||
):
|
||||
"""Merge `<remote>/<branch>` into the current branch, machinery only:
|
||||
every path under a content stage (kb/, raw/, work/, reports/) is forced
|
||||
back to the local side except a stack-owned path (`<stage>/CONTRACT.md`,
|
||||
or anything ending `.template` under a content stage), which is taken
|
||||
from the upstream - including a deletion, if the upstream removed one. A
|
||||
real conflict elsewhere (tools/, types/, instructions/) leaves the merge
|
||||
open and unresolved rather than guessing. Not idempotent: it can leave an
|
||||
open merge behind on refusal. See instructions/private-instance.md."""
|
||||
problem = _precondition_failure(remote)
|
||||
if problem:
|
||||
fail(problem)
|
||||
return
|
||||
|
||||
_remote_gate_warning()
|
||||
|
||||
before = _rev_parse("HEAD")
|
||||
if before is None:
|
||||
fail("HEAD does not resolve - is this a git repository with at least one commit?")
|
||||
return
|
||||
|
||||
if not no_fetch:
|
||||
fetch_result = _run(["git", "fetch", remote, branch])
|
||||
if fetch_result.returncode != 0:
|
||||
fail(f"`git fetch {remote} {branch}` failed:\n{fetch_result.stderr}")
|
||||
return
|
||||
|
||||
remote_ref = f"{remote}/{branch}"
|
||||
if _rev_parse(remote_ref) is None:
|
||||
fail(f"'{remote_ref}' does not resolve - fetch it first, or check --remote/--branch.")
|
||||
return
|
||||
|
||||
if _is_ancestor(remote_ref, "HEAD"):
|
||||
success(f"Already up to date with {remote_ref}.")
|
||||
return
|
||||
|
||||
# The exit code is deliberately not the test - conflicts under the content
|
||||
# stages are expected here and are exactly what the next steps undo. What
|
||||
# *is* load-bearing is that a merge actually opened: without MERGE_HEAD,
|
||||
# `_tree_paths("MERGE_HEAD")` is empty, and every stack-owned path in HEAD
|
||||
# would then read as "the upstream deleted it" and be removed. A merge git
|
||||
# refused to start (unrelated histories, an ignored file in the way) must
|
||||
# therefore stop here, with the tree untouched.
|
||||
merge_result = _run(["git", "merge", "--no-commit", "--no-ff", remote_ref])
|
||||
if not _merge_in_progress():
|
||||
fail(
|
||||
f"`git merge --no-commit --no-ff {remote_ref}` did not open a merge, so there is "
|
||||
f"nothing to scope - the working tree is unchanged:\n"
|
||||
f"{merge_result.stdout}{merge_result.stderr}"
|
||||
)
|
||||
return
|
||||
|
||||
merge_head_paths = _tree_paths("MERGE_HEAD")
|
||||
head_paths = _tree_paths("HEAD")
|
||||
tracked_paths = merge_head_paths | head_paths
|
||||
|
||||
for stage in ownership.CONTENT_STAGES:
|
||||
_restore_stage_to_local(stage, tracked_paths)
|
||||
|
||||
stack_paths = sorted(
|
||||
p for p in (merge_head_paths | head_paths) if ownership.is_stack_owned(p)
|
||||
)
|
||||
|
||||
# Only the deletions are recorded: what was *restored* is every stack-owned
|
||||
# path in MERGE_HEAD, which is not the same question as what changed - the
|
||||
# success message asks git for that instead.
|
||||
deleted: list[str] = []
|
||||
for relative in stack_paths:
|
||||
if relative in merge_head_paths:
|
||||
checkout = _run(["git", "checkout", "MERGE_HEAD", "--", relative])
|
||||
if checkout.returncode != 0:
|
||||
fail(
|
||||
f"`git checkout MERGE_HEAD -- {relative}` failed even though it is listed "
|
||||
f"in MERGE_HEAD's own tree:\n{checkout.stderr}\nThe merge is left open."
|
||||
)
|
||||
return
|
||||
else:
|
||||
_run(["git", "rm", "-q", "--cached", "--ignore-unmatch", relative])
|
||||
target = config.ROOT / relative
|
||||
if target.exists():
|
||||
target.unlink()
|
||||
deleted.append(relative)
|
||||
|
||||
unresolved = [p for p in _run(["git", "diff", "--name-only", "--diff-filter=U"]).stdout.splitlines() if p]
|
||||
if unresolved:
|
||||
fail(_unresolved_conflict_message(unresolved, remote, branch))
|
||||
return
|
||||
|
||||
commit_result = _run(["git", "commit", "--no-edit"])
|
||||
if commit_result.returncode != 0:
|
||||
fail(f"`git commit --no-edit` failed:\n{commit_result.stderr}")
|
||||
return
|
||||
|
||||
leaks = _content_leaks(before, "HEAD")
|
||||
if leaks:
|
||||
fail(_postcheck_failure_message(leaks, before))
|
||||
return
|
||||
|
||||
success(
|
||||
_merge_success_message(_stack_paths_changed(before, "HEAD"), deleted, remote, branch)
|
||||
)
|
||||
|
||||
|
||||
# --- upstream verify ---------------------------------------------------------
|
||||
|
||||
|
||||
def _verify_failure_message(leaks: list[str], since: str, until: str) -> str:
|
||||
listed = "\n".join(f" - {p}" for p in leaks)
|
||||
return (
|
||||
f"Content under a content stage (kb/, raw/, work/, reports/) changed between {since} "
|
||||
f"and {until} through a path that is not stack-owned:\n{listed}\n\n"
|
||||
"That is upstream content (or an equivalent local change) that reached this range "
|
||||
"outside of a stack-owned path - inspect it before trusting this range as machinery-only."
|
||||
)
|
||||
|
||||
|
||||
def _verify_success_message(stack_moved: list[str], since: str, until: str) -> str:
|
||||
if not stack_moved:
|
||||
return f"No content changed between {since} and {until} under kb/, raw/, work/, reports/."
|
||||
listed = "\n".join(f" - {p}" for p in stack_moved)
|
||||
return (
|
||||
f"Clean: only stack-owned paths changed under kb/, raw/, work/, reports/ between "
|
||||
f"{since} and {until}:\n{listed}"
|
||||
)
|
||||
|
||||
|
||||
@cli_contract.record(cli_contract.CommandRecord(
|
||||
path="upstream verify",
|
||||
summary="Compare two revisions: did anything under a content stage change except through "
|
||||
"a stack-owned path?",
|
||||
synopsis=(cli_contract.Variant(usage="upstream verify --since <rev> [--until HEAD]"),),
|
||||
properties=cli_contract.Properties(
|
||||
effect=cli_contract.Effect.READ,
|
||||
idempotent=cli_contract.Idempotent.YES,
|
||||
atomic="Read-only",
|
||||
budget=cli_contract.Budget.EXEMPT,
|
||||
),
|
||||
notes=(
|
||||
"Compares `--since` with `--until` (default `HEAD`): did anything under a content stage "
|
||||
"change except through a stack-owned path?",
|
||||
"The same check `upstream merge` runs after its commit, so a hand-resolved merge "
|
||||
"conflict, or a `dist upgrade`, can be verified the same way.",
|
||||
"Exits 1 with the offending paths if anything leaked; otherwise reports which "
|
||||
"stack-owned paths legitimately moved.",
|
||||
"Read-only and exempt from the Iteration Budget Gate.",
|
||||
),
|
||||
failures=(
|
||||
cli_contract.Failure(
|
||||
cause="A leak: content changed under a content stage through a path that is not "
|
||||
"stack-owned",
|
||||
reaction="A finding is not fixed by re-running - it names the paths that leaked",
|
||||
),
|
||||
cli_contract.Failure(
|
||||
cause="`--since`/`--until` is not a revision in this repository",
|
||||
reaction="Fix the revision argument and retry",
|
||||
),
|
||||
),
|
||||
examples=(
|
||||
"tools/wikitool upstream verify --since HEAD~1",
|
||||
"tools/wikitool upstream verify --since v7.0.0 --until HEAD",
|
||||
),
|
||||
never=(
|
||||
"Never re-run to make a leak finding go away.",
|
||||
),
|
||||
see_also=(
|
||||
"`wikitool upstream merge` - runs this check after its commit",
|
||||
"`instructions/private-instance.md` - the private-instance workflow",
|
||||
),
|
||||
))
|
||||
@app.command("verify")
|
||||
def verify_command(
|
||||
since: str = typer.Option(..., "--since", help="Git revision to compare from"),
|
||||
until: str = typer.Option("HEAD", "--until", help="Git revision to compare to"),
|
||||
):
|
||||
"""Check that nothing under a content stage changed between --since and
|
||||
--until except through a stack-owned path. Read-only, and exempt from the
|
||||
Iteration Budget Gate - the same treatment `migrate verify` gets, for the
|
||||
same reason: a check an agent has to ration is a check that gets skipped."""
|
||||
leaks = _content_leaks(since, until)
|
||||
if leaks:
|
||||
fail(_verify_failure_message(leaks, since, until))
|
||||
return
|
||||
success(_verify_success_message(_stack_paths_changed(since, until), since, until))
|
||||
@@ -265,7 +265,10 @@ def new_command(
|
||||
|
||||
typer.echo(f"Run key: {run_key}")
|
||||
typer.echo(f"Workshop: {rel_path(target)}/")
|
||||
typer.echo(f"Next: fill in plan.md, then export WIKITOOL_SESSION_ID=\"{run_key}/u1\"")
|
||||
typer.echo(
|
||||
f"Next: fill in plan.md, then set WIKITOOL_SESSION_ID to {run_key}/u1 "
|
||||
"(instructions/session-setup.md)"
|
||||
)
|
||||
success(f"Created workshop {run_key}")
|
||||
|
||||
|
||||
|
||||
@@ -226,8 +226,8 @@ TELEMETRY_FILENAME = ".wikitool-telemetry.json"
|
||||
|
||||
# Which push targets `publish` may write to, for a checkout that says so. The
|
||||
# danger this addresses is one checkout's content reaching another checkout's
|
||||
# remote - a private instance pushing its own `kb/` to a public upstream, where
|
||||
# it cannot be taken back.
|
||||
# remote - a private instance pushing its own `kb/` to a public repository,
|
||||
# where it cannot be taken back.
|
||||
#
|
||||
# It pins **URLs, not remote names**: a name-based list would pass a `publish`
|
||||
# whose `origin` had been repointed, which is the failure it exists to catch.
|
||||
|
||||
+12
-14
@@ -1,14 +1,13 @@
|
||||
"""The ownership boundary for a path under a content stage: does it belong to
|
||||
the *stack* (ships with every distribution, wins over local content when a
|
||||
private instance merges from a public upstream) or to the *instance* (never
|
||||
ships filled, wins over the upstream's version)?
|
||||
the *stack* (ships with every distribution, and a release replaces it) or to
|
||||
the *instance* (never ships filled, and no release touches it)?
|
||||
|
||||
One predicate, so `dist_cmd.py` (export) and `upstream_cmd.py` (merge/verify)
|
||||
answer the same question about the same paths instead of each keeping its own
|
||||
literal list that can drift out of sync with the other - see AGENTS.md
|
||||
invariant 8, and Gitea #30 for the incident that made the drift concrete
|
||||
(the private-instance merge procedure hardcoded a three-path list that
|
||||
`dist_cmd.py` had already outgrown).
|
||||
One predicate, so every caller answers the same question about the same paths
|
||||
instead of keeping its own literal list that can drift out of sync - see
|
||||
AGENTS.md invariant 8, and Gitea #30 for the incident that made the drift
|
||||
concrete (the private-instance merge procedure, since removed with
|
||||
`upstream merge` in Gitea #153, hardcoded a three-path list that `dist_cmd.py`
|
||||
had already outgrown).
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -21,9 +20,8 @@ from __future__ import annotations
|
||||
CONTENT_STAGES = ("kb", "raw", "work", "reports")
|
||||
|
||||
# Bare filenames `dist export` overwrites with a fresh stub rather than
|
||||
# shipping the stack's own copy. Not stack-owned: an upstream merge takes the
|
||||
# *local* side for these (they are the instance's own log/placeholder),
|
||||
# while `dist export` writes a brand-new one regardless of either side.
|
||||
# shipping the stack's own copy. Not stack-owned: they are the instance's own
|
||||
# log/placeholder, which `dist export` writes brand-new rather than copying.
|
||||
EXPORT_STUB_NAMES = ("log.md", ".gitkeep")
|
||||
|
||||
# The single machinery filename directly under a content stage's own root.
|
||||
@@ -33,7 +31,7 @@ _STAGE_CONTRACT_NAME = "CONTRACT.md"
|
||||
def is_stack_owned(relative: str) -> bool:
|
||||
"""Whether `relative` - a path under a content stage, e.g. "kb/CONTRACT.md"
|
||||
or "kb/entities/COLLECTION.md.template" - is machinery: it ships with
|
||||
every distribution, and it is the side an upstream merge keeps.
|
||||
every distribution, and a release replaces it.
|
||||
|
||||
True for exactly two shapes:
|
||||
|
||||
@@ -48,7 +46,7 @@ def is_stack_owned(relative: str) -> bool:
|
||||
|
||||
False for everything else under a content stage, `EXPORT_STUB_NAMES`
|
||||
included - those are handled separately by whichever caller cares about
|
||||
them, because the two callers disagree about which side wins for a stub.
|
||||
them.
|
||||
"""
|
||||
parts = relative.split("/")
|
||||
if len(parts) < 2 or parts[0] not in CONTENT_STAGES:
|
||||
|
||||
@@ -254,7 +254,7 @@ def test_top_level_help_is_the_index_without_frames(monkeypatch):
|
||||
line.split(" ")[0].strip() for line in text.splitlines() if " non-idempotent " in line
|
||||
}
|
||||
assert {
|
||||
"new", "log append", "publish", "upstream merge",
|
||||
"new", "log append", "publish",
|
||||
"version bump", "version release", "migrate done",
|
||||
} <= non_idempotent
|
||||
|
||||
@@ -344,7 +344,6 @@ def test_network_yes_is_exactly_the_commands_that_can_reach_outside_this_checkou
|
||||
expected = {
|
||||
"sync",
|
||||
"publish",
|
||||
"upstream merge",
|
||||
"version check",
|
||||
"version notes",
|
||||
"dist upgrade",
|
||||
|
||||
@@ -600,3 +600,64 @@ def test_validate_markers_rejects_nested_starts():
|
||||
dist_cmd._validate_markers(
|
||||
"<!-- dist:strip-start --><!-- dist:strip-start --><!-- dist:strip-end -->", "x"
|
||||
)
|
||||
|
||||
|
||||
# --- dist adopt ----------------------------------------------------------------
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def instance(repo):
|
||||
"""A tree in the shape `dist export` leaves behind: the collection contract
|
||||
and the page type-spec with its schema only as `.template`."""
|
||||
(repo / "kb" / "entities" / "COLLECTION.md").rename(
|
||||
repo / "kb" / "entities" / "COLLECTION.md.template"
|
||||
)
|
||||
for name in ("entity.md", "entity.schema.yaml"):
|
||||
(repo / "types" / name).rename(repo / "types" / f"{name}.template")
|
||||
return repo
|
||||
|
||||
|
||||
def test_adopt_without_a_path_copies_every_collection_and_type_template(instance):
|
||||
dist_cmd.run_adopt([])
|
||||
|
||||
for relative in ("kb/entities/COLLECTION.md", "types/entity.md", "types/entity.schema.yaml"):
|
||||
adopted = instance / relative
|
||||
template = instance / f"{relative}.template"
|
||||
assert adopted.read_bytes() == template.read_bytes()
|
||||
# Not in scope: the conventions template carries a sentinel and is filled, not copied.
|
||||
assert (instance / "kb" / "CONVENTIONS.md").read_text(encoding="utf-8").startswith("---")
|
||||
|
||||
|
||||
def test_adopt_never_overwrites_an_existing_target(instance):
|
||||
own = instance / "types" / "entity.md"
|
||||
own.write_text("# this instance's own entity\n", encoding="utf-8")
|
||||
|
||||
dist_cmd.run_adopt([])
|
||||
|
||||
assert own.read_text(encoding="utf-8") == "# this instance's own entity\n"
|
||||
assert (instance / "types" / "entity.schema.yaml").exists()
|
||||
|
||||
|
||||
def test_adopt_with_paths_copies_only_those(instance):
|
||||
dist_cmd.run_adopt([Path("types/entity.md.template")])
|
||||
|
||||
assert (instance / "types" / "entity.md").exists()
|
||||
assert not (instance / "types" / "entity.schema.yaml").exists()
|
||||
assert not (instance / "kb" / "entities" / "COLLECTION.md").exists()
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"given", ["kb/CONVENTIONS.md.template", "USER.md.template", "types/missing.md.template"]
|
||||
)
|
||||
def test_adopt_refuses_a_path_outside_its_set(instance, given):
|
||||
with pytest.raises(typer.Exit):
|
||||
dist_cmd.run_adopt([Path(given)])
|
||||
|
||||
assert not (instance / "kb" / "entities" / "COLLECTION.md").exists()
|
||||
|
||||
|
||||
def test_adopt_dry_run_writes_nothing(instance):
|
||||
dist_cmd.run_adopt([], dry_run=True)
|
||||
|
||||
assert not (instance / "types" / "entity.md").exists()
|
||||
assert not (instance / "kb" / "entities" / "COLLECTION.md").exists()
|
||||
@@ -0,0 +1,121 @@
|
||||
"""The stack's shipped instructions read the same in bash, Git Bash and PowerShell 7.
|
||||
|
||||
`instructions/CONTRACT.md` § Writing an instruction states the rule; this is the check behind it.
|
||||
An instruction is run by whichever harness the operator uses - Claude Code under Git Bash on
|
||||
Windows, Copilot under PowerShell 7 - so a command block that only one shell reads sends the
|
||||
other agent off to translate it, which is where the Weg-D install went wrong (Gitea #140, #153).
|
||||
|
||||
Scope: every instruction `dist export` ships, minus `instructions/migrations/`, which belong to
|
||||
the release they shipped with. A test rather than an `instructions verify` rule because the rule
|
||||
binds what the stack ships; an instance's own instructions are its own decision.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
REPO = Path(__file__).resolve().parents[3]
|
||||
INSTRUCTIONS = REPO / "instructions"
|
||||
|
||||
# The info strings of a block an agent runs; a json/yaml/markdown block is content, not a command.
|
||||
COMMAND_FENCES = {"", "bash", "sh", "shell", "console", "powershell", "pwsh"}
|
||||
|
||||
FORBIDDEN = (
|
||||
("heredoc", re.compile(r"<<")),
|
||||
("export", re.compile(r"(^|[;&|]\s*)export\s")),
|
||||
("command substitution", re.compile(r"\$\(")),
|
||||
("shell variable", re.compile(r"\$\{|\$[A-Z_][A-Z0-9_]*\b")),
|
||||
("inline environment", re.compile(r"^[A-Z_][A-Z0-9_]*=\S*\s+\S")),
|
||||
("&&", re.compile(r"&&")),
|
||||
("for loop", re.compile(r"^\s*for\s.*;\s*do\b")),
|
||||
("cp", re.compile(r"(^|[;&|]\s*)cp\s")),
|
||||
("cat >", re.compile(r"\bcat\s+>")),
|
||||
("sha256sum", re.compile(r"\bsha256sum\b")),
|
||||
("curl", re.compile(r"\bcurl\b")),
|
||||
("tar", re.compile(r"(^|[;&|]\s*)tar\s")),
|
||||
)
|
||||
|
||||
# The two sanctioned exceptions, each one line per shell (instructions/CONTRACT.md): the session
|
||||
# id (D26) and the preflight download before an instance exists (E2). Keyed by exact line, so a
|
||||
# second use of the same construct elsewhere still fails.
|
||||
ALLOWED = {
|
||||
("session-setup.md", 'export WIKITOOL_SESSION_ID="wiki-20261001-1430"'),
|
||||
("session-setup.md", "$env:WIKITOOL_SESSION_ID = 'wiki-20261001-1430'"),
|
||||
("setup-instance.md", "curl -fLO <browser_download_url of preflight.sh>"),
|
||||
}
|
||||
|
||||
|
||||
def shipped_instructions() -> list[Path]:
|
||||
return sorted(
|
||||
path
|
||||
for path in INSTRUCTIONS.rglob("*.md")
|
||||
if not {"dev", "migrations"} & set(path.relative_to(INSTRUCTIONS).parts[:-1])
|
||||
)
|
||||
|
||||
|
||||
def command_lines(path: Path):
|
||||
"""`(line number, line)` for every line inside a command fence."""
|
||||
fence = None
|
||||
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
|
||||
stripped = line.strip()
|
||||
if stripped.startswith("```"):
|
||||
fence = None if fence is not None else stripped[3:].strip()
|
||||
continue
|
||||
if fence is not None and fence in COMMAND_FENCES and stripped:
|
||||
yield number, stripped
|
||||
|
||||
|
||||
def test_the_scope_is_not_empty():
|
||||
names = {path.name for path in shipped_instructions()}
|
||||
assert {"setup-instance.md", "session-setup.md", "upgrade-instance.md"} <= names
|
||||
assert not any("migrations" in path.parts for path in shipped_instructions())
|
||||
|
||||
|
||||
@pytest.mark.parametrize("path", shipped_instructions(), ids=lambda p: str(p.relative_to(INSTRUCTIONS)))
|
||||
def test_a_shipped_instruction_uses_no_shell_specific_syntax(path):
|
||||
found = [
|
||||
f"{path.relative_to(REPO)}:{number}: {name}: {line}"
|
||||
for number, line in command_lines(path)
|
||||
if (path.name, line) not in ALLOWED
|
||||
for name, pattern in FORBIDDEN
|
||||
if pattern.search(line)
|
||||
]
|
||||
assert not found, "\n".join(found)
|
||||
|
||||
|
||||
def test_every_exception_is_still_in_use():
|
||||
"""An allowance nobody uses any more is a gap waiting for the next construct."""
|
||||
used = {
|
||||
(path.name, line)
|
||||
for path in shipped_instructions()
|
||||
for _, line in command_lines(path)
|
||||
}
|
||||
assert ALLOWED <= used, ALLOWED - used
|
||||
|
||||
|
||||
SHIPPED_DOCS = ("AGENTS.md", "README.md", "INSTALL.md", "EVALS.md")
|
||||
|
||||
# A line that starts the PowerShell preflight - bare (`.\tools\preflight.ps1`, `& preflight.ps1`)
|
||||
# or through pwsh - as opposed to one that merely names the file (a comment, a download).
|
||||
PREFLIGHT_CALL = re.compile(r"^(?:&\s*)?(?:\.[\\/])?(?:tools[\\/])?preflight\.ps1\b|^pwsh\b.*preflight\.ps1")
|
||||
BYPASS = "pwsh -NoProfile -ExecutionPolicy Bypass -File "
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"path",
|
||||
[REPO / name for name in SHIPPED_DOCS] + shipped_instructions(),
|
||||
ids=lambda p: str(p.relative_to(REPO)),
|
||||
)
|
||||
def test_every_powershell_preflight_call_carries_the_bypass(path):
|
||||
"""Copilot started `.\\tools\\preflight.ps1` bare in the #151 hand check; in a checkout that
|
||||
carries a Mark of the Web that call fails with PowerShell's own refusal and no guidance."""
|
||||
if not path.is_file():
|
||||
pytest.skip(f"{path.name} is not in this tree")
|
||||
bare = [
|
||||
f"{number}: {line}"
|
||||
for number, line in command_lines(path)
|
||||
if PREFLIGHT_CALL.match(line) and not line.startswith(BYPASS)
|
||||
]
|
||||
assert not bare, "\n".join(bare)
|
||||
@@ -421,29 +421,29 @@ def build_release(base: Path, *, limit: int | None = None, tops: tuple[str, ...]
|
||||
|
||||
|
||||
class AssetMachine(Machine):
|
||||
"""The release asset on a machine with nothing unpacked yet: just the script, alone in a folder."""
|
||||
"""The release asset on a machine with nothing unpacked yet: just the script, alone in
|
||||
the folder the wiki is to be installed in."""
|
||||
|
||||
def __init__(self, base: Path, *, filled: bool = False, **release):
|
||||
def __init__(self, base: Path, *, filled: bool = False, script: str = "preflight.sh", **release):
|
||||
super().__init__(base)
|
||||
self.tarball = build_release(base, **release)
|
||||
self.download = base / "download"
|
||||
self.download.mkdir()
|
||||
for name, pairs in PLACEHOLDERS.items():
|
||||
text = (TOOLS / name).read_text(encoding="utf-8")
|
||||
for empty, full in pairs:
|
||||
assert empty in text, f"{name} lost its placeholder {empty}"
|
||||
if filled:
|
||||
text = text.replace(empty, full)
|
||||
(self.download / name).write_text(text, encoding="utf-8")
|
||||
self.script = self.download / "preflight.sh"
|
||||
self.root = self.download / "chemenu"
|
||||
text = (TOOLS / script).read_text(encoding="utf-8")
|
||||
for empty, full in PLACEHOLDERS[script]:
|
||||
assert empty in text, f"{script} lost its placeholder {empty}"
|
||||
if filled:
|
||||
text = text.replace(empty, full)
|
||||
self.script = self.download / script
|
||||
self.script.write_text(text, encoding="utf-8")
|
||||
self.root = self.download
|
||||
self.tools = self.root / "tools"
|
||||
self.cwd = self.download
|
||||
self.extra_env.update({"RELEASE_DIR": str(self.tarball.parent), "CURL_LOG": str(base / "curl.log")})
|
||||
self.standard()
|
||||
|
||||
def unpacked(self, root: Path | None = None) -> bool:
|
||||
return (root or self.root).exists()
|
||||
return ((root or self.root) / "tools").exists()
|
||||
|
||||
def leftovers(self) -> list[str]:
|
||||
found = [str(path) for path in self.base.rglob(".chemenu-unpack.*")]
|
||||
@@ -457,16 +457,28 @@ def asset(tmp_path: Path) -> AssetMachine:
|
||||
|
||||
|
||||
@pytest.mark.parametrize("shell", SHELLS)
|
||||
def test_asset_unpacks_next_to_itself_and_runs_the_tree_copy(asset, shell):
|
||||
def test_asset_unpacks_into_its_own_folder_and_runs_the_tree_copy(asset, shell):
|
||||
result = asset.run("--archive", str(asset.tarball), shell=shell)
|
||||
assert result.returncode == 0, result.stdout + result.stderr
|
||||
assert "sha256 OK" in result.stdout and "Preflight passed" in result.stdout
|
||||
assert (asset.tools / "preflight.sh").is_file() and (asset.tools / "prerequisites.txt").is_file()
|
||||
assert asset.recorded()["complete"] is True
|
||||
assert (asset.tools / ".venv").is_dir()
|
||||
# The asset itself is gone, so the first commit holds the stack and nothing else.
|
||||
assert not asset.script.exists()
|
||||
assert not asset.leftovers()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("shell", SHELLS)
|
||||
def test_an_empty_clone_is_an_empty_folder(asset, shell):
|
||||
(asset.root / ".git").mkdir()
|
||||
(asset.root / ".git" / "HEAD").write_text("ref: refs/heads/main\n", encoding="utf-8")
|
||||
result = asset.run("--archive", str(asset.tarball), shell=shell)
|
||||
assert result.returncode == 0, result.stdout + result.stderr
|
||||
assert (asset.root / ".git" / "HEAD").read_text(encoding="utf-8") == "ref: refs/heads/main\n"
|
||||
assert (asset.tools / "preflight.sh").is_file()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("shell", SHELLS)
|
||||
def test_into_chooses_the_target_and_creates_missing_parents(asset, shell):
|
||||
target = asset.base / "deep" / "er" / "wiki"
|
||||
@@ -475,6 +487,8 @@ def test_into_chooses_the_target_and_creates_missing_parents(asset, shell):
|
||||
assert (target / "tools" / "preflight.sh").is_file()
|
||||
assert (target / ".wikitool-tools.json").is_file()
|
||||
assert not asset.unpacked()
|
||||
# Not in the target, so not the instance's to keep out of a commit.
|
||||
assert asset.script.exists()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("shell", SHELLS)
|
||||
@@ -486,13 +500,18 @@ def test_a_relative_into_resolves_against_the_working_directory(asset, shell):
|
||||
|
||||
|
||||
@pytest.mark.parametrize("shell", SHELLS)
|
||||
def test_an_existing_target_is_refused_and_left_alone(asset, shell):
|
||||
asset.root.mkdir()
|
||||
(asset.root / "mine.txt").write_text("keep", encoding="utf-8")
|
||||
result = asset.run("--archive", str(asset.tarball), shell=shell)
|
||||
@pytest.mark.parametrize("into", [False, True])
|
||||
def test_an_occupied_target_is_refused_and_left_alone(asset, shell, into):
|
||||
target = asset.base / "occupied" if into else asset.root
|
||||
target.mkdir(exist_ok=True)
|
||||
(target / "mine.txt").write_text("keep", encoding="utf-8")
|
||||
before = sorted(path.name for path in target.iterdir())
|
||||
args = ("--into", str(target)) if into else ()
|
||||
result = asset.run("--archive", str(asset.tarball), *args, shell=shell)
|
||||
assert result.returncode == 1
|
||||
assert "already exists" in result.stderr and "--into" in result.stderr
|
||||
assert [path.name for path in asset.root.iterdir()] == ["mine.txt"]
|
||||
assert "is not empty" in result.stderr and "--into" in result.stderr
|
||||
assert sorted(path.name for path in target.iterdir()) == before
|
||||
assert asset.script.exists()
|
||||
assert not asset.leftovers()
|
||||
|
||||
|
||||
@@ -618,7 +637,8 @@ def test_the_folder_limit_is_judged_at_the_final_target_from_the_archive(
|
||||
result = asset.run("--archive", str(asset.tarball), "--into", str(target), shell=shell)
|
||||
assert result.returncode == expected, result.stdout + result.stderr
|
||||
if expected == 42:
|
||||
assert_guidance(result.stdout, f"too long ({length} characters, at most {limit or 95})")
|
||||
assert_guidance(result.stdout, f"too long ({length} characters, at most {limit or 95})",
|
||||
"such as C:\\Chemenu - put this script there", "--into C:\\Chemenu.")
|
||||
assert not asset.unpacked(target) and not asset.leftovers()
|
||||
else:
|
||||
assert (target / "tools" / "preflight.sh").is_file()
|
||||
@@ -643,7 +663,8 @@ def test_the_release_workflow_fills_exactly_the_placeholders_the_scripts_keep():
|
||||
expression = f"s|^{as_written_in_the_workflow(empty)}|{as_written_in_the_workflow(filled)}|"
|
||||
assert expression in text, f"release.yml does not run {expression}"
|
||||
assert 'download="${PUBLIC_BASE_URL}/${GITHUB_REPOSITORY}/releases/download/${TAG}"' in text
|
||||
assert 'for asset in "${NAME}.tar.gz" "${NAME}.tar.gz.sha256" preflight.sh preflight.ps1; do' in text
|
||||
assert ('for asset in "${NAME}.tar.gz" "${NAME}.tar.gz.sha256" preflight.sh preflight.ps1 '
|
||||
'setup-instance.md preflight.md; do') in text
|
||||
|
||||
|
||||
# --- the launcher -----------------------------------------------------------------
|
||||
|
||||
@@ -216,41 +216,49 @@ def _asset_run(asset: AssetMachine, *args: str) -> subprocess.CompletedProcess:
|
||||
**asset.extra_env,
|
||||
}
|
||||
return subprocess.run(
|
||||
[PWSH, "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(asset.download / "preflight.ps1"), *args],
|
||||
[PWSH, "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(asset.script), *args],
|
||||
capture_output=True, text=True, env=env, timeout=120, cwd=asset.cwd,
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def asset(tmp_path: Path) -> AssetMachine:
|
||||
return AssetMachine(tmp_path.resolve())
|
||||
return AssetMachine(tmp_path.resolve(), script="preflight.ps1")
|
||||
|
||||
|
||||
def test_asset_unpacks_next_to_itself_and_runs_the_tree_copy(asset):
|
||||
def test_asset_unpacks_into_its_own_folder_and_runs_the_tree_copy(asset):
|
||||
result = _asset_run(asset, "--archive", str(asset.tarball))
|
||||
assert result.returncode == 0, result.stdout + result.stderr
|
||||
assert "sha256 OK" in result.stdout and "Preflight passed" in result.stdout
|
||||
assert (asset.tools / "preflight.ps1").is_file()
|
||||
assert asset.recorded()["complete"] is True
|
||||
assert not asset.script.exists()
|
||||
assert not asset.leftovers()
|
||||
|
||||
|
||||
def test_an_empty_clone_is_an_empty_folder(asset):
|
||||
(asset.root / ".git").mkdir()
|
||||
result = _asset_run(asset, "--archive", str(asset.tarball))
|
||||
assert result.returncode == 0, result.stdout + result.stderr
|
||||
assert (asset.root / ".git").is_dir() and (asset.tools / "preflight.ps1").is_file()
|
||||
|
||||
|
||||
def test_into_chooses_the_target_and_a_relative_one_follows_the_working_directory(asset):
|
||||
far = asset.base / "deep" / "er" / "wiki"
|
||||
assert _asset_run(asset, "--archive", str(asset.tarball), "--into", str(far)).returncode == 0
|
||||
assert (far / "tools" / "preflight.ps1").is_file() and not asset.unpacked()
|
||||
assert asset.script.exists()
|
||||
asset.cwd = asset.base
|
||||
assert _asset_run(asset, "--archive", str(asset.tarball), "--into", "here").returncode == 0
|
||||
assert (asset.base / "here" / "tools" / "preflight.ps1").is_file()
|
||||
|
||||
|
||||
def test_an_existing_target_is_refused_and_left_alone(asset):
|
||||
asset.root.mkdir()
|
||||
def test_an_occupied_target_is_refused_and_left_alone(asset):
|
||||
(asset.root / "mine.txt").write_text("keep", encoding="utf-8")
|
||||
result = _asset_run(asset, "--archive", str(asset.tarball))
|
||||
assert result.returncode == 1
|
||||
assert "already exists" in result.stderr and "--into" in result.stderr
|
||||
assert [path.name for path in asset.root.iterdir()] == ["mine.txt"]
|
||||
assert "is not empty" in result.stderr and "--into" in result.stderr
|
||||
assert sorted(path.name for path in asset.root.iterdir()) == ["mine.txt", "preflight.ps1"]
|
||||
|
||||
|
||||
def test_a_wrong_sha256_exits_1_and_unpacks_nothing(asset):
|
||||
@@ -270,7 +278,7 @@ def test_archive_without_a_checksum_file_exits_1(asset):
|
||||
|
||||
|
||||
def test_an_archive_with_two_top_level_folders_exits_1(tmp_path):
|
||||
asset = AssetMachine(tmp_path.resolve(), tops=("chemenu-stack-9.9.9", "stray"))
|
||||
asset = AssetMachine(tmp_path.resolve(), script="preflight.ps1", tops=("chemenu-stack-9.9.9", "stray"))
|
||||
result = _asset_run(asset, "--archive", str(asset.tarball))
|
||||
assert result.returncode == 1 and "exactly one top-level folder" in result.stderr
|
||||
assert not asset.unpacked() and not asset.leftovers()
|
||||
@@ -296,7 +304,7 @@ def test_set_and_the_exit_code_pass_through_to_the_tree_copy(asset):
|
||||
assert_guidance(refused.stdout, "The path given for ripgrep (rg) does not work")
|
||||
assert (asset.tools / "preflight.ps1").is_file() and not asset.tools_file.exists()
|
||||
|
||||
second = AssetMachine(asset.base / "second")
|
||||
second = AssetMachine(asset.base / "second", script="preflight.ps1")
|
||||
elsewhere = second.stub("rg", "#!/bin/sh\necho 'ripgrep 14.1.1'\n", asset.base / "opt")
|
||||
ok = _asset_run(second, "--archive", str(second.tarball), "--set", f"rg={elsewhere}")
|
||||
assert ok.returncode == 0, ok.stdout
|
||||
@@ -321,14 +329,15 @@ def test_the_folder_limit_is_judged_at_the_final_target_from_the_archive(
|
||||
base = tmp_path.resolve()
|
||||
name_length = length - len(str(base / "download")) - 1
|
||||
assert name_length > 0, "tmp_path is too long for this test"
|
||||
asset = AssetMachine(base, limit=limit)
|
||||
asset = AssetMachine(base, script="preflight.ps1", limit=limit)
|
||||
asset.standard(pwsh=True)
|
||||
asset.extra_env.update({"CHEMENU_PREFLIGHT_PLATFORM": "windows", "CHEMENU_PREFLIGHT_LONGPATHS": longpaths})
|
||||
target = asset.download / ("t" * name_length)
|
||||
result = _asset_run(asset, "--archive", str(asset.tarball), "--into", str(target))
|
||||
assert result.returncode == expected, result.stdout + result.stderr
|
||||
if expected == 42:
|
||||
assert_guidance(result.stdout, f"too long ({length} characters, at most {limit or 95})")
|
||||
assert_guidance(result.stdout, f"too long ({length} characters, at most {limit or 95})",
|
||||
"such as C:\\Chemenu - put this script there", "--into C:\\Chemenu.")
|
||||
assert not asset.unpacked(target) and not asset.leftovers()
|
||||
else:
|
||||
assert (target / "tools" / "preflight.ps1").is_file()
|
||||
@@ -340,7 +349,7 @@ def release_server(asset):
|
||||
handler.log_message = lambda *args: None
|
||||
server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), handler)
|
||||
threading.Thread(target=server.serve_forever, daemon=True).start()
|
||||
script = asset.download / "preflight.ps1"
|
||||
script = asset.script
|
||||
script.write_text(
|
||||
(TOOLS / "preflight.ps1").read_text(encoding="utf-8").replace(
|
||||
"$ReleaseArchiveUrl = \'\'", f"$ReleaseArchiveUrl = \'http://127.0.0.1:{server.server_port}/{asset.tarball.name}\'").replace(
|
||||
|
||||
@@ -265,7 +265,7 @@ def test_exempt_budget_matches_the_pre_121_skip_sets():
|
||||
"search", "doctor", "review", # old SKIP_COMMANDS
|
||||
"budget status", "eval score", "eval sessions", "cite id", "links show",
|
||||
"version show", "version check", "version notes",
|
||||
"migrate list", "migrate status", "migrate verify", "upstream verify",
|
||||
"migrate list", "migrate status", "migrate verify",
|
||||
}
|
||||
actual = {
|
||||
path
|
||||
|
||||
@@ -1,470 +0,0 @@
|
||||
"""Tests for `wikitool upstream merge`/`upstream verify` - the code procedure
|
||||
that replaces private-instance.md's prose merge script (Gitea #30).
|
||||
|
||||
Two real git repos stand in for a private instance (`repo`, remote name
|
||||
`upstream`) and the public repo it takes updates from (`upstream`, a plain
|
||||
repo committed to directly - a fetch-only remote does not need to be bare for
|
||||
`git fetch` to work against it). Each scenario diverges the two by committing
|
||||
independently on each side, exactly like a real fetch-only upstream would.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import subprocess
|
||||
|
||||
import pytest
|
||||
import typer
|
||||
|
||||
from chemenu import config, ownership
|
||||
from chemenu.commands import git_publish, upstream_cmd
|
||||
|
||||
|
||||
def _git(root, *args):
|
||||
result = subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
|
||||
assert result.returncode == 0, result.stderr
|
||||
return result
|
||||
|
||||
|
||||
def _write(root, relative, content):
|
||||
path = root / relative
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(content, encoding="utf-8")
|
||||
|
||||
|
||||
def _commit(root, message):
|
||||
_git(root, "add", "-A")
|
||||
_git(root, "commit", "-m", message)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def two_repos(tmp_path, monkeypatch):
|
||||
"""`repo`, a private instance, with a fetch-only `upstream` remote pointing
|
||||
at a second, independent repo. Both start from the same seed commit -
|
||||
kb/CONTRACT.md, kb/CONVENTIONS.md(.template), kb/entities/COLLECTION.md,
|
||||
raw/CONTRACT.md, work/CONTRACT.md, reports/CONTRACT.md, and one tools/
|
||||
file - which is what a private instance looks like right after the
|
||||
private-instance.md setup: the tracked machinery, plus its own filled
|
||||
instance files layered on top.
|
||||
"""
|
||||
seed = tmp_path / "seed"
|
||||
seed.mkdir()
|
||||
_git(seed, "init", "-b", "main")
|
||||
_git(seed, "config", "user.name", "Seed")
|
||||
_git(seed, "config", "user.email", "seed@example.com")
|
||||
# .wikitool-remotes.json is gitignored in the real repo (it is per-checkout,
|
||||
# see config.PUBLISH_REMOTES_FILENAME) - without this, dropping one into the
|
||||
# fixture during a test would show up as an untracked file and trip the
|
||||
# dirty-working-tree precondition for a reason that has nothing to do with
|
||||
# what that test is checking.
|
||||
# Mirrors the real .gitignore in the two ways that matter here:
|
||||
# `.wikitool-remotes.json` is per-checkout (dropping one in during a test
|
||||
# must not read as a dirty tree), and `reports/` is derived output that is
|
||||
# ignored except for its contract - which is what makes a content stage
|
||||
# able to hold local, non-recomputable data a merge must not touch.
|
||||
_write(
|
||||
seed,
|
||||
".gitignore",
|
||||
f"/{config.PUBLISH_REMOTES_FILENAME}\n/reports/*\n!/reports/CONTRACT.md\n",
|
||||
)
|
||||
_write(seed, "kb/CONTRACT.md", "stack kb contract v1\n")
|
||||
_write(seed, "kb/CONVENTIONS.md.template", "template v1\n")
|
||||
_write(seed, "kb/CONVENTIONS.md", "instance conventions v1\n")
|
||||
_write(seed, "kb/entities/COLLECTION.md", "instance collection contract v1\n")
|
||||
_write(seed, "kb/Both.md", "page both sides delete\n")
|
||||
_write(seed, "kb/ToDelete.md", "page the instance will delete\n")
|
||||
_write(seed, "kb/RegularPage.md", "an ordinary page neither side has touched yet\n")
|
||||
_write(seed, "raw/CONTRACT.md", "raw contract v1\n")
|
||||
_write(seed, "work/CONTRACT.md", "work contract v1\n")
|
||||
_write(seed, "reports/CONTRACT.md", "reports contract v1\n")
|
||||
_write(seed, "tools/wikitool.py", "line one\nline two\nline three\n")
|
||||
_commit(seed, "seed")
|
||||
|
||||
upstream = tmp_path / "upstream"
|
||||
subprocess.run(["git", "clone", str(seed), str(upstream)], check=True, capture_output=True)
|
||||
_git(upstream, "config", "user.name", "Upstream")
|
||||
_git(upstream, "config", "user.email", "upstream@example.com")
|
||||
|
||||
# Cloned from `upstream`, not from `seed` directly: the remote (renamed
|
||||
# below) must resolve to the path this fixture actually commits new
|
||||
# upstream state into, or a later `git fetch upstream main` silently
|
||||
# fetches from `seed` instead and never sees anything new.
|
||||
repo = tmp_path / "repo"
|
||||
subprocess.run(["git", "clone", str(upstream), str(repo)], check=True, capture_output=True)
|
||||
_git(repo, "config", "user.name", "Test")
|
||||
_git(repo, "config", "user.email", "test@example.com")
|
||||
_git(repo, "remote", "rename", "origin", "upstream")
|
||||
|
||||
monkeypatch.setattr(config, "ROOT", repo)
|
||||
monkeypatch.setenv("WIKITOOL_SESSION_ID", "test-session")
|
||||
return upstream, repo
|
||||
|
||||
|
||||
def _merge(**overrides):
|
||||
kwargs = dict(remote="upstream", branch="main", no_fetch=False)
|
||||
kwargs.update(overrides)
|
||||
upstream_cmd.merge_command(**kwargs)
|
||||
|
||||
|
||||
# --- the four restbefund regressions, plus the baseline table from the issue ---
|
||||
|
||||
|
||||
def test_upstream_edit_of_a_page_the_instance_deleted_does_not_land(two_repos):
|
||||
upstream, repo = two_repos
|
||||
_git(repo, "rm", "-q", "kb/ToDelete.md")
|
||||
_commit(repo, "instance deletes ToDelete")
|
||||
|
||||
_write(upstream, "kb/ToDelete.md", "upstream edited it after the instance deleted it\n")
|
||||
_commit(upstream, "upstream edits ToDelete")
|
||||
|
||||
_merge()
|
||||
|
||||
assert not (repo / "kb/ToDelete.md").exists()
|
||||
|
||||
|
||||
def test_upstream_new_page_does_not_land(two_repos):
|
||||
upstream, repo = two_repos
|
||||
_write(upstream, "kb/NewPage.md", "a demo page the upstream added\n")
|
||||
_commit(upstream, "upstream adds NewPage")
|
||||
|
||||
_merge()
|
||||
|
||||
assert not (repo / "kb/NewPage.md").exists()
|
||||
|
||||
|
||||
def test_page_deleted_on_both_sides_is_a_noop(two_repos):
|
||||
upstream, repo = two_repos
|
||||
_git(repo, "rm", "-q", "kb/Both.md")
|
||||
_commit(repo, "instance deletes Both")
|
||||
_git(upstream, "rm", "-q", "kb/Both.md")
|
||||
_commit(upstream, "upstream deletes Both")
|
||||
|
||||
_merge() # must not raise
|
||||
|
||||
assert not (repo / "kb/Both.md").exists()
|
||||
|
||||
|
||||
def test_kb_contract_change_lands(two_repos):
|
||||
upstream, repo = two_repos
|
||||
_write(upstream, "kb/CONTRACT.md", "stack kb contract v2\n")
|
||||
_commit(upstream, "upstream changes kb/CONTRACT.md")
|
||||
|
||||
_merge()
|
||||
|
||||
assert (repo / "kb/CONTRACT.md").read_text(encoding="utf-8") == "stack kb contract v2\n"
|
||||
|
||||
|
||||
def test_conventions_template_change_lands_local_conventions_untouched(two_repos):
|
||||
upstream, repo = two_repos
|
||||
_write(upstream, "kb/CONVENTIONS.md.template", "template v2\n")
|
||||
_commit(upstream, "upstream changes the conventions template")
|
||||
|
||||
_merge()
|
||||
|
||||
assert (repo / "kb/CONVENTIONS.md.template").read_text(encoding="utf-8") == "template v2\n"
|
||||
assert (repo / "kb/CONVENTIONS.md").read_text(encoding="utf-8") == "instance conventions v1\n"
|
||||
|
||||
|
||||
def test_collection_contract_change_does_not_land(two_repos):
|
||||
"""A COLLECTION.md is instance-owned since #39 - one level deeper than
|
||||
`<stage>/CONTRACT.md`, so `is_stack_owned` must say no to it."""
|
||||
upstream, repo = two_repos
|
||||
_write(repo, "kb/entities/COLLECTION.md", "instance collection contract v2 (local)\n")
|
||||
_commit(repo, "instance rewrites its own collection contract")
|
||||
|
||||
_write(upstream, "kb/entities/COLLECTION.md", "upstream collection contract v2\n")
|
||||
_commit(upstream, "upstream changes the default collection contract")
|
||||
|
||||
_merge()
|
||||
|
||||
assert (repo / "kb/entities/COLLECTION.md").read_text(encoding="utf-8") == (
|
||||
"instance collection contract v2 (local)\n"
|
||||
)
|
||||
|
||||
|
||||
def test_upstream_deletion_of_a_contract_file_lands(two_repos):
|
||||
"""Restbefund 2: a machinery file the upstream deleted must not silently
|
||||
survive because `git checkout MERGE_HEAD -- <path>` has nothing to check
|
||||
out."""
|
||||
upstream, repo = two_repos
|
||||
_git(upstream, "rm", "-q", "raw/CONTRACT.md")
|
||||
_commit(upstream, "upstream drops raw/CONTRACT.md")
|
||||
|
||||
_merge()
|
||||
|
||||
assert not (repo / "raw/CONTRACT.md").exists()
|
||||
|
||||
|
||||
def test_new_stack_template_under_a_content_stage_lands(two_repos):
|
||||
"""Restbefund 4: a brand-new stack-owned path the local tree has never
|
||||
seen must still be recognised by the predicate, not by a literal list."""
|
||||
upstream, repo = two_repos
|
||||
_write(upstream, "kb/GLOSSARY.md.template", "a stack-owned template that never existed before\n")
|
||||
_commit(upstream, "upstream adds a new template")
|
||||
|
||||
_merge()
|
||||
|
||||
assert (repo / "kb/GLOSSARY.md.template").read_text(encoding="utf-8") == (
|
||||
"a stack-owned template that never existed before\n"
|
||||
)
|
||||
|
||||
|
||||
def test_open_workshop_run_files_do_not_land(two_repos):
|
||||
upstream, repo = two_repos
|
||||
_write(upstream, "work/some-run/README.md", "an in-progress workshop run\n")
|
||||
_commit(upstream, "upstream ships an open work/ run")
|
||||
|
||||
_merge()
|
||||
|
||||
assert not (repo / "work/some-run").exists()
|
||||
|
||||
|
||||
def test_merge_keeps_ignored_local_data_under_a_content_stage(two_repos):
|
||||
"""`reports/` is gitignored except its contract, so a content stage's
|
||||
working tree holds local data that is in no git tree and is not
|
||||
recomputable - the telemetry traces `eval score` reads, saved eval
|
||||
reports, past lint reports. Forcing the stage back to the local side must
|
||||
not take those out as collateral: this instance had 497 trace directories
|
||||
under reports/telemetry/ when the first version of this command wiped the
|
||||
stage wholesale."""
|
||||
upstream, repo = two_repos
|
||||
_write(repo, "reports/telemetry/session-a/trace.jsonl", '{"event": "local"}\n')
|
||||
_write(repo, "reports/Lint Report 2026-09-04.md", "a local lint report\n")
|
||||
assert _git(repo, "status", "--porcelain").stdout == "" # ignored, so the tree is clean
|
||||
|
||||
_write(upstream, "kb/CONTRACT.md", "stack kb contract v2\n")
|
||||
_commit(upstream, "upstream changes kb/CONTRACT.md")
|
||||
|
||||
_merge()
|
||||
|
||||
assert (repo / "reports/telemetry/session-a/trace.jsonl").read_text(encoding="utf-8") == (
|
||||
'{"event": "local"}\n'
|
||||
)
|
||||
assert (repo / "reports/Lint Report 2026-09-04.md").exists()
|
||||
assert (repo / "reports/CONTRACT.md").read_text(encoding="utf-8") == "reports contract v1\n"
|
||||
|
||||
|
||||
def test_upstream_content_under_a_stage_absent_from_head_does_not_land(two_repos):
|
||||
"""The stage guard must not rest on the local side happening to track
|
||||
something under that stage: an instance whose `work/` holds no tracked
|
||||
file at all must still not receive the upstream's open run."""
|
||||
upstream, repo = two_repos
|
||||
_git(repo, "rm", "-q", "work/CONTRACT.md")
|
||||
_commit(repo, "instance has nothing tracked under work/")
|
||||
|
||||
_write(upstream, "work/some-run/README.md", "an in-progress workshop run\n")
|
||||
_commit(upstream, "upstream ships an open work/ run")
|
||||
|
||||
_merge()
|
||||
|
||||
assert not (repo / "work/some-run").exists()
|
||||
|
||||
|
||||
def test_one_upstream_commit_mixing_every_case_at_once(two_repos):
|
||||
"""The acceptance test from the issue: a single upstream commit that edits
|
||||
a page the instance deleted, adds a new page, deletes an untouched page,
|
||||
changes a stack contract, changes a template, and deletes a different
|
||||
stack contract - all at once, all restored or discarded correctly by one
|
||||
`upstream merge` call."""
|
||||
upstream, repo = two_repos
|
||||
_git(repo, "rm", "-q", "kb/ToDelete.md")
|
||||
_commit(repo, "instance deletes ToDelete")
|
||||
|
||||
_write(upstream, "kb/ToDelete.md", "upstream edited it after the instance deleted it\n")
|
||||
_write(upstream, "kb/BrandNewPage.md", "a demo page the upstream added\n")
|
||||
_git(upstream, "rm", "-q", "kb/RegularPage.md")
|
||||
_write(upstream, "kb/CONTRACT.md", "stack kb contract v2\n")
|
||||
_write(upstream, "kb/CONVENTIONS.md.template", "template v2\n")
|
||||
_git(upstream, "rm", "-q", "raw/CONTRACT.md")
|
||||
_commit(upstream, "one upstream commit: edit + add + delete + contract + template + contract-delete")
|
||||
|
||||
_merge()
|
||||
|
||||
assert not (repo / "kb/ToDelete.md").exists()
|
||||
assert not (repo / "kb/BrandNewPage.md").exists()
|
||||
assert (repo / "kb/RegularPage.md").exists()
|
||||
assert (repo / "kb/CONTRACT.md").read_text(encoding="utf-8") == "stack kb contract v2\n"
|
||||
assert (repo / "kb/CONVENTIONS.md.template").read_text(encoding="utf-8") == "template v2\n"
|
||||
assert (repo / "kb/CONVENTIONS.md").read_text(encoding="utf-8") == "instance conventions v1\n"
|
||||
assert not (repo / "raw/CONTRACT.md").exists()
|
||||
|
||||
|
||||
def test_real_conflict_in_tools_leaves_the_merge_open(two_repos):
|
||||
upstream, repo = two_repos
|
||||
|
||||
_write(repo, "tools/wikitool.py", "line one\nLOCAL CHANGE\nline three\n")
|
||||
_commit(repo, "local edits tools/wikitool.py")
|
||||
before = _git(repo, "rev-parse", "HEAD").stdout.strip()
|
||||
|
||||
_write(upstream, "tools/wikitool.py", "line one\nUPSTREAM CHANGE\nline three\n")
|
||||
_commit(upstream, "upstream edits the same line")
|
||||
|
||||
with pytest.raises(typer.Exit) as excinfo:
|
||||
_merge()
|
||||
assert excinfo.value.exit_code == 1
|
||||
|
||||
assert _git(repo, "rev-parse", "HEAD").stdout.strip() == before
|
||||
assert (repo / ".git" / "MERGE_HEAD").exists()
|
||||
|
||||
|
||||
def test_a_merge_git_refuses_to_open_deletes_nothing(two_repos, tmp_path):
|
||||
"""The failure mode with the worst blast radius if it is not guarded:
|
||||
without MERGE_HEAD, every stack-owned path in HEAD reads as "the upstream
|
||||
deleted it", and the restore loop would remove kb/CONTRACT.md,
|
||||
raw/CONTRACT.md and every template. A merge git refuses to start must stop
|
||||
before that, with the tree untouched."""
|
||||
upstream, repo = two_repos
|
||||
unrelated = tmp_path / "unrelated"
|
||||
unrelated.mkdir()
|
||||
_git(unrelated, "init", "-b", "main")
|
||||
_git(unrelated, "config", "user.name", "Unrelated")
|
||||
_git(unrelated, "config", "user.email", "unrelated@example.com")
|
||||
_write(unrelated, "somefile.md", "no shared history with the instance\n")
|
||||
_commit(unrelated, "unrelated root commit")
|
||||
|
||||
_git(repo, "remote", "set-url", "upstream", str(unrelated))
|
||||
before = _git(repo, "rev-parse", "HEAD").stdout.strip()
|
||||
|
||||
with pytest.raises(typer.Exit) as excinfo:
|
||||
_merge()
|
||||
assert excinfo.value.exit_code == 1
|
||||
|
||||
assert _git(repo, "rev-parse", "HEAD").stdout.strip() == before
|
||||
assert (repo / "kb/CONTRACT.md").read_text(encoding="utf-8") == "stack kb contract v1\n"
|
||||
assert (repo / "raw/CONTRACT.md").exists()
|
||||
assert (repo / "kb/CONVENTIONS.md.template").exists()
|
||||
assert _git(repo, "status", "--porcelain").stdout == ""
|
||||
|
||||
|
||||
def test_success_message_reports_what_changed_not_what_was_restored(two_repos, capsys):
|
||||
"""Restoring every stack-owned path from MERGE_HEAD touches all of them
|
||||
whether or not the upstream moved any, so the report has to ask git what
|
||||
changed - otherwise a one-file update is announced as five."""
|
||||
upstream, repo = two_repos
|
||||
_write(upstream, "kb/CONTRACT.md", "stack kb contract v2\n")
|
||||
_commit(upstream, "upstream changes exactly one stack path")
|
||||
|
||||
_merge()
|
||||
|
||||
out = capsys.readouterr().out
|
||||
assert "Stack paths changed (1)" in out
|
||||
assert "kb/CONTRACT.md" in out
|
||||
assert "kb/CONVENTIONS.md.template" not in out
|
||||
|
||||
|
||||
def test_dirty_working_tree_is_refused_untouched(two_repos):
|
||||
upstream, repo = two_repos
|
||||
before = _git(repo, "rev-parse", "HEAD").stdout.strip()
|
||||
(repo / "kb/CONTRACT.md").write_text("uncommitted local edit\n", encoding="utf-8")
|
||||
|
||||
_write(upstream, "kb/CONTRACT.md", "stack kb contract v2\n")
|
||||
_commit(upstream, "upstream changes kb/CONTRACT.md")
|
||||
|
||||
with pytest.raises(typer.Exit) as excinfo:
|
||||
_merge()
|
||||
assert excinfo.value.exit_code == 1
|
||||
|
||||
assert _git(repo, "rev-parse", "HEAD").stdout.strip() == before
|
||||
assert (repo / "kb/CONTRACT.md").read_text(encoding="utf-8") == "uncommitted local edit\n"
|
||||
|
||||
|
||||
def test_already_up_to_date_is_a_noop(two_repos):
|
||||
upstream, repo = two_repos
|
||||
before = _git(repo, "rev-parse", "HEAD").stdout.strip()
|
||||
|
||||
_merge() # nothing new upstream at all
|
||||
|
||||
assert _git(repo, "rev-parse", "HEAD").stdout.strip() == before
|
||||
|
||||
|
||||
def test_merge_warns_when_the_publish_remote_gate_is_unarmed(two_repos, capsys):
|
||||
upstream, repo = two_repos
|
||||
assert git_publish.read_allowed_push_urls() is None # no .wikitool-remotes.json in this repo
|
||||
|
||||
_write(upstream, "kb/CONTRACT.md", "stack kb contract v2\n")
|
||||
_commit(upstream, "upstream changes kb/CONTRACT.md")
|
||||
|
||||
_merge()
|
||||
|
||||
captured = capsys.readouterr()
|
||||
assert "WARN" in captured.out
|
||||
assert ".wikitool-remotes.json" in captured.out
|
||||
|
||||
|
||||
def test_merge_stays_silent_when_the_publish_remote_gate_is_armed(two_repos, capsys):
|
||||
upstream, repo = two_repos
|
||||
(repo / config.PUBLISH_REMOTES_FILENAME).write_text(
|
||||
'{"schema": 1, "allowed_push_urls": ["ssh://example/test.git"]}\n', encoding="utf-8"
|
||||
)
|
||||
|
||||
_write(upstream, "kb/CONTRACT.md", "stack kb contract v2\n")
|
||||
_commit(upstream, "upstream changes kb/CONTRACT.md")
|
||||
|
||||
_merge()
|
||||
|
||||
captured = capsys.readouterr()
|
||||
assert "WARN" not in captured.out
|
||||
|
||||
|
||||
def test_dist_cmd_contract_only_stages_agree_with_ownership(two_repos):
|
||||
"""Consistency guard for the ownership refactor: `dist_cmd`'s own list of
|
||||
stage-contract paths and `ownership.is_stack_owned` must not be able to
|
||||
name a different set of stages - both are sourced from
|
||||
`ownership.CONTENT_STAGES` now, so a stage added to one and not the other
|
||||
fails this rather than only surfacing in a real merge."""
|
||||
from chemenu.commands import dist_cmd
|
||||
|
||||
assert dist_cmd.CONTRACT_ONLY_STAGES # sanity: the derivation still yields entries
|
||||
for relative in dist_cmd.CONTRACT_ONLY_STAGES:
|
||||
assert ownership.is_stack_owned(relative)
|
||||
|
||||
|
||||
# --- upstream verify --------------------------------------------------------
|
||||
|
||||
|
||||
def test_verify_is_clean_on_a_stack_owned_only_change(two_repos):
|
||||
upstream, repo = two_repos
|
||||
since = _git(repo, "rev-parse", "HEAD").stdout.strip()
|
||||
|
||||
_write(repo, "kb/CONTRACT.md", "stack kb contract v2\n")
|
||||
_commit(repo, "advance kb/CONTRACT.md")
|
||||
|
||||
upstream_cmd.verify_command(since=since, until="HEAD") # must not raise
|
||||
|
||||
|
||||
def test_verify_fails_on_a_hand_botched_merge(two_repos, capsys):
|
||||
upstream, repo = two_repos
|
||||
since = _git(repo, "rev-parse", "HEAD").stdout.strip()
|
||||
|
||||
_write(repo, "kb/SneakedIn.md", "content that arrived outside a stack-owned path\n")
|
||||
_commit(repo, "a hand-resolved merge that let content through")
|
||||
|
||||
with pytest.raises(typer.Exit) as excinfo:
|
||||
upstream_cmd.verify_command(since=since, until="HEAD")
|
||||
assert excinfo.value.exit_code == 1
|
||||
|
||||
captured = capsys.readouterr()
|
||||
assert "kb/SneakedIn.md" in captured.out
|
||||
|
||||
|
||||
# --- ownership predicate, exercised directly ---------------------------------
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"relative,expected",
|
||||
[
|
||||
("kb/CONTRACT.md", True),
|
||||
("raw/CONTRACT.md", True),
|
||||
("work/CONTRACT.md", True),
|
||||
("reports/CONTRACT.md", True),
|
||||
("kb/CONVENTIONS.md.template", True),
|
||||
("kb/entities/COLLECTION.md.template", True),
|
||||
("kb/GLOSSARY.md.template", True),
|
||||
("kb/CONVENTIONS.md", False),
|
||||
("kb/entities/COLLECTION.md", False),
|
||||
("kb/concepts/Some Page.md", False),
|
||||
("raw/notes/x.md", False),
|
||||
("tools/CONTRACT.md", False), # not a content stage
|
||||
("kb/log.md", False), # export stub, not stack-owned
|
||||
],
|
||||
)
|
||||
def test_is_stack_owned(relative, expected):
|
||||
assert ownership.is_stack_owned(relative) == expected
|
||||
@@ -77,11 +77,11 @@ REGION_NAME = "toc"
|
||||
HEADING_TEXT = "Contents"
|
||||
|
||||
# The suffix `dist export` re-keys an instance-owned file to, and the one
|
||||
# `setup-instance.md` adopts away again. Lives here because this module is what
|
||||
# `dist adopt` adopts away again. Lives here because this module is what
|
||||
# decides which files are reference material *in both their forms*;
|
||||
# `docs_verify` imports it rather than keeping a second spelling. `ownership.py`
|
||||
# keeps its own literal deliberately - it answers a different question (which
|
||||
# side an upstream merge keeps) over a narrower scope.
|
||||
# path a release replaces) over a narrower scope.
|
||||
TEMPLATE_SUFFIX = ".template"
|
||||
|
||||
# The line threshold Anthropic's own guidance names. Measured on the body
|
||||
|
||||
+53
-14
@@ -8,8 +8,10 @@
|
||||
# As the release asset `preflight.ps1` - a copy with no tools/prerequisites.txt next
|
||||
# to it - the script is the first install step instead: it downloads the stack
|
||||
# release named in $ReleaseArchiveUrl / $ReleaseChecksumUrl, checks the sha256,
|
||||
# unpacks it into <script folder>\chemenu (or --into <path>), and runs the copy of
|
||||
# this script inside the unpacked tree, which does everything above.
|
||||
# unpacks it into the folder it lies in (or --into <path>), removes itself there, and
|
||||
# runs the copy of this script inside the unpacked tree, which does everything above.
|
||||
# That folder has to be empty apart from this script and a .git (an empty clone of the
|
||||
# instance's own repository).
|
||||
#
|
||||
# pwsh -NoProfile -ExecutionPolicy Bypass -File preflight.ps1 [--into <path>] [--archive <tarball>]
|
||||
#
|
||||
@@ -108,8 +110,8 @@ while ($index -lt $args.Count) {
|
||||
Write-Line 'means the user has to act - the output says how.'
|
||||
Write-Line ''
|
||||
Write-Line 'The second form is the release asset: it downloads the release (or takes'
|
||||
Write-Line '--archive), checks its sha256, unpacks it into <script folder>\chemenu or --into,'
|
||||
Write-Line 'and runs the preflight inside it.'
|
||||
Write-Line '--archive), checks its sha256, unpacks it into its own folder or --into (empty,'
|
||||
Write-Line 'or holding only .git), and runs the preflight inside it.'
|
||||
exit 0
|
||||
} else {
|
||||
Write-ErrorLine "preflight: unknown argument: $arg"
|
||||
@@ -235,10 +237,33 @@ function Resolve-AssetPath {
|
||||
return [IO.Path]::GetFullPath($Path).TrimEnd('\', '/')
|
||||
}
|
||||
|
||||
# Whether the install folder holds anything besides this script and a .git - the two
|
||||
# things an empty folder may already carry: the script was downloaded into it, and the
|
||||
# user may have cloned the instance's own, still empty repository there.
|
||||
function Test-TargetOccupied {
|
||||
param([string]$Target)
|
||||
$selfName = Split-Path -Leaf $PSCommandPath
|
||||
$isOwnFolder = [IO.Path]::GetFullPath($Target).TrimEnd('\', '/') -eq [IO.Path]::GetFullPath($Dir).TrimEnd('\', '/')
|
||||
foreach ($entry in @(Get-ChildItem -LiteralPath $Target -Force)) {
|
||||
if ($entry.Name -eq '.git') {
|
||||
continue
|
||||
}
|
||||
if ($isOwnFolder -and $entry.Name -eq $selfName) {
|
||||
continue
|
||||
}
|
||||
return $true
|
||||
}
|
||||
return $false
|
||||
}
|
||||
|
||||
function Invoke-AssetMode {
|
||||
$target = if ($Into) { Resolve-AssetPath $Into } else { Join-Path $Dir 'chemenu' }
|
||||
if ($null -ne (Get-Item -LiteralPath $target -Force -ErrorAction SilentlyContinue)) {
|
||||
Exit-Asset "$target already exists - nothing was unpacked. Choose another folder with --into <path>, or move the existing one away."
|
||||
$target = if ($Into) { Resolve-AssetPath $Into } else { $Dir.TrimEnd('\', '/') }
|
||||
$existing = Get-Item -LiteralPath $target -Force -ErrorAction SilentlyContinue
|
||||
if ($null -ne $existing -and -not $existing.PSIsContainer) {
|
||||
Exit-Asset "$target exists and is not a folder - nothing was unpacked."
|
||||
}
|
||||
if ($null -ne $existing -and (Test-TargetOccupied $target)) {
|
||||
Exit-Asset "$target is not empty - nothing was unpacked. The wiki installs into an empty folder (an empty git clone is fine): put this script into one and run it there, or pass --into <path>."
|
||||
}
|
||||
|
||||
if (-not $Archive -and (-not $ReleaseArchiveUrl -or -not $ReleaseChecksumUrl)) {
|
||||
@@ -327,20 +352,28 @@ function Invoke-AssetMode {
|
||||
if ($length -gt $limit) {
|
||||
Add-Problem "The folder this wiki would be installed in is too long ($length characters, at most $limit): $target" `
|
||||
"Windows on this computer only allows paths of up to 259 characters, and the wiki's own files need the rest" `
|
||||
"Run this again with a shorter folder, for example: --into C:\Chemenu`nAlternatively, someone with administrator rights can turn on long paths in Windows."
|
||||
"Use a shorter folder such as C:\Chemenu - put this script there and run it again,`nor pass --into C:\Chemenu.`nAlternatively, someone with administrator rights can turn on long paths in Windows."
|
||||
Exit-WithGuide
|
||||
}
|
||||
}
|
||||
|
||||
$parent = Split-Path -Parent $target
|
||||
$null = New-Item -ItemType Directory -Path $parent -Force
|
||||
$unpack = Join-Path $parent ".chemenu-unpack.$PID"
|
||||
# Unpacked inside the target rather than beside it: the folder above may be a drive
|
||||
# root nobody can write to. Only then are the entries moved up, one by one.
|
||||
$null = New-Item -ItemType Directory -Path $target -Force
|
||||
$unpack = Join-Path $target ".chemenu-unpack.$PID"
|
||||
$null = New-Item -ItemType Directory -Path $unpack
|
||||
$null = Invoke-NativeVerbose $tar.Source @('-xzf', $archivePath, '-C', $unpack)
|
||||
if (-not (Test-Path -LiteralPath (Join-Path $unpack $top) -PathType Container)) {
|
||||
Exit-Asset "unpacking failed - the target was not created."
|
||||
$unpacked = Join-Path $unpack $top
|
||||
if (-not (Test-Path -LiteralPath $unpacked -PathType Container)) {
|
||||
Exit-Asset 'unpacking failed - nothing was installed.'
|
||||
}
|
||||
foreach ($entry in @(Get-ChildItem -LiteralPath $unpacked -Force)) {
|
||||
try {
|
||||
Move-Item -LiteralPath $entry.FullName -Destination $target
|
||||
} catch {
|
||||
Exit-Asset "could not move $($entry.Name) into $target - the folder holds part of the stack now; empty it (keep .git) and run this again."
|
||||
}
|
||||
}
|
||||
Move-Item -LiteralPath (Join-Path $unpack $top) -Destination $target
|
||||
} finally {
|
||||
foreach ($leftover in @($work, $unpack)) {
|
||||
if ($leftover -and (Test-Path -LiteralPath $leftover)) {
|
||||
@@ -353,6 +386,12 @@ function Invoke-AssetMode {
|
||||
if (-not (Test-Path -LiteralPath $treeScript -PathType Leaf)) {
|
||||
Exit-Asset 'the unpacked stack has no tools/preflight.ps1.'
|
||||
}
|
||||
# The release asset is not part of the stack; left in the folder, it would end up in
|
||||
# the instance's first commit beside the tree's own tools/preflight.ps1. PowerShell has
|
||||
# read the whole script before running it, so removing the file is safe here.
|
||||
if ($target -eq $Dir.TrimEnd('\', '/')) {
|
||||
Remove-Item -LiteralPath $PSCommandPath -Force
|
||||
}
|
||||
Write-Line "Unpacked into $target."
|
||||
Write-Line 'If a later step stops, run tools/preflight.ps1 from inside that folder.'
|
||||
Write-Line ''
|
||||
|
||||
+47
-15
@@ -8,8 +8,10 @@
|
||||
# As the release asset `preflight.sh` - a copy with no tools/prerequisites.txt next
|
||||
# to it - the script is the first install step instead: it downloads the stack
|
||||
# release named in RELEASE_ARCHIVE_URL / RELEASE_CHECKSUM_URL, checks the sha256,
|
||||
# unpacks it into <script folder>/chemenu (or --into <path>), and runs the copy of
|
||||
# this script inside the unpacked tree, which does everything above.
|
||||
# unpacks it into the folder it lies in (or --into <path>), removes itself there, and
|
||||
# runs the copy of this script inside the unpacked tree, which does everything above.
|
||||
# That folder has to be empty apart from this script and a .git (an empty clone of the
|
||||
# instance's own repository).
|
||||
#
|
||||
# preflight.sh [--into <path>] [--archive <tarball>] [--set <tool>=<path>]...
|
||||
#
|
||||
@@ -59,8 +61,8 @@ in .wikitool-tools.json and sets up tools/.venv. Exit 0 means ready; exit 42
|
||||
means the user has to act - the output says how.
|
||||
|
||||
The second form is the release asset: it downloads the release (or takes
|
||||
--archive), checks its sha256, unpacks it into <script folder>/chemenu or --into,
|
||||
and runs the preflight inside it.
|
||||
--archive), checks its sha256, unpacks it into its own folder or --into (empty,
|
||||
or holding only .git), and runs the preflight inside it.
|
||||
EOF
|
||||
}
|
||||
|
||||
@@ -207,6 +209,23 @@ sha256_of() { # <file>
|
||||
fi
|
||||
}
|
||||
|
||||
# Whether the install folder holds anything besides this script and a .git - the
|
||||
# two things an empty folder may already carry: the script was downloaded into it, and
|
||||
# the user may have cloned the instance's own, still empty repository there.
|
||||
target_is_occupied() {
|
||||
[ -d "$TARGET" ] || return 1
|
||||
self_name=${0##*/}
|
||||
target_real=$(CDPATH='' cd -- "$TARGET" && pwd -P)
|
||||
for entry in "$TARGET"/* "$TARGET"/.[!.]* "$TARGET"/..?*; do
|
||||
[ -e "$entry" ] || [ -L "$entry" ] || continue
|
||||
name=${entry##*/}
|
||||
[ "$name" = .git ] && continue
|
||||
[ "$target_real" = "$DIR" ] && [ "$name" = "$self_name" ] && continue
|
||||
return 0
|
||||
done
|
||||
return 1
|
||||
}
|
||||
|
||||
asset_mode() {
|
||||
# GNU tar reads `C:` as a host name; Git Bash has to hand it `/c/...`.
|
||||
if [ "$PLATFORM" = windows ] && command -v cygpath >/dev/null 2>&1; then
|
||||
@@ -216,11 +235,14 @@ asset_mode() {
|
||||
if [ -n "$INTO" ]; then
|
||||
case "$INTO" in /*) TARGET=$INTO ;; *) TARGET="$(pwd)/$INTO" ;; esac
|
||||
else
|
||||
TARGET="$DIR/chemenu"
|
||||
TARGET=$DIR
|
||||
fi
|
||||
TARGET=${TARGET%/}
|
||||
if [ -e "$TARGET" ] || [ -L "$TARGET" ]; then
|
||||
asset_fail "$(native_path "$TARGET") already exists - nothing was unpacked. Choose another folder with --into <path>, or move the existing one away."
|
||||
if { [ -e "$TARGET" ] || [ -L "$TARGET" ]; } && [ ! -d "$TARGET" ]; then
|
||||
asset_fail "$(native_path "$TARGET") exists and is not a folder - nothing was unpacked."
|
||||
fi
|
||||
if target_is_occupied; then
|
||||
asset_fail "$(native_path "$TARGET") is not empty - nothing was unpacked. The wiki installs into an empty folder (an empty git clone is fine): put this script into one and run it there, or pass --into <path>."
|
||||
fi
|
||||
|
||||
if [ -z "$ARCHIVE" ] && { [ -z "$RELEASE_ARCHIVE_URL" ] || [ -z "$RELEASE_CHECKSUM_URL" ]; }; then
|
||||
@@ -287,21 +309,31 @@ asset_mode() {
|
||||
if [ "$length" -gt "$limit" ]; then
|
||||
problem "The folder this wiki would be installed in is too long ($length characters, at most $limit): $folder" \
|
||||
"Windows on this computer only allows paths of up to 259 characters, and the wiki's own files need the rest" \
|
||||
"Run this again with a shorter folder, for example: --into C:\\\\Chemenu
|
||||
"Use a shorter folder such as C:\\Chemenu - put this script there and run it again,
|
||||
or pass --into C:\\Chemenu.
|
||||
Alternatively, someone with administrator rights can turn on long paths in Windows."
|
||||
stop
|
||||
fi
|
||||
fi
|
||||
|
||||
parent=$(dirname -- "$TARGET")
|
||||
mkdir -p "$parent" || asset_fail "could not create $parent."
|
||||
UNPACK="$parent/.chemenu-unpack.$$"
|
||||
mkdir "$UNPACK" || asset_fail "could not create a temporary folder next to the target."
|
||||
tar -xzf "$archive" -C "$UNPACK" || asset_fail "unpacking failed - the target was not created."
|
||||
[ -d "$UNPACK/$top" ] || asset_fail "unpacking produced no $top folder - the target was not created."
|
||||
mv "$UNPACK/$top" "$TARGET" || asset_fail "could not move the unpacked stack to $(native_path "$TARGET")."
|
||||
# Unpacked inside the target rather than beside it: the folder above may be a drive
|
||||
# root nobody can write to. Only then are the entries moved up, one by one.
|
||||
mkdir -p "$TARGET" || asset_fail "could not create $(native_path "$TARGET")."
|
||||
UNPACK="$TARGET/.chemenu-unpack.$$"
|
||||
mkdir "$UNPACK" || asset_fail "could not create a temporary folder in the target."
|
||||
tar -xzf "$archive" -C "$UNPACK" || asset_fail "unpacking failed - nothing was installed."
|
||||
[ -d "$UNPACK/$top" ] || asset_fail "unpacking produced no $top folder - nothing was installed."
|
||||
for entry in "$UNPACK/$top"/* "$UNPACK/$top"/.[!.]* "$UNPACK/$top"/..?*; do
|
||||
[ -e "$entry" ] || [ -L "$entry" ] || continue
|
||||
mv "$entry" "$TARGET/" || asset_fail "could not move ${entry##*/} into $(native_path "$TARGET") - the folder holds part of the stack now; empty it (keep .git) and run this again."
|
||||
done
|
||||
rm -rf "$UNPACK"
|
||||
UNPACK=""
|
||||
# The release asset is not part of the stack; left in the folder, it would end up in
|
||||
# the instance's first commit beside the tree's own tools/preflight.sh.
|
||||
if [ "$(CDPATH='' cd -- "$TARGET" && pwd -P)" = "$DIR" ]; then
|
||||
rm -f -- "$DIR/${0##*/}"
|
||||
fi
|
||||
|
||||
[ -f "$TARGET/tools/preflight.sh" ] || asset_fail "the unpacked stack has no tools/preflight.sh."
|
||||
echo "Unpacked into $(native_path "$TARGET")."
|
||||
|
||||
Reference in new issue
Block a user