C3: Improve help output (#5376)

* C3: Improve help output

* changest

* Fix e2e

* Address PR feedback

* Fix issue

* Custom implementation of strictOptions

* Remove process.stdout.columns override

* fix workers e2e test

* Fix deployment url lookup

.changeset/kind-lies-beg.md

@@ -0,0 +1,5 @@
+---
+"create-cloudflare": patch
+---
+
+feat: Improve the output of `--help`.

packages/create-cloudflare/e2e-tests/frameworks.test.ts

@@ -458,7 +458,7 @@ const runCli = async (
 	const deployedUrlRe =
 		/deployment is ready at: (https:\/\/.+\.(pages|workers)\.dev)/;
 
-	const match = output.match(deployedUrlRe);
+	const match = output.replaceAll("\n", "n").match(deployedUrlRe);
 	if (!match || !match[1]) {
 		expect(false, "Couldn't find deployment url in C3 output").toBe(true);
 		return "";

packages/create-cloudflare/e2e-tests/workers.test.ts

@@ -180,7 +180,7 @@ const runCli = async (
 	const deployedUrlRe =
 		/deployment is ready at: (https:\/\/.+\.(workers)\.dev)/;
 
-	const match = output.match(deployedUrlRe);
+	const match = output.replaceAll("\n", "").match(deployedUrlRe);
 	if (!match || !match[1]) {
 		expect(false, "Couldn't find deployment url in C3 output").toBe(true);
 		return;

packages/create-cloudflare/package.json

@@ -74,6 +74,7 @@
 		"execa": "^7.1.1",
 		"glob": "^10.3.3",
 		"haikunator": "^2.1.2",
+		"indent-string": "^5.0.0",
 		"magic-string": "^0.30.5",
 		"open": "^8.4.0",
 		"pnpm": "^8.10.0",
@@ -84,6 +85,7 @@
 		"vite-tsconfig-paths": "^4.0.8",
 		"which-pm-runs": "^1.1.0",
 		"wrangler": "workspace:*",
+		"wrap-ansi": "^9.0.0",
 		"yargs": "^17.7.1",
 		"yarn": "^1.22.19"
 	},

packages/create-cloudflare/src/help.ts

@@ -0,0 +1,108 @@
+import { logRaw } from "@cloudflare/cli";
+import { bold, brandColor, dim } from "@cloudflare/cli/colors";
+import { detectPackageManager } from "helpers/packageManagers";
+import indentString from "indent-string";
+import wrap from "wrap-ansi";
+import { version } from "../package.json";
+import type {
+	AllowedValueDefinition,
+	ArgDefinition,
+	ArgumentsDefinition,
+	OptionDefinition,
+} from "helpers/args";
+
+const MAX_WIDTH = 100;
+const PADDING_RIGHT = 5;
+
+export const showHelp = ({
+	positionals,
+	options,
+	intro,
+}: ArgumentsDefinition) => {
+	const { name: pm } = detectPackageManager();
+
+	logRaw(`${brandColor("create-cloudflare")} ${dim("v" + version)}\n`);
+	indent(`${intro.trim()}\n`, 1);
+
+	logRaw(bold("USAGE\n"));
+	const latest = pm === "yarn" ? "" : "@latest";
+	const opts = pm === "npm" ? "-- options" : "options";
+	indent(`${pm} create cloudflare${latest} [directory] [${opts}]\n`, 1);
+
+	logRaw(bold("OPTIONS\n"));
+
+	renderPositionals(positionals);
+	renderOptions(options);
+};
+
+/**
+ * Indent the provided string by the specified level and write to stdout. Lines
+ * will be wrapped to the width of the terminal or a preset maximum width, whichever
+ * is smaller.
+ *
+ * @param str The string to be indented
+ * @param level The indentation level
+ */
+const indent = (str: string, level = 0) => {
+	const maxWidth = Math.min(MAX_WIDTH, process.stdout.columns - PADDING_RIGHT);
+	logRaw(indentString(wrap(str, maxWidth - level), level, { indent: "  " }));
+};
+
+const renderPositionals = (positionals?: ArgDefinition[]) => {
+	if (!positionals) {
+		return;
+	}
+
+	if (positionals) {
+		for (const { name, description } of positionals) {
+			indent(bold(`${name}`), 1);
+			indent(`${description.trim()}\n`, 2);
+		}
+	}
+};
+
+const renderOptions = (options?: OptionDefinition[]) => {
+	if (!options) {
+		return;
+	}
+
+	for (const option of options) {
+		const { name, description, alias, values, type, hidden } = option;
+		if (hidden) {
+			continue;
+		}
+
+		let heading =
+			type === "boolean"
+				? bold(`--${name}, --no-${name}`)
+				: `${bold(`--${name}`)}=<value>`;
+
+		heading = alias ? `${heading}, ${bold(`-${alias}`)}` : heading;
+
+		indent(heading, 1);
+		indent(`${description.trim()}\n`, 2);
+
+		renderValues(values);
+	}
+};
+
+const renderValues = (values?: AllowedValueDefinition[]) => {
+	if (!values || !(values.length > 0)) {
+		return;
+	}
+
+	indent("Allowed Values:\n", 2);
+
+	if (values[0].description) {
+		for (const { name, description } of values) {
+			indent(`${name}`, 3);
+			indent(`${description}`, 4);
+		}
+		// Newline
+		logRaw("");
+		return;
+	}
+
+	const content = values.map((val) => val.name).join(", ");
+	indent(`${content}\n`, 3);
+};

packages/create-cloudflare/src/helpers/__tests__/args.test.ts

@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, test, vi } from "vitest";
 import { parseArgs } from "../args";
 import type { MockInstance } from "vitest";
 
+vi.mock("@cloudflare/cli");
 vi.mock("yargs/helpers", () => ({ hideBin: (x: string[]) => x }));
 
 describe("Cli", () => {