@boneskull/bargs 0.1.1

package/dist/bargs.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bargs.js","sourceRoot":"","sources":["../src/bargs.ts"],"names":[],"mappings":"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"}

package/dist/bargs.d.cts

@@ -0,0 +1,31 @@
+/**
+ * Core bargs parsing functions for both sync and async CLI execution.
+ *
+ * Provides `bargs()` (synchronous) and `bargsAsync()` (asynchronous) entry
+ * points that handle configuration validation, built-in `--help` and
+ * `--version` flags, argument parsing, and handler invocation. Supports both
+ * simple CLIs with options/positionals and command-based CLIs with
+ * subcommands.
+ *
+ * @packageDocumentation
+ */
+import type { BargsConfig, BargsConfigWithCommands, BargsOptions, BargsResult, CommandConfigInput, InferOptions, InferPositionals, OptionsSchema, PositionalsSchema } from "./types.cjs";
+/**
+ * Main bargs entry point for simple CLIs (no commands) - sync version. Throws
+ * if any handler returns a thenable.
+ */
+export declare function bargs<TOptions extends OptionsSchema, TPositionals extends PositionalsSchema>(config: BargsConfig<TOptions, TPositionals, undefined>, options?: BargsOptions): BargsResult<InferOptions<TOptions>, InferPositionals<TPositionals>, undefined>;
+/**
+ * Main bargs entry point for command-based CLIs - sync version. Throws if any
+ * handler returns a thenable.
+ */
+export declare function bargs<TOptions extends OptionsSchema, TCommands extends Record<string, CommandConfigInput>>(config: BargsConfigWithCommands<TOptions, TCommands>, options?: BargsOptions): BargsResult<InferOptions<TOptions>, unknown[], string | undefined>;
+/**
+ * Main bargs entry point for simple CLIs (no commands) - async version.
+ */
+export declare function bargsAsync<TOptions extends OptionsSchema, TPositionals extends PositionalsSchema>(config: BargsConfig<TOptions, TPositionals, undefined>, options?: BargsOptions): Promise<BargsResult<InferOptions<TOptions>, InferPositionals<TPositionals>, undefined>>;
+/**
+ * Main bargs entry point for command-based CLIs - async version.
+ */
+export declare function bargsAsync<TOptions extends OptionsSchema, TCommands extends Record<string, CommandConfigInput>>(config: BargsConfigWithCommands<TOptions, TCommands>, options?: BargsOptions): Promise<BargsResult<InferOptions<TOptions>, unknown[], string | undefined>>;
+//# sourceMappingURL=bargs.d.ts.map

package/dist/bargs.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bargs.d.ts","sourceRoot":"","sources":["../src/bargs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,uBAAuB,EACvB,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EAClB,oBAAmB;AAsIpB;;;GAGG;AACH,wBAAgB,KAAK,CACnB,QAAQ,SAAS,aAAa,EAC9B,YAAY,SAAS,iBAAiB,EAEtC,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC,EACtD,OAAO,CAAC,EAAE,YAAY,GACrB,WAAW,CACZ,YAAY,CAAC,QAAQ,CAAC,EACtB,gBAAgB,CAAC,YAAY,CAAC,EAC9B,SAAS,CACV,CAAC;AAEF;;;GAGG;AACH,wBAAgB,KAAK,CACnB,QAAQ,SAAS,aAAa,EAC9B,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAEpD,MAAM,EAAE,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,EACpD,OAAO,CAAC,EAAE,YAAY,GACrB,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAiDtE;;GAEG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,SAAS,aAAa,EAC9B,YAAY,SAAS,iBAAiB,EAEtC,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC,EACtD,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CACR,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,CAC/E,CAAC;AAEF;;GAEG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,SAAS,aAAa,EAC9B,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAEpD,MAAM,EAAE,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,EACpD,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC"}

package/dist/bargs.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Core bargs parsing functions for both sync and async CLI execution.
+ *
+ * Provides `bargs()` (synchronous) and `bargsAsync()` (asynchronous) entry
+ * points that handle configuration validation, built-in `--help` and
+ * `--version` flags, argument parsing, and handler invocation. Supports both
+ * simple CLIs with options/positionals and command-based CLIs with
+ * subcommands.
+ *
+ * @packageDocumentation
+ */
+import type { BargsConfig, BargsConfigWithCommands, BargsOptions, BargsResult, CommandConfigInput, InferOptions, InferPositionals, OptionsSchema, PositionalsSchema } from "./types.js";
+/**
+ * Main bargs entry point for simple CLIs (no commands) - sync version. Throws
+ * if any handler returns a thenable.
+ */
+export declare function bargs<TOptions extends OptionsSchema, TPositionals extends PositionalsSchema>(config: BargsConfig<TOptions, TPositionals, undefined>, options?: BargsOptions): BargsResult<InferOptions<TOptions>, InferPositionals<TPositionals>, undefined>;
+/**
+ * Main bargs entry point for command-based CLIs - sync version. Throws if any
+ * handler returns a thenable.
+ */
+export declare function bargs<TOptions extends OptionsSchema, TCommands extends Record<string, CommandConfigInput>>(config: BargsConfigWithCommands<TOptions, TCommands>, options?: BargsOptions): BargsResult<InferOptions<TOptions>, unknown[], string | undefined>;
+/**
+ * Main bargs entry point for simple CLIs (no commands) - async version.
+ */
+export declare function bargsAsync<TOptions extends OptionsSchema, TPositionals extends PositionalsSchema>(config: BargsConfig<TOptions, TPositionals, undefined>, options?: BargsOptions): Promise<BargsResult<InferOptions<TOptions>, InferPositionals<TPositionals>, undefined>>;
+/**
+ * Main bargs entry point for command-based CLIs - async version.
+ */
+export declare function bargsAsync<TOptions extends OptionsSchema, TCommands extends Record<string, CommandConfigInput>>(config: BargsConfigWithCommands<TOptions, TCommands>, options?: BargsOptions): Promise<BargsResult<InferOptions<TOptions>, unknown[], string | undefined>>;
+//# sourceMappingURL=bargs.d.ts.map

package/dist/bargs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bargs.d.ts","sourceRoot":"","sources":["../src/bargs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,uBAAuB,EACvB,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EAClB,mBAAmB;AAsIpB;;;GAGG;AACH,wBAAgB,KAAK,CACnB,QAAQ,SAAS,aAAa,EAC9B,YAAY,SAAS,iBAAiB,EAEtC,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC,EACtD,OAAO,CAAC,EAAE,YAAY,GACrB,WAAW,CACZ,YAAY,CAAC,QAAQ,CAAC,EACtB,gBAAgB,CAAC,YAAY,CAAC,EAC9B,SAAS,CACV,CAAC;AAEF;;;GAGG;AACH,wBAAgB,KAAK,CACnB,QAAQ,SAAS,aAAa,EAC9B,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAEpD,MAAM,EAAE,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,EACpD,OAAO,CAAC,EAAE,YAAY,GACrB,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAiDtE;;GAEG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,SAAS,aAAa,EAC9B,YAAY,SAAS,iBAAiB,EAEtC,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,CAAC,EACtD,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CACR,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,CAC/E,CAAC;AAEF;;GAEG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,SAAS,aAAa,EAC9B,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAEpD,MAAM,EAAE,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,EACpD,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC"}

package/dist/bargs.js

@@ -0,0 +1,163 @@
+/**
+ * Core bargs parsing functions for both sync and async CLI execution.
+ *
+ * Provides `bargs()` (synchronous) and `bargsAsync()` (asynchronous) entry
+ * points that handle configuration validation, built-in `--help` and
+ * `--version` flags, argument parsing, and handler invocation. Supports both
+ * simple CLIs with options/positionals and command-based CLIs with
+ * subcommands.
+ *
+ * @packageDocumentation
+ */
+import { HelpError } from "./errors.js";
+import { generateCommandHelp, generateHelp } from "./help.js";
+import { parseCommandsAsync, parseCommandsSync, parseSimple, runHandlers, runSyncHandlers, } from "./parser.js";
+import { defaultTheme, getTheme } from "./theme.js";
+import { validateConfig } from "./validate.js";
+/**
+ * Check if config has commands.
+ */
+const hasCommands = (config) => config.commands !== undefined && Object.keys(config.commands).length > 0;
+/**
+ * Check if user defined their own help option (by name or alias).
+ */
+const hasUserDefinedHelp = (options) => {
+    if (!options) {
+        return false;
+    }
+    if ('help' in options) {
+        return true;
+    }
+    // Check if any option has 'h' as an alias
+    return Object.values(options).some((opt) => opt.aliases?.includes('h'));
+};
+/**
+ * Check if user defined their own version option (by name or alias).
+ */
+const hasUserDefinedVersion = (options) => {
+    if (!options) {
+        return false;
+    }
+    if ('version' in options) {
+        return true;
+    }
+    // Check if any option has 'V' as an alias
+    return Object.values(options).some((opt) => opt.aliases?.includes('V'));
+};
+/**
+ * Handle help and version flags. Returns true if we should exit.
+ */
+const handleBuiltinFlags = (config, args, theme = defaultTheme) => {
+    // Handle --help (unless user defined their own help option)
+    const userDefinedHelp = hasUserDefinedHelp(config.options);
+    if (!userDefinedHelp && (args.includes('--help') || args.includes('-h'))) {
+        if (hasCommands(config)) {
+            // Check for command-specific help: cmd --help
+            const helpIndex = args.findIndex((a) => a === '--help' || a === '-h');
+            const commandIndex = args.findIndex((a) => !a.startsWith('-'));
+            if (commandIndex >= 0 && commandIndex < helpIndex) {
+                const commandName = args[commandIndex];
+                console.log(generateCommandHelp(config, commandName, theme));
+            }
+            else {
+                console.log(generateHelp(config, theme));
+            }
+        }
+        else {
+            console.log(generateHelp(config, theme));
+        }
+        process.exit(0);
+    }
+    // Handle --version (unless user defined their own version option)
+    const userDefinedVersion = hasUserDefinedVersion(config.options);
+    if (!userDefinedVersion && args.includes('--version') && config.version) {
+        console.log(config.version);
+        process.exit(0);
+    }
+    return false;
+};
+/**
+ * Handle HelpError by printing message and help text.
+ */
+const handleHelpError = (error, config, theme = defaultTheme) => {
+    if (error instanceof HelpError) {
+        console.error(error.message);
+        if (hasCommands(config)) {
+            console.log(generateHelp(config, theme));
+        }
+        else {
+            console.log(generateHelp(config, theme));
+        }
+        process.exit(1);
+    }
+    throw error;
+};
+/**
+ * Main bargs entry point (sync implementation). Throws BargsError if any
+ * handler returns a thenable.
+ */
+export function bargs(config, options) {
+    // Validate config upfront (throws ValidationError if invalid)
+    validateConfig(config);
+    const args = config.args ?? process.argv.slice(2);
+    const theme = options?.theme
+        ? getTheme(options.theme)
+        : getTheme('default');
+    try {
+        handleBuiltinFlags(config, args, theme);
+        // Parse
+        if (hasCommands(config)) {
+            return parseCommandsSync({ ...config, args });
+        }
+        else {
+            const result = parseSimple({
+                args,
+                options: config.options,
+                positionals: config.positionals,
+            });
+            // Call handler(s) if provided (sync)
+            if (config.handler) {
+                runSyncHandlers(config.handler, result);
+            }
+            return result;
+        }
+    }
+    catch (error) {
+        return handleHelpError(error, config, theme);
+    }
+}
+/**
+ * Main bargs entry point (async implementation). Awaits all handlers,
+ * supporting async handlers.
+ */
+export async function bargsAsync(config, options) {
+    // Validate config upfront (throws ValidationError if invalid)
+    validateConfig(config);
+    const args = config.args ?? process.argv.slice(2);
+    const theme = options?.theme
+        ? getTheme(options.theme)
+        : getTheme('default');
+    try {
+        handleBuiltinFlags(config, args, theme);
+        // Parse
+        if (hasCommands(config)) {
+            return await parseCommandsAsync({ ...config, args });
+        }
+        else {
+            const result = parseSimple({
+                args,
+                options: config.options,
+                positionals: config.positionals,
+            });
+            // Call handler(s) if provided (async)
+            if (config.handler) {
+                await runHandlers(config.handler, result);
+            }
+            return result;
+        }
+    }
+    catch (error) {
+        return handleHelpError(error, config, theme);
+    }
+}
+//# sourceMappingURL=bargs.js.map

package/dist/bargs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bargs.js","sourceRoot":"","sources":["../src/bargs.ts"],"names":[],"mappings":"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"}

package/dist/errors.cjs

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Custom error classes for bargs.
+ *
+ * Defines the error hierarchy used throughout bargs:
+ *
+ * - {@link BargsError} - Base class for all bargs errors
+ * - {@link HelpError} - Triggers help text display when user needs guidance
+ * - {@link ValidationError} - Thrown when configuration validation fails
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = exports.HelpError = exports.BargsError = void 0;
+/**
+ * Custom error class for bargs errors.
+ */
+class BargsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BargsError';
+    }
+}
+exports.BargsError = BargsError;
+/**
+ * Error that triggers help text display. Thrown when the user needs guidance.
+ *
+ * @param message - Error message to show before help text
+ * @param command - Command name for command-specific help, undefined for
+ *   general help
+ */
+class HelpError extends BargsError {
+    command;
+    constructor(message, command) {
+        super(message);
+        this.name = 'HelpError';
+        this.command = command;
+    }
+}
+exports.HelpError = HelpError;
+/**
+ * Error thrown when bargs config validation fails.
+ *
+ * @param message - Description of what's invalid
+ * @param path - Dot-notation path to the invalid property (e.g.,
+ *   "options.verbose.aliases[0]")
+ */
+class ValidationError extends BargsError {
+    path;
+    constructor(path, message) {
+        super(`Invalid config at "${path}": ${message}`);
+        this.name = 'ValidationError';
+        this.path = path;
+    }
+}
+exports.ValidationError = ValidationError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH;;GAEG;AACH,MAAa,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AALD,gCAKC;AAED;;;;;;GAMG;AACH,MAAa,SAAU,SAAQ,UAAU;IAC9B,OAAO,CAAU;IAE1B,YAAY,OAAe,EAAE,OAAgB;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AARD,8BAQC;AAED;;;;;;GAMG;AACH,MAAa,eAAgB,SAAQ,UAAU;IACpC,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,sBAAsB,IAAI,MAAM,OAAO,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AARD,0CAQC"}

package/dist/errors.d.cts

@@ -0,0 +1,40 @@
+/**
+ * Custom error classes for bargs.
+ *
+ * Defines the error hierarchy used throughout bargs:
+ *
+ * - {@link BargsError} - Base class for all bargs errors
+ * - {@link HelpError} - Triggers help text display when user needs guidance
+ * - {@link ValidationError} - Thrown when configuration validation fails
+ *
+ * @packageDocumentation
+ */
+/**
+ * Custom error class for bargs errors.
+ */
+export declare class BargsError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error that triggers help text display. Thrown when the user needs guidance.
+ *
+ * @param message - Error message to show before help text
+ * @param command - Command name for command-specific help, undefined for
+ *   general help
+ */
+export declare class HelpError extends BargsError {
+    readonly command?: string;
+    constructor(message: string, command?: string);
+}
+/**
+ * Error thrown when bargs config validation fails.
+ *
+ * @param message - Description of what's invalid
+ * @param path - Dot-notation path to the invalid property (e.g.,
+ *   "options.verbose.aliases[0]")
+ */
+export declare class ValidationError extends BargsError {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,UAAU;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAK9C;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C"}

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Custom error classes for bargs.
+ *
+ * Defines the error hierarchy used throughout bargs:
+ *
+ * - {@link BargsError} - Base class for all bargs errors
+ * - {@link HelpError} - Triggers help text display when user needs guidance
+ * - {@link ValidationError} - Thrown when configuration validation fails
+ *
+ * @packageDocumentation
+ */
+/**
+ * Custom error class for bargs errors.
+ */
+export declare class BargsError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error that triggers help text display. Thrown when the user needs guidance.
+ *
+ * @param message - Error message to show before help text
+ * @param command - Command name for command-specific help, undefined for
+ *   general help
+ */
+export declare class HelpError extends BargsError {
+    readonly command?: string;
+    constructor(message: string, command?: string);
+}
+/**
+ * Error thrown when bargs config validation fails.
+ *
+ * @param message - Description of what's invalid
+ * @param path - Dot-notation path to the invalid property (e.g.,
+ *   "options.verbose.aliases[0]")
+ */
+export declare class ValidationError extends BargsError {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,UAAU;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAK9C;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C"}

package/dist/errors.js

@@ -0,0 +1,51 @@
+/**
+ * Custom error classes for bargs.
+ *
+ * Defines the error hierarchy used throughout bargs:
+ *
+ * - {@link BargsError} - Base class for all bargs errors
+ * - {@link HelpError} - Triggers help text display when user needs guidance
+ * - {@link ValidationError} - Thrown when configuration validation fails
+ *
+ * @packageDocumentation
+ */
+/**
+ * Custom error class for bargs errors.
+ */
+export class BargsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BargsError';
+    }
+}
+/**
+ * Error that triggers help text display. Thrown when the user needs guidance.
+ *
+ * @param message - Error message to show before help text
+ * @param command - Command name for command-specific help, undefined for
+ *   general help
+ */
+export class HelpError extends BargsError {
+    command;
+    constructor(message, command) {
+        super(message);
+        this.name = 'HelpError';
+        this.command = command;
+    }
+}
+/**
+ * Error thrown when bargs config validation fails.
+ *
+ * @param message - Description of what's invalid
+ * @param path - Dot-notation path to the invalid property (e.g.,
+ *   "options.verbose.aliases[0]")
+ */
+export class ValidationError extends BargsError {
+    path;
+    constructor(path, message) {
+        super(`Invalid config at "${path}": ${message}`);
+        this.name = 'ValidationError';
+        this.path = path;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,SAAU,SAAQ,UAAU;IAC9B,OAAO,CAAU;IAE1B,YAAY,OAAe,EAAE,OAAgB;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,eAAgB,SAAQ,UAAU;IACpC,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,sBAAsB,IAAI,MAAM,OAAO,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}