feat(wrangler/cli): add @bomb.sh/tab completions

.changeset/rude-cows-cheat.md

@@ -0,0 +1,21 @@
+---
+"wrangler": minor
+---
+
+Add `wrangler complete` command for shell completion scripts (bash, zsh, powershell)
+
+Usage:
+
+```bash
+# Bash
+wrangler complete bash >> ~/.bashrc
+
+# Zsh
+wrangler complete zsh >> ~/.zshrc
+
+# PowerShell
+wrangler complete powershell > $PROFILE
+```
+
+- Uses `@bomb.sh/tab` library for cross-shell compatibility
+- Completions are dynamically generated from `experimental_getWranglerCommands()` API

packages/wrangler/package.json

@@ -77,6 +77,7 @@
 	},
 	"devDependencies": {
 		"@aws-sdk/client-s3": "^3.721.0",
+		"@bomb.sh/tab": "^0.0.11",
 		"@cloudflare/cli": "workspace:*",
 		"@cloudflare/containers-shared": "workspace:*",
 		"@cloudflare/eslint-config-shared": "workspace:*",

packages/wrangler/src/__tests__/complete.test.ts

@@ -0,0 +1,204 @@
+import { execSync } from "node:child_process";
+import { describe, test } from "vitest";
+import { mockConsoleMethods } from "./helpers/mock-console";
+import { runInTempDir } from "./helpers/run-in-tmp";
+import { runWrangler } from "./helpers/run-wrangler";
+
+function shellAvailable(shell: string): boolean {
+	try {
+		execSync(`which ${shell}`, { stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+describe("wrangler", () => {
+	describe("complete", () => {
+		const std = mockConsoleMethods();
+		runInTempDir();
+
+		describe("complete --", () => {
+			test("should return top-level commands", async ({ expect }) => {
+				await runWrangler('complete -- ""');
+
+				expect(std.out).toContain("deploy\t");
+				expect(std.out).toContain("dev\t");
+				expect(std.out).toContain("kv\t");
+			});
+
+			test("should return subcommands for namespace", async ({ expect }) => {
+				await runWrangler('complete -- kv ""');
+
+				expect(std.out).toContain("namespace\t");
+				expect(std.out).toContain("key\t");
+			});
+
+			test("should return flags for a command", async ({ expect }) => {
+				await runWrangler("complete -- dev --");
+
+				expect(std.out).toContain("--port\t");
+				expect(std.out).toContain("--ip\t");
+			});
+
+			test("should not include internal commands", async ({ expect }) => {
+				await runWrangler('complete -- ""');
+
+				expect(std.out).toContain("deploy\t");
+				expect(std.out).toContain("dev\t");
+				// Internal commands like "_dev" should not be exposed
+				expect(std.out).not.toMatch(/^_dev\t/m);
+			});
+
+			test("should handle deeply nested commands", async ({ expect }) => {
+				await runWrangler('complete -- queues consumer http ""');
+
+				expect(std.out).toContain("add\t");
+				expect(std.out).toContain("remove\t");
+			});
+
+			test("should output tab-separated format", async ({ expect }) => {
+				await runWrangler('complete -- ""');
+
+				// Most lines should be "value\tdescription" format
+				const lines = std.out.trim().split("\n");
+				let tabSeparatedCount = 0;
+				for (const line of lines) {
+					if (line.trim() && !line.startsWith(":")) {
+						if (line.includes("\t")) {
+							tabSeparatedCount++;
+						}
+					}
+				}
+				// Most commands should have descriptions
+				expect(tabSeparatedCount).toBeGreaterThan(10);
+			});
+
+			test("should return options with choices", async ({ expect }) => {
+				await runWrangler('complete -- dev --log-level=""');
+
+				expect(std.out).toContain("debug\t");
+				expect(std.out).toContain("info\t");
+				expect(std.out).toContain("warn\t");
+				expect(std.out).toContain("error\t");
+			});
+		});
+
+		const shells = ["bash", "zsh", "fish"] as const;
+
+		describe.each(shells)("%s", (shell) => {
+			test("should output valid shell script", async ({ expect }) => {
+				await runWrangler(`complete ${shell}`);
+
+				expect(std.out.length).toBeGreaterThan(100);
+			});
+
+			test("should reference wrangler complete", async ({ expect }) => {
+				await runWrangler(`complete ${shell}`);
+
+				expect(std.out).toContain("wrangler complete --");
+			});
+		});
+
+		describe("bash", () => {
+			test.skipIf(!shellAvailable("bash"))(
+				"should generate valid bash syntax",
+				async ({ expect }) => {
+					await runWrangler("complete bash");
+
+					// bash -n checks syntax without executing
+					expect(() => {
+						execSync("bash -n", { input: std.out });
+					}).not.toThrow();
+				}
+			);
+
+			test("should define __wrangler_complete function", async ({ expect }) => {
+				await runWrangler("complete bash");
+
+				expect(std.out).toContain("__wrangler_complete()");
+			});
+
+			test("should register completion with complete builtin", async ({
+				expect,
+			}) => {
+				await runWrangler("complete bash");
+
+				expect(std.out).toContain("complete -F __wrangler_complete wrangler");
+			});
+		});
+
+		describe("zsh", () => {
+			test.skipIf(!shellAvailable("zsh"))(
+				"should generate valid zsh syntax",
+				async ({ expect }) => {
+					await runWrangler("complete zsh");
+
+					// zsh -n checks syntax without executing
+					expect(() => {
+						execSync("zsh -n", { input: std.out });
+					}).not.toThrow();
+				}
+			);
+
+			test("should start with #compdef directive", async ({ expect }) => {
+				await runWrangler("complete zsh");
+
+				expect(std.out).toContain("#compdef wrangler");
+			});
+
+			test("should define _wrangler function", async ({ expect }) => {
+				await runWrangler("complete zsh");
+
+				expect(std.out).toContain("_wrangler()");
+			});
+
+			test("should register with compdef", async ({ expect }) => {
+				await runWrangler("complete zsh");
+
+				expect(std.out).toContain("compdef _wrangler wrangler");
+			});
+		});
+
+		describe("fish", () => {
+			test.skipIf(!shellAvailable("fish"))(
+				"should generate valid fish syntax",
+				async ({ expect }) => {
+					await runWrangler("complete fish");
+
+					// fish -n checks syntax without executing
+					expect(() => {
+						execSync("fish -n", { input: std.out });
+					}).not.toThrow();
+				}
+			);
+
+			test("should define __wrangler_perform_completion function", async ({
+				expect,
+			}) => {
+				await runWrangler("complete fish");
+
+				expect(std.out).toContain("function __wrangler_perform_completion");
+			});
+
+			test("should register completion with complete builtin", async ({
+				expect,
+			}) => {
+				await runWrangler("complete fish");
+
+				expect(std.out).toContain("complete -c wrangler");
+			});
+
+			test("should use commandline for token extraction", async ({
+				expect,
+			}) => {
+				await runWrangler("complete fish");
+
+				// commandline -opc gets completed tokens
+				expect(std.out).toContain("commandline -opc");
+				// commandline -ct gets current token being typed
+				expect(std.out).toContain("commandline -ct");
+			});
+		});
+	});
+});

packages/wrangler/src/complete.ts

@@ -0,0 +1,117 @@
+import t from "@bomb.sh/tab";
+import { experimental_getWranglerCommands } from "./experimental-commands-api";
+import type { DefinitionTreeNode } from "./core/types";
+
+function setupCompletions() {
+	const { registry, globalFlags } = experimental_getWranglerCommands();
+
+	// global flags that work on every command
+	for (const [flagName, flagDef] of Object.entries(globalFlags)) {
+		// skip hidden flags
+		if ("hidden" in flagDef && flagDef.hidden) continue;
+
+		const description = flagDef.describe || "";
+		t.option(flagName, description);
+
+		if ("alias" in flagDef && flagDef.alias) {
+			const aliases = Array.isArray(flagDef.alias)
+				? flagDef.alias
+				: [flagDef.alias];
+			for (const alias of aliases) {
+				t.option(alias, `Alias for --${flagName}`);
+			}
+		}
+	}
+
+	// recursively add commands from the registry tree
+	function addCommandsFromTree(
+		node: DefinitionTreeNode,
+		parentPath: string[] = []
+	) {
+		for (const [name, childNode] of node.subtree.entries()) {
+			const commandPath = [...parentPath, name];
+			const commandName = commandPath.join(" ");
+
+			if (childNode.definition) {
+				const def = childNode.definition;
+				let description = "";
+
+				if (def.metadata?.description) {
+					description = def.metadata.description;
+				}
+
+				if (
+					def.metadata?.status &&
+					def.metadata.status !== "stable" &&
+					!def.metadata.hidden
+				) {
+					const statusLabels = {
+						experimental: "[experimental]",
+						alpha: "[alpha]",
+						"private-beta": "[private-beta]",
+						"open-beta": "[open-beta]",
+					};
+					const statusLabel =
+						statusLabels[def.metadata.status as keyof typeof statusLabels];
+					if (statusLabel) {
+						description = `${description} ${statusLabel}`;
+					}
+				}
+
+				if (!def.metadata?.hidden) {
+					const cmd = t.command(commandName, description);
+
+					if (def.type === "command" && "args" in def) {
+						const args = def.args || {};
+						for (const [argName, argDef] of Object.entries(args)) {
+							if (argDef.hidden) continue;
+
+							const argDescription = argDef.describe || "";
+
+							if (argDef.choices && Array.isArray(argDef.choices)) {
+								cmd.option(argName, argDescription, (complete) => {
+									for (const choice of argDef.choices as string[]) {
+										complete(choice, choice);
+									}
+								});
+							} else {
+								cmd.option(argName, argDescription);
+							}
+
+							if (argDef.alias) {
+								const aliases = Array.isArray(argDef.alias)
+									? argDef.alias
+									: [argDef.alias];
+								for (const alias of aliases) {
+									cmd.option(alias, `Alias for --${argName}`);
+								}
+							}
+						}
+					}
+				}
+			}
+
+			if (childNode.subtree.size > 0) {
+				addCommandsFromTree(childNode, commandPath);
+			}
+		}
+	}
+
+	addCommandsFromTree(registry);
+
+	return t;
+}
+// Handle completion requests from the shell
+export function handleCompletion(args: string[]) {
+	const shell = args[0];
+
+	if (shell === "--") {
+		// Parse completion request from shell
+		setupCompletions();
+		t.parse(args.slice(1));
+	} else {
+		// Generate shell completion script
+		setupCompletions();
+		t.setup("wrangler", "wrangler", shell);
+	}
+}

packages/wrangler/src/index.ts

@@ -26,6 +26,7 @@ import {
 } from "./cert/cert";
 import { checkNamespace, checkStartupCommand } from "./check/commands";
 import { cloudchamber } from "./cloudchamber";
+import { handleCompletion } from "./complete";
 import { getDefaultEnvFiles, loadDotEnv } from "./config/dot-env";
 import { containers } from "./containers";
 import { demandSingleValue } from "./core";
@@ -1730,6 +1731,12 @@ export function createCLIParser(argv: string[]) {
 export async function main(argv: string[]): Promise<void> {
 	setupSentry();
 
+	// Handle shell completion requests
+	if (argv[0] === "complete") {
+		handleCompletion(argv.slice(1));
+		return;
+	}
+
 	checkMacOSVersion({ shouldThrow: false });
 
 	const startTime = Date.now();