fix: use process.exit() for early exit scenarios

Restore standard CLI behavior where --help, --version, completion flags,
and error conditions (unknown/missing commands) terminate the process.

Changes:
- `exitProcess()` calls `process.exit()` for help/version/completions
- `handleHelpError()` calls `process.exit(1)` after displaying help
- Remove `earlyExit` flag from return types (no longer needed)
- Update tests to mock `process.exit` instead of checking return values
- Document process termination behavior in README.md

This is what users expect from a CLI - these flags print output and exit.

Author: boneskull

README.md

@@ -707,17 +707,46 @@ See `examples/completion.ts` for a complete example.
 
 ## Advanced Usage
 
+### Process Termination
+
+**bargs** automatically terminates the process (via `process.exit()`) in certain scenarios. This is standard CLI behavior—users expect these flags to print output and exit immediately:
+
+| Scenario                  | Exit Code | Output                            |
+| ------------------------- | --------- | --------------------------------- |
+| `--help` / `-h`           | 0         | Help text to stdout               |
+| `--version`               | 0         | Version string to stdout          |
+| `--completion-script`     | 0         | Shell completion script to stdout |
+| Unknown command           | 1         | Error + help text to stderr       |
+| Missing required command  | 1         | Error + help text to stderr       |
+| `--get-bargs-completions` | 0         | Completion candidates to stdout   |
+
+For testing, you can mock `process.exit` to capture the exit code:
+
+```typescript
+const originalExit = process.exit;
+let exitCode: number | undefined;
+
+process.exit = ((code?: number) => {
+  exitCode = code ?? 0;
+  throw new Error('process.exit called');
+}) as typeof process.exit;
+
+try {
+  cli.parse(['--help']);
+} catch {
+  // process.exit was called
+}
+
+process.exit = originalExit;
+console.log(exitCode); // 0
+```
+
 ### Error Handling
 
-**bargs** exports some `Error` subclasses:
+**bargs** exports some `Error` subclasses for errors that _don't_ cause automatic process termination:
 
 ```typescript
-import {
-  bargs,
-  BargsError,
-  HelpError,
-  ValidationError,
-} from '@boneskull/bargs';
+import { bargs, BargsError, ValidationError } from '@boneskull/bargs';
 
 try {
   await bargs('my-cli').parseAsync();
@@ -726,10 +755,6 @@ try {
     // Config validation failed (e.g., invalid schema)
     // i.e., "you screwed up"
     console.error(`Config error at "${error.path}": ${error.message}`);
-  } else if (error instanceof HelpError) {
-    // Likely invalid options, command or positionals;
-    // re-throw to trigger help display
-    throw error;
   } else if (error instanceof BargsError) {
     // General bargs error
     console.error(error.message);

src/bargs.ts

@@ -563,37 +563,23 @@ const createCliBuilder = <V, P extends readonly unknown[]>(
       parentGlobals: ParseResult<unknown, readonly unknown[]>,
       allowAsync: boolean,
     ):
-      | (ParseResult<V, P> & { command?: string; earlyExit?: boolean })
-      | Promise<ParseResult<V, P> & { command?: string; earlyExit?: boolean }> {
+      | (ParseResult<V, P> & { command?: string })
+      | Promise<ParseResult<V, P> & { command?: string }> {
       const stateWithGlobals = { ...state, parentGlobals };
       try {
         const result = parseCore(stateWithGlobals, args, allowAsync);
         if (isThenable(result)) {
           return result.catch((error: unknown) => {
             if (error instanceof HelpError) {
-              return handleHelpError(error, stateWithGlobals) as ParseResult<
-                V,
-                P
-              > & {
-                command?: string;
-                earlyExit: true;
-              };
+              handleHelpError(error, stateWithGlobals); // exits process
             }
             throw error;
-          }) as Promise<
-            ParseResult<V, P> & { command?: string; earlyExit?: boolean }
-          >;
+          }) as Promise<ParseResult<V, P> & { command?: string }>;
         }
         return result as ParseResult<V, P> & { command?: string };
       } catch (error) {
         if (error instanceof HelpError) {
-          return handleHelpError(error, stateWithGlobals) as ParseResult<
-            V,
-            P
-          > & {
-            command?: string;
-            earlyExit: true;
-          };
+          handleHelpError(error, stateWithGlobals); // exits process
         }
         throw error;
       }
@@ -789,7 +775,7 @@ const createCliBuilder = <V, P extends readonly unknown[]>(
 
     parse(
       args: string[] = process.argv.slice(2),
-    ): ParseResult<V, P> & { command?: string; earlyExit?: boolean } {
+    ): ParseResult<V, P> & { command?: string } {
       try {
         const result = parseCore(state, args, false);
         if (isThenable(result)) {
@@ -800,28 +786,22 @@ const createCliBuilder = <V, P extends readonly unknown[]>(
         return result as ParseResult<V, P> & { command?: string };
       } catch (error) {
         if (error instanceof HelpError) {
-          return handleHelpError(error, state) as ParseResult<V, P> & {
-            command?: string;
-            earlyExit: true;
-          };
+          handleHelpError(error, state); // exits process, never returns
         }
         throw error;
       }
     },
 
     async parseAsync(
       args: string[] = process.argv.slice(2),
-    ): Promise<ParseResult<V, P> & { command?: string; earlyExit?: boolean }> {
+    ): Promise<ParseResult<V, P> & { command?: string }> {
       try {
         return (await parseCore(state, args, true)) as ParseResult<V, P> & {
           command?: string;
         };
       } catch (error) {
         if (error instanceof HelpError) {
-          return handleHelpError(error, state) as ParseResult<V, P> & {
-            command?: string;
-            earlyExit: true;
-          };
+          handleHelpError(error, state); // exits process, never returns
         }
         throw error;
       }
@@ -849,19 +829,17 @@ const parseCore = (
   const { aliasMap, commands, options, theme } = state;
 
   /**
-   * Helper to create an early-exit result (for help, version, completions).
-   * Sets process.exitCode and returns a result with earlyExit: true.
+   * Terminates the process for early-exit scenarios (--help, --version,
+   * --completion-script). This is standard CLI behavior - users expect these
+   * flags to print output and exit immediately.
    *
+   * @remarks
+   * The return statement exists only to satisfy TypeScript. In practice,
+   * `process.exit()` terminates the process and this function never returns.
    * @function
    */
-  const createEarlyExitResult = (
-    exitCode: number,
-  ): ParseResult<unknown, readonly unknown[]> & {
-    command?: string;
-    earlyExit: true;
-  } => {
-    process.exitCode = exitCode;
-    return { command: undefined, earlyExit: true, positionals: [], values: {} };
+  const exitProcess = (exitCode: number): never => {
+    process.exit(exitCode);
   };
 
   // Handle --help
@@ -909,12 +887,12 @@ const parseCore = (
 
         // Regular command help
         console.log(generateCommandHelpNew(state, commandName, theme));
-        return createEarlyExitResult(0);
+        return exitProcess(0);
       }
     }
 
     console.log(generateHelpNew(state, theme));
-    return createEarlyExitResult(0);
+    return exitProcess(0);
   }
 
   // Handle --version
@@ -925,7 +903,7 @@ const parseCore = (
     } else {
       console.log('Version information not available');
     }
-    return createEarlyExitResult(0);
+    return exitProcess(0);
   }
 
   // Handle shell completion (when enabled)
@@ -938,15 +916,15 @@ const parseCore = (
         console.error(
           'Error: --completion-script requires a shell argument (bash, zsh, or fish)',
         );
-        return createEarlyExitResult(1);
+        return exitProcess(1);
       }
       try {
         const shell = validateShell(shellArg);
         console.log(generateCompletionScript(state.name, shell));
-        return createEarlyExitResult(0);
+        return exitProcess(0);
       } catch (err) {
         console.error(`Error: ${(err as Error).message}`);
-        return createEarlyExitResult(1);
+        return exitProcess(1);
       }
     }
 
@@ -956,7 +934,7 @@ const parseCore = (
       const shellArg = args[getCompletionsIndex + 1];
       if (!shellArg) {
         // No shell specified, output nothing
-        return createEarlyExitResult(0);
+        return exitProcess(0);
       }
       try {
         const shell = validateShell(shellArg);
@@ -966,10 +944,10 @@ const parseCore = (
         if (candidates.length > 0) {
           console.log(candidates.join('\n'));
         }
-        return createEarlyExitResult(0);
+        return exitProcess(0);
       } catch {
         // Invalid shell, output nothing
-        return createEarlyExitResult(0);
+        return exitProcess(0);
       }
     }
   }
@@ -985,31 +963,22 @@ const parseCore = (
 
 /**
  * Show help for a nested command group by delegating to the nested builder.
+ * This function always terminates the process (either via the nested builder's
+ * help handling or via error exit).
  *
  * @function
  */
 const showNestedCommandHelp = (
   state: InternalCliState,
   commandName: string,
-):
-  | (ParseResult<unknown, readonly unknown[]> & {
-      command?: string;
-      earlyExit?: boolean;
-    })
-  | Promise<
-      ParseResult<unknown, readonly unknown[]> & {
-        command?: string;
-        earlyExit?: boolean;
-      }
-    > => {
+): never => {
   const commandEntry = state.commands.get(commandName);
   if (!commandEntry || commandEntry.type !== 'nested') {
     console.error(`Unknown command group: ${commandName}`);
-    process.exitCode = 1;
-    return { command: undefined, earlyExit: true, positionals: [], values: {} };
+    process.exit(1);
   }
 
-  // Delegate to nested builder with --help
+  // Delegate to nested builder with --help - this will exit the process
   const internalNestedBuilder = commandEntry.builder as InternalCliBuilder<
     unknown,
     readonly unknown[]
@@ -1019,12 +988,18 @@ const showNestedCommandHelp = (
     values: {},
   };
 
-  // This will show the nested builder's help
-  return internalNestedBuilder.__parseWithParentGlobals(
+  // This will show the nested builder's help and exit the process.
+  // The void operator explicitly marks this as intentionally unhandled since
+  // process.exit() inside will terminate before the promise resolves.
+  void internalNestedBuilder.__parseWithParentGlobals(
     ['--help'],
     emptyGlobals,
     true,
   );
+
+  // This should never be reached since help handling calls process.exit()
+  // but TypeScript needs it for the never return type
+  process.exit(0);
 };
 
 /**
@@ -1131,13 +1106,15 @@ const generateHelpNew = (state: InternalCliState, theme: Theme): string => {
  *
  * @function
  */
-const handleHelpError = (
-  error: HelpError,
-  state: InternalCliState,
-): ParseResult<unknown, readonly unknown[]> & {
-  command?: string;
-  earlyExit: true;
-} => {
+/**
+ * Handles HelpError by displaying the error message, showing help, and
+ * terminating the process with exit code 1. This is standard CLI behavior -
+ * when a user provides an unknown command or forgets to specify a required
+ * command, they see help and the process exits.
+ *
+ * @function
+ */
+const handleHelpError = (error: HelpError, state: InternalCliState): never => {
   const { theme } = state;
 
   // Write error message to stderr
@@ -1148,16 +1125,8 @@ const handleHelpError = (
   process.stderr.write(helpText);
   process.stderr.write('\n');
 
-  // Set exit code to indicate error (don't call process.exit())
-  process.exitCode = 1;
-
-  // Return a result indicating help was shown
-  return {
-    command: error.command,
-    earlyExit: true,
-    positionals: [],
-    values: {},
-  };
+  // Terminate with error exit code
+  process.exit(1);
 };
 
 /**

src/types.ts

@@ -163,28 +163,28 @@ export interface CliBuilder<
    *
    * Throws if any transform or handler returns a Promise.
    *
-   * When an early exit occurs (--help, --version, --completion-script, or
-   * HelpError), output is displayed, process.exitCode is set appropriately, and
-   * a result with `earlyExit: true` is returned instead of throwing.
+   * @remarks
+   * Early exit scenarios (`--help`, `--version`, `--completion-script`, or
+   * invalid/missing commands) will call `process.exit()` and never return. This
+   * is standard CLI behavior.
    */
   parse(args?: string[]): ParseResult<TGlobalValues, TGlobalPositionals> & {
     command?: string;
-    earlyExit?: boolean;
   };
 
   /**
    * Parse arguments asynchronously and run handlers.
    *
    * Supports async transforms and handlers.
    *
-   * When an early exit occurs (--help, --version, --completion-script, or
-   * HelpError), output is displayed, process.exitCode is set appropriately, and
-   * a result with `earlyExit: true` is returned instead of rejecting.
+   * @remarks
+   * Early exit scenarios (`--help`, `--version`, `--completion-script`, or
+   * invalid/missing commands) will call `process.exit()` and never return. This
+   * is standard CLI behavior.
    */
   parseAsync(args?: string[]): Promise<
     ParseResult<TGlobalValues, TGlobalPositionals> & {
       command?: string;
-      earlyExit?: boolean;
     }
   >;
 }