feat: add experimental API to expose Wrangler command tree structure by devin-ai-integration[bot] · Pull Request #10242 · cloudflare/workers-sdk

devin-ai-integration · 2025-08-06T09:09:44Z

Summary

This PR adds a new experimental API experimental_getWranglerCommands() to expose Wrangler's complete command tree structure with metadata for cloudflare-docs consumption. The API leverages the existing CommandRegistry infrastructure to provide programmatic access to all registered commands, their hierarchical relationships, and associated metadata.

Link to Devin run: https://app.devin.ai/sessions/e7ce795996a34292a84d4aabe9ec9f92
Requested by: @penalosa

Key Changes

New experimental method in CommandRegistry.ts: Added experimental_getCommandsForDocs() to expose the internal command tree
New API module experimental-commands-api.ts: Contains experimental_getWranglerCommands() function that registers all Wrangler commands and returns the tree structure
Export from CLI: Added export in cli.ts following existing experimental API patterns
Comprehensive tests: Added test coverage for command tree structure, metadata validation, and nested command verification
Changeset: Added minor version bump changeset for the new feature

Important Review Areas

⚠️ Command Coverage Completeness: During implementation, several command imports had to be removed due to import errors (typesCommand, whoamiCommand, queues, r2, vectorize, hyperdrive, triggers). Please verify that all important Wrangler commands are actually included in the experimental API output.

⚠️ Manual Synchronization: The experimental API currently duplicates command definitions from index.ts, creating a maintenance burden. Consider whether this approach is sustainable or if a more automated solution is needed.

⚠️ API Design: The API recreates the command registry on each call. Verify this performance characteristic is acceptable for cloudflare-docs usage patterns.

Testing

The new API has been tested to ensure:

Returns valid command tree structure with Map-based subtrees
Includes expected commands (docs, init, dev, deploy, etc.) with proper metadata
Preserves nested command hierarchies (e.g., d1 subcommands, kv operations)
Validates metadata properties (description, status, owner)
Distinguishes between command types (commands vs namespaces)

All tests pass locally and verify the basic structure, though human verification of complete command coverage is recommended.

Tests
- Tests included
Public documentation
- Documentation not necessary because: This is an experimental API for internal tooling consumption
Wrangler V3 Backport
- Not necessary because: This is a new feature, not a bug fix, and experimental APIs don't require v3 backporting

devin-ai-integration · 2025-08-06T09:09:47Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment and CI monitoring

changeset-bot · 2025-08-06T09:09:48Z

🦋 Changeset detected

Latest commit: 7d48ad5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
wrangler	Minor
@cloudflare/vite-plugin	Major
@cloudflare/vitest-pool-workers	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2025-08-06T09:11:51Z

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@10242

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@10242

miniflare

npm i https://pkg.pr.new/miniflare@10242

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@10242

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@10242

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@10242

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@10242

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@10242

wrangler

npm i https://pkg.pr.new/wrangler@10242

commit: 7d48ad5

packages/wrangler/src/core/CommandRegistry.ts

packages/wrangler/src/experimental-commands-api.ts

packages/wrangler/src/index.ts

packages/wrangler/src/cli.ts

packages/wrangler/src/index.ts

@penalosa

- Remove unnecessary experimental_getCommandsForDocs() method from CommandRegistry - Refactor experimental API to use createCLIParser and existing registry - Eliminate command registration duplication in experimental-commands-api.ts - Use existing getDefinitionTreeRoot() method instead of duplicate implementation Addresses feedback from @penalosa on PR #10242 Co-Authored-By: smacleod@cloudflare.com <smacleod@cloudflare.com>

petebacondarwin · 2025-08-11T07:37:25Z

@penalosa - can you try to get the CI green?

- Add experimental_getCommandsForDocs() method to CommandRegistry - Create experimental_getWranglerCommands() function in new experimental-commands-api.ts - Export experimental API from cli.ts following existing patterns - Add comprehensive tests for the new experimental API - Include changeset for minor version bump This API exposes the raw command tree structure with all metadata for cloudflare-docs to consume for documentation generation. Co-Authored-By: smacleod@cloudflare.com <smacleod@cloudflare.com>

@penalosa

- Remove unnecessary experimental_getCommandsForDocs() method from CommandRegistry - Refactor experimental API to use createCLIParser and existing registry - Eliminate command registration duplication in experimental-commands-api.ts - Use existing getDefinitionTreeRoot() method instead of duplicate implementation Addresses feedback from @penalosa on PR #10242 Co-Authored-By: smacleod@cloudflare.com <smacleod@cloudflare.com>

…rors build failure - Add createCLIParser export to cli.ts to make it available to external packages - Maintain backward compatibility while exposing experimental API functionality - Fixes CI failures in format-errors package build Co-Authored-By: smacleod@cloudflare.com <smacleod@cloudflare.com>

- Replace globalRegistry variable with createCommandRegistry function - Address GitHub PR comment from penalosa about avoiding global variables - Maintain backward compatibility for createCLIParser function - All experimental API tests continue to pass Co-Authored-By: smacleod@cloudflare.com <smacleod@cloudflare.com>

- Remove createCLIParser export from cli.ts as requested - Remove duplicative createCommandRegistry function from index.ts - Modify createCLIParser to attach registry via Object.defineProperty - Update experimental API to access registry from attached property - Maintain backward compatibility for existing createCLIParser callers - All experimental API tests continue to pass Co-Authored-By: smacleod@cloudflare.com <smacleod@cloudflare.com>

…stry } Address PR feedback by modifying createCLIParser() to return an object with named properties instead of using Object.defineProperty. This provides cleaner access to both wrangler and registry while maintaining backward compatibility for all existing callers. - Update createCLIParser() to return { wrangler, registry } - Update all callers to destructure the new return type - Maintain functionality for main(), build command, and check command - Update experimental API to use new structure directly Co-Authored-By: smacleod@cloudflare.com <smacleod@cloudflare.com>

…tibility - E2E tests import from CLI module via WRANGLER_IMPORT - Adding export ensures backward compatibility while maintaining refactored signature - All experimental API tests pass locally (6/6 tests) Co-Authored-By: smacleod@cloudflare.com <smacleod@cloudflare.com>

penalosa · 2025-08-11T11:23:23Z

@petebacondarwin CI is green, so this should be ready for a review

petebacondarwin · 2025-08-11T11:55:28Z

packages/wrangler/src/__tests__/experimental-commands-api.test.ts

It might be nice to JSON stringify the tree for these tests, then you could use snapshot matchers.

holopin-bot · 2025-08-11T11:55:51Z

Congratulations @devin-ai-integration[bot], the maintainer of this repository has issued you a holobyte! Here it is: https://holopin.io/holobyte/cme723jvj080407jmfg397nh5

This badge can only be claimed by you, so make sure that your GitHub account is linked to your Holopin account. You can manage those preferences here: https://holopin.io/account.
Or if you're new to Holopin, you can simply sign up with GitHub, which will do the trick!

… matchers - Replace individual assertions with comprehensive snapshot testing - Add serializeCommandTree helper to convert Maps to plain objects - Use proper TypeScript types (unknown instead of any) - Addresses petebacondarwin's feedback on PR #10242 Co-Authored-By: smacleod@cloudflare.com <smacleod@cloudflare.com>

workers-devprod added this to workers-sdk Aug 6, 2025

github-project-automation bot moved this to Untriaged in workers-sdk Aug 6, 2025

penalosa self-assigned this Aug 6, 2025

penalosa requested changes Aug 6, 2025

View reviewed changes

packages/wrangler/src/core/CommandRegistry.ts Outdated Show resolved Hide resolved

packages/wrangler/src/experimental-commands-api.ts Outdated Show resolved Hide resolved

github-project-automation bot moved this from Untriaged to In Review in workers-sdk Aug 6, 2025

penalosa reviewed Aug 6, 2025

View reviewed changes

packages/wrangler/src/index.ts Outdated Show resolved Hide resolved

penalosa reviewed Aug 7, 2025

View reviewed changes

packages/wrangler/src/cli.ts Outdated Show resolved Hide resolved

penalosa reviewed Aug 7, 2025

View reviewed changes

packages/wrangler/src/index.ts Outdated Show resolved Hide resolved

penalosa reviewed Aug 7, 2025

View reviewed changes

packages/wrangler/src/index.ts Outdated Show resolved Hide resolved

penalosa marked this pull request as ready for review August 8, 2025 09:29

penalosa requested a review from a team as a code owner August 8, 2025 09:29

penalosa approved these changes Aug 8, 2025

View reviewed changes

github-project-automation bot moved this from In Review to Approved in workers-sdk Aug 8, 2025

penalosa added the skip-v3-pr label Aug 8, 2025

petebacondarwin force-pushed the devin/1754470383-expose-commands-experimental-api branch from 74742b3 to a7a7566 Compare August 8, 2025 17:29

devin-ai-integration bot and others added 8 commits August 11, 2025 11:13

fix exports

7d48ad5

penalosa force-pushed the devin/1754470383-expose-commands-experimental-api branch from e74f592 to 7d48ad5 Compare August 11, 2025 10:14

petebacondarwin approved these changes Aug 11, 2025

View reviewed changes

petebacondarwin merged commit 70bd966 into main Aug 11, 2025
44 of 46 checks passed

petebacondarwin deleted the devin/1754470383-expose-commands-experimental-api branch August 11, 2025 11:55

github-project-automation bot moved this from Approved to Done in workers-sdk Aug 11, 2025

workers-devprod added the contribution [Holopin] Recognizes an open-source contribution, big or small label Aug 11, 2025

workers-devprod mentioned this pull request Aug 11, 2025

Version Packages #10263

Merged

lrapoport-cf mentioned this pull request Aug 12, 2025

Update cold-wasps-tease.md #10332

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add experimental API to expose Wrangler command tree structure#10242

feat: add experimental API to expose Wrangler command tree structure#10242
petebacondarwin merged 8 commits intomainfrom
devin/1754470383-expose-commands-experimental-api

devin-ai-integration bot commented Aug 6, 2025 •

edited by penalosa

Loading

Uh oh!

devin-ai-integration bot commented Aug 6, 2025

Uh oh!

changeset-bot bot commented Aug 6, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Aug 6, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

petebacondarwin commented Aug 11, 2025

Uh oh!

penalosa commented Aug 11, 2025

Uh oh!

petebacondarwin Aug 11, 2025

Uh oh!

Uh oh!

holopin-bot bot commented Aug 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

devin-ai-integration bot commented Aug 6, 2025 • edited by penalosa Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes

Important Review Areas

Testing

Uh oh!

devin-ai-integration bot commented Aug 6, 2025

🤖 Devin AI Engineer

Uh oh!

changeset-bot bot commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

petebacondarwin commented Aug 11, 2025

Uh oh!

penalosa commented Aug 11, 2025

Uh oh!

petebacondarwin Aug 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

holopin-bot bot commented Aug 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

devin-ai-integration bot commented Aug 6, 2025 •

edited by penalosa

Loading

changeset-bot bot commented Aug 6, 2025 •

edited

Loading

pkg-pr-new bot commented Aug 6, 2025 •

edited

Loading