docs: correct stale credential-helper and workspace layout in CLAUDE.md

The documented build command `go build -o bin/docker-credential-atcr
./cmd/credential-helper` has not worked since the helper was split into
per-brand modules: that path holds no Go files, so the command fails with
"no Go files in .../cmd/credential-helper".

Point it at cmd/credential-helper/atcr, grouped with the scanner under a
"separate modules" heading since both need the cd-and-build form, and note
that `make build-credential-helper` is the same build with version/commit
ldflags stamped.

The workspace section claimed two modules; there are five. The two
credential helpers and deploy/upcloud were missing, and the main module no
longer contains the credential helper. Added why the helpers are split out
at all: `go install atcr.io/cmd/credential-helper/atcr@latest` has to
resolve without the main module's dependency tree, which is what the
`require atcr.io vX.Y.Z` pin in each is for.

Both documented commands verified against the current tree.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KWoKzpgtBJ33sCyGxJGR7x
This commit is contained in:
Evan Jarrett
2026-09-01 09:07:23 -05:00
co-authored by Claude Opus 5
parent 15871ad188
commit fd8e4b0bde
+15 -5
View File
@@ -8,9 +8,18 @@ ATCR (ATProto Container Registry) is an OCI-compliant container registry that us
## Go Workspace
The project uses a Go workspace (`go.work`) with two modules:
- `atcr.io` — Main module (appview, hold, credential-helper, oauth-helper)
The project uses a Go workspace (`go.work`) with five modules:
- `atcr.io` — Main module (appview, hold, oauth-helper)
- `atcr.io/scanner` — Scanner module (separate to isolate heavy Syft/Grype dependencies)
- `atcr.io/cmd/credential-helper/atcr` — Credential helper, atcr brand
- `seamark.dev/cmd/credential-helper/seamark` — Credential helper, seamark brand
- `atcr.io/deploy` — UpCloud deployment tooling
The credential helpers are separate modules so that `go install
atcr.io/cmd/credential-helper/atcr@latest` resolves standalone without dragging
in the main module's dependency tree. Each pins `require atcr.io vX.Y.Z` for
that standalone path; the workspace overrides it during local development. Bump
that pin when cutting a credhelper release.
## Build Commands
@@ -20,11 +29,12 @@ Always build into the `bin/` directory (`-o bin/...`), not the project root.
# Build main binaries
go build -o bin/atcr-appview ./cmd/appview
go build -o bin/atcr-hold ./cmd/hold
go build -o bin/docker-credential-atcr ./cmd/credential-helper
go build -o bin/oauth-helper ./cmd/oauth-helper
# Build scanner (separate module)
# Build separate modules (scanner, credential helper)
cd scanner && go build -o ../bin/atcr-scanner ./cmd/scanner && cd ..
cd cmd/credential-helper/atcr && go build -o ../../../bin/docker-credential-atcr . && cd ../../..
# `make build-credential-helper` does the same and stamps version/commit ldflags.
# Build appview with billing support (optional build tag; billing lives in pkg/billing/, appview-side only)
go build -tags billing -o bin/atcr-appview ./cmd/appview
@@ -74,7 +84,7 @@ ATCR uses **distribution/distribution** as a library, extending it via middlewar
1. **AppView** (`cmd/appview`) — OCI Distribution API server. Resolves identities, routes manifests to PDS, routes blobs to hold service, validates OAuth, issues registry JWTs. Includes web UI for browsing.
2. **Hold Service** (`cmd/hold`) — BYOS blob storage. Embedded PDS with captain/crew/stats/scan records (all ATProto records in CAR store), S3-compatible storage, presigned URLs. Supports did:web (default) or did:plc identity with auto-recovery. Optional subsystems: admin UI, quotas, GC, scan dispatch, Bluesky status posts.
3. **Scanner** (`scanner/cmd/scanner`) — Vulnerability scanning. Connects to hold via WebSocket, generates SBOMs (Syft), scans vulnerabilities (Grype). Priority queue with tier-based scheduling.
4. **Credential Helper** (`cmd/credential-helper`) — Docker credential helper implementing ATProto OAuth flow, exchanges OAuth token for registry JWT.
4. **Credential Helper** (`cmd/credential-helper/atcr`) — Docker credential helper implementing ATProto OAuth flow, exchanges OAuth token for registry JWT.
### Request Flow Summary