From fd8e4b0bde701551d813fb77ed66a92c3d2c3db6 Mon Sep 17 00:00:00 2001 From: Evan Jarrett Date: Tue, 1 Sep 2026 09:07:23 -0500 Subject: [PATCH] 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) Claude-Session: https://claude.ai/code/session_01KWoKzpgtBJ33sCyGxJGR7x --- CLAUDE.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 049cb28..7798730 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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