refactor(commands): fail through the context and read options from it

`ctx.fail(message, { help })` replaces the commands' direct use of $errors, and signing and install options are read from the typed `ctx.options` instead of the global options object.
edusperoni · Sep 14, 2026 · Sep 14, 2026 · Sep 14, 2026 · Sep 14, 2026 · Sep 14, 2026
commit d987e0bd0d95654b03bd4c89712c0e024d8d53fb
diff --git a/defining-commands.md b/defining-commands.md
@@ -183,9 +183,9 @@ spelling _means_:
 stringOption({ alias: "p" })` steals `--path`'s shorthand. Restating an
   option's own shorthand (`path: stringOption({ alias: "p" })`) is fine.
 
-The merge replaces the CLI-wide entry rather than patching it, so a
-redeclaration inherits nothing: restate the `alias` and `hasSensitiveValue` the
-global declaration carries if the command still wants them.
+A redeclaration that leaves `alias`, `default` or `hasSensitiveValue` unset
+keeps what the CLI-wide declaration carries for them, so `path: stringOption()`
+still answers to `-p` and stays out of the logs; set one only to change it.
 
 ### How validation behaves
 
@@ -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`

diff --git a/lib/commands/add-platform.ts b/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 },
 				);
 			}
 

diff --git a/lib/commands/apple-login.ts b/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 },
 			);
 		}
 

diff --git a/lib/commands/appstore-list.ts b/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 },
 			);
 		}
 

diff --git a/lib/commands/appstore-upload.ts b/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 },
 			);
 		}
 

diff --git a/lib/commands/build.ts b/lib/commands/build.ts
@@ -2,7 +2,11 @@ import {
 	ANDROID_RELEASE_BUILD_ERROR_MESSAGE,
 	AndroidAppBundleMessages,
 } from "../constants";
-import { canExecuteCommandBase, validatePlatformOptions } from "./command-base";
+import {
+	canExecuteCommandBase,
+	platformSigningOptions,
+	validatePlatformOptions,
+} from "./command-base";
 import { hasValidAndroidSigning } from "../common/helpers";
 import {
 	IAndroidBundleValidatorHelper,
@@ -12,7 +16,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,
@@ -29,6 +32,7 @@ import { inject } from "../common/di";
 type BuildPlatform = "iOS" | "Android" | "visionOS";
 
 const buildCommandOptions = {
+	...platformSigningOptions,
 	watch: booleanOption({ default: false }),
 	hmr: booleanOption({ default: false }),
 	force: booleanOption(),
@@ -52,7 +56,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 +85,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 +100,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);

diff --git a/lib/commands/command-base.ts b/lib/commands/command-base.ts
@@ -5,12 +5,31 @@ import {
 	ICanExecuteCommandOptions,
 	INotConfiguredEnvOptions,
 } from "../common/definitions/commands";
-import { ArgumentSpec, CommandContext } from "../common/define-command";
+import {
+	ArgumentSpec,
+	CommandContext,
+	CommandOptionsSchema,
+	objectOption,
+} from "../common/define-command";
 import { Injector } from "../common/di";
 
+/**
+ * The CLI-wide signing options `validatePlatformOptions` checks. A command
+ * that validates them spreads this into its own schema.
+ */
+export const platformSigningOptions = {
+	provision: objectOption(),
+	teamId: objectOption(),
+} satisfies CommandOptionsSchema;
+
 /** The part of a command context these helpers read. */
 type PlatformCommandContext = Pick<CommandContext<any>, "injector">;
 
+type PlatformSigningContext = Pick<
+	CommandContext<typeof platformSigningOptions>,
+	"injector" | "options"
+>;
+
 /**
  * The declarative form of `$platformCommandParameter`. Initializing the
  * project data is what makes the platform check possible, so it stays part of
@@ -38,17 +57,16 @@ export const platformArgument: ArgumentSpec<any> = {
 };
 
 export function validatePlatformOptions(
-	context: PlatformCommandContext,
+	context: PlatformSigningContext,
 	platform: string,
 ): Promise<boolean> {
-	const $options = context.injector.get<IOptions>("options");
 	const $projectData = context.injector.get<IProjectData>("projectData");
 
 	return context.injector
 		.get<IPlatformValidationService>("platformValidationService")
 		.validateOptions(
-			$options.provision,
-			$options.teamId,
+			context.options.provision,
+			context.options.teamId,
 			$projectData,
 			platform,
 		);
@@ -82,9 +100,19 @@ function hasUsableEnvironment(
 	);
 }
 
-export async function canExecuteCommandBase(
+export function canExecuteCommandBase(
+	context: PlatformSigningContext,
+	platform: string,
+	options: ICanExecuteCommandOptions & { validateOptions: true },
+): Promise<boolean>;
+export function canExecuteCommandBase(
 	context: PlatformCommandContext,
 	platform: string,
+	options?: ICanExecuteCommandOptions & { validateOptions?: false },
+): Promise<boolean>;
+export async function canExecuteCommandBase(
+	context: PlatformCommandContext | PlatformSigningContext,
+	platform: string,
 	options: ICanExecuteCommandOptions = {},
 ): Promise<boolean> {
 	const validatePlatformOutput = await validatePlatformBase(
@@ -96,7 +124,10 @@ export async function canExecuteCommandBase(
 	let result = canExecute;
 
 	if (canExecute && options.validateOptions) {
-		result = await validatePlatformOptions(context, platform);
+		result = await validatePlatformOptions(
+			<PlatformSigningContext>context,
+			platform,
+		);
 	}
 
 	return result;