fix: catch HelpError and display help instead of throwing

When a HelpError is thrown (e.g., unknown command, no command specified),
`parse()` and `parseAsync()` now catch it and handle gracefully:

- Error message is printed to stderr
- Help text is displayed to stderr
- `process.exitCode` is set to 1 (no `process.exit()` call)
- Returns result with `helpShown: true` flag

This prevents HelpError from bubbling up to global exception handlers
while still providing useful feedback to the user.

Closes #31

Author: boneskull

src/bargs.ts

@@ -760,22 +760,42 @@ const createCliBuilder = <V, P extends readonly unknown[]>(
 
     parse(
       args: string[] = process.argv.slice(2),
-    ): ParseResult<V, P> & { command?: string } {
-      const result = parseCore(state, args, false);
-      if (isThenable(result)) {
-        throw new BargsError(
-          'Async transform or handler detected. Use parseAsync() instead of parse().',
-        );
+    ): ParseResult<V, P> & { command?: string; helpShown?: boolean } {
+      try {
+        const result = parseCore(state, args, false);
+        if (isThenable(result)) {
+          throw new BargsError(
+            'Async transform or handler detected. Use parseAsync() instead of parse().',
+          );
+        }
+        return result as ParseResult<V, P> & { command?: string };
+      } catch (error) {
+        if (error instanceof HelpError) {
+          return handleHelpError(error, state) as ParseResult<V, P> & {
+            command?: string;
+            helpShown: true;
+          };
+        }
+        throw error;
       }
-      return result as ParseResult<V, P> & { command?: string };
     },
 
     async parseAsync(
       args: string[] = process.argv.slice(2),
-    ): Promise<ParseResult<V, P> & { command?: string }> {
-      return parseCore(state, args, true) as Promise<
-        ParseResult<V, P> & { command?: string }
-      >;
+    ): Promise<ParseResult<V, P> & { command?: string; helpShown?: boolean }> {
+      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;
+            helpShown: true;
+          };
+        }
+        throw error;
+      }
     },
   };
 
@@ -1053,6 +1073,44 @@ const generateHelpNew = (state: InternalCliState, theme: Theme): string => {
 };
 /* c8 ignore stop */
 
+/**
+ * Handle a HelpError by displaying the error message and help text to stderr,
+ * setting the exit code, and returning a result indicating help was shown.
+ *
+ * This prevents HelpError from bubbling up to global exception handlers while
+ * still providing useful feedback to the user.
+ *
+ * @function
+ */
+const handleHelpError = (
+  error: HelpError,
+  state: InternalCliState,
+): ParseResult<unknown, readonly unknown[]> & {
+  command?: string;
+  helpShown: true;
+} => {
+  const { theme } = state;
+
+  // Write error message to stderr
+  process.stderr.write(`Error: ${error.message}\n\n`);
+
+  // Generate and write help text to stderr
+  const helpText = generateHelpNew(state, theme);
+  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,
+    helpShown: true,
+    positionals: [],
+    values: {},
+  };
+};
+
 /**
  * Check if something is a Parser (has __brand: 'Parser'). Parsers can be either
  * objects or functions (CallableParser).

src/types.ts

@@ -162,20 +162,30 @@ export interface CliBuilder<
    * Parse arguments synchronously and run handlers.
    *
    * Throws if any transform or handler returns a Promise.
+   *
+   * When a HelpError occurs (e.g., unknown command, no command specified), help
+   * text is displayed to stderr, process.exitCode is set to 1, and a result
+   * with `helpShown: true` is returned instead of throwing.
    */
-  parse(
-    args?: string[],
-  ): ParseResult<TGlobalValues, TGlobalPositionals> & { command?: string };
+  parse(args?: string[]): ParseResult<TGlobalValues, TGlobalPositionals> & {
+    command?: string;
+    helpShown?: boolean;
+  };
 
   /**
    * Parse arguments asynchronously and run handlers.
    *
    * Supports async transforms and handlers.
+   *
+   * When a HelpError occurs (e.g., unknown command, no command specified), help
+   * text is displayed to stderr, process.exitCode is set to 1, and a result
+   * with `helpShown: true` is returned instead of rejecting.
    */
-  parseAsync(
-    args?: string[],
-  ): Promise<
-    ParseResult<TGlobalValues, TGlobalPositionals> & { command?: string }
+  parseAsync(args?: string[]): Promise<
+    ParseResult<TGlobalValues, TGlobalPositionals> & {
+      command?: string;
+      helpShown?: boolean;
+    }
   >;
 }
 

test/bargs.test.ts

@@ -1,7 +1,7 @@
 /**
  * Tests for the main bargs API.
  */
-import { expect, expectAsync } from 'bupkis';
+import { expect } from 'bupkis';
 import { describe, it } from 'node:test';
 
 import type { StringOption } from '../src/types.js';
@@ -189,17 +189,31 @@ describe('.parseAsync()', () => {
     expect(handlerCalled, 'to be', true);
   });
 
-  it('throws on unknown command', async () => {
-    const cli = bargs('test-cli').command(
-      'greet',
-      handle(opt.options({}), () => {}),
-    );
+  it('handles unknown command by showing help and setting exitCode', async () => {
+    const originalExitCode = process.exitCode;
+    const stderrWrites: string[] = [];
+    const originalStderrWrite = process.stderr.write.bind(process.stderr);
 
-    await expectAsync(
-      cli.parseAsync(['unknown']),
-      'to reject with error satisfying',
-      /Unknown command/,
-    );
+    process.stderr.write = ((chunk: unknown) => {
+      stderrWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+
+    try {
+      const cli = bargs('test-cli').command(
+        'greet',
+        handle(opt.options({}), () => {}),
+      );
+
+      const result = await cli.parseAsync(['unknown']);
+
+      expect(result.helpShown, 'to be true');
+      expect(process.exitCode, 'to equal', 1);
+      expect(stderrWrites.join(''), 'to contain', 'Unknown command: unknown');
+    } finally {
+      process.stderr.write = originalStderrWrite;
+      process.exitCode = originalExitCode;
+    }
   });
 
   it('returns parsed result with command name', async () => {
@@ -786,23 +800,108 @@ describe('merge() edge cases', () => {
 });
 
 describe('error paths', () => {
-  it('throws HelpError when no command specified and no default', async () => {
-    const cli = bargs('test-cli')
-      .command(
-        'run',
-        handle(opt.options({}), () => {}),
-      )
-      .command(
-        'build',
-        handle(opt.options({}), () => {}),
-      );
-    // No defaultCommand set
+  describe('HelpError handling', () => {
+    it('catches HelpError on no command, displays help, and sets exitCode', async () => {
+      const originalExitCode = process.exitCode;
+      const stderrWrites: string[] = [];
+      const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+      // Capture stderr
+      process.stderr.write = ((chunk: unknown) => {
+        stderrWrites.push(String(chunk));
+        return true;
+      }) as typeof process.stderr.write;
+
+      try {
+        const cli = bargs('test-cli')
+          .command(
+            'run',
+            handle(opt.options({}), () => {}),
+          )
+          .command(
+            'build',
+            handle(opt.options({}), () => {}),
+          );
+
+        // This should NOT throw - it should catch HelpError and handle it
+        const result = await cli.parseAsync([]);
+
+        // Verify exitCode was set to 1
+        expect(process.exitCode, 'to equal', 1);
+
+        // Verify error message was shown
+        const output = stderrWrites.join('');
+        expect(output, 'to contain', 'No command specified');
+
+        // Verify help was displayed
+        expect(output, 'to contain', 'USAGE');
+        expect(output, 'to contain', 'COMMANDS');
+
+        // Verify result indicates help was shown
+        expect(result.helpShown, 'to be true');
+      } finally {
+        process.stderr.write = originalStderrWrite;
+        process.exitCode = originalExitCode;
+      }
+    });
 
-    await expectAsync(
-      cli.parseAsync([]),
-      'to reject with error satisfying',
-      /No command specified/,
-    );
+    it('catches HelpError on unknown command, displays help, and sets exitCode', async () => {
+      const originalExitCode = process.exitCode;
+      const stderrWrites: string[] = [];
+      const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+      process.stderr.write = ((chunk: unknown) => {
+        stderrWrites.push(String(chunk));
+        return true;
+      }) as typeof process.stderr.write;
+
+      try {
+        const cli = bargs('test-cli').command(
+          'run',
+          handle(opt.options({}), () => {}),
+        );
+
+        const result = await cli.parseAsync(['unknown-command']);
+
+        expect(process.exitCode, 'to equal', 1);
+
+        const output = stderrWrites.join('');
+        expect(output, 'to contain', 'Unknown command: unknown-command');
+        expect(output, 'to contain', 'USAGE');
+
+        expect(result.helpShown, 'to be true');
+      } finally {
+        process.stderr.write = originalStderrWrite;
+        process.exitCode = originalExitCode;
+      }
+    });
+
+    it('catches HelpError in sync parse() as well', () => {
+      const originalExitCode = process.exitCode;
+      const stderrWrites: string[] = [];
+      const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+      process.stderr.write = ((chunk: unknown) => {
+        stderrWrites.push(String(chunk));
+        return true;
+      }) as typeof process.stderr.write;
+
+      try {
+        const cli = bargs('test-cli').command(
+          'run',
+          handle(opt.options({}), () => {}),
+        );
+
+        const result = cli.parse([]);
+
+        expect(process.exitCode, 'to equal', 1);
+        expect(stderrWrites.join(''), 'to contain', 'No command specified');
+        expect(result.helpShown, 'to be true');
+      } finally {
+        process.stderr.write = originalStderrWrite;
+        process.exitCode = originalExitCode;
+      }
+    });
   });
 
   it('handles async global transform in nested commands', async () => {

test/parser-commands.test.ts

@@ -4,7 +4,7 @@
  * These tests focus on command dispatching and parsing behaviors complementary
  * to the tests in bargs.test.ts.
  */
-import { expect, expectAsync } from 'bupkis';
+import { expect } from 'bupkis';
 import { describe, it } from 'node:test';
 
 import { bargs, handle } from '../src/bargs.js';
@@ -96,22 +96,36 @@ describe('command parsing', () => {
     });
   });
 
-  it('throws on unknown command', async () => {
-    const cli = bargs('test-cli')
-      .command(
-        'add',
-        handle(opt.options({}), () => {}),
-      )
-      .command(
-        'remove',
-        handle(opt.options({}), () => {}),
-      );
-
-    await expectAsync(
-      cli.parseAsync(['unknown']),
-      'to reject with error satisfying',
-      /Unknown command: unknown/,
-    );
+  it('handles unknown command by showing help and setting exitCode', async () => {
+    const originalExitCode = process.exitCode;
+    const stderrWrites: string[] = [];
+    const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+    process.stderr.write = ((chunk: unknown) => {
+      stderrWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+
+    try {
+      const cli = bargs('test-cli')
+        .command(
+          'add',
+          handle(opt.options({}), () => {}),
+        )
+        .command(
+          'remove',
+          handle(opt.options({}), () => {}),
+        );
+
+      const result = await cli.parseAsync(['unknown']);
+
+      expect(result.helpShown, 'to be true');
+      expect(process.exitCode, 'to equal', 1);
+      expect(stderrWrites.join(''), 'to contain', 'Unknown command: unknown');
+    } finally {
+      process.stderr.write = originalStderrWrite;
+      process.exitCode = originalExitCode;
+    }
   });
 
   it('merges global and command options', async () => {