cloudflare / cloudflare/workers-oauth-provider

feat: codemod CLI for migrating single-Worker AS + RS deployments to 1.0

Open
#310 0 comments 0 reactions 0 assignees View on GitHub
enhancement v1
Dominant language
TypeScript
Stars
1.9k
Forks
134
PR merge metrics
No merged PRs in 30d

Description

## Summary

Provide a CLI that automatically migrates the common deployment shape, one Worker acting as both authorization server and resource server through `OAuthProvider`, from 0.x to 1.0. Users on this shape should be able to run one command and get a working config, with the remaining manual decisions printed clearly.

## Scope

Target only the single-Worker `OAuthProvider` shape. Multi-resource and split AS/RS deployments are new 1.0 topologies with design decisions the tool cannot make; the migration guide and the agent skill cover those.

## Transforms

Based on the breaking changes in #289 and #210:

- Add `resourceMetadata: { resource: '' }` when missing. Infer from an existing `apiRoute` plus a `wrangler` route or custom domain when possible; otherwise insert a placeholder and report it.
- Remove `resourceMatchOriginOnly` and explain the replacement.
- Rewrite `resolveExternalToken` return sites that omit `audience`, or flag them when the value cannot be inferred.
- Update `OAuthProvider` option renames or removals introduced by #289 and #292.
- Flag DCR clients registered with a narrow `grant_types` set that will now be enforced (#210), since that is data, not code.
- Bump the dependency in `package.json`.

## Design

- Invocation: `npx @cloudflare/workers-oauth-provider migrate` or a separate `@cloudflare/workers-oauth-provider-codemod` package. Decide based on whether we want the codemod's dependencies in the runtime package.
- AST based, TypeScript and JavaScript, using `ts-morph` or `jscodeshift`.
- Dry-run by default with a diff, `--write` to apply.
- Exit non-zero with a list of items that need a human, so the agent skill can read them.
- Idempotent: running twice makes no further changes.

## Tests

- Fixture Workers for each 0.x config pattern in the README and `docs/advanced-configuration.md`, with expected output.
- A fixture for a Hono-based Worker, since that is what the 1.0 README example uses.

## Related

- Migration guide issue: defines the transforms.
- Agent skill issue: invokes this tool.

Contributor guide

Open the contributing guide

Research direction

Start by reading the breaking changes in #289, #210, and #292, then inventory the 0.x configuration patterns in README and docs/advanced-configuration.md. Use package.json to assess the package boundary and define fixture coverage, including the Hono example. Done means a dry-run diff, optional --write, idempotent output, and non-zero reporting for unresolved human decisions, with expected fixture results.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, nodejs, typescript
Domain
cli, developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.