Scripts reference

The commands a maintainer runs: the Justfile recipes, the workspace and per-package pnpm scripts, and the checks under scripts/.

Taskfile.yml no longer exists. The Justfile is the only task runner in the repository.

Contributor setup and the commit conventions are in CONTRIBUTING.md. What each environment variable a recipe sets does is in configuration.

Justfile recipes

just <recipe>. Recipes taking a parameter show its default.

The frontend recipes exist as separate commands because the API and the SPA are separate processes reading separate environments. Setting feature flags only on the API leaves the rail showing sections the API no longer serves; see feature flags.

Three recipes export FEATURE_QUERIES_ENABLED, FEATURE_RULES_ENABLED and FEATURE_ETL_ENABLED. Nothing reads those names — the real ones have no _ENABLED suffix — so those recipes run with the default flags.

Workspace scripts

Run from the repository root.

Package scripts

Run one with pnpm --filter @sparql-query-lib/<pkg> <script>.

api

The smoke scripts need a running service or network and are not part of the CI pipeline.

web

Other packages

contracts, types, runtime and runtime-oxigraph build with tsup plus a declaration-only tsc; the two runtime packages then run scripts/emit-cjs-declarations.mjs over dist. mcp-server, srl, tools, compiler, runtime-duckdb, runtime-etl, runtime-srl and rdf-delta build with tsc. All of them except contracts and types have a vitest test.

mcp-server also has dev (stdio), dev:http, dev:dual-http, dev:debug-http and the matching start* scripts, which set MCP_TRANSPORT and run the built output.

rdf-delta has poc:blob-snapshot and poc:patch-log, two proof-of-concept runners kept beside the package.

Nine of the ten packages define lint as echo "TODO: add lint". The only real linting in the repository is stylelint over packages/web. pnpm -r --if-present lint therefore passes without reading a line of TypeScript, and scripts/ci/lint.sh prints a warning naming the packages whose green tick means an echo succeeded.

The CI pipeline

All CI logic is in scripts/ci/, so every step runs locally with plain bash scripts/ci/<step>.sh. The GitHub Actions workflow is a dispatcher. bash scripts/ci/all.sh runs the required sequence:

1. install.sh — pnpm install --frozen-lockfile
2. lint.sh — pnpm -r --if-present lint, then check-doc-links.mjs
3. ratchet-selftest.sh — proves the ratchets still fail when they should
4. any-ratchet.sh — count-any.mjs
5. orphan-ratchet.sh — check-orphans.mjs
6. typecheck.sh — nuxi typecheck over packages/web, against a baseline
7. build.sh — pnpm -r build in topological order, which also typechecks every other package
8. publish-check.sh — four checks on the publishable packages
9. test.sh — vitest across the affected packages

Steps outside that sequence:

• e2e.sh — Playwright against the production preview build, with the API mocked at the network layer. No API server is started. It runs on workflow_dispatch, not as a required gate. WEB_PORT defaults to 3701 in CI so a locally running preview on 3001 cannot red out a job.
• commitlint.sh — conventional commits, warn only. It never fails a build; making it blocking means changing its final exit 0 to exit "$status".
• fuzz-nightly.sh — the query group property harness at PHASE2_FUZZ_RUNS (default 1000) and a clock-derived seed, over test/phase2/ and test/web/. The PR suite runs the same files at a fixed seed and about 50 cases. The seed is printed before the run, so a red nightly reproduces with PHASE2_FUZZ_SEED=<seed> PHASE2_FUZZ_RUNS=<n> bash scripts/ci/fuzz-nightly.sh.
• docker-build-push.sh — builds the server image from the root Dockerfile and tags it sha-<short>, plus latest on trunk and X.Y.Z when building a vX.Y.Z tag or when RELEASE_VERSION is set. It only pushes when PUSH=true, so running it locally builds and stops. Login is the caller's job.
• docker-build-push-web.sh — the same, for the web UI bundle image built from Dockerfile.web and tagged under ghcr.io/<owner>/sqlib-web. That image carries the static site at /site and runs nothing; see deploying. It passes the commit, version and build time in as build arguments, which become the image's OCI labels and its /bundle-info.json.
• dependabot-automerge.sh — merges Dependabot bumps whose CI is green. The calling job's needs list is the only gate, image and web-image included, because a base image bump once merged itself green and broke every publish afterwards.

lib.sh is sourced by each script. It sets set -euo pipefail, changes to the repository root, and times the step. scripts/ci/budgets.txt gives per-step budgets in seconds; exceeding one raises a warning annotation and never fails the step, because wall-clock time is too variable to gate on.

The ratchets

Three checks compare the tree against a recorded baseline rather than against zero, so a cleanup can land incrementally while the number cannot regress.

any — scripts/count-any.mjs

Counts as any, : any and catch (x: any) in TypeScript under packages/, excluding node_modules, dist, *.d.ts and *.generated.ts, split into source and test totals. The baseline is scripts/any-baseline.json.

Two different promises:

• Whole repo: only an increase over srcTotal or testTotal fails.
• Strict zone (packages/api/src/): any as any or catch (x: any) is an outright failure, not merely an increase. : any is not in the strict zone.

When it trips: a strict-zone violation names the file; remove the as any. A rise names the amount; remove the new occurrences, or if they are justified, run --update in the same change so the new number is reviewable in the diff. When counts drop, the script says so and asks you to run --update — an unlowered baseline is slack that absorbs the next regression silently.

Orphan modules — scripts/check-orphans.mjs

Reports source files nothing can reach. Roots are package entry points (main, module, exports, bin), files named in package scripts, tests, tool configs, and Nuxt's convention directories, since a page or component is reached by the router rather than by an import. The baseline is scripts/orphan-baseline.json, and it lists paths, not a count: an entry is a claim that a human looked at that specific file and decided it stays.

When it trips: it names the unreachable files. Either delete the file, wire it up, or — if it is deliberately kept, as the benchmark and debug scripts under packages/api/scripts/ are — accept it with --update so the addition appears in review. When a baseline entry is no longer an orphan the script says so and asks you to run --update to lower it.

Web type errors — scripts/ci/typecheck.sh

Counts error TS lines from nuxi typecheck in packages/web and compares against packages/web/.typecheck-baseline, a file holding a plain integer. It is currently 0.

When it trips: it prints the errors. Fix them, or — if the count went down — lower the baseline with echo <count> > packages/web/.typecheck-baseline.

The script also fails when it cannot measure. A missing baseline file, a baseline that is not a plain integer, and a checker that exits non-zero while printing nothing countable are each a hard failure rather than a zero, because a crashed checker and a clean run both produce no error TS lines. TYPECHECK_CMD and TYPECHECK_BASELINE_FILE exist so the self-test can exercise those guards against a stub.

scripts/ci/ratchet-selftest.sh

Every gate that counts something reports the same number when it measured nothing as when everything is fine. The guards that close that gap only fire in situations a healthy CI run never reaches, so nothing would notice them rotting. This script gives each guard a sandbox reproducing its failure, asserts the script exits non-zero, and asserts a matching healthy case still passes. It runs in about a second and needs no install.

The publish lane

scripts/ci/publish-check.sh runs four checks over the packages that are not private: true: runtime, runtime-oxigraph, and the six the CLI is built from (compiler, srl, runtime-duckdb, runtime-etl, runtime-srl, cli). It publishes nothing and needs no token. It runs after build.sh, because what it checks is built output. Each asks a different question:

The first three read the working tree or the tarball; the fourth reads an artefact that exists only in someone else's project. All four are invisible from inside the workspace, where every import resolves through pnpm's symlinks.

When one trips: each names the package and the specific expectation. For check-public-api.mjs the fix is usually to regenerate or edit packages/<pkg>/public-api.md in the same change as the surface change, which is the point of the file.

Other scripts