feat(commands): give ctx.fail a help flag and migrate commands off $errors

ctx.fail always printed the usage help suggestion, so a command failing
over the environment or the project state - a missing platform, a file
that already exists - either misreported it as a command-line mistake
or kept injecting the errors service for the plain form, which most of
the built-ins did.

ctx.fail(message, options?) takes a CommandFailOptions bag; help
defaults to true and { help: false } fails without the suggestion. The
type is exported from nativescript/contracts. The built-in commands
now fail through their context: failWithHelp calls became ctx.fail and
plain fail calls became ctx.fail with help off, and the errors service
injection went with them where nothing else used it. Calls that pass
format arguments or an error object stay on the errors service.

Author: edusperoni

defining-commands.md

@@ -349,15 +349,22 @@ The run context
 - `ctx.injector` — this invocation's injector, a child of the one the command
   was registered against; see
   [Injection, and the first `await`](#injection-and-the-first-await).
-- `ctx.fail(message)` — fails the command with `message` and a usage help
-  suggestion.
+- `ctx.fail(message, options?)` — fails the command with `message`, followed
+  by a usage help suggestion unless `options.help` is `false`.
 
 `run` may be synchronous or `async`; the CLI awaits the result and treats a
 rejection as a command failure.
 
 ### Failing a command
 
-`ctx.fail(message)` is the idiomatic way to stop a command:
+`ctx.fail(message)` is the idiomatic way to stop a command. By default it
+follows the message with the usage help suggestion — the "Run `ns widget add
+--help`" line — which is what the user needs when they got the command line
+wrong: a missing argument, an unknown value, an invalid combination of options.
+
+When the command line was fine and something else is not — the environment,
+the project, a file on disk — the help suggestion only gets in the way. Pass
+`{ help: false }` to print the message alone:
 
 ```ts
 defineCommand({
@@ -369,17 +376,22 @@ defineCommand({
 			ctx.fail("--output is required.");
 		}
 
+		if (fs.existsSync(ctx.options.output)) {
+			ctx.fail(`${ctx.options.output} already exists.`, { help: false });
+		}
+
 		/* ... */
 	},
 });
 ```
 
-It is available on the `canExecute` context as well, and it returns `never`, so
-it can end a branch without a `return`. The message must be a non-empty string.
+It is available on the `setup` and `canExecute` contexts as well, and it
+returns `never`, so it can end a branch without a `return`. The message must be
+a non-empty string, and `options`, when given, a plain object. The two forms
+map onto the `errors` service's `failWithHelp` and `fail`.
 
-Throwing is equivalent and keeps working — `ctx.fail` is sugar over the
-`errors` service's `failWithHelp`, which is what adds the "Run `ns widget add
---help`" line. Throw when you already have an `Error` to propagate; call
+Throwing keeps working too: an error thrown from a handler propagates
+unchanged. Throw when you already have an `Error` to propagate; call
 `ctx.fail` when you are writing the message.
 
 Injection, and the first `await`

lib/commands/add-platform.ts

@@ -4,7 +4,6 @@ import {
 	IPlatformValidationService,
 } from "../declarations";
 import { IProjectData } from "../definitions/project";
-import { IErrors } from "../common/declarations";
 import {
 	Command,
 	CommandOptionsSchema,
@@ -23,7 +22,6 @@ export class AddPlatformCommand extends Command({
 	options: addPlatformCommandOptions,
 	arguments: "any",
 }) {
-	private $errors = inject<IErrors>("errors");
 	private $platformCommandHelper = inject<IPlatformCommandHelper>(
 		"platformCommandHelper",
 	);
@@ -40,7 +38,7 @@ export class AddPlatformCommand extends Command({
 	public async canExecute(): Promise<boolean> {
 		const args = this.args;
 		if (!args || args.length === 0) {
-			this.$errors.failWithHelp(
+			this.context.fail(
 				"No platform specified. Please specify a platform to add.",
 			);
 		}
@@ -55,8 +53,9 @@ export class AddPlatformCommand extends Command({
 					this.$projectData,
 				)
 			) {
-				this.$errors.fail(
+				this.context.fail(
 					`Applications for platform ${arg} cannot be built on this OS`,
+					{ help: false },
 				);
 			}
 

lib/commands/apple-login.ts

@@ -1,4 +1,3 @@
-import { IErrors } from "../common/declarations";
 import { defineCommand } from "../common/define-command";
 import { inject } from "../common/di";
 import { IApplePortalSessionService } from "../services/apple-portal/definitions";
@@ -11,7 +10,6 @@ export const appleLoginCommandDefinition = defineCommand({
 		const $applePortalSessionService = inject<IApplePortalSessionService>(
 			"applePortalSessionService",
 		);
-		const $errors = inject<IErrors>("errors");
 		const $logger = inject<ILogger>("logger");
 		const $prompter = inject<IPrompter>("prompter");
 
@@ -32,8 +30,9 @@ export const appleLoginCommandDefinition = defineCommand({
 			password,
 		});
 		if (!user.areCredentialsValid) {
-			$errors.fail(
+			context.fail(
 				`Invalid username and password combination. Used '${username}' as the username.`,
+				{ help: false },
 			);
 		}
 

lib/commands/appstore-list.ts

@@ -1,4 +1,3 @@
-import { IErrors } from "../common/declarations";
 import {
 	Command,
 	CommandOptionsSchema,
@@ -31,7 +30,6 @@ export class ListiOSAppsCommand extends Command({
 	private $devicePlatformsConstants = inject<Mobile.IDevicePlatformsConstants>(
 		"devicePlatformsConstants",
 	);
-	private $errors = inject<IErrors>("errors");
 	private $logger = inject<ILogger>("logger");
 	private $platformValidationService = inject<IPlatformValidationService>(
 		"platformValidationService",
@@ -51,8 +49,9 @@ export class ListiOSAppsCommand extends Command({
 				this.$projectData,
 			)
 		) {
-			this.$errors.fail(
+			this.context.fail(
 				`Applications for platform ${this.$devicePlatformsConstants.iOS} can not be built on this OS`,
+				{ help: false },
 			);
 		}
 
@@ -76,8 +75,9 @@ export class ListiOSAppsCommand extends Command({
 			},
 		);
 		if (!user.areCredentialsValid) {
-			this.$errors.fail(
+			this.context.fail(
 				`Invalid username and password combination. Used '${username}' as the username.`,
+				{ help: false },
 			);
 		}
 

lib/commands/appstore-upload.ts

@@ -1,5 +1,5 @@
 import * as path from "path";
-import { IErrors, IHostInfo } from "../common/declarations";
+import { IHostInfo } from "../common/declarations";
 import {
 	booleanOption,
 	Command,
@@ -41,7 +41,6 @@ export class PublishIOSCommand extends Command({
 	private $devicePlatformsConstants = inject<Mobile.IDevicePlatformsConstants>(
 		"devicePlatformsConstants",
 	);
-	private $errors = inject<IErrors>("errors");
 	private $hostInfo = inject<IHostInfo>("hostInfo");
 	private $itmsTransporterService = inject<IITMSTransporterService>(
 		"itmsTransporterService",
@@ -61,7 +60,9 @@ export class PublishIOSCommand extends Command({
 
 	public canExecute(): boolean {
 		if (!this.$hostInfo.isDarwin) {
-			this.$errors.fail("iOS publishing is only available on macOS.");
+			this.context.fail("iOS publishing is only available on macOS.", {
+				help: false,
+			});
 		}
 
 		if (
@@ -70,8 +71,9 @@ export class PublishIOSCommand extends Command({
 				this.$projectData,
 			)
 		) {
-			this.$errors.fail(
+			this.context.fail(
 				`Applications for platform ${this.$devicePlatformsConstants.iOS} can not be built on this OS`,
+				{ help: false },
 			);
 		}
 
@@ -135,8 +137,9 @@ export class PublishIOSCommand extends Command({
 			},
 		);
 		if (!user.areCredentialsValid) {
-			this.$errors.fail(
+			this.context.fail(
 				`Invalid username and password combination. Used '${username}' as the username.`,
+				{ help: false },
 			);
 		}
 

lib/commands/build.ts

@@ -12,7 +12,6 @@ import {
 import { IBuildController, IBuildDataService } from "../definitions/build";
 import { IMigrateController } from "../definitions/migrate";
 import { IProjectData } from "../definitions/project";
-import { IErrors } from "../common/declarations";
 import {
 	booleanOption,
 	CommandName,
@@ -52,7 +51,6 @@ const defineBuildCommand = <const TName extends CommandName>(
 		async canExecute(context): Promise<boolean> {
 			const $devicePlatformsConstants =
 				inject<Mobile.IDevicePlatformsConstants>("devicePlatformsConstants");
-			const $errors = inject<IErrors>("errors");
 			const $migrateController =
 				inject<IMigrateController>("migrateController");
 			const $platformValidationService = inject<IPlatformValidationService>(
@@ -82,8 +80,9 @@ const defineBuildCommand = <const TName extends CommandName>(
 					$projectData,
 				)
 			) {
-				$errors.fail(
+				context.fail(
 					`Applications for platform ${platform} can not be built on this OS`,
+					{ help: false },
 				);
 			}
 
@@ -96,7 +95,7 @@ const defineBuildCommand = <const TName extends CommandName>(
 				context.options.release &&
 				!hasValidAndroidSigning(context.options)
 			) {
-				$errors.failWithHelp(ANDROID_RELEASE_BUILD_ERROR_MESSAGE);
+				context.fail(ANDROID_RELEASE_BUILD_ERROR_MESSAGE);
 			}
 
 			return validatePlatformOptions(context, platform);

lib/commands/config.ts

@@ -1,6 +1,5 @@
 import { IProjectConfigService } from "../definitions/project";
 import { SupportedConfigValues } from "../tools/config-manipulation/config-transformer";
-import { IErrors } from "../common/declarations";
 import { CommandContext, defineCommand } from "../common/define-command";
 import { inject } from "../common/di";
 import { color } from "../color";
@@ -38,9 +37,7 @@ function getConvertedValue(v: any): any {
 
 function requireConfigKey(context: CommandContext): void {
 	if (!context.args[0]) {
-		context.injector
-			.get<IErrors>("errors")
-			.failWithHelp("You must specify a key. Eg: ios.id");
+		context.fail("You must specify a key. Eg: ios.id");
 	}
 }
 
@@ -93,12 +90,10 @@ export const configSetCommandDefinition = defineCommand({
 	description: "Sets a value in the project configuration.",
 	arguments: "any",
 	async canExecute(context): Promise<boolean> {
-		const $errors = inject<IErrors>("errors");
-
 		requireConfigKey(context);
 
 		if (!context.args[1]) {
-			$errors.failWithHelp("You must specify a value.");
+			context.fail("You must specify a value.");
 		}
 
 		return true;
@@ -108,13 +103,13 @@ export const configSetCommandDefinition = defineCommand({
 			"projectConfigService",
 		);
 		const $logger = inject<ILogger>("logger");
-		const $errors = inject<IErrors>("errors");
 
 		const [key, value] = context.args;
 		const current = $projectConfigService.getValue(key);
 		if (current && typeof current === "object") {
-			$errors.fail(
+			context.fail(
 				`Unable to change object values. Please update individual values instead.\nEg: ns config set android.codeCache true`,
+				{ help: false },
 			);
 		}
 		const convertedValue = getConvertedValue(value);

lib/commands/debug.ts

@@ -1,4 +1,4 @@
-import { IErrors, ISysInfo } from "../common/declarations";
+import { ISysInfo } from "../common/declarations";
 import { commandShortcutsEnabled } from "../common/contracts/key-shortcuts";
 import {
 	booleanOption,
@@ -61,7 +61,6 @@ async function canExecuteDebugCommand(
 		context.injector.get<Mobile.IDevicePlatformsConstants>(
 			"devicePlatformsConstants",
 		);
-	const $errors = context.injector.get<IErrors>("errors");
 	const $migrateController =
 		context.injector.get<IMigrateController>("migrateController");
 	const $platformValidationService =
@@ -86,13 +85,14 @@ async function canExecuteDebugCommand(
 	if (
 		!$platformValidationService.isPlatformSupportedForOS(platform, $projectData)
 	) {
-		$errors.fail(
+		context.fail(
 			`Applications for platform ${platform} can not be built on this OS`,
+			{ help: false },
 		);
 	}
 
 	if (context.options.release) {
-		$errors.failWithHelp("--release flag is not applicable to this command.");
+		context.fail("--release flag is not applicable to this command.");
 	}
 
 	return canExecuteCommandBase(context, platform, {
@@ -235,7 +235,6 @@ const defineApplePlatformDebugCommand = <const TName extends CommandName>(
 		async canExecute(context): Promise<boolean> {
 			const $devicePlatformsConstants =
 				inject<Mobile.IDevicePlatformsConstants>("devicePlatformsConstants");
-			const $errors = inject<IErrors>("errors");
 			const $platformValidationService = inject<IPlatformValidationService>(
 				"platformValidationService",
 			);
@@ -261,14 +260,16 @@ const defineApplePlatformDebugCommand = <const TName extends CommandName>(
 					$projectData,
 				)
 			) {
-				$errors.fail(
+				context.fail(
 					`Applications for platform ${platform} can not be built on this OS`,
+					{ help: false },
 				);
 			}
 
 			if (!isValidTimeoutOption(context.options.timeout)) {
-				$errors.fail(
+				context.fail(
 					`Timeout option specifies the seconds NativeScript CLI will wait to find the inspector socket port from device's logs. Must be a number.`,
+					{ help: false },
 				);
 			}
 
@@ -278,8 +279,9 @@ const defineApplePlatformDebugCommand = <const TName extends CommandName>(
 					macOSWarning &&
 					macOSWarning.severity === SystemWarningsSeverity.high
 				) {
-					$errors.fail(
+					context.fail(
 						`You cannot use NativeScript Inspector on this OS. To use it, please update your OS.`,
+						{ help: false },
 					);
 				}
 			}
@@ -305,14 +307,13 @@ export const androidDebugCommand = defineCommand({
 	options: debugCommandOptions,
 	arguments: "any",
 	async canExecute(context): Promise<boolean> {
-		const $errors = inject<IErrors>("errors");
 		const $projectData = inject<IProjectData>("projectData");
 		$projectData.initializeProjectData();
 
 		const canExecuteBase = await canExecuteDebugCommand(context, "Android");
 		if (canExecuteBase) {
 			if (context.options.aab && !hasValidAndroidSigning(context.options)) {
-				$errors.failWithHelp(ANDROID_APP_BUNDLE_SIGNING_ERROR_MESSAGE);
+				context.fail(ANDROID_APP_BUNDLE_SIGNING_ERROR_MESSAGE);
 			}
 		}
 

lib/commands/deploy.ts

@@ -7,7 +7,6 @@ import { DeployCommandHelper } from "../helpers/deploy-command-helper";
 import { hasValidAndroidSigning } from "../common/helpers";
 import { IMigrateController } from "../definitions/migrate";
 import { IProjectData } from "../definitions/project";
-import { IErrors } from "../common/declarations";
 import {
 	booleanOption,
 	CommandOptionsSchema,
@@ -34,7 +33,6 @@ export const deployCommandDefinition = defineCommand({
 	options: deployCommandOptions,
 	arguments: [platformArgument],
 	async canExecute(context): Promise<boolean> {
-		const $errors = inject<IErrors>("errors");
 		const $migrateController = inject<IMigrateController>("migrateController");
 		const $mobileHelper = inject<Mobile.IMobileHelper>("mobileHelper");
 		const $projectData = inject<IProjectData>("projectData");
@@ -59,9 +57,9 @@ export const deployCommandDefinition = defineCommand({
 			!hasValidAndroidSigning(context.options)
 		) {
 			if (context.options.release) {
-				$errors.failWithHelp(ANDROID_RELEASE_BUILD_ERROR_MESSAGE);
+				context.fail(ANDROID_RELEASE_BUILD_ERROR_MESSAGE);
 			} else {
-				$errors.failWithHelp(ANDROID_APP_BUNDLE_SIGNING_ERROR_MESSAGE);
+				context.fail(ANDROID_APP_BUNDLE_SIGNING_ERROR_MESSAGE);
 			}
 		}