joakimp
34cae2a1d2
ALL FOUR releases v0.74.0 -> v0.75.5 had been shipping the same image bytes due to a Docker layer-cache hit on the bare 'npm install -g @earendil-works/pi-coding-agent' command (when PI_VERSION=latest). The command string is identical across builds, so the layer-hash is identical, so registry buildcache (cache-from/cache-to) silently reuses the layer from whatever pi version was current when the cache was first populated. Verification: docker manifest inspect joakimp/pi-devbox:vX.Y.Z showed identical SHA256 digests on both linux/amd64 and linux/arm64 for v0.74.0, v0.75.3, v0.75.4, v0.75.5. Users on :latest were getting whatever pi version was baked into the v0.74.0 build. DISCOVERED 2026-05-23 by user trying to update pi-devbox on MBP-M1 and seeing pi 0.74.0 reported despite pulling v0.75.5. CHANGES .gitea/workflows/docker-publish.yml — both smoke and publish jobs get a new 'Resolve PI_VERSION from tag' step that strips the leading 'v' and any trailing letter suffix from github.ref_name. Result is passed as a build-arg to docker/build-push-action so the npm install layer's hash includes the concrete version, forcing cache miss when pi bumps. scripts/smoke-test.sh — new run_expect helper that asserts pi --version contains the EXPECTED_PI_VERSION env var. Smoke job sets this from the resolve step output. Would have caught this regression on v0.75.3. Dockerfile — comment block above ARG PI_VERSION=latest documenting the cache-hit footgun. The 'if latest' branch in the install RUN is preserved for local dev convenience but never fires in CI now. AGENTS.md — new convention bullet explaining the cache-hit class of bug and noting the latent same-bug in opencode-devbox's with-pi variants (currently masked by OPENCODE_VERSION bumps; will manifest when cutting a vN.N.Nb-style opencode-version-unchanged release that only bumps pi). CHANGELOG.md — full entry under v0.75.5b describing the recovery, the silent-failure mechanism, and the verification steps. NO IMAGE-CONTENT CHANGES vs v0.75.5 INTENT. This build produces the actual pi 0.75.5 image content that v0.75.5 was supposed to ship. NEXT FOLLOWUP (parked, not in this commit) opencode-devbox should get the same workflow change for its build-variant-with-pi and build-variant-omos-with-pi jobs. Currently masked because every release also bumps OPENCODE_VERSION which invalidates the cache, but that masking would fail on a pi-only bump release.
65 lines
4.4 KiB
Markdown
65 lines
4.4 KiB
Markdown
# AGENTS.md — pi-devbox
|
|
|
|
Container image that adds pi coding-agent on top of the opencode-devbox base image.
|
|
|
|
## Repository layout
|
|
|
|
- `Dockerfile` — single-stage build, `FROM opencode-devbox:base-latest`, installs pi + companion repos
|
|
- `docker-compose.yml` — compose file for local use
|
|
- `.env.example` — environment variable template
|
|
- `scripts/smoke-test.sh` — sanity checks run by CI before pushing to Docker Hub
|
|
- `.gitea/workflows/docker-publish.yml` — CI pipeline: smoke amd64 → multi-arch push → update Hub description
|
|
|
|
## Versioning scheme
|
|
|
|
- Tags follow the pi npm version: `v{pi_version}[letter]`
|
|
- Bump `PI_VERSION` build-arg default in `Dockerfile` when cutting a new release
|
|
- Docker Hub: `joakimp/pi-devbox:vX.Y.Z` + `joakimp/pi-devbox:latest`
|
|
|
|
## Release-day checklist
|
|
|
|
1. Bump `PI_VERSION` in `Dockerfile` (or leave as `latest` to pick up current)
|
|
2. Update `CHANGELOG.md`: promote `Unreleased` → `vX.Y.Z — YYYY-MM-DD`
|
|
3. Add fresh `## Unreleased` section
|
|
4. Commit, tag `vX.Y.Z`, push tag → CI fires automatically
|
|
|
|
When drafting CHANGELOG entries, pull pi's release notes from the
|
|
`CHANGELOG.md` shipped inside the npm tarball:
|
|
|
|
```bash
|
|
cd /tmp && npm pack @earendil-works/pi-coding-agent@<version>
|
|
tar -xzf earendil-works-pi-coding-agent-<version>.tgz package/CHANGELOG.md
|
|
head -40 package/CHANGELOG.md
|
|
```
|
|
|
|
Pi's CHANGELOG has rich New Features / Added / Changed / Fixed sections
|
|
per version. Don't try to derive notes from the npm registry metadata
|
|
(`npm view`) — it doesn't include the changelog body.
|
|
|
|
## Key facts
|
|
|
|
- **Base image**: `joakimp/opencode-devbox:base-latest` — rebuilt whenever opencode-devbox cuts a new base
|
|
- **pi binary**: baked at `/usr/bin/pi` (system npm prefix); `NPM_CONFIG_PREFIX=/home/developer/.pi/npm-global` at runtime so user-installed pi/packages land on the named volume
|
|
- **Companion repos**: pi-toolkit and pi-extensions cloned to `/opt/` at build time; `entrypoint-user.sh` (inherited from base) deploys symlinks to `~/.pi/agent/` on container start
|
|
- **MemPalace**: fully operational — inherited from base image; bridge extension deployed by entrypoint
|
|
|
|
## Conventions
|
|
|
|
- Do NOT call `mempalace-toolkit/install.sh` in the Dockerfile — the base entrypoint handles it
|
|
- `NPM_CONFIG_PREFIX=/usr` must be set per-RUN for any build-time `npm install -g` to keep baked binaries off the volume-shadowed path
|
|
- The smoke test threshold is 2200 MB — update if the image legitimately grows past it
|
|
- **PI_VERSION must be passed explicitly by CI as a concrete version** (derived from the git tag), not left as the `latest` default. The Dockerfile's bare `npm install -g @earendil-works/pi-coding-agent` (without `@${PI_VERSION}`) produces an identical layer-hash across builds; combined with registry buildcache (`cache-from`/`cache-to`) the layer gets reused even when `latest` would have resolved to a newer pi version. **All releases v0.74.0 → v0.75.5 silently shipped the same image bytes** because of this (verified via `docker manifest inspect` — identical digests across both arches and all four tags). Fixed in v0.75.5b: workflow now derives `PI_VERSION` from `${{ github.ref_name }}` and passes it as a build-arg; smoke-test asserts the resulting `pi --version` matches via `EXPECTED_PI_VERSION` env var. Same latent bug exists in opencode-devbox's `with-pi` variants but is masked there because `OPENCODE_VERSION` bumps invalidate downstream layers — will only manifest when cutting a `vN.N.Nb`-style opencode-version-unchanged release that only bumps pi.
|
|
|
|
## Documentation drift sweep
|
|
|
|
Before committing any non-trivial change, check that prose still matches code. Drift hotspots in this repo:
|
|
|
|
- `README.md` — quick-start examples, env-var table, base-image reference (must match `FROM` in `Dockerfile`).
|
|
- `AGENTS.md` (this file) — `Key facts` block (pi binary path, `NPM_CONFIG_PREFIX`, base-image tag), smoke-test threshold number.
|
|
- `CHANGELOG.md` — promote `Unreleased` only on tag, but record post-release fixes in a fresh `Unreleased` block.
|
|
- `DOCKER_HUB.md` — hand-maintained slim Hub description; sync anything user-facing that changes (env vars, run command, base image).
|
|
- `.env.example` — hand-updated, must match Dockerfile/entrypoint env vars.
|
|
- `Dockerfile` `PI_VERSION` ARG default — if you intend to pin (rather than `latest`), bump it on release.
|
|
|
|
Quick triage: `git diff --name-only HEAD | xargs -I{} grep -l 'thing-you-changed' README.md AGENTS.md DOCKER_HUB.md CHANGELOG.md .env.example`.
|