werkdock/CHANGELOG.md

# Changelog

Release notes for consumers of the `werkdock` CLI, Werkator first among them.
Each entry says what changed, what still works unchanged, and what a consumer
should adapt — and by when.

A release is a merge to main; there is no separate release step. So a branch
that changes behavior sets the version in `internal/cli/cli.go` (what
`werkdock version` prints) and titles its section here with that version and
the merge date, before it is merged. Nothing on main is ever "unreleased".

## 0.6.0 (2026-09-10)

Theme: the API socket — RFC 0005 milestone 3, and with it milestone 4:
Testcontainers starts a real PostgreSQL in werkdock. Purely additive;
no CLI verb changes behaviour.

### New

- `werkdock system service [--time D] [unix://PATH]` serves the Docker
  Engine API subset a client actually uses, on
  `$XDG_RUNTIME_DIR/werkdock.sock` by default (podman's verb and
  podman's manners: optional, started when needed, `--time` to exit
  when idle). A client is pointed at it with
  `DOCKER_HOST=unix://<path>`.
- Testcontainers (validated with 1.19.3, `PostgreSQLContainer`) works
  against it: pull, create, start, logs with the wait strategy, exec,
  kill, remove, and the session cleanup. It needs
  `TESTCONTAINERS_RYUK_DISABLED=true`, because Ryuk wants the API
  socket inside a container of its own.
- The endpoints are those measured from a real run, written down in
  `docs/testcontainers-api.md`. Everything outside the subset answers
  **501 with the reason**, never 404, so a client that needs more says
  so plainly.
- Instances carry docker labels (`config.json`), and the instance list
  filters on them, which is how a client finds what it left behind.
- An exec is a record of its own with an id and an exit code, because
  the API creates, starts, and inspects it in three calls.

### Refused rather than ignored

- `logs` parameters werkdock cannot honour say so with 501 and the
  reason: `tail` (the output is streamed whole), `timestamps` and a
  non-zero `since`/`until` (no clock is recorded beside the output).
  What a client actually sends — `stdout`, `stderr`, `follow`,
  `since=0`, `tail=all` — is served.

### Ports, the deliberate deviation

Werkdock shares the host's network and cannot map a port. Where a
client asks for a published port, werkdock therefore picks a free one
and tells the *service* to bind it, through the environment variable
the image honours (`PGPORT`, `MARIADB_TCP_PORT`, `MYSQL_TCP_PORT`,
`REDIS_PORT`). An image outside that small table keeps its own port,
which is right as long as one instance of it runs at a time; asking to
move it fails with the reason instead of silently reporting a port
nothing listens on. The same table carries the user an image needs when
its entrypoint expects to drop privileges itself (`postgres`), which
werkdock cannot do with one uid.

### Version reporting

`/version` and `/info` report the Docker Engine version whose API is
served (25.0.0), not werkdock's: clients compare that field against a
minimum, and 0.x fails it forever. Werkdock's own version is beside it
in `Components` and in `/info`'s `OperatingSystem`.

### For Werkator

- Nothing to change. The service is not started unless someone asks
  for it, and no CLI verb behaves differently.
- New possibility: an integration test in a build sandbox can get a
  real database. Bind the socket into the sandbox
  (`-v $XDG_RUNTIME_DIR/werkdock.sock:/run/docker.sock`) and set
  `DOCKER_HOST` and `TESTCONTAINERS_RYUK_DISABLED` in the build.

## 0.5.0 (2026-09-10)

Theme: the instance lifecycle — RFC 0005 milestone 2. A service image
runs in the background, can be stopped, restarted, queried, and talked
to. Additive for `run --rm`; two small semantic changes below.

### New

- `run -d` starts the instance under a background supervisor and prints
  its 64-hex id; `--name NAME` names it (default: image basename plus six
  characters of the id); `-i` passes stdin (no pty: `-t` is refused).
- `ps [-a] [-q] [--format FMT]` lists instances with docker's columns
  (`CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES`; PORTS stays
  empty, the network is the host's); `stop [-t SECONDS]`, `kill [-s SIG]`,
  `rm [-f]`, `wait`, `logs [-f]`, `create`, `start`, and `inspect` on an
  instance id, unique prefix, or name. Each prints what docker prints
  (the argument on success, `werkdock: …` and exit 125 per failure).
- `exec [-e K=V] [-w DIR] [-u USER] [-i] INSTANCE CMD...` runs a second
  command in the instance's sandbox: same rootfs, mounts, uid, env,
  `/run` and volumes; not the same pid namespace.
- docker's management form is accepted: `container ls|start|stop|...`,
  `image ls|rm|pull|...`.
- State lives in `$WERKDOCK_HOME/instances/<id>/`: `config.json`
  (`version: 1`), `state.json`, `stdout`, `stderr`, `run/`, `volumes/`.
  A state left "running" by a dead supervisor (reboot, `kill -9`) is
  repaired to exited 255 on the next read; an exited `--rm` instance
  found that way is removed.

### Changed

- A `run` without `--rm` no longer fails ("persistent instances are not
  implemented yet"); the instance stays for `ps -a`, `logs`, `start`, `rm`.
- The command is pid 1 of its sandbox (`bwrap --as-pid-1`), as in
  docker, so `stop`'s SIGTERM can reach it. As in docker, an entrypoint
  without a SIGTERM handler (`sh -c '…'`) is only ended by the SIGKILL
  after the timeout, and orphaned children are its own to reap.
- A foreground `run` forwards the first SIGINT/SIGTERM/SIGHUP to the
  command and kills it on the second, or after 10 seconds; bwrap runs in its own process
  group, so Ctrl-C no longer kills bwrap (and with it the command)
  outright. Werkator's builds see the same exit codes as before; a
  `sh -c` build interrupted with SIGTERM now ends 10 seconds later, on
  the SIGKILL, unless the script traps TERM.
- Anonymous volumes (the image's `VOLUME`s) and `/run` are directories
  of the instance instead of tmpfs, so they survive `stop`/`start` and
  are visible to `exec`. For a `--rm` run the difference is disk instead
  of RAM for those paths, and nothing else.

### For Werkator

- Nothing to change: `run --rm …` behaves as before. The `ps` output
  is new and Werkator does not parse it.

## 0.4.0 (2026-09-10)

Theme: service images — the first milestone of RFC 0005 (PostgreSQL in the
sandbox, Testcontainers as the destination). Additive; a `run` without the
new flags on an image without `USER`/`VOLUME` behaves exactly as before.

### New

- `run --user USER[:GROUP]` (`-u`) makes the caller appear as that user inside
  the sandbox: a name is resolved in the image's `/etc/passwd` and `/etc/group`,
  a number needs no entry. `HOME` follows the passwd entry when there is one.
  Still one uid only — the caller is mapped to it; there is no second user.
- `run --userns=keep-id` (podman's spelling) maps the caller to their own uid
  and gid. Other `--userns` modes are refused with the reason.
- An image's `USER` (OCI config) applies when neither flag is given, as with
  podman; unknown names fail with `image USER: …`. Default stays uid 0.
- An image's `VOLUME` paths are mounted as anonymous tmpfs unless a `-v` or
  `--mount` covers them, so `postgres:16` starts without knowing its data and
  socket directories by heart.
- `/run` is a tmpfs in every sandbox, beside `/tmp` and `/root`. `/var/run`
  points there in practically every image, and services keep pid files, locks
  and sockets under it without declaring a `VOLUME` (`postgres` needs
  `/var/run/postgresql` writable). A `--tmpfs`/`-v` on a path below `/run`
  still works, it just lands inside the tmpfs.
- `import -c` accepts `USER user[:group]` and `VOLUME /path` (or a JSON array);
  `inspect` shows `User` and `Volumes` in `Config`.

### For Werkator

- Nothing to change. Builds keep running as uid 0. If a build image ever sets
  `USER`, that user applies; add `--user 0` to keep root.

### Podman before Docker

- Where the two differ, werkdock follows podman from now on (RFC 0005):
  `--userns=keep-id` is the first case.

## 0.3.0 (2026-09-10)

Theme: `werkdock pull` — images come straight from a registry, no docker
on any machine needed (RFC 0002 level 2, RFC 0004). Additive; nothing a
consumer calls today changes.

### New

- `werkdock pull [--platform OS/ARCH] [REGISTRY/]REPOSITORY[:TAG]` fetches an
  image and stores it exactly as `load -i` would: layers flattened, OCI
  config kept, listed by `images` under the reference given. Prints
  `Pulled image: REF`; exit 125 with the reason if the registry refuses,
  the image already exists, or crane is missing. `--platform` defaults to
  `linux/<host arch>`.
- The registry side is the `crane` binary
  (github.com/google/go-containerregistry, one static executable, no
  privileges). werkdock looks for it in `PATH`, then beside its own
  binary, or at `WERKDOCK_CRANE`. A deployment on a managed webspace ships
  it next to `werkdock`. Credentials come from `~/.docker/config.json`
  (`DOCKER_CONFIG`), as with docker.
- `werkdock rmi IMAGE...` removes images (`docker rmi`): prints `Untagged: REF`
  per image, tries every argument and exits 125 if one failed. Works on the
  legacy flat layout too, so Werkator's pre-0.2.0 build image can be removed
  with it. `pull` and `load` now name `rmi` in their "already exists" message.
- `werkdock images` takes docker's `--format`: a Go template over
  `.Repository`, `.Tag`, `.ID`, `.CreatedAt`, `.CreatedSince`, `.Size`, or
  `table [TEMPLATE]` for docker's column layout (`--format table` prints
  `REPOSITORY TAG IMAGE ID CREATED SIZE`); `-q` prints IDs; an optional
  `REPOSITORY[:TAG]` argument filters. Without flags the output is unchanged:
  one short reference per line. `inspect` gains an `Id` field. The ID is
  a hash of the image metadata, shared by tags of the same image; it is
  not docker's config digest.
- `werkdock doctor` warns when crane is not in `PATH` (a warning, not a
  failure: everything but `pull` works without it).

### For Werkator

- Optional: replace "download archive, `werkdock load -i`" with a single
  `werkdock pull IMAGE` where the image is a public registry image; the
  self-built archives keep going through `import`/`load`.
- Deployment: put `crane` beside `werkdock` if `pull` is to be used.
- Optional: retire old build images with `werkdock rmi` instead of deleting
  store directories.

## 0.2.0 (2026-09-10)

Theme: the `run` surface, image names, and the image store move closer to
`docker run --rm` (RFC 0002, RFC 0004). Everything Werkator invokes today keeps working; two of its calls
now have a preferred docker-shaped form.

### Compatible — nothing to change

- `werkdock images` still prints one image per line and still prints a bare
  name for images loaded without a tag. Werkator's exact-line existence check
  (`image in loaded`) matches as before. Images that carry a tag other than
  `latest` print as `repository:tag`.
- `werkdock load -i ARCHIVE --name NAME` still imports a rootfs archive; it
  now additionally prints one note on stderr pointing to `werkdock import`.
  Exit code and stdout are unchanged (`Loaded image: NAME` became
  `Imported image: NAME` — adjust if the stdout line is parsed).
- `werkdock run --rm -v ... --tmpfs ... -e ... -w ... IMAGE CMD...` is
  unchanged in syntax and mount order. Two semantic corrections match docker:
  a bare `-e KEY` whose variable the host does not have is no longer passed as
  `KEY=` (it is omitted); a missing `-w DIR` is created when it lies in a
  writable area (tmpfs or a read-write bind) instead of failing with bwrap's
  "Can't chdir".
- Existing stores: the flat layout `images/NAME/` written by earlier versions
  is still read as `NAME:latest`. No reload after the upgrade; new imports land
  in `images/REPOSITORY/TAG/`. The pre-existing `image.json` files lack the new
  metadata fields and read back as an image without ENTRYPOINT/CMD/Env, which
  is exactly what they were.
- `werkdock doctor`, `version`, exit codes (125 for werkdock's own errors,
  the command's code otherwise): unchanged.

### Preferred new forms — adapt at the next convenient change

- `werkdock import ARCHIVE [REPOSITORY[:TAG]]` replaces `load -i --name` for
  rootfs archives (`docker import` semantics). Plan: `load -i --name` stays
  accepted until Werkator has switched, then it is removed together with the
  stderr note.
- `werkdock load -i ARCHIVE` loads a `docker save` archive (legacy and OCI
  layout) or a plain OCI image layout: layers flattened into one rootfs,
  whiteouts applied, the OCI config kept as image metadata, the image named by
  its RepoTags (every tag becomes a hardlinked copy). A multi-arch index picks
  the host platform. This is the intended path for build environments from now
  on: `docker build`, `docker save`, upload, `werkdock load` — with ENTRYPOINT,
  ENV, and WORKDIR intact (RFC 0004). Layers compressed with zstd need the
  `zstd` binary, as `import` does.
- Image names may carry a tag: `werkator-buildenv-<hash>` keeps working and
  equals `werkator-buildenv-<hash>:latest`; a consumer may also use
  `werkator-buildenv:<hash>` or a registry-style `git.javagil.de/mi/buildenv:<hash>`.
  Name grammar: `[registry/]repository[:tag]`, repository components lowercase
  `[a-z0-9]` with `.`, `_`, `-` between them, tag `[A-Za-z0-9_][A-Za-z0-9_.-]*`,
  max 128 characters. The `.tmp` tag suffix is reserved.
- `import -c 'ENTRYPOINT [...]'`, `-c 'CMD ...'`, `-c 'ENV K=V'`,
  `-c 'WORKDIR /d'`, `-c 'LABEL k=v'` store OCI metadata with the image;
  `werkdock inspect IMAGE` prints it as a docker-shaped JSON array
  (`RepoTags`, `Created`, `Architecture`, `Os`, `Config`, plus a `Werkdock`
  section with `Source` and `RootFS`). A consumer that wants to check
  existence like `docker image inspect` can use `inspect` (exit 125 when the
  image is missing) instead of scanning `images`.
- `werkdock run IMAGE` without a command runs the image's ENTRYPOINT+CMD;
  `--entrypoint PROGRAM` overrides ENTRYPOINT and drops CMD; positional
  arguments replace CMD; `-e` and `-w` override the image's Env and WorkingDir.
- `--mount type=bind,src=SRC,dst=DEST[,readonly]` and
  `--mount type=tmpfs,dst=DEST` are accepted beside `-v` and `--tmpfs`; all
  three feed one ordered mount list (the git-metadata mask ordering still
  holds across them).
- `--network host` (and `--net host`) is accepted as a no-op, so a build
  script can pass a docker-compatible command line unchanged. Other modes fail
  with: `network mode "X" is not available in unprivileged shared-webspace
  environments; only "host" is supported`. `-p/--publish` remain refused.

### Incompatible

- None for the calls Werkator makes. For everyone else: an image name with an
  uppercase letter or a leading `.`/`-`/`_` in the repository was accepted by
  the old name check and is refused now (docker's grammar); `..`-style names
  were refused before and still are.