refactor(hooks): split ctx.abort into ctx.fail and ctx.skip

`abort(message, { asWarning: true })` did not abort anything — it warned
and the command carried on, so one verb meant opposite things depending
on a flag. The two outcomes now have a verb each: `ctx.fail(message)`
fails the command, `ctx.skip(message)` warns and lets it continue.

Both still stop the handler by throwing, so both are typed `never` and
the "handler ends here" behavior is unchanged; only the command's fate
differs. A missing message falls back to one naming the hook point and
the method.

`abort` and the `asWarning` option are removed outright rather than
shimmed, as the API is unreleased and never exposed either name.

Author: edusperoni

extending-cli.md

@@ -153,16 +153,28 @@ The wrappable hook points are:
 
 `before-buildAndroid` · `before-buildAndroidPlugin` · `before-buildIOS` · `before-checkEnvironment` · `before-checkForChanges` · `before-install` · `before-prepare` · `before-prepareNativeApp` · `before-resolveCommand` · `before-watch` · `before-watchPatterns`
 
-### `ctx.abort(message)`
+### `ctx.fail(message)` and `ctx.skip(message)`
 
-`ctx.abort(message)` stops the hook and fails the command. Pass `{ asWarning: true }` to print the message as a warning and let the command continue instead. The message is required in practice — calling `abort()` without one falls back to a message naming the hook point.
+Both end the handler immediately — nothing after the call runs — and differ in what happens to the command.
+
+`ctx.fail(message)` fails the command, printing `message` as the error:
+
+```JavaScript
+module.exports = defineHook("before-prepare", (ctx) => {
+	ctx.fail("The generated bundle is missing; run the bundler first.");
+});
+```
+
+`ctx.skip(message)` prints `message` as a warning and lets the command continue:
 
 ```JavaScript
 module.exports = defineHook("before-prepare", (ctx) => {
-	ctx.abort("Nothing to prepare.", { asWarning: true });
+	ctx.skip("Nothing to prepare.");
 });
 ```
 
+The message is required in practice — calling either without one falls back to a message naming the hook point and the method.
+
 ### Plain function hooks
 
 Exporting a plain function is still supported. It runs in an injection context too, so `inject()` works the same way; declare a `hookArgs` parameter if you need the payload.
@@ -190,7 +202,7 @@ Member | Type | Description
 
 A plain-function hook can also return a function, which the CLI folds into a middleware chain around the hooked method.
 
-With `defineHook` neither convention is needed, and neither applies: `ctx.abort` replaces throwing an error carrying `stopExecution`/`errorAsWarning`, and `ctx.wrap` replaces returning a function. A definition whose `run` returns a function is warned about — the returned function is not used as a middleware.
+With `defineHook` neither convention is needed, and neither applies: `ctx.fail`/`ctx.skip` replace throwing an error carrying `stopExecution`/`errorAsWarning`, and `ctx.wrap` replaces returning a function. A definition whose `run` returns a function is warned about — the returned function is not used as a middleware.
 
 ## Legacy: parameter-name injection
 

lib/common/define-hook.ts

@@ -42,10 +42,20 @@ export interface HookContext<TPayload = any> {
 	wrap(middleware: HookMiddleware): void;
 
 	/**
-	 * Stops the hook. With `asWarning`, the CLI logs the message and continues
-	 * the command; otherwise the command fails.
+	 * Ends the handler and fails the command with `message`.
+	 *
+	 * Typed `never` because it stops the handler by throwing, so nothing after
+	 * the call runs.
 	 */
-	abort(message: string, opts?: { asWarning?: boolean }): never;
+	fail(message: string): never;
+
+	/**
+	 * Ends the handler and logs `message` as a warning; the command continues.
+	 *
+	 * Typed `never` because it stops the handler by throwing, so nothing after
+	 * the call runs — only the command outlives it.
+	 */
+	skip(message: string): never;
 }
 
 export type HookHandler<TPayload = any> = (
@@ -209,24 +219,31 @@ export function createHookInvocation<TPayload = any>(
 
 			middlewares.push(middleware);
 		},
-		abort(message: string, opts?: { asWarning?: boolean }): never {
-			const text =
-				typeof message === "string" && message.trim().length
-					? message
-					: `The "${hookName}" hook aborted without a message.`;
-			const error: any = new Error(text);
-			if (opts && opts.asWarning) {
-				// The pair the hooks service checks for to downgrade a rejection.
-				error.stopExecution = false;
-				error.errorAsWarning = true;
-			}
+		fail(message: string): never {
+			throw new Error(hookMessage(message, hookName, "fail"));
+		},
+		skip(message: string): never {
+			const error: any = new Error(hookMessage(message, hookName, "skip"));
+			// The pair the hooks service checks for to downgrade a rejection.
+			error.stopExecution = false;
+			error.errorAsWarning = true;
 			throw error;
 		},
 	};
 
 	return { context, middlewares };
 }
 
+function hookMessage(
+	message: string,
+	hookName: string,
+	method: string,
+): string {
+	return typeof message === "string" && message.trim().length
+		? message
+		: `The "${hookName}" hook called ctx.${method}() without a message.`;
+}
+
 function derivePayload(hookArguments: any): any {
 	if (!hookArguments || typeof hookArguments !== "object") {
 		return undefined;

test/define-hook.ts

@@ -224,35 +224,39 @@ describe("defineHook", () => {
 		assert.isUndefined(capture.originalRan);
 	});
 
-	it("logs a warning and continues when the handler aborts with asWarning", async () => {
+	it("warns and continues the command when the handler skips, stopping the handler", async () => {
 		writeHook(
 			projectDir,
 			"before-case7",
 			`const { defineHook } = require(${JSON.stringify(apiPath)});
 			module.exports = defineHook("before-case7", async (ctx) => {
-				ctx.abort("soft-abort", { asWarning: true });
+				ctx.skip("soft-skip");
+				global.__hookCapture.afterSkip = true;
 			});`,
 		);
 
 		await hooksService().executeBeforeHooks("case7");
 
-		assert.include(logger().warnOutput, "soft-abort");
+		assert.include(logger().warnOutput, "soft-skip");
+		assert.isUndefined(capture.afterSkip);
 	});
 
-	it("fails the command when the handler aborts without asWarning", async () => {
+	it("fails the command when the handler fails, stopping the handler", async () => {
 		writeHook(
 			projectDir,
 			"before-case8",
 			`const { defineHook } = require(${JSON.stringify(apiPath)});
 			module.exports = defineHook("before-case8", async (ctx) => {
-				ctx.abort("hard-abort");
+				ctx.fail("hard-fail");
+				global.__hookCapture.afterFail = true;
 			});`,
 		);
 
 		await assert.isRejected(
 			hooksService().executeBeforeHooks("case8"),
-			/hard-abort/,
+			/hard-fail/,
 		);
+		assert.isUndefined(capture.afterFail);
 	});
 
 	it("keeps a legacy param-name hook on the old path, and never reports a definition hook", async () => {
@@ -377,19 +381,37 @@ describe("defineHook", () => {
 		);
 	});
 
-	it("defaults the abort() message instead of failing with Error(undefined)", async () => {
+	it("defaults the fail() message instead of failing with Error(undefined)", async () => {
 		writeHook(
 			projectDir,
 			"before-case15",
 			`const { defineHook } = require(${JSON.stringify(apiPath)});
 			module.exports = defineHook("before-case15", (ctx) => {
-				ctx.abort();
+				ctx.fail();
 			});`,
 		);
 
 		await assert.isRejected(
 			hooksService().executeBeforeHooks("case15"),
-			/The "before-case15" hook aborted without a message\./,
+			/The "before-case15" hook called ctx\.fail\(\) without a message\./,
+		);
+	});
+
+	it("defaults the skip() message", async () => {
+		writeHook(
+			projectDir,
+			"before-case18",
+			`const { defineHook } = require(${JSON.stringify(apiPath)});
+			module.exports = defineHook("before-case18", (ctx) => {
+				ctx.skip();
+			});`,
+		);
+
+		await hooksService().executeBeforeHooks("case18");
+
+		assert.include(
+			logger().warnOutput,
+			'The "before-case18" hook called ctx.skip() without a message.',
 		);
 	});