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

* feat: add experimental API to expose Wrangler command tree structure

- 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: [email protected] <[email protected]>

* refactor: address PR comments by removing duplication

- 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: [email protected] <[email protected]>

* fix: export createCLIParser from CLI entry point to resolve format-errors 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: [email protected] <[email protected]>

* refactor: remove global variables from experimental API

- 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: [email protected] <[email protected]>

* refactor: address PR feedback by removing code duplication

- 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: [email protected] <[email protected]>

* refactor: change createCLIParser signature to return { wrangler, registry }

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: [email protected] <[email protected]>

* fix: add createCLIParser export back to CLI module for E2E test compatibility

- 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: [email protected] <[email protected]>

* fix exports

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: [email protected] <[email protected]>

Author: devin-ai-integration[bot]

.changeset/cold-wasps-tease.md

@@ -0,0 +1,5 @@
+---
+"wrangler": minor
+---
+
+Add experimental API to expose Wrangler command tree structure for documentation generation

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

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "vitest";
+import { experimental_getWranglerCommands } from "../experimental-commands-api";
+
+describe("experimental_getWranglerCommands", () => {
+	test("returns command tree structure", () => {
+		const commandTree = experimental_getWranglerCommands();
+
+		expect(commandTree).toBeDefined();
+		expect(commandTree.subtree).toBeInstanceOf(Map);
+	});
+
+	test("includes expected commands with metadata", () => {
+		const commandTree = experimental_getWranglerCommands();
+
+		expect(commandTree.subtree.has("docs")).toBe(true);
+		expect(commandTree.subtree.has("init")).toBe(true);
+		expect(commandTree.subtree.has("dev")).toBe(true);
+		expect(commandTree.subtree.has("deploy")).toBe(true);
+
+		const docsCommand = commandTree.subtree.get("docs");
+		expect(docsCommand?.definition?.metadata).toBeDefined();
+		expect(docsCommand?.definition?.metadata?.description).toBeDefined();
+		expect(docsCommand?.definition?.metadata?.status).toBeDefined();
+	});
+
+	test("includes nested commands", () => {
+		const commandTree = experimental_getWranglerCommands();
+
+		const d1Command = commandTree.subtree.get("d1");
+		expect(d1Command?.subtree).toBeInstanceOf(Map);
+		expect(d1Command?.subtree.has("list")).toBe(true);
+		expect(d1Command?.subtree.has("create")).toBe(true);
+		expect(d1Command?.subtree.has("delete")).toBe(true);
+	});
+
+	test("includes command arguments and metadata", () => {
+		const commandTree = experimental_getWranglerCommands();
+
+		const initCommand = commandTree.subtree.get("init");
+		expect(initCommand?.definition?.type).toBe("command");
+		if (initCommand?.definition?.type === "command") {
+			expect(initCommand.definition.metadata).toBeDefined();
+			expect(initCommand.definition.metadata.description).toBeDefined();
+			expect(initCommand.definition.metadata.status).toBeDefined();
+			expect(initCommand.definition.metadata.owner).toBeDefined();
+		}
+	});
+
+	test("includes namespace commands", () => {
+		const commandTree = experimental_getWranglerCommands();
+
+		const kvCommand = commandTree.subtree.get("kv");
+		expect(kvCommand?.definition?.type).toBe("namespace");
+		expect(kvCommand?.subtree).toBeInstanceOf(Map);
+		expect(kvCommand?.subtree.has("namespace")).toBe(true);
+		expect(kvCommand?.subtree.has("key")).toBe(true);
+	});
+
+	test("preserves command metadata properties", () => {
+		const commandTree = experimental_getWranglerCommands();
+
+		const deployCommand = commandTree.subtree.get("deploy");
+		if (deployCommand?.definition?.type === "command") {
+			const metadata = deployCommand.definition.metadata;
+			expect(metadata.description).toBeDefined();
+			expect(metadata.status).toBeDefined();
+			expect(metadata.owner).toBeDefined();
+			expect(typeof metadata.description).toBe("string");
+			expect([
+				"experimental",
+				"alpha",
+				"private-beta",
+				"open-beta",
+				"stable",
+			]).toContain(metadata.status);
+		}
+	});
+});

packages/wrangler/src/build/index.ts

@@ -13,12 +13,13 @@ export const buildCommand = createCommand({
 		provideConfig: false,
 	},
 	async handler(buildArgs) {
-		await createCLIParser([
+		const { wrangler } = createCLIParser([
 			"deploy",
 			"--dry-run",
 			"--outdir=dist",
 			...(buildArgs.env ? ["--env", buildArgs.env] : []),
 			...(buildArgs.config ? ["--config", buildArgs.config] : []),
-		]).parse();
+		]);
+		await wrangler.parse();
 	},
 });

packages/wrangler/src/check/commands.ts

@@ -57,8 +57,8 @@ async function checkStartupHandler(
 		}
 
 		await spinnerWhile({
-			promise: async () =>
-				await createCLIParser(
+			promise: async () => {
+				const { wrangler } = createCLIParser(
 					config.pages_build_output_dir || pages
 						? [
 								"pages",
@@ -73,7 +73,9 @@ async function checkStartupHandler(
 								"--dry-run",
 								`--outfile=${workerBundle}`,
 							]
-				).parse(),
+				);
+				await wrangler.parse();
+			},
 			startMessage: "Building your Worker",
 			endMessage: chalk.green("Worker Built! 🎉"),
 		});

packages/wrangler/src/cli.ts

@@ -73,3 +73,5 @@ export {
 	type RemoteProxySession as Experimental_RemoteProxySession,
 	convertConfigBindingsToStartWorkerBindings as unstable_convertConfigBindingsToStartWorkerBindings,
 } from "./api";
+
+export { experimental_getWranglerCommands } from "./experimental-commands-api";

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

@@ -0,0 +1,13 @@
+import { createCLIParser } from "./index";
+import type { DefinitionTreeNode } from "./core/types";
+
+/**
+ * EXPERIMENTAL: Get all registered Wrangler commands for documentation generation.
+ * This API is experimental and may change without notice.
+ *
+ * @returns The complete command tree structure with all metadata
+ */
+export function experimental_getWranglerCommands(): DefinitionTreeNode {
+	const { registry } = createCLIParser([]);
+	return registry.getDefinitionTreeRoot();
+}

packages/wrangler/src/index.ts

@@ -1483,7 +1483,7 @@ export function createCLIParser(argv: string[]) {
 
 	wrangler.exitProcess(false);
 
-	return wrangler;
+	return { wrangler, registry };
 }
 
 export async function main(argv: string[]): Promise<void> {
@@ -1492,7 +1492,7 @@ export async function main(argv: string[]): Promise<void> {
 	checkMacOSVersion({ shouldThrow: false });
 
 	const startTime = Date.now();
-	const wrangler = createCLIParser(argv);
+	const { wrangler } = createCLIParser(argv);
 	let command: string | undefined;
 	let metricsArgs: Record<string, unknown> | undefined;
 	let dispatcher: ReturnType<typeof getMetricsDispatcher> | undefined;
@@ -1567,7 +1567,8 @@ export async function main(argv: string[]): Promise<void> {
 			// We are not able to ask the `wrangler` CLI parser to show help for a subcommand programmatically.
 			// The workaround is to re-run the parsing with an additional `--help` flag, which will result in the correct help message being displayed.
 			// The `wrangler` object is "frozen"; we cannot reuse that with different args, so we must create a new CLI parser to generate the help message.
-			await createCLIParser([...argv, "--help"]).parse();
+			const { wrangler: helpWrangler } = createCLIParser([...argv, "--help"]);
+			await helpWrangler.parse();
 		} else if (
 			isAuthenticationError(e) ||
 			// Is this a Containers/Cloudchamber-based auth error?