53 lines
3.2 KiB
Markdown
53 lines
3.2 KiB
Markdown
# werkdock Agent Instructions
|
|
|
|
## Project
|
|
|
|
werkdock is a docker-like sandbox CLI over `bwrap`, with filesystem isolation only; see [README.md](README.md).
|
|
Werkator runs its CI builds and werkrevisor's reviews in werkdock sandboxes on mih09.
|
|
[docs/werkdock.werkbaum](docs/werkdock.werkbaum) holds the plan, [docs/rfcs/](docs/rfcs/) the decisions.
|
|
|
|
## Build and Test
|
|
|
|
```sh
|
|
go test ./... # all tests; sandbox integration tests skip without bwrap/userns
|
|
go vet ./... && gofmt -l . # quality gates (gofmt must print nothing)
|
|
CGO_ENABLED=0 go build -o dist/werkdock . # one static linux binary
|
|
tools/check-licenses # licenses of the dependencies against tools/allowed-licenses.txt; each build
|
|
go run ./tools/vulncheck -base origin/main # only the called vulnerabilities this branch brings; each PR
|
|
go run ./tools/vulncheck # all called vulnerabilities; main each night
|
|
```
|
|
|
|
The checks load govulncheck and go-licenses by `go run` at a pinned version; neither becomes a dependency of the module.
|
|
Their levels come from [docs/risk-analysis.md](docs/risk-analysis.md), criticality high.
|
|
An exception from a vulnerability goes into `tools/vulnerability-exceptions.txt`, with its reason.
|
|
|
|
## Hard Invariants
|
|
|
|
- Filesystem isolation only: network, uid, `/proc`, `/dev` and `/tmp` come from the host by contract.
|
|
This is what makes werkdock work without root on a Hostsharing Managed Webspace.
|
|
- Go, one static binary, standard library only ([RFC 0001](docs/rfcs/0001-implementation-language.md));
|
|
a third-party dependency needs an RFC.
|
|
- Verbs and flags follow docker ([RFC 0002](docs/rfcs/0002-docker-compatible-surface.md));
|
|
where docker and podman differ, werkdock follows podman.
|
|
A docker flag or API endpoint that werkdock does not support fails with the reason, never silently.
|
|
- The Docker Engine API serves only endpoints measured from a real client,
|
|
listed in [docs/testcontainers-api.md](docs/testcontainers-api.md); every other one answers 501 with the reason.
|
|
- A quirk is measured knowledge about one image version; an image that no longer matches it is refused, not guessed at.
|
|
- No imports from Werkator code and no coupling to the Werkator build; Werkator consumes the binary through `PATH`.
|
|
|
|
## Workflow
|
|
|
|
Follow [docs/agentic-workflow.md](docs/agentic-workflow.md), the workflow of all Werk repositories:
|
|
roles, steps of a PR, review rounds, PR documents, the plan, versions and the writing style.
|
|
In addition, for werkdock:
|
|
|
|
- Documents are in English.
|
|
- The version stands in `internal/cli/cli.go` (what `werkdock version` prints).
|
|
Each PR raises it and adds a section with that version and the merge date to [CHANGELOG.md](CHANGELOG.md):
|
|
what changed, what stays compatible, and what a consumer, Werkator first, must adapt.
|
|
A change that consumers do not notice gets a section marked as internal.
|
|
- A decision larger than one PR is an RFC under `docs/rfcs/`.
|
|
- A merge to `main` is a release; the CI deploys nothing.
|
|
The rollout to mih09 is manual: the new binary to `~/.werkator/bin/werkdock` of the account `mih09-werkator`,
|
|
then a restart of the systemd user units `werkdock-api-*.service`, which otherwise keep serving the old code.
|