You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 562ff9e
Browse filesBrowse the repository at this point in the historyBrowse files
Replace scripts/build-site.py with justfile recipes and run Zensical and
the Python checks on demand with uvx, dropping the project virtual
environment (pyproject.toml, uv.lock). Windows recipes now use Git Bash,
so the build assembly is shared across platforms.
Copy file name to clipboardExpand all lines: AGENTS.md
+15-16Lines changed: 15 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -48,15 +48,14 @@ Credentials are generated with the browser Crypto API. All input, validation, an
48
48
49
49
## Running the documentation locally
50
50
51
-
Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
51
+
Requires [uv](https://docs.astral.sh/uv/); `uvx` fetches the pinned Zensical and Python on demand, so no project virtual environment is created.
52
52
53
53
```sh
54
-
uv sync --locked
55
-
uv run --locked zensical serve -f tuic/zensical.toml
56
-
uv run --locked zensical serve -f wind/zensical.toml
54
+
just docs
55
+
just docs-wind
57
56
```
58
57
59
-
Each documentation site has its own `zensical.toml` and `docs/`; the development server serves only one site at a time, and the configuration generator runs separately with the Vite server above. When adding a documentation site, create `<project>/zensical.toml` and `<project>/docs/`, and add it to the site list in `scripts/build-site.py` and to the portal links.
58
+
Each documentation site has its own `zensical.toml` and `docs/`; the development server serves only one site at a time, and the configuration generator runs separately with the Vite server above. When adding a documentation site, create `<project>/zensical.toml` and `<project>/docs/`, and add it to the `build` recipe in `justfile` and to the portal links.
Preview: `http://127.0.0.1:8765/`, `http://127.0.0.1:8765/tuic/`, `http://127.0.0.1:8765/config-generator/`, `http://127.0.0.1:8765/wind/`. Run `npm ci --prefix config-generator` first to install the frontend dependencies; the combined script clean-builds each documentation site, places the standalone generator under `site/config-generator/`, and copies `portal/index.html` to `site/index.html`. Stop the documentation development servers before a clean build to avoid cache conflicts.
80
+
Preview: `http://127.0.0.1:8765/`, `http://127.0.0.1:8765/tuic/`, `http://127.0.0.1:8765/config-generator/`, `http://127.0.0.1:8765/wind/`. Run `npm ci --prefix config-generator` first to install the frontend dependencies; the combined build clean-builds each documentation site, places the standalone generator under `site/config-generator/`, and copies `portal/index.html` to `site/index.html`. Stop the documentation development servers before a clean build to avoid cache conflicts.
82
81
83
82
### Standalone format parsing and real TUIC checks
The real parsing check requires the neighboring `../tuic`, its submodules, cached dependencies, and the corresponding build tools; omit `--offline` when the dependency cache is missing. The auxiliary Cargo project writes only to `.cache/`, starts from TUIC's lock file, and does not modify TUIC manifests, sources, lock files, or submodules. The loopback allowance applies only to the in-memory test configuration, and error diagnostics never print configuration contents.
@@ -104,17 +103,17 @@ npm ci --prefix tests/config-generator
104
103
node tests/config-generator/browser.mjs
105
104
106
105
# Test the built standalone artifact; the temporary local server shuts down with the test
107
-
uv run --locked python tests/config-generator/run-browser.py
106
+
uvx python tests/config-generator/run-browser.py
108
107
109
108
# Use the deployment prefix for the assembled site build
110
-
uv run --locked python tests/config-generator/run-browser.py --directory site/config-generator --prefix /config-generator/
`PLAYWRIGHT_MODULE_PATH` can point to an existing Playwright module directory; `BROWSER_CHANNEL` accepts `msedge`, `chrome`, and `chromium`, with CI defaulting to `chromium`. The standalone Vite development server uses `PREVIEW_URL=http://127.0.0.1:8080/`. The tests cover WASM loading, standalone page structure, pairing consistency, user removal, TLS switching, input validation, forwarding edits, copy/download, escaping, mobile, theming, no external requests, and no input persistence; screenshots go to `.cache/`. The reuse check builds with `schema/example.xml` into `.cache/generic-site` and runs `uv run --locked python tests/config-generator/run-browser.py --directory .cache/generic-site --script tests/config-generator/browser-generic.mjs`; see the DSL documentation for the full command. CI likewise keeps the default site artifacts for later publishing.
116
+
`PLAYWRIGHT_MODULE_PATH` can point to an existing Playwright module directory; `BROWSER_CHANNEL` accepts `msedge`, `chrome`, and `chromium`, with CI defaulting to `chromium`. The standalone Vite development server uses `PREVIEW_URL=http://127.0.0.1:8080/`. The tests cover WASM loading, standalone page structure, pairing consistency, user removal, TLS switching, input validation, forwarding edits, copy/download, escaping, mobile, theming, no external requests, and no input persistence; screenshots go to `.cache/`. The reuse check builds with `schema/example.xml` into `.cache/generic-site` and runs `uvx python tests/config-generator/run-browser.py --directory .cache/generic-site --script tests/config-generator/browser-generic.mjs`; see the DSL documentation for the full command. CI likewise keeps the default site artifacts for later publishing.
118
117
119
118
## DSL and maintenance conventions
120
119
@@ -143,7 +142,7 @@ Configuration state is modified only by the Rust `Session`. Svelte submits gener
143
142
|`wind/zensical.toml` / `wind/docs/`| Wind Chinese protocol specifications and design documents (single publishing source) |
144
143
|`wind/docs/specs/`| Wind English specifications and RFC template, published under `/wind/specs/` and kept in sync with the Chinese editions |
145
144
|`portal/index.html`| Site root portal page |
146
-
|`scripts/build-site.py`| Buildall documentation sites and the generator and assemble them into `site/`; does not publish|
145
+
|`justfile`| Build, check, and preview recipes; the `build` recipe assembles all documentation sites and the generator into `site/` without publishing|
147
146
|`tests/config-generator/`| Standalone parser, real TUIC, site, and browser checks |
148
147
|`.github/workflows/deploy.yml`| GitHub Pages build and publish workflow |
149
148
@@ -153,7 +152,7 @@ The main documentation is maintained only in Simplified Chinese; the English spe
153
152
154
153
The [CI and Pages workflow](.github/workflows/deploy.yml) runs on pull requests, pushes to `main`, and manual triggers:
155
154
156
-
-`check`: nightly rustfmt, stable native and WASM Clippy, Rust/XML DSL tests, and independent TOML/JSON/YAML parsing round trips. Python is pinned to 3.13, and dependencies use `uv.lock`.
155
+
-`check`: nightly rustfmt, stable native and WASM Clippy, Rust/XML DSL tests, and independent TOML/JSON/YAML parsing round trips. Python is pinned to 3.13 via `UV_PYTHON`, and tools run on demand with `uvx`.
157
156
-`build`: builds the standalone SPA with wasm-pack, the Svelte checker, and Vite, assembles all documentation sites, checks site links and assets, and then runs the TUIC and no-TUIC-field XML reuse browser regressions through the locked Playwright/Chromium. Rust, uv, and npm use dependency caching.
158
157
-`deploy`: depends on `check` and `build` succeeding, and publishes only on pushes to `main` or manual runs; Pages write and OIDC permissions are granted only to this job, while pull requests only validate and build.
0 commit comments