Apply quality of life improvements to the opennextjs-cloudflare CLI (#1097)

---------

Co-authored-by: Victor Berchet <[email protected]>
Co-authored-by: James Anderson <[email protected]>

Author: 3 people

.changeset/yellow-pears-relax.md

@@ -0,0 +1,11 @@
+---
+"@opennextjs/cloudflare": patch
+---
+
+Add `--help` and `--version` to the `opennextjs-cloudflare` CLI
+
+Improve the `opennextjs-cloudflare` CLI by:
+
+- ensuring that unknown commands (e.g., `opennextjs-cloudflare foo`) display a clear and helpful error message
+- adding a `-h`|`--help` flag to display the CLI's help message
+- adding a `-v`|`--version` flag to display the package's version

packages/cloudflare/src/cli/commands/build.ts

@@ -53,7 +53,7 @@ async function buildCommand(
  */
 export function addBuildCommand<T extends yargs.Argv>(y: T) {
 	return y.command(
-		"build",
+		"build [args..]",
 		"Build an OpenNext Cloudflare worker",
 		(c) =>
 			withWranglerOptions(c)

packages/cloudflare/src/cli/commands/deploy.ts

@@ -74,7 +74,7 @@ export async function deployCommand(args: WithWranglerArgs<{ cacheChunkSize?: nu
  */
 export function addDeployCommand<T extends yargs.Argv>(y: T) {
 	return y.command(
-		"deploy",
+		"deploy [args..]",
 		"Deploy a built OpenNext app to Cloudflare Workers",
 		(c) => withPopulateCacheOptions(c),
 		(args) => deployCommand(withWranglerPassthroughArgs(args))

packages/cloudflare/src/cli/commands/populate-cache.ts

@@ -389,13 +389,13 @@ export function addPopulateCacheCommand<T extends yargs.Argv>(y: T) {
 	return y.command("populateCache", "Populate the cache for a built Next.js app", (c) =>
 		c
 			.command(
-				"local",
+				"local [args..]",
 				"Local dev server cache",
 				(c) => withPopulateCacheOptions(c),
 				(args) => populateCacheCommand("local", withWranglerPassthroughArgs(args))
 			)
 			.command(
-				"remote",
+				"remote [args..]",
 				"Remote Cloudflare Worker cache",
 				(c) => withPopulateCacheOptions(c),
 				(args) => populateCacheCommand("remote", withWranglerPassthroughArgs(args))

packages/cloudflare/src/cli/commands/preview.ts

@@ -52,7 +52,7 @@ export async function previewCommand(
  */
 export function addPreviewCommand<T extends yargs.Argv>(y: T) {
 	return y.command(
-		"preview",
+		"preview [args..]",
 		"Preview a built OpenNext app with a Wrangler dev server",
 		(c) =>
 			withPopulateCacheOptions(c).option("remote", {

packages/cloudflare/src/cli/commands/upload.ts

@@ -71,7 +71,7 @@ export async function uploadCommand(args: WithWranglerArgs<{ cacheChunkSize?: nu
  */
 export function addUploadCommand<T extends yargs.Argv>(y: T) {
 	return y.command(
-		"upload",
+		"upload [args..]",
 		"Upload a built OpenNext app to Cloudflare Workers",
 		(c) => withPopulateCacheOptions(c),
 		(args) => uploadCommand(withWranglerPassthroughArgs(args))

packages/cloudflare/src/cli/commands/utils.ts

@@ -142,7 +142,12 @@ type WranglerInputArgs = {
  * @param args
  * @returns An array of arguments that can be given to wrangler commands, including the `--config` and `--env` args.
  */
-function getWranglerArgs(args: WranglerInputArgs & { _: (string | number)[] }): string[] {
+function getWranglerArgs(
+	args: WranglerInputArgs & {
+		_: (string | number)[];
+		args?: (string | number)[];
+	}
+): string[] {
 	if (args.configPath) {
 		logger.warn("The `--configPath` flag is deprecated, please use `--config` instead.");
 
@@ -159,8 +164,8 @@ function getWranglerArgs(args: WranglerInputArgs & { _: (string | number)[] }):
 		...(args.config ? ["--config", args.config] : []),
 		...(args.env ? ["--env", args.env] : []),
 		...(args.remote ? ["--remote"] : []),
-		// Note: the first args in `_` will be the commands.
-		...args._.slice(args._[0] === "populateCache" ? 2 : 1).map((a) => `${a}`),
+		// Note: the `args` array contains unrecognised flags.
+		...(args.args?.map((a) => `${a}`) ?? []),
 	];
 }
 

packages/cloudflare/src/cli/index.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
+import logger from "@opennextjs/aws/logger.js";
 import yargs from "yargs";
 
+import { getVersion } from "./build/utils/version.js";
 import { addBuildCommand } from "./commands/build.js";
 import { addDeployCommand } from "./commands/deploy.js";
 import { addMigrateCommand } from "./commands/migrate.js";
@@ -12,7 +14,22 @@ import { addUploadCommand } from "./commands/upload.js";
 export function runCommand() {
 	const y = yargs(process.argv.slice(2).filter((arg) => arg !== "--"))
 		.scriptName("opennextjs-cloudflare")
-		.parserConfiguration({ "unknown-options-as-args": true });
+		.parserConfiguration({ "unknown-options-as-args": true })
+		.strictCommands()
+		.help()
+		.alias("h", "help")
+		.version(getVersion().cloudflare)
+		.alias("v", "version")
+		.fail((msg, err, yargs) => {
+			if (msg) {
+				logger.error(`${msg}\n`);
+			}
+			if (err) {
+				throw err;
+			}
+			yargs.showHelp();
+			process.exit(1);
+		});
 
 	addBuildCommand(y);
 	addPreviewCommand(y);