bob-core 3.0.0-beta.1 → 3.0.0-beta.11

package/README.md

@@ -100,7 +100,7 @@ static flags = {
   name:      Flags.string({ required: true, description: 'Your name' }),
   count:     Flags.number({ min: 1, max: 10, default: 1 }),
   force:     Flags.boolean({ alias: 'f' }),
-  level:     Flags.enum({ options: ['debug', 'info', 'warn', 'error'] as const }),
+  level:     Flags.option({ options: ['debug', 'info', 'warn', 'error'] as const }),
   config:    Flags.file({ exists: true, description: 'Config file path' }),
   outDir:    Flags.directory({ exists: true }),
   endpoint:  Flags.url({ description: 'API endpoint' }),
@@ -113,13 +113,13 @@ static flags = {
 | `Flags.string()` | `string` | `secret` |
 | `Flags.number()` | `number` | `min`, `max` |
 | `Flags.boolean()` | `boolean` | |
-| `Flags.enum()` | union of `options` | `options` (readonly tuple) |
+| `Flags.option()` | union of `options` | `options` (readonly tuple) |
 | `Flags.file()` | `string` | `exists` |
 | `Flags.directory()` | `string` | `exists` |
 | `Flags.url()` | `URL` | |
 | `Flags.custom<T>()` | `T` | `parse` (required) |
 
-`Args` is an alias for `Flags` -- use it for semantic clarity when defining `static args`.
+`Args` is a separate builder set from `Flags` (it omits `boolean`) -- use it for semantic clarity when defining `static args`.
 
 Use `satisfies FlagsSchema` on both `static flags` and `static args` to enable full type inference with `Parsed<typeof YourCommand>`.
 

package/dist/cjs/{src/Cli.d.ts → Cli.d.ts}

@@ -10,6 +10,14 @@ export type CliOptions<C extends ContextDefinition = ContextDefinition> = {
     version?: string;
     logger?: Logger;
 };
+/**
+ * CLI host. Wires together a {@link CommandRegistry}, {@link ExceptionHandler},
+ * and the built-in {@link HelpCommand}, and provides the entry point used by
+ * binaries to dispatch a command.
+ *
+ * The `C` generic threads a typed application context through to every command
+ * registered with the CLI.
+ */
 export declare class Cli<C extends ContextDefinition = ContextDefinition> {
     private readonly ctx?;
     private readonly logger;
@@ -22,10 +30,22 @@ export declare class Cli<C extends ContextDefinition = ContextDefinition> {
         logger: Logger;
     }): ExceptionHandler;
     constructor(opts?: CliOptions<C>);
+    /** Registers a custom resolver used by `loadCommandsPath` to import command modules. */
     withCommandResolver(resolver: CommandResolver): this;
+    /** Overrides how command files are imported (useful for tests / virtual filesystems). */
     withFileImporter(importer: FileImporter): this;
+    /**
+     * Registers commands by class, instance, or directory path. String args are
+     * treated as filesystem paths and walked via the registry's resolver.
+     */
     withCommands(...commands: Array<typeof Command<C> | Command<C> | string>): Promise<void>;
+    /**
+     * Resolves and runs a command. Bob errors are formatted by the
+     * {@link ExceptionHandler} and yield a non-zero exit code; non-Bob errors
+     * propagate so they remain visible in stack traces. Returns the exit code.
+     */
     runCommand(command: string | typeof Command | Command | undefined, ...args: string[]): Promise<number>;
+    /** Convenience entry point that prints help with the registered commands. */
     runHelpCommand(): Promise<number>;
     protected registerCommand(command: typeof Command<C>): void;
 }

package/dist/cjs/Command.d.ts

@@ -0,0 +1,91 @@
+import { CommandParser } from './CommandParser.js';
+import { Logger } from './Logger.js';
+import { ArgsSchema, ContextDefinition, FlagsSchema, Parsed } from './lib/types.js';
+import { UX } from './ux/index.js';
+export type CommandRunExample = {
+    description: string;
+    command: string;
+};
+export type CommandRunOption<C = ContextDefinition> = {
+    logger: Logger;
+    ctx: C;
+} & ({
+    args: string[];
+} | {
+    args: Record<string, any>;
+    flags: Record<string, any>;
+});
+/**
+ * Base class for declarative commands.
+ *
+ * Subclasses set static metadata (`command`, `description`, `args`, `flags`,
+ * `examples`, `aliases`, `group`, `hidden`) and implement `handle(ctx, parsed)`.
+ * The framework parses argv, validates against `args`/`flags`, optionally
+ * prompts for missing required values, then invokes `preHandle` (if defined)
+ * and finally `handle`.
+ *
+ * The `C` generic threads a typed application context through to `handle`.
+ */
+export declare abstract class Command<C extends ContextDefinition = ContextDefinition> {
+    /** Discriminator used by `isBobCommandClass` for `instanceof`-free checks. */
+    static $type: "BobCommand";
+    /** Canonical command name typed at the CLI (e.g. `"deploy"`, `"db:migrate"`). */
+    static command: string;
+    /** One-line description rendered in `help`. */
+    static description: string;
+    /** Optional grouping label for the help screen — defaults to the prefix before `:` if any. */
+    static group?: string;
+    /** Positional argument schema (use `Args.*` builders). */
+    static args: ArgsSchema;
+    /** Named flag schema (use `Flags.*` builders). */
+    static flags: FlagsSchema;
+    /** Example invocations rendered in `--help`. */
+    static examples: CommandRunExample[];
+    /** When true, the command is omitted from the help index but still runnable. */
+    static hidden: boolean;
+    /** Alternative names that resolve to this command. */
+    static aliases: string[];
+    /** When true, `baseFlags` (including `--help`) are not auto-merged. */
+    static disableDefaultOptions: boolean;
+    /** When true, missing required values will not trigger interactive prompts. */
+    static disablePrompting: boolean;
+    /** When true, unknown flags are accepted instead of throwing `InvalidFlag`. */
+    static allowUnknownFlags: boolean;
+    /** When true, extra positional arguments throw `TooManyArguments`. */
+    static strictMode: boolean;
+    protected ctx: C;
+    protected logger: Logger;
+    protected ux: UX;
+    protected parser: CommandParser<FlagsSchema, ArgsSchema>;
+    /**
+     * Optional pre-handler hook. Returning a non-zero number short-circuits
+     * execution and is propagated as the command's exit code.
+     */
+    protected preHandle?(): Promise<void | number>;
+    /**
+     * Main entry point. Receives the typed context and the parsed flags/args.
+     * Returning a number sets the exit code; void/undefined is treated as 0.
+     */
+    protected abstract handle(ctx: C, parsed: Parsed<any>): Promise<number | void> | number | void;
+    /** Flags merged into every command's flag schema (`--help` by default). */
+    static baseFlags: FlagsSchema;
+    protected newCommandParser(opts: {
+        flags: FlagsSchema;
+        args: ArgsSchema;
+        ctx: ContextDefinition;
+        ux: UX;
+        cmd: typeof Command;
+    }): CommandParser<FlagsSchema, ArgsSchema>;
+    protected newUX(): UX;
+    /**
+     * Runs the command lifecycle. Resolves to the exit code:
+     *   - `0` — success (or `void` from `handle`)
+     *   - returned number from `preHandle` / `handle` for early exits
+     *   - `0` for flag-handler short-circuits like `--help`
+     *
+     * Either parses raw `args: string[]` or accepts pre-parsed `flags`/`args`
+     * objects (used internally to invoke commands programmatically without
+     * re-running the parser).
+     */
+    run(runOpts: CommandRunOption<C>): Promise<number | void>;
+}

package/dist/cjs/CommandParser.d.ts

@@ -0,0 +1,122 @@
+import { Command } from './Command.js';
+import { ArgsSchema, ContextDefinition, FlagDefinition, FlagReturnType, FlagsObject, FlagsSchema } from './lib/types.js';
+import { UX } from './ux/index.js';
+/**
+ * Parses command-line arguments into typed flags and arguments.
+ *
+ * Lifecycle:
+ *   1. `init(argv)` — runs minimist, validates unknown flags, type-converts each
+ *      value via its definition's `parse` function, and resolves defaults.
+ *   2. `validate()` — checks for missing required values; if prompting is
+ *      enabled and the definition declares an `ask` function, the user is
+ *      prompted and the response is fed back through `parse`.
+ *   3. `flag(name)` / `argument(name)` — typed accessors for the parsed values.
+ */
+export declare class CommandParser<Flags extends FlagsSchema, Arguments extends ArgsSchema> {
+    protected opts: {
+        flags: Flags;
+        args: Arguments;
+        ctx?: ContextDefinition;
+        ux: UX;
+        cmd?: typeof Command;
+    };
+    protected flags: FlagsSchema;
+    protected parsedFlags: FlagsObject<Flags> | null;
+    protected args: ArgsSchema;
+    protected parsedArgs: FlagsObject<Arguments> | null;
+    protected ux: UX;
+    protected shouldPromptForMissingFlags: boolean;
+    protected shouldValidateUnknownFlags: boolean;
+    protected shouldRejectExtraArguments: boolean;
+    constructor(opts: {
+        flags: Flags;
+        args: Arguments;
+        ctx?: ContextDefinition;
+        ux: UX;
+        cmd?: typeof Command;
+    });
+    /**
+     * Parses raw command-line arguments into structured flags and arguments.
+     *
+     * @param args - Raw command line arguments (typically from `process.argv.slice(2)`).
+     * @returns Object containing parsed flags and arguments.
+     * @throws {InvalidFlag} If an unknown flag is provided and `allowUnknownFlags` is off.
+     * @throws {BadCommandFlag} If a flag's value cannot be converted by its `parse` function.
+     * @throws {BadCommandArgument} If an argument's value cannot be converted by its `parse` function.
+     * @throws {TooManyArguments} If more positional arguments were supplied than declared and strict mode is on.
+     */
+    init(args: string[]): Promise<{
+        flags: FlagsObject<Flags>;
+        args: FlagsObject<Arguments>;
+    }>;
+    /**
+     * Validates that all required flags and arguments have a value. Prompts for
+     * missing values when prompting is enabled and the definition declares an
+     * `ask` function; otherwise throws.
+     *
+     * @throws {MissingRequiredFlagValue} If a required flag is missing.
+     * @throws {MissingRequiredArgumentValue} If a required argument is missing.
+     * @throws {BadCommandFlag} / {BadCommandArgument} If a prompted value fails to parse.
+     */
+    validate(): Promise<void>;
+    /**
+     * Retrieves a parsed flag value by name. The runtime `defaultValue` is only
+     * used when the parsed value is empty (null/undefined/empty string/empty
+     * array) — it does not override a real value the user supplied.
+     *
+     * @throws {Error} If `init()` has not been called yet.
+     */
+    flag<FlagName extends keyof Flags>(name: FlagName, defaultValue?: FlagReturnType<Flags[FlagName]>): FlagReturnType<Flags[FlagName]>;
+    setFlag<FlagName extends keyof Flags>(name: FlagName, value: FlagReturnType<Flags[FlagName]>): Promise<void>;
+    /**
+     * Retrieves a parsed argument value by name. Same `defaultValue` semantics
+     * as {@link flag}.
+     *
+     * @throws {Error} If `init()` has not been called yet.
+     */
+    argument<ArgName extends keyof Arguments>(name: ArgName, defaultValue?: FlagReturnType<Arguments[ArgName]>): FlagReturnType<Arguments[ArgName]>;
+    setArgument<ArgName extends keyof Arguments>(name: ArgName, value: FlagReturnType<Arguments[ArgName]>): Promise<void>;
+    /**
+     * "Empty" for runtime accessor / required-prompt purposes: null, undefined,
+     * an all-whitespace string, or an empty array. Whitespace strings are
+     * intentionally included so a user typing `--name=" "` is still treated as
+     * not having satisfied a required flag (and so accessor defaults still kick
+     * in for blank values).
+     *
+     * Use {@link isMissing} when you only care whether the user *omitted* a
+     * value — that's the right check for "should I substitute the schema's
+     * default?"
+     */
+    private isEmptyValue;
+    /**
+     * "Missing" for default-substitution purposes: the user did not supply
+     * anything. An empty/whitespace string is *not* missing — the user typed it
+     * and the schema's `parse` should be allowed to accept or reject it.
+     */
+    private isMissing;
+    private validateUnknownFlags;
+    private handleOptions;
+    private handleArguments;
+    private resolveFlagValue;
+    private parseValue;
+    private buildOpts;
+    /**
+     * Wraps a definition's `parse` and converts user-input failures into
+     * {@link BadCommandFlag}/{@link BadCommandArgument}. Programmer bugs (any
+     * error that isn't a {@link ValidationError}) propagate unchanged so they
+     * surface as real stack traces instead of being misreported as "flag value
+     * is invalid".
+     */
+    private safeParse;
+    private validateSchema;
+    /** Disables prompting for missing flag and argument values — useful for non-interactive environments. */
+    disablePrompting(): this;
+    allowUnknownFlags(): this;
+    strictMode(): this;
+    /**
+     * Prompts the user for a missing value via the definition's `ask` function.
+     * Returns `null` if no `ask` is registered or the user cancels — callers
+     * are responsible for translating that into a `MissingRequired*` error.
+     */
+    protected promptFor(name: string, definition: FlagDefinition): Promise<string | number | string[] | boolean | null>;
+}

package/dist/cjs/{src/CommandRegistry.d.ts → CommandRegistry.d.ts}

@@ -26,7 +26,19 @@ export declare class CommandRegistry {
     registerCommand(command: typeof Command<any>, force?: boolean): void;
     loadCommandsPath(commandsPath: string): Promise<void>;
     runCommand(ctx: ContextDefinition, command: string | typeof Command | Command, ...args: string[]): Promise<number>;
+    /**
+     * Looks for a similarly-named command and offers it to the user via prompts.
+     * Returns the resolved command name, or `null` for both "no match" and
+     * "user cancelled / declined the suggestion" — the caller throws
+     * {@link CommandNotFoundError} on `null`. Cancellation is logged at debug
+     * level so it's still distinguishable from "no match" in verbose output.
+     */
     private suggestCommand;
     private askRunSimilarCommand;
+    /**
+     * Recursively yields every importable command file under `basePath`. Errors
+     * from `readdir` are wrapped with the offending path so partial loads
+     * surface a clear cause instead of a bare "ENOENT" / "EACCES".
+     */
     private listCommandsFiles;
 }

package/dist/cjs/ExceptionHandler.d.ts

@@ -0,0 +1,14 @@
+import { LoggerContract } from './contracts/index.js';
+/**
+ * Default error dispatcher used by {@link Cli.runCommand}.
+ *
+ * Renders {@link BobError}s through their `pretty` method and returns `-1` so
+ * the caller can use the value as a process exit code. Any other error type
+ * propagates unchanged — these typically represent programmer bugs and should
+ * not be silently formatted as user-facing errors.
+ */
+export declare class ExceptionHandler {
+    private readonly logger;
+    constructor(logger: LoggerContract);
+    handle(err: Error): number;
+}

package/dist/cjs/HelpFlag.d.ts

@@ -0,0 +1,25 @@
+import { FlagDefinition, FlagOpts } from './lib/types.js';
+export declare const HelpCommandFlag: {
+    [x: string]: unknown;
+} & {
+    parse: (input: any, opts: FlagOpts<boolean, import('./lib/types.js').CustomOptions, any>) => boolean;
+    type?: import('./lib/types.js').FlagKind;
+    ask?: ((opts: FlagOpts<boolean, import('./lib/types.js').CustomOptions, any>) => Promise<any>) | undefined;
+    description?: string;
+    required?: boolean;
+    default?: boolean | boolean[] | (() => boolean | boolean[] | null) | (() => Promise<boolean | boolean[] | null>) | null | undefined;
+    multiple?: boolean;
+    help?: string;
+    alias?: string | readonly string[];
+    handler?: ((value: boolean, opts: FlagOpts<boolean, import('./lib/types.js').CustomOptions, any>) => {
+        shouldStop: boolean;
+    } | void) | undefined;
+} & Partial<FlagDefinition<boolean, import('./lib/types.js').CustomOptions, any>> & {
+    readonly alias: readonly ["h"];
+    readonly description: "Displays help information about the command";
+    readonly handler: (value: boolean, opts: FlagOpts) => {
+        shouldStop: false;
+    } | {
+        shouldStop: true;
+    };
+};

package/dist/cjs/StringSimilarity.d.ts

@@ -0,0 +1,31 @@
+export interface SimilarityResult {
+    rating: number;
+    target: string;
+}
+export interface BestMatchResult {
+    bestMatch: SimilarityResult;
+    bestMatchIndex: number;
+    ratings: SimilarityResult[];
+}
+/**
+ * String similarity calculator using the Jaro-Winkler distance.
+ *
+ * Jaro-Winkler favors strings that share a common prefix, which matches the
+ * shape of CLI typos ("migrat" → "migrate", "user:lis" → "user:list") better
+ * than bigram-based metrics like Dice's Coefficient.
+ */
+export declare class StringSimilarity {
+    /**
+     * Calculate Jaro-Winkler similarity between two strings (0-1 scale).
+     *
+     * A length-ratio guard scales the score down when the inputs differ
+     * significantly in length, so that a short query cannot incidentally match
+     * a much longer candidate just because a few characters line up.
+     */
+    calculateSimilarity(str1: string, str2: string): number;
+    private jaro;
+    /**
+     * Find best matching string and ratings for all candidates
+     */
+    findBestMatch(target: string, candidates: string[]): BestMatchResult;
+}

package/dist/cjs/args/index.d.ts

@@ -0,0 +1,135 @@
+import { custom } from '../flags/custom.js';
+import { optionFlag } from '../flags/option.js';
+/**
+ * Builders for positional arguments (`static args = { ... }`).
+ *
+ * Same surface as {@link Flags} minus `boolean` — booleans don't make sense as
+ * positional inputs and the `ArgsSchema` type rejects them at compile time.
+ */
+export declare const Args: {
+    string: <Ctx extends unknown = any, const O extends Partial<import('../index.js').FlagDefinition<string, import('../index.js').CustomOptions, Ctx>> = Partial<import('../index.js').FlagDefinition<string, import('../index.js').CustomOptions, Ctx>>>(overrides?: O | undefined) => {
+        [x: string]: unknown;
+    } & {
+        parse: (input: any, opts: import('../index.js').FlagOpts<string, import('../index.js').CustomOptions, Ctx>) => string;
+        type?: import('../index.js').FlagKind;
+        ask?: ((opts: import('../index.js').FlagOpts<string, import('../index.js').CustomOptions, Ctx>) => Promise<any>) | undefined;
+        description?: string;
+        required?: boolean;
+        default?: string | string[] | (() => string | string[] | null) | (() => Promise<string | string[] | null>) | null | undefined;
+        multiple?: boolean;
+        help?: string;
+        alias?: string | readonly string[];
+        handler?: ((value: string, opts: import('../index.js').FlagOpts<string, import('../index.js').CustomOptions, Ctx>) => {
+            shouldStop: boolean;
+        } | void) | undefined;
+    } & Partial<import('../index.js').FlagDefinition<string, import('../index.js').CustomOptions, any>> & O;
+    number: <Ctx extends unknown = any, const O extends Partial<import('../index.js').FlagDefinition<number, {
+        min?: number;
+        max?: number;
+    }, Ctx>> = Partial<import('../index.js').FlagDefinition<number, {
+        min?: number;
+        max?: number;
+    }, Ctx>>>(overrides?: O | undefined) => {
+        min?: number | undefined;
+        max?: number | undefined;
+    } & {
+        parse: (input: any, opts: import('../index.js').FlagOpts<number, {
+            min?: number;
+            max?: number;
+        }, Ctx>) => number;
+        type?: import('../index.js').FlagKind;
+        ask?: ((opts: import('../index.js').FlagOpts<number, {
+            min?: number;
+            max?: number;
+        }, Ctx>) => Promise<any>) | undefined;
+        description?: string;
+        required?: boolean;
+        default?: number | number[] | (() => number | number[] | null) | (() => Promise<number | number[] | null>) | null | undefined;
+        multiple?: boolean;
+        help?: string;
+        alias?: string | readonly string[];
+        handler?: ((value: number, opts: import('../index.js').FlagOpts<number, {
+            min?: number;
+            max?: number;
+        }, Ctx>) => {
+            shouldStop: boolean;
+        } | void) | undefined;
+    } & Partial<import('../index.js').FlagDefinition<number, {
+        min?: number;
+        max?: number;
+    }, any>> & O;
+    option: typeof optionFlag;
+    file: <Ctx extends unknown = any, const O extends Partial<import('../index.js').FlagDefinition<string, {
+        exists?: boolean;
+    }, Ctx>> = Partial<import('../index.js').FlagDefinition<string, {
+        exists?: boolean;
+    }, Ctx>>>(overrides?: O | undefined) => {
+        exists?: boolean | undefined;
+    } & {
+        parse: (input: any, opts: import('../index.js').FlagOpts<string, {
+            exists?: boolean;
+        }, Ctx>) => string;
+        type?: import('../index.js').FlagKind;
+        ask?: ((opts: import('../index.js').FlagOpts<string, {
+            exists?: boolean;
+        }, Ctx>) => Promise<any>) | undefined;
+        description?: string;
+        required?: boolean;
+        default?: string | string[] | (() => string | string[] | null) | (() => Promise<string | string[] | null>) | null | undefined;
+        multiple?: boolean;
+        help?: string;
+        alias?: string | readonly string[];
+        handler?: ((value: string, opts: import('../index.js').FlagOpts<string, {
+            exists?: boolean;
+        }, Ctx>) => {
+            shouldStop: boolean;
+        } | void) | undefined;
+    } & Partial<import('../index.js').FlagDefinition<string, {
+        exists?: boolean;
+    }, any>> & O;
+    directory: <Ctx extends unknown = any, const O extends Partial<import('../index.js').FlagDefinition<string, {
+        exists?: boolean;
+    }, Ctx>> = Partial<import('../index.js').FlagDefinition<string, {
+        exists?: boolean;
+    }, Ctx>>>(overrides?: O | undefined) => {
+        exists?: boolean | undefined;
+    } & {
+        parse: (input: any, opts: import('../index.js').FlagOpts<string, {
+            exists?: boolean;
+        }, Ctx>) => string;
+        type?: import('../index.js').FlagKind;
+        ask?: ((opts: import('../index.js').FlagOpts<string, {
+            exists?: boolean;
+        }, Ctx>) => Promise<any>) | undefined;
+        description?: string;
+        required?: boolean;
+        default?: string | string[] | (() => string | string[] | null) | (() => Promise<string | string[] | null>) | null | undefined;
+        multiple?: boolean;
+        help?: string;
+        alias?: string | readonly string[];
+        handler?: ((value: string, opts: import('../index.js').FlagOpts<string, {
+            exists?: boolean;
+        }, Ctx>) => {
+            shouldStop: boolean;
+        } | void) | undefined;
+    } & Partial<import('../index.js').FlagDefinition<string, {
+        exists?: boolean;
+    }, any>> & O;
+    url: <Ctx extends unknown = any, const O extends Partial<import('../index.js').FlagDefinition<URL, import('../index.js').CustomOptions, Ctx>> = Partial<import('../index.js').FlagDefinition<URL, import('../index.js').CustomOptions, Ctx>>>(overrides?: O | undefined) => {
+        [x: string]: unknown;
+    } & {
+        parse: (input: any, opts: import('../index.js').FlagOpts<URL, import('../index.js').CustomOptions, Ctx>) => URL;
+        type?: import('../index.js').FlagKind;
+        ask?: ((opts: import('../index.js').FlagOpts<URL, import('../index.js').CustomOptions, Ctx>) => Promise<any>) | undefined;
+        description?: string;
+        required?: boolean;
+        default?: URL | URL[] | (() => URL | URL[] | null) | (() => Promise<URL | URL[] | null>) | null | undefined;
+        multiple?: boolean;
+        help?: string;
+        alias?: string | readonly string[];
+        handler?: ((value: URL, opts: import('../index.js').FlagOpts<URL, import('../index.js').CustomOptions, Ctx>) => {
+            shouldStop: boolean;
+        } | void) | undefined;
+    } & Partial<import('../index.js').FlagDefinition<URL, import('../index.js').CustomOptions, any>> & O;
+    custom: typeof custom;
+};

package/dist/{esm/src → cjs}/errors/BadCommandArgument.d.ts

@@ -1,4 +1,4 @@
-import { Logger } from '../Logger.js';
+import { LoggerContract } from '../contracts/index.js';
 import { BobError } from './BobError.js';
 import { FlagDefinition } from '../lib/types.js';
 export type ArgumentProps = {
@@ -6,9 +6,11 @@ export type ArgumentProps = {
     value?: any;
     reason?: string;
 };
+/** Thrown when a positional argument's value cannot be converted by its `parse` function. */
 export declare class BadCommandArgument extends BobError {
     readonly detail: ArgumentProps;
     readonly argDefinition?: FlagDefinition | undefined;
+    readonly $type: "BadCommandArgument";
     constructor(detail: ArgumentProps, argDefinition?: FlagDefinition | undefined);
-    pretty(logger: Logger): void;
+    pretty(logger: LoggerContract): void;
 }

package/dist/cjs/{src/errors → errors}/BadCommandFlag.d.ts

@@ -1,4 +1,4 @@
-import { Logger } from '../Logger.js';
+import { LoggerContract } from '../contracts/index.js';
 import { BobError } from './BobError.js';
 import { FlagDefinition } from '../lib/types.js';
 export type BadFlagParams = {
@@ -6,9 +6,11 @@ export type BadFlagParams = {
     value?: any;
     reason?: string;
 };
+/** Thrown when a flag's value cannot be converted by its `parse` function (validation failure, type mismatch, …). */
 export declare class BadCommandFlag extends BobError {
     readonly param: BadFlagParams;
     readonly flagDefinition?: FlagDefinition | undefined;
+    readonly $type: "BadCommandFlag";
     constructor(param: BadFlagParams, flagDefinition?: FlagDefinition | undefined);
-    pretty(logger: Logger): void;
+    pretty(logger: LoggerContract): void;
 }

package/dist/cjs/errors/BobError.d.ts

@@ -0,0 +1,13 @@
+import { LoggerContract } from '../contracts/index.js';
+/**
+ * Base class for every framework-recognised error.
+ *
+ * Subclasses are expected to override `$type` with their own literal so the
+ * field doubles as a discriminator (useful for telemetry and structured logs).
+ * `pretty` renders the error to a {@link LoggerContract}; the dispatch is wired
+ * up in {@link ExceptionHandler}.
+ */
+export declare abstract class BobError extends Error {
+    abstract readonly $type: string;
+    abstract pretty(logger: LoggerContract): void;
+}

package/dist/cjs/errors/CommandNotFoundError.d.ts

@@ -0,0 +1,9 @@
+import { LoggerContract } from '../contracts/index.js';
+import { BobError } from './BobError.js';
+/** Thrown by {@link CommandRegistry} when a requested command does not exist and no suggestion was accepted. */
+export declare class CommandNotFoundError extends BobError {
+    readonly command: string;
+    readonly $type: "CommandNotFoundError";
+    constructor(command: string);
+    pretty(logger: LoggerContract): void;
+}

package/dist/{esm/src → cjs}/errors/InvalidFlag.d.ts

@@ -1,9 +1,11 @@
-import { Logger } from '../Logger.js';
+import { LoggerContract } from '../contracts/index.js';
 import { BobError } from './BobError.js';
 import { FlagsSchema } from '../lib/types.js';
+/** Thrown when an unknown flag is supplied and `allowUnknownFlags` is off. */
 export declare class InvalidFlag extends BobError {
     private flag;
     private flagsSchema;
+    readonly $type: "InvalidFlag";
     constructor(flag: string, flagsSchema?: FlagsSchema);
-    pretty(logger: Logger): void;
+    pretty(logger: LoggerContract): void;
 }

package/dist/cjs/errors/MissingRequiredArgumentValue.d.ts

@@ -0,0 +1,9 @@
+import { LoggerContract } from '../contracts/index.js';
+import { BobError } from './BobError.js';
+/** Thrown when a required positional argument was not provided and no value could be obtained. */
+export declare class MissingRequiredArgumentValue extends BobError {
+    readonly argument: string;
+    readonly $type: "MissingRequiredArgumentValue";
+    constructor(argument: string);
+    pretty(logger: LoggerContract): void;
+}

package/dist/cjs/errors/MissingRequiredFlagValue.d.ts

@@ -0,0 +1,9 @@
+import { LoggerContract } from '../contracts/index.js';
+import { BobError } from './BobError.js';
+/** Thrown when a required flag was not provided and no value could be obtained (prompt cancelled or disabled). */
+export declare class MissingRequiredFlagValue extends BobError {
+    readonly flag: string;
+    readonly $type: "MissingRequiredFlagValue";
+    constructor(flag: string);
+    pretty(logger: LoggerContract): void;
+}

package/dist/cjs/errors/TooManyArguments.d.ts

@@ -0,0 +1,10 @@
+import { LoggerContract } from '../contracts/index.js';
+import { BobError } from './BobError.js';
+/** Thrown in strict mode when more positional arguments were supplied than the schema declares. */
+export declare class TooManyArguments extends BobError {
+    readonly expected: number;
+    readonly received: number;
+    readonly $type: "TooManyArguments";
+    constructor(expected: number, received: number);
+    pretty(logger: LoggerContract): void;
+}

package/dist/cjs/errors/ValidationError.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Raised by `parse`/`ask` validators to signal user-facing input problems.
+ *
+ * `safeParse` in {@link CommandParser} catches this specifically (and re-wraps
+ * it as {@link BadCommandFlag} or {@link BadCommandArgument}) — anything else
+ * is treated as a programmer bug and propagates unchanged.
+ */
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}

package/dist/cjs/errors/renderError.d.ts

@@ -0,0 +1,9 @@
+import { LoggerContract } from '../contracts/index.js';
+export type ErrorDetail = [label: string, value: string];
+export type RenderErrorOptions = {
+    title: string;
+    details?: ErrorDetail[];
+    hint?: string;
+};
+export declare function quote(name: string): string;
+export declare function renderError(logger: LoggerContract, opts: RenderErrorOptions): void;