Skip to content

Development

Vladimir Kochnev edited this page Nov 17, 2026 · 1 revision

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.

Requirements

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.

Build and test

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 -v

The other gates

bash 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, anchors

contract-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/.

Release

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.

Clone this wiki locally