Register the stack's API token as a build token when the account has none (0.3.1)

[nicu-chiciuc]

Summary

WorkersBuilds.Repository no longer needs a manual step in the Cloudflare dashboard on an account without a build token. Version 0.3.1.

• Before: without buildToken, a new configuration used the account's first build token. With no build token on the account, the deploy failed and told you to connect a Worker to Git once in the dashboard, because the dashboard creates a build token.
• Now: in that case the provider registers the stack's own API token as a build token. It reads the token id from GET /user/tokens/verify (distilled user.verifyToken), then calls POST /accounts/{account_id}/builds/tokens (distilled workersBuilds.createToken) with build_token_name: alchemy-<stack name> (Alchemy's StackName), build_token_secret, and cloudflare_token_id.
• Order for a new configuration (resolveBuildToken): buildToken, then the account's first build token, then the registration. An existing configuration keeps its token, as before.
• Credentials: the secret comes from the stack's distilled Credentials. Only type: "apiToken" can register. OAuth and global API key credentials keep the clear WorkersBuildsError, because Workers Builds accepts only API tokens. The create request is marked as holding the secret and is never logged.
• Destroy keeps the registered build token: build tokens belong to the account, and other configurations can use them.
• Permissions: POST .../builds/tokens is in the same OpenAPI token group (Workers CI Write) as the PATCH .../builds/workers call that already works with Workers Builds Configuration: Edit, so registration needs no new permission. The README now says the token also needs the permissions of the deploy: Workers Scripts: Edit, and R2, KV, D1 edit when the Wrangler file binds them.

What the unit tests prove

test/Repository.test.ts, resolveBuildToken, against a served HTTP client and payloads from Cloudflare's OpenAPI schema (user_tokens_verify.json, builds_tokens_create.json):

• buildToken wins and makes no call.
• An existing build token wins next: one list call, no registration.
• No build token: list, verify, create, in this order. The create body has exactly build_token_name: "alchemy-MyApp", cloudflare_token_id from the verify response, and build_token_secret, which the test checks only by presence, so a failure never prints it.
• OAuth credentials: WorkersBuildsError (operation register build token), only the list call, no token in the message.
• A create result without build_token_uuid fails with WorkersBuildsError.

pnpm run check: 79 passed, 3 skipped (the live tests, unchanged and pending). pnpm run build passes.

Open points

• No live run has registered a build token yet. The payloads come from the API schema; replace them with recordings after the first live registration.
• GET /user/tokens/verify is for user tokens. An account-owned token probably fails there (not tested): with HTTP 401 or 403 it becomes WorkersBuildsPermissionError, else WorkersBuildsError. The README already says Workers Builds needs a user-scoped token.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}