wrangler 2.6.1 → 2.7.0

package/src/generate/index.ts

@@ -0,0 +1,300 @@
+import fs from "node:fs";
+import path from "node:path";
+import { cloneIntoDirectory, initializeGit } from "../git-client";
+import { CommandLineArgsError, printWranglerBanner } from "../index";
+import { initHandler } from "../init";
+import { logger } from "../logger";
+import type {
+	CommonYargsOptions,
+	YargsOptionsToInterface,
+} from "../yargs-types";
+import type { Argv } from "yargs";
+
+export function generateOptions(yargs: Argv<CommonYargsOptions>) {
+	return yargs
+		.positional("name", {
+			describe: "Name of the Workers project",
+			type: "string",
+			demandOption: true,
+		})
+		.positional("template", {
+			type: "string",
+			describe: "The URL of a GitHub template",
+		})
+		.option("type", {
+			alias: "t",
+			type: "string",
+			hidden: true,
+			deprecated: true,
+		})
+		.option("site", {
+			alias: "s",
+			type: "boolean",
+			hidden: true,
+			deprecated: true,
+		});
+}
+type GenerateArgs = YargsOptionsToInterface<typeof generateOptions>;
+
+// Originally, generate was a rust function: https://github.com/cloudflare/wrangler/blob/master/src/cli/mod.rs#L106-L123
+export async function generateHandler(args: GenerateArgs) {
+	// somehow, `init` marks name as required but then also runs fine
+	// with the name omitted, and then substitutes it at runtime with ""
+	// delegate to `wrangler init` if no template is specified
+	if (args.template === undefined) {
+		return initHandler({
+			name: args.name,
+			template: undefined,
+			site: undefined,
+			yes: undefined,
+			fromDash: undefined,
+			"from-dash": undefined,
+			v: undefined,
+			config: undefined,
+			env: undefined,
+			type: undefined,
+			_: args._,
+			$0: args.$0,
+		});
+	}
+
+	// print down here cuz `init` prints it own its own
+	await printWranglerBanner();
+
+	if (args.type) {
+		let message = "The --type option is no longer supported.";
+		if (args.type === "webpack") {
+			message +=
+				"\nIf you wish to use webpack then you will need to create a custom build.";
+			// TODO: Add a link to docs
+		}
+		throw new CommandLineArgsError(message);
+	}
+
+	if (args.name && isRemote(args.name)) {
+		[args.template, args.name] = [args.name, args.template];
+	}
+
+	const creationDirectory = generateWorkerDirectoryName(args.name);
+
+	if (args.site) {
+		const gitDirectory =
+			creationDirectory !== process.cwd()
+				? path.basename(creationDirectory)
+				: "my-site";
+		const message =
+			"The --site option is no longer supported.\n" +
+			"If you wish to create a brand new Worker Sites project then clone the `worker-sites-template` starter repository:\n\n" +
+			"```\n" +
+			`git clone --depth=1 --branch=wrangler2 https://github.com/cloudflare/worker-sites-template ${gitDirectory}\n` +
+			`cd ${gitDirectory}\n` +
+			"```\n\n" +
+			"Find out more about how to create and maintain Sites projects at https://developers.cloudflare.com/workers/platform/sites.\n" +
+			"Have you considered using Cloudflare Pages instead? See https://pages.cloudflare.com/.";
+		throw new CommandLineArgsError(message);
+	}
+
+	logger.log(
+		`Creating a worker in ${path.basename(creationDirectory)} from ${
+			args.template
+		}`
+	);
+
+	const { remote, subdirectory } = parseTemplatePath(args.template);
+
+	await cloneIntoDirectory(remote, creationDirectory, subdirectory);
+	await initializeGit(creationDirectory);
+
+	logger.log("✨ Success!");
+}
+
+/**
+ * Creates a path based on the current working directory and a worker name.
+ * Automatically increments a counter when searching for an available directory.
+ *
+ * Running `wrangler generate worker https://some-git-repo` in a directory
+ * with the structure:
+ * ```
+ * - workers
+ * |
+ * | - worker
+ * | | - wrangler.toml
+ * | | ...
+ * |
+ * | - worker-1
+ * | | - wrangler.toml
+ * | | ...
+ * ```
+ *
+ * will result in a new worker called `worker-2` being generated.
+ *
+ * @param workerName the name of the generated worker
+ * @returns an absolute path to the directory to generate the worker into
+ */
+function generateWorkerDirectoryName(workerName: string): string {
+	let workerDirectoryPath = path.resolve(process.cwd(), workerName);
+	let i = 1;
+
+	while (fs.existsSync(workerDirectoryPath)) {
+		workerDirectoryPath = path.resolve(process.cwd(), `${workerName}-${i}`);
+		i++;
+	}
+
+	return workerDirectoryPath;
+}
+
+/**
+ * Checks if an arg is a template, which can be useful if the order
+ * of template & worker name args is switched
+ *
+ * @param arg a template to generate from, or a folder to generate into
+ * @returns true if the given arg was remote (a template)
+ */
+function isRemote(arg: string) {
+	return /^(https?|ftps?|file|git|ssh):\/\//.test(arg) || arg.includes(":");
+}
+
+/**
+ * unreadable regex basically copied from degit. i put some named capture groups in,
+ * but uhh...there's not much to do short of using pomsky or some other tool.
+ *
+ * notably: this only supports `https://` and `git@` urls,
+ * and is missing support for:
+ * - `http`
+ * - `ftp(s)`
+ * - `file`
+ * - `ssh`
+ */
+const TEMPLATE_REGEX =
+	/^(?:(?:https:\/\/)?(?<httpsUrl>[^:/]+\.[^:/]+)\/|git@(?<gitUrl>[^:/]+)[:/]|(?<shorthandUrl>[^/]+):)?(?<user>[^/\s]+)\/(?<repository>[^/\s#]+)(?:(?<subdirectoryPath>(?:\/[^/\s#]+)+))?(?:\/)?(?:#(?<tag>.+))?/;
+
+// there are a few URL formats we support:
+// - `user/repo` -> assume github, use "https://github.com/user/repo.git"
+// - `https://<httpsUrl>
+// - `git@<gitUrl>`
+// - `(bb|bitbucket|gh|github|gl|gitlab):user/repo` -> parse shorthand into https url
+
+/**
+ * There's no URL, so assume a github repo
+ */
+type NoUrl = {
+	httpsUrl: undefined;
+	gitUrl: undefined;
+	shorthandUrl: undefined;
+};
+
+/**
+ * A https url (e.g. https://bitbucket.org/user/repo)
+ */
+type HttpsUrl = Omit<NoUrl, "httpsUrl"> & { httpsUrl: string };
+
+/**
+ * A git url (e.g. git@gitlab.com:user/repo)
+ */
+type GitUrl = Omit<NoUrl, "gitUrl"> & { gitUrl: string };
+
+/**
+ * A shorthand url (e.g. github:user/repo)
+ */
+type ShorthandUrl = Omit<NoUrl, "shorthandUrl"> & { shorthandUrl: string };
+
+/**
+ * Union of all possible URL groups. Exactly one will be present, the rest
+ * will be `undefined`.
+ */
+type TemplateRegexUrlGroup = NoUrl | HttpsUrl | GitUrl | ShorthandUrl;
+
+/**
+ * Possible matches of `TEMPLATE_REGEX` against a passed-in template arg
+ */
+type TemplateRegexGroups = {
+	/** The user the repo is under */
+	user: string;
+
+	/** The repo name */
+	repository: string;
+
+	/** Optional, path to subdirectory containing template. Begins with `/` */
+	subdirectoryPath?: string;
+
+	/** Optional tag (or branch, etc.) to clone */
+	tag?: string;
+} & TemplateRegexUrlGroup;
+
+/**
+ * Parses a regex match on any of the URL groups into a URL base
+ *
+ * @param urlGroup a regex hit for a URL of any sort
+ * @returns the protocol and domain name of the url to clone from
+ */
+function toUrlBase({ httpsUrl, gitUrl, shorthandUrl }: TemplateRegexUrlGroup) {
+	if (httpsUrl !== undefined) {
+		return `https://${httpsUrl}`;
+	}
+
+	if (gitUrl !== undefined) {
+		return `git@${gitUrl}`;
+	}
+
+	if (shorthandUrl !== undefined) {
+		switch (shorthandUrl) {
+			case "github":
+			case "gh":
+				return "https://github.com";
+			case "gitlab":
+			case "gl":
+				return "https://gitlab.com";
+			case "bitbucket":
+			case "bb":
+				return "https://bitbucket.org";
+			default:
+				throw new Error(
+					`Unable to parse shorthand ${shorthandUrl}. Supported options are "bitbucket" ("bb"), "github" ("gh"), and "gitlab" ("gl")`
+				);
+		}
+	}
+
+	return "https://github.com";
+}
+
+/**
+ * Parses a template string (e.g. "user/repo", "github:user/repo/path/to/subdirectory")
+ * into a remote URL to clone from and an optional subdirectory to filter for
+ *
+ * @param templatePath the template string to parse
+ * @returns an object containing the remote url and an optional subdirectory to clone
+ */
+function parseTemplatePath(templatePath: string): {
+	remote: string;
+	subdirectory?: string;
+} {
+	if (!templatePath.includes("/")) {
+		// template is a cloudflare canonical template, it doesn't include a slash in the name
+		return {
+			remote: "https://github.com/cloudflare/templates.git",
+			subdirectory: templatePath,
+		};
+	}
+
+	const groups = TEMPLATE_REGEX.exec(templatePath)?.groups as unknown as
+		| TemplateRegexGroups
+		| undefined;
+
+	if (!groups) {
+		throw new Error(`Unable to parse ${templatePath} as a template`);
+	}
+
+	const { user, repository, subdirectoryPath, tag, ...urlGroups } = groups;
+
+	const urlBase = toUrlBase(urlGroups);
+	const isHttp = urlBase.startsWith("http");
+
+	const remote = `${urlBase}${isHttp ? "/" : ":"}${user}/${repository}.git${
+		tag ? `#${tag}` : ""
+	}`;
+
+	// remove starting /
+	const subdirectory = subdirectoryPath?.slice(1);
+
+	return { remote, subdirectory };
+}

package/src/{index.tsx → index.ts}

@@ -15,8 +15,6 @@ import {
 	buildOptions,
 	configHandler,
 	noOpOptions,
-	generateHandler,
-	generateOptions,
 	previewHandler,
 	previewOptions,
 	route,
@@ -26,6 +24,8 @@ import {
 } from "./deprecated";
 import { devHandler, devOptions } from "./dev";
 import { workerNamespaceCommands } from "./dispatch-namespace";
+import { docsHandler, docsOptions } from "./docs";
+import { generateHandler, generateOptions } from "./generate";
 import { initHandler, initOptions } from "./init";
 import { kvNamespace, kvKey, kvBulk } from "./kv";
 import { logBuildFailure, logger } from "./logger";
@@ -264,24 +264,30 @@ export function createCLIParser(argv: string[]) {
 	// I wish we could enforce this pattern, but this comment will have to do for now.
 	// (It's also annoying that choices[] doesn't get inferred as an enum. 🤷‍♂.)
 
-	// [DEPRECATED] generate
+	// docs
 	wrangler.command(
-		// we definitely want to move away from us cloning github templates
-		// we can do something better here, let's see
-		"generate [name] [template]",
-		false,
-		generateOptions,
-		generateHandler
+		"docs [command]",
+		"📚 Open wrangler's docs in your browser",
+		docsOptions,
+		docsHandler
 	);
 
 	// init
 	wrangler.command(
 		"init [name]",
-		"📥 Create a wrangler.toml configuration file",
+		"📥 Initialize a basic Worker project, including a wrangler.toml file",
 		initOptions,
 		initHandler
 	);
 
+	// generate
+	wrangler.command(
+		"generate [name] [template]",
+		"✨ Generate a new Worker project from an existing Worker template. See https://github.com/cloudflare/templates",
+		generateOptions,
+		generateHandler
+	);
+
 	// [DEPRECATED] build
 	wrangler.command("build", false, buildOptions, buildHandler);
 

package/src/init.ts

@@ -22,10 +22,14 @@ import type { Route, SimpleRoute } from "./config/environment";
 import type { WorkerMetadata } from "./create-worker-upload-form";
 import type { ConfigPath } from "./index";
 import type { PackageManager } from "./package-manager";
-import type { CommonYargsOptions } from "./yargs-types";
-import type { Argv, ArgumentsCamelCase } from "yargs";
+import type { PackageJSON } from "./parse";
+import type {
+	CommonYargsOptions,
+	YargsOptionsToInterface,
+} from "./yargs-types";
+import type { Argv } from "yargs";
 
-export async function initOptions(yargs: Argv<CommonYargsOptions>) {
+export function initOptions(yargs: Argv<CommonYargsOptions>) {
 	return yargs
 		.positional("name", {
 			describe: "The name of your worker",
@@ -49,18 +53,14 @@ export async function initOptions(yargs: Argv<CommonYargsOptions>) {
 			alias: "y",
 		})
 		.option("from-dash", {
-			describe: "Download script from the dashboard for local development",
+			describe:
+				"The name of the Worker you wish to download from the Cloudflare dashboard for local development.",
 			type: "string",
 			requiresArg: true,
 		});
 }
 
-interface InitArgs {
-	name: string;
-	type?: string;
-	site?: boolean;
-	yes?: boolean;
-}
+type InitArgs = YargsOptionsToInterface<typeof initOptions>;
 
 export type ServiceMetadataRes = {
 	id: string;
@@ -109,7 +109,7 @@ export type CronTriggersRes = {
 	];
 };
 
-export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
+export async function initHandler(args: InitArgs) {
 	await printWranglerBanner();
 	if (args.type) {
 		let message = "The --type option is no longer supported.";
@@ -124,7 +124,7 @@ export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
 	const devDepsToInstall: string[] = [];
 	const instructions: string[] = [];
 	let shouldRunPackageManagerInstall = false;
-	const fromDashScriptName = args["from-dash"] as string;
+	const fromDashScriptName = args.fromDash;
 	const creationDirectory = path.resolve(
 		process.cwd(),
 		(args.name ? args.name : fromDashScriptName) ?? ""
@@ -165,6 +165,27 @@ export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
 	);
 	let justCreatedWranglerToml = false;
 
+	let accountId = "";
+	let serviceMetadata: undefined | ServiceMetadataRes;
+
+	// If --from-dash, check that script actually exists
+	if (fromDashScriptName) {
+		const config = readConfig(args.config as ConfigPath, args);
+		accountId = await requireAuth(config);
+		try {
+			serviceMetadata = await fetchResult<ServiceMetadataRes>(
+				`/accounts/${accountId}/workers/services/${fromDashScriptName}`
+			);
+		} catch (err) {
+			if ((err as { code?: number }).code === 10090) {
+				throw new Error(
+					"wrangler couldn't find a Worker script with that name in your account.\nRun `wrangler whoami` to confirm you're logged into the correct account."
+				);
+			}
+			throw err;
+		}
+	}
+
 	if (fs.existsSync(wranglerTomlDestination)) {
 		let shouldContinue = false;
 		logger.warn(
@@ -309,7 +330,7 @@ export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
 			isTypescriptProject = true;
 			await writeFile(
 				path.join(creationDirectory, "./tsconfig.json"),
-				readFileSync(path.join(getBasePath(), "templates/tsconfig.json"))
+				readFileSync(path.join(getBasePath(), "templates/tsconfig.init.json"))
 			);
 			devDepsToInstall.push("@cloudflare/workers-types");
 			devDepsToInstall.push("typescript");
@@ -411,7 +432,7 @@ export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
 								: `wrangler publish ${scriptPath}`,
 							...(isAddingTestScripts && { test: testRunner }),
 						},
-					},
+					} as PackageJSON,
 					null,
 					2
 				) + "\n"
@@ -449,19 +470,15 @@ export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
 			);
 			if (fromDashScriptName) {
 				logger.warn(
-					`After running "wrangler init --from-dash", modifying your worker via the Cloudflare dashboard is discouraged.
-					Edits made via the Dashboard will not be synchronized locally and will be overridden by your local code and config when you publish.`
+					"After running `wrangler init --from-dash`, modifying your worker via the Cloudflare dashboard is discouraged.\nEdits made via the Dashboard will not be synchronized locally and will be overridden by your local code and config when you publish."
 				);
-				const config = readConfig(args.config as ConfigPath, args);
-				const accountId = await requireAuth(config);
+
 				await mkdir(path.join(creationDirectory, "./src"), {
 					recursive: true,
 				});
-				const serviceMetaData = await fetchResult<ServiceMetadataRes>(
-					`/accounts/${accountId}/workers/services/${fromDashScriptName}`
-				);
+
 				const defaultEnvironment =
-					serviceMetaData.default_environment.environment;
+					serviceMetadata?.default_environment.environment;
 				// I want the default environment, assuming it's the most up to date code.
 				const dashScript = await fetchDashboardScript(
 					`/accounts/${accountId}/workers/services/${fromDashScriptName}/environments/${defaultEnvironment}/content`
@@ -479,7 +496,7 @@ export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
 					scriptPath: "src/index.ts",
 					extraToml: (await getWorkerConfig(accountId, fromDashScriptName, {
 						defaultEnvironment,
-						environments: serviceMetaData.environments,
+						environments: serviceMetadata?.environments,
 					})) as TOML.JsonMap,
 				});
 			} else {
@@ -493,6 +510,7 @@ export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
 					await mkdir(path.join(creationDirectory, "./src"), {
 						recursive: true,
 					});
+
 					await writeFile(
 						path.join(creationDirectory, "./src/index.ts"),
 						readFileSync(path.join(getBasePath(), `templates/${template}`))
@@ -505,10 +523,43 @@ export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
 						)}`
 					);
 
+					shouldCreateTests =
+						yesFlag ||
+						(await confirm(
+							"Would you like us to write your first test with Vitest?"
+						));
+
+					if (shouldCreateTests) {
+						if (yesFlag) {
+							logger.info("Your project will use Vitest to run your tests.");
+						}
+
+						newWorkerTestType = "vitest";
+						devDepsToInstall.push(newWorkerTestType);
+
+						await writeFile(
+							path.join(creationDirectory, "./src/index.test.ts"),
+							readFileSync(
+								path.join(
+									getBasePath(),
+									`templates/init-tests/test-${newWorkerTestType}-new-worker.ts`
+								)
+							)
+						);
+						logger.log(
+							`✨ Created ${path.relative(
+								process.cwd(),
+								path.join(creationDirectory, "./src/index.test.ts")
+							)}`
+						);
+					}
+
 					await writePackageJsonScriptsAndUpdateWranglerToml({
 						isWritingScripts: shouldWritePackageJsonScripts,
+						isAddingTests: shouldCreateTests,
 						isCreatingWranglerToml: justCreatedWranglerToml,
 						packagePath: pathToPackageJson,
+						testRunner: newWorkerTestType,
 						scriptPath: "src/index.ts",
 						extraToml: getNewWorkerToml(newWorkerType),
 					});
@@ -524,20 +575,15 @@ export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
 
 			if (fromDashScriptName) {
 				logger.warn(
-					`After running "wrangler init --from-dash", modifying your worker via the Cloudflare dashboard is discouraged.
-					Edits made via the Dashboard will not be synchronized locally and will be overridden by your local code and config when you publish.`
+					"After running `wrangler init --from-dash`, modifying your worker via the Cloudflare dashboard is discouraged.\nEdits made via the Dashboard will not be synchronized locally and will be overridden by your local code and config when you publish."
 				);
-				const config = readConfig(args.config as ConfigPath, args);
-				const accountId = await requireAuth(config);
+
 				await mkdir(path.join(creationDirectory, "./src"), {
 					recursive: true,
 				});
 
-				const serviceMetaData = await fetchResult<ServiceMetadataRes>(
-					`/accounts/${accountId}/workers/services/${fromDashScriptName}`
-				);
 				const defaultEnvironment =
-					serviceMetaData.default_environment.environment;
+					serviceMetadata?.default_environment.environment;
 
 				// I want the default environment, assuming it's the most up to date code.
 				const dashScript = await fetchDashboardScript(
@@ -557,7 +603,7 @@ export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
 					//? Should we have Environment argument for `wrangler init --from-dash` - Jacob
 					extraToml: (await getWorkerConfig(accountId, fromDashScriptName, {
 						defaultEnvironment,
-						environments: serviceMetaData.environments,
+						environments: serviceMetadata?.environments,
 					})) as TOML.JsonMap,
 				});
 			} else {
@@ -588,7 +634,7 @@ export async function initHandler(args: ArgumentsCamelCase<InitArgs>) {
 						(await confirm("Would you like us to write your first test?"));
 
 					if (shouldCreateTests) {
-						newWorkerTestType = await getNewWorkerTestType();
+						newWorkerTestType = await getNewWorkerTestType(yesFlag);
 						devDepsToInstall.push(newWorkerTestType);
 						await writeFile(
 							path.join(creationDirectory, "./src/index.test.js"),
@@ -678,41 +724,41 @@ async function installPackages(
 }
 
 async function getNewWorkerType(newWorkerFilename: string) {
-	return select(
-		`Would you like to create a Worker at ${newWorkerFilename}?`,
-		[
+	return select(`Would you like to create a Worker at ${newWorkerFilename}?`, {
+		choices: [
 			{
 				value: "none",
-				label: "None",
+				title: "None",
 			},
 			{
 				value: "fetch",
-				label: "Fetch handler",
+				title: "Fetch handler",
 			},
 			{
 				value: "scheduled",
-				label: "Scheduled handler",
+				title: "Scheduled handler",
 			},
 		],
-		1
-	) as Promise<"none" | "fetch" | "scheduled">;
+		defaultOption: 1,
+	});
 }
 
-async function getNewWorkerTestType() {
-	return select(
-		`Which test runner would you like to use?`,
-		[
-			{
-				value: "vitest",
-				label: "Vitest",
-			},
-			{
-				value: "jest",
-				label: "Jest",
-			},
-		],
-		1
-	) as Promise<"jest" | "vitest">;
+async function getNewWorkerTestType(yesFlag?: boolean) {
+	return yesFlag
+		? "jest"
+		: select(`Which test runner would you like to use?`, {
+				choices: [
+					{
+						value: "vitest",
+						title: "Vitest",
+					},
+					{
+						value: "jest",
+						title: "Jest",
+					},
+				],
+				defaultOption: 1,
+		  });
 }
 
 function getNewWorkerTemplate(
@@ -770,8 +816,8 @@ async function getWorkerConfig(
 		defaultEnvironment,
 		environments,
 	}: {
-		defaultEnvironment: string;
-		environments: ServiceMetadataRes["environments"];
+		defaultEnvironment: string | undefined;
+		environments: ServiceMetadataRes["environments"] | undefined;
 	}
 ): Promise<RawConfig> {
 	const [bindings, routes, serviceEnvMetadata, cronTriggers] =
@@ -870,7 +916,7 @@ async function getWorkerConfig(
 						];
 					}
 					break;
-				case "namespace":
+				case "dispatch_namespace":
 					{
 						configObj.dispatch_namespaces = [
 							...(configObj.dispatch_namespaces ?? []),
@@ -967,7 +1013,7 @@ async function getWorkerConfig(
 			crons: cronTriggers.schedules.map((scheduled) => scheduled.cron),
 		},
 		env: environments
-			.filter((env) => env.environment !== "production")
+			?.filter((env) => env.environment !== "production")
 			// `env` can have multiple Environments, with different configs.
 			.reduce((envObj, { environment }) => {
 				return { ...envObj, [environment]: {} };

package/src/jest.d.ts

@@ -0,0 +1,4 @@
+declare global {
+	const jest: unknown;
+}
+export {};