/ Current View source
Projects/ImmuKnow Studio/Build and contribute

Build and contribute

Studio is the browser workspace for developing ImmuKnow templates. This guide is for contributors building the application. For everyday use, start with Get started; no development setup is needed for the hosted application.

Choose the right repository

Change the editor, browser previews, drafts, imports, exports, example presentation and this manual here. Change the native pipeline, schemas and shared Typst components in ImmuKnow. Change starter letters, Settings, translations, example branding, project configuration, reference lists and native project instructions in ImmuKnow Template, then refresh its pinned resource dependency here. ImmuKnow ships no starter letters. Change the shared documentation presentation and catalogue in WDGPH/docs.

Read AGENTS.md before contributing. Use fictional data and public assets, make small changes, and include the checks and any remaining limits in your PR.

ImmuKnow dependency

immuknow-revision.txt pins standalone Rust ImmuKnow. Template's packaged immuknow-revision.txt must match. pyproject.toml and uv.lock pin Template's resource package and Python build tools, with no Python ImmuKnow dependency.

The initial build installs the exact clean ImmuKnow source recorded in that pin.

The installer builds the recorded commit and stores the executable, source revision, Typst version and binary fingerprint under ignored .immuknow/. Build commands verify those bytes; immuknow --version alone is not source provenance. For a matching clean local checkout, add --source /path/to/ImmuKnow. Only installation fetches/builds ImmuKnow; ordinary preparation uses the verified local executable and public prepare and resources commands.

For dependency changes, follow Update the project template. Browser compiler pins are separate; shared-resource updates do not require rebuilding an unchanged browser compiler.

Template owns the fictional client CSV. Studio's examples/previews.json supplies IDs and descriptions. Builds generate facts without changing clients to fit a notice.

GitHub Pages and dependency updates

The Studio Pages workflow builds and checks pull requests and pushes to main. Successful builds on main deploy dist/ through GitHub Pages after the site build, Python checks, frontend type checks, lint and unit tests pass. Playwright and native export tests run only when full_tests is selected in a manual run; routine builds do not install Chromium or native Typst. A passing routine build does not establish browser/native rendering parity. Configure the Studio repository’s Pages source as Settings → Pages → Build and deployment → Source → GitHub Actions. GitHub documents the required Pages configuration and deployment permissions in its custom workflow guide.

The manual refresh_immuknow option rebuilds the exact recorded native ImmuKnow commit instead of reusing its verified cache. It does not change pins or the lockfile. full_tests enables the browser/native suite; those checks must pass before a selected main build deploys. Other branches perform checks without deploying. Ordinary pull requests retain the existing cheaper check policy.

The run summary records ImmuKnow and Studio revisions. The build-inputs artifact retains the effective lock, pins, native executable fingerprint and generated build identity for 30 days. ImmuKnow and browser binaries use separate caches; source revision and binary hashes are checked before reuse.

Compiler and renderer binaries, build metadata and Rust licence notices are cached together and verified against their input fingerprints and file hashes. The cache is saved immediately after preparation, before the site and test checks. Ordinary UI, npm and ImmuKnow updates reuse it without Rust or compiler sources. A cold cache requires a source build with a prebuilt, checksum-verified wasm-bindgen CLI. Compiler pins, patches or preparation-script changes invalidate the cache; GitHub may also evict it. Only prepared outputs are cached, rather than the compiler checkout and Cargo target directory.

Dependabot checks npm, uv and GitHub Actions dependencies every Monday at 09:00 UTC. Version updates are grouped by ecosystem and have a seven-day cooldown. Review and merge the resulting pull requests through the same checks. Browser compiler/renderer source revisions and Rust/bindgen pins in compiler-pins.json are maintained explicitly with their patches and checks.

Install and build

Use Linux, Python 3.11 or later, uv, Node.js 24 or later and npm. The native ImmuKnow build requires Rust 1.100 or later; install that toolchain with rustup. Browser compiler builds separately need Git, Bash 4+, GNU sha256sum, Rust/rustup, a native compiler/linker, pkg-config and OpenSSL development headers. Browser pins are in compiler-pins.json:

rustup toolchain install 1.100.0 --profile minimal
rustup toolchain install 1.92.0 --profile minimal
cargo +1.92.0 install --locked wasm-bindgen-cli --version 0.2.118
uv sync --locked
uv run --locked python -m scripts.immuknow install
npm ci
npm run build:site

The build verifies or builds the pinned compiler and renderer, retains license notices, prepares examples and fonts, generates validators from exported ImmuKnow schemas, and writes dist/. It does not build the manual or publish. Documentation has its own build instructions. The first compiler build takes longer. Subsequent build:site runs verify and reuse the prepared binaries and Rust notices without invoking Cargo or needing the compiler checkout. npm notices are regenerated for every build. CI uses npm run build:site -- --require-prepared-toolchain to forbid an unexpected source rebuild after the cache preparation step. Use --compiler-source /path/to/typst.ts with uv run --locked python -m scripts.build-site to reuse a source checkout, or set IMMUKNOW_COMPILER_BUILD_DIR.

After the initial compiler preparation, npm run dev and npm run build regenerate the examples, fonts, notices and browser validators automatically. The Studio SHA and latest reachable version tag are embedded during that build. The footer displays only ImmuKnow Studio and its tag or short SHA. Actions supplies IMMUKNOW_STUDIO_BUILD_SHA and IMMUKNOW_STUDIO_BUILD_TAG; local builds read Git directly. The targeted ImmuKnow revision comes from the verified ImmuKnow build and exported resources. For example, an exact v0.1.0 release shows v0.1.0; later commits show v0.1.0+. Before the first version tag, only the Studio SHA is shown. Restart npm run dev after ImmuKnow or example inputs change, or run npm run prepare:assets to refresh the project data without restarting the server. Type and unit commands also refresh the ImmuKnow resource copies and validators. Generated browser assets stay under public/generated/ and generated/; none are committed.

Python dependency groups separate the usual build and lint tools (dev), browser/native comparison tools (browser), and documentation tools (docs). Ordinary site builds do not need the browser group. The full Python type check includes browser helpers and installs that group explicitly. npm run test:browser also installs its locked Python tools automatically. Ajv and Ajv Formats are npm runtime dependencies because generated browser validators include their helper code. Their licences stay in the site notices.

Run locally

npm run dev -- --host 0.0.0.0 --port 5173

Open http://localhost:5173/. Startup checks the prepared compiler and renderer, regenerates the current example data and starts hot reload. It does not build Rust or download a compiler automatically. To serve the production artifact instead, run npm run serve and open http://localhost:4173/. Relative production URLs also support a proxy prefix.

For a stripping notebook proxy, set IMMUKNOW_DEV_PROXY_BASE to the full path with leading/trailing slashes and set __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS to the proxy hostname when starting dev. To see updated starters instead of a saved draft, export work you want to keep, choose Project → Reset workspace… → Saved draft only in Studio, confirm, then reload.

Checks

Install Git hooks once per clone with uv run --locked prek install. The hooks lint and format Python with Ruff; CI checks the same rules without rewriting files. Run them manually with uv run --locked prek run --all-files. The hooks run the Ruff version locked by the project. Change and check Template-owned packaging and checks in Template.

Install native Typst 0.15.1 for native/browser comparisons. The Playwright configuration makes native test subprocesses use the same verified fonts in assets/fonts as the browser, ignoring both system and embedded fallback fonts. This keeps comparisons independent of the runner's font package; production ImmuKnow uses system fonts. Set TYPST_BIN if Typst is outside PATH. Install Playwright's full Chromium browser and its system dependencies for the encrypted PDF reader tests.

uv run --locked --group browser ty check
uv run --locked ruff check --no-fix .
uv run --locked ruff format --check .
uv run --locked python -m unittest discover -s tests -p 'test_*.py'
npm run typecheck
npm run lint
npm run test:unit
npm run build:site
npx playwright install --with-deps chromium
npm run test:browser

Browser checks serve dist/ at the root. Set IMMUKNOW_BASE_URL to test an already served artifact, including any proxy prefix and trailing slash. Do not rebuild an artifact while it is being tested. Evidence stays in test-results/. Downloaded-project checks extract the ZIP outside either checkout and run the ImmuKnow executable directly with an empty command search path. They install no Python environment or tools into the project. Python stays in the test harness for PDF and QR inspection. Four cases cover a customized English notice through single-template selection, long French output, saved-run review for a French notice with warnings, and a guardian-directed suspension order for a younger student. Template's maintainer tests run in its own repository; fresh downloads contain native setup instructions and sample selections. PDF reader checks use Studio's own example inputs.

Add or update example clients in Template. Aim for plausible records that help people develop notice wording and layout. Use complete contact details, consistent dates and notices that match the supplied facts. Keep deliberately incomplete or conflicting data in separate test fixtures. ImmuKnow owns tests of native validation and delivery decisions.

ImmuKnow maintains its separate native test fixtures. Studio's contract cases under unit/fixtures/ are a local snapshot, not imports from ImmuKnow's test package.

Test scope and Actions minutes

Follow the shared testing strategy. ImmuKnow tests native input rules, validation, notice families and delivery. Studio tests the browser and the handoff from an authored project to native output. The same contract cases run against the ImmuKnow and browser validators because each implementation needs to accept and reject the right data.

Pull requests and main builds run the site build, type checks, lint and unit tests. The full browser/native suite is deliberately manual to conserve GitHub Actions minutes. Select full_tests in the Studio Pages manual workflow to run it. Ordinary deployment does not require that manual run. Build summaries record whether it ran, so a successful ordinary build should not be described as a browser/native test pass.

Run relevant browser checks locally for editor, draft, import or download changes. Run the full suite for ImmuKnow/compiler updates, changes to shared contracts and release preparation. Keep the manual workflow available for those checks when local tools are unavailable.

Downloaded-project tests cover representative native handoffs; ImmuKnow owns the full persistence, input validation and encryption suites. Add an expensive browser/native case when it protects an uncovered Studio boundary.

Native interface boundary

scripts/immuknow.py owns executable installation, fingerprint verification and public command calls. prepare returns row identity, facts and checks; resources supplies unversioned rendering.json, report.json, the shared library and its manifest. Build identity combines the verified source-build record with those exported hashes and independent browser compiler pins.

Installed Template resources stay read-only. Copies belong in disposable generated/immuknow/, browser output or downloaded projects. ImmuKnow owns validation; Studio owns its browser validator and native handoff regressions. Browser reports use render-report v4 with component geometry. Native saved-report contracts are documented in ImmuKnow's review guide.

Update the project template

Studio consumes the maintained immuknow-template-resources package. Its contributor guide owns packaging and Template verification. Studio copies the installed resources before editing and gets the complete shared library from ImmuKnow.

For a ImmuKnow upgrade, first update and test Template against the intended clean ImmuKnow commit. Update Studio's immuknow-revision.txt and Template pin together, then reinstall the native executable with uv run --locked python -m scripts.immuknow install. After a Template change, update immuknow-template-resources.rev in pyproject.toml to its full reviewed commit SHA, then:

uv lock --upgrade-package immuknow-template-resources
uv sync --locked
uv run --locked python -m scripts.project_template
npm run prepare:assets

A ImmuKnow upgrade also requires a Template revision whose immuknow-revision.txt selects that ImmuKnow commit. scripts.project_template checks ImmuKnow compatibility and Git source provenance from the installed package. Never edit installed resources. The resource package excludes Python helpers, Python environment files and maintainer tests from the exported scaffold. Downloaded projects use native project commands; their standalone executable is supplied separately. Python remains a Studio build/test/documentation dependency, and is not required for production notice generation.

ImmuKnow and Template are public repositories, so dependency installation needs no GitHub credentials. Dependencies stay locked and installed; ordinary builds perform no ad hoc upstream fetches.

After either dependency changes, verify browser rendering, drafts and project downloads. Run the browser/native downloaded-project checks to verify native setup, the sample, both notice selectors and saved-run rebundling. Template maintains its resource-wheel/source-archive and presentation and packaging tests in its own repository.