Repository navigation
Development
Building, testing, the contract gate and the sandbox check. Two rules from
AGENTS.md shape everything here: the contract in
docs/history/reference/ts-manager-contract.md outranks the TypeScript sources,
and no line of TypeScript is ported over.
Go 1.27.4 — go.mod asks for it exactly. With GOTOOLCHAIN=auto a matching
toolchain is downloaded when the local one is older. bash and curl for the
scripts; bwrap for the sandbox check.
go build ./...
go vet ./...
go test ./... -race -count=1 -p 1-p 1 is required: internal/manager and e2e start real sets on the shared
9100–9199 range and take each other's ports when packages run in parallel. The
race-enabled suite is the stage gate — config loading, both transports, the nine
meta-tools, permissions, OAuth, the panel API, supervision, statistics.
A package whose tests start stdio servers needs a TestMain calling
downstream.RunChildGuardMode(os.Args): the guard is os.Executable(), and
without the handover the test binary runs tests instead of serving, so the
sandbox silently leaks.
The fastest way to see the whole chain work — panel, set and a stdio downstream, no external services:
go test ./e2e -run TestLifecycle -vbash scripts/contract-e2e.sh # needs a live panel, E2E_BASE default http://127.0.0.1:9091
bash scripts/sandbox-e2e.sh # 14/14 PASS on a host where bwrap works
bash scripts/docs-check.sh # links, personal paths, orphans, EN/RU parity, anchorscontract-e2e.sh runs go test ./e2e -run TestContract against a running
manager. E2E_STRICT=1 (the default) fails on known reference defects;
E2E_STRICT=0 downgrades them to log lines. An empty E2E_BASE skips the suite,
and with E2E_STRICT=1 a skipped run exits non-zero, so it cannot read as a
passed gate.
sandbox-e2e.sh checks the host, not the code: that bubblewrap really hides
$HOME, secrets, the network, writes and /proc/1/root. It fails where
unprivileged user namespaces are denied.
docs-check.sh fails on a broken relative link, a path from
docs/forbidden.txt, a page nothing links to, different file listings in
docs/en and docs/ru, or a value in docs/anchors.txt that no longer matches.
Run it before any pull request that touches docs/.
A v* tag is the trigger. release.yml repeats go vet and the race suite,
then goreleaser release --clean --skip=publish builds the archives and
checksums.txt, gh release creates the page, and docker build/push sends
slim and full images to GHCR. Nothing is published by hand.
Details: docs/en/dev/development.md
and docs/en/dev/release.md.