bob-core 3.0.0-beta.4 → 3.0.0-beta.6

package/dist/esm/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/esm/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/src → esm}/errors/renderError.d.ts

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

package/dist/esm/flags/boolean.d.ts

@@ -0,0 +1,20 @@
+import { FlagOpts } from '../lib/types.js';
+/** Boolean flag (`--debug` / `--no-debug`). Defaults to `false` when omitted. */
+export declare const booleanFlag: <const O extends Partial<import('../lib/types.js').FlagDefinition<boolean, import('../lib/types.js').CustomOptions>>>(overrides?: O | undefined) => {
+    [x: string]: unknown;
+} & {
+    parse: (input: any, opts: FlagOpts<any, import('../lib/types.js').CustomOptions>) => boolean;
+    type?: import('../lib/types.js').FlagKind;
+    ask?: (opts: FlagOpts) => Promise<any>;
+    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) => {
+        shouldStop: boolean;
+    } | void) | undefined;
+} & Omit<import('../lib/types.js').FlagDefinition<boolean, import('../lib/types.js').CustomOptions>, "parse"> & {
+    parse?: ((input: any, opts: FlagOpts<any, import('../lib/types.js').CustomOptions>) => boolean) | undefined;
+} & O;

package/dist/esm/flags/custom.d.ts

@@ -0,0 +1,12 @@
+import { CustomOptions, FlagDefinition, InitFlagDefinition } from '../lib/types.js';
+/**
+ * Escape hatch for declaring arbitrary parameter types. Returns a builder
+ * function — call it with overrides to produce a `FlagDefinition`.
+ *
+ * `parse` is required when there's no built-in for the target type. `multiple`
+ * defaults the value to `[]`; non-multiple flags default to `null`.
+ *
+ * The `type` literal supplied in `defaults` is preserved in the returned shape
+ * so downstream consumers can rely on it (e.g. for help rendering).
+ */
+export declare function custom<T, C extends CustomOptions = CustomOptions, const D extends InitFlagDefinition<T, C> = InitFlagDefinition<T, C>>(defaults?: D): <const O extends Partial<FlagDefinition<T, C>>>(overrides?: O) => FlagDefinition<T, C> & D & O;

package/dist/esm/flags/directory.d.ts

@@ -0,0 +1,27 @@
+/** Filesystem directory flag. Pass `exists: true` to require the directory to exist at parse time. */
+export declare const directoryFlag: <const O extends Partial<import('../index.js').FlagDefinition<string, {
+    exists?: boolean;
+}>>>(overrides?: O | undefined) => {
+    exists?: boolean | undefined;
+} & {
+    parse: (input: any, opts: import('../index.js').FlagOpts<any, {
+        exists?: boolean;
+    }>) => string;
+    type?: import('../index.js').FlagKind;
+    ask?: (opts: import('../index.js').FlagOpts) => Promise<any>;
+    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) => {
+        shouldStop: boolean;
+    } | void) | undefined;
+} & Omit<import('../index.js').FlagDefinition<string, {
+    exists?: boolean;
+}>, "parse"> & {
+    parse?: ((input: any, opts: import('../index.js').FlagOpts<any, {
+        exists?: boolean;
+    }>) => string) | undefined;
+} & O;

package/dist/esm/flags/file.d.ts

@@ -0,0 +1,27 @@
+/** Filesystem file flag. Pass `exists: true` to require the path to exist at parse time. */
+export declare const fileFlag: <const O extends Partial<import('../index.js').FlagDefinition<string, {
+    exists?: boolean;
+}>>>(overrides?: O | undefined) => {
+    exists?: boolean | undefined;
+} & {
+    parse: (input: any, opts: import('../index.js').FlagOpts<any, {
+        exists?: boolean;
+    }>) => string;
+    type?: import('../index.js').FlagKind;
+    ask?: (opts: import('../index.js').FlagOpts) => Promise<any>;
+    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) => {
+        shouldStop: boolean;
+    } | void) | undefined;
+} & Omit<import('../index.js').FlagDefinition<string, {
+    exists?: boolean;
+}>, "parse"> & {
+    parse?: ((input: any, opts: import('../index.js').FlagOpts<any, {
+        exists?: boolean;
+    }>) => string) | undefined;
+} & O;

package/dist/esm/flags/helpers.d.ts

@@ -0,0 +1,9 @@
+import { FlagDefinition } from '../lib/types.js';
+export declare function formatPromptMessage(name: string, definition: FlagDefinition): string;
+export declare function normalizeAliases(alias: string | readonly string[] | undefined): readonly string[];
+/**
+ * Formats an alias with the correct dash prefix for help/error output:
+ * single-character aliases get one dash (`-v`), multi-character aliases get
+ * two (`--verbose`). This matches POSIX/minimist parsing conventions.
+ */
+export declare function formatAlias(alias: string): string;

package/dist/esm/flags/index.d.ts

@@ -0,0 +1,160 @@
+import { custom } from './custom.js';
+import { optionFlag } from './option.js';
+/**
+ * Flag builders used in `static flags = { ... }` schemas.
+ *
+ *   - `Flags.string({ secret? })` — text input; `secret` masks the prompt.
+ *   - `Flags.number({ min?, max? })` — numeric input with range validation.
+ *   - `Flags.boolean()` — toggle flag (`--debug` / `--no-debug`).
+ *   - `Flags.option({ options: [...] as const })` — fixed enum.
+ *   - `Flags.file({ exists? })` / `Flags.directory({ exists? })` — filesystem
+ *     paths; `exists` validates presence at parse time.
+ *   - `Flags.url()` — `URL`-typed input.
+ *   - `Flags.custom<T>({ parse, ... })` — escape hatch for arbitrary types;
+ *     `parse` is required.
+ *
+ * Every builder accepts the common `FlagProps` (description, alias, required,
+ * default, multiple, ask, handler, help) plus its builder-specific extras.
+ */
+export declare const Flags: {
+    string: <const O extends Partial<import('../index.js').FlagDefinition<string, import('../index.js').CustomOptions>>>(overrides?: O | undefined) => {
+        [x: string]: unknown;
+    } & {
+        parse: (input: any, opts: import('../index.js').FlagOpts<any, import('../index.js').CustomOptions>) => string;
+        type?: import('../index.js').FlagKind;
+        ask?: (opts: import('../index.js').FlagOpts) => Promise<any>;
+        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) => {
+            shouldStop: boolean;
+        } | void) | undefined;
+    } & Omit<import('../index.js').FlagDefinition<string, import('../index.js').CustomOptions>, "parse"> & {
+        parse?: ((input: any, opts: import('../index.js').FlagOpts<any, import('../index.js').CustomOptions>) => string) | undefined;
+    } & O;
+    number: <const O extends Partial<import('../index.js').FlagDefinition<number, {
+        min?: number;
+        max?: number;
+    }>>>(overrides?: O | undefined) => {
+        min?: number | undefined;
+        max?: number | undefined;
+    } & {
+        parse: (input: any, opts: import('../index.js').FlagOpts<any, {
+            min?: number;
+            max?: number;
+        }>) => number;
+        type?: import('../index.js').FlagKind;
+        ask?: (opts: import('../index.js').FlagOpts) => Promise<any>;
+        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) => {
+            shouldStop: boolean;
+        } | void) | undefined;
+    } & Omit<import('../index.js').FlagDefinition<number, {
+        min?: number;
+        max?: number;
+    }>, "parse"> & {
+        parse?: ((input: any, opts: import('../index.js').FlagOpts<any, {
+            min?: number;
+            max?: number;
+        }>) => number) | undefined;
+    } & O;
+    boolean: <const O extends Partial<import('../index.js').FlagDefinition<boolean, import('../index.js').CustomOptions>>>(overrides?: O | undefined) => {
+        [x: string]: unknown;
+    } & {
+        parse: (input: any, opts: import('../index.js').FlagOpts<any, import('../index.js').CustomOptions>) => boolean;
+        type?: import('../index.js').FlagKind;
+        ask?: (opts: import('../index.js').FlagOpts) => Promise<any>;
+        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: import('../index.js').FlagOpts) => {
+            shouldStop: boolean;
+        } | void) | undefined;
+    } & Omit<import('../index.js').FlagDefinition<boolean, import('../index.js').CustomOptions>, "parse"> & {
+        parse?: ((input: any, opts: import('../index.js').FlagOpts<any, import('../index.js').CustomOptions>) => boolean) | undefined;
+    } & O;
+    option: typeof optionFlag;
+    file: <const O extends Partial<import('../index.js').FlagDefinition<string, {
+        exists?: boolean;
+    }>>>(overrides?: O | undefined) => {
+        exists?: boolean | undefined;
+    } & {
+        parse: (input: any, opts: import('../index.js').FlagOpts<any, {
+            exists?: boolean;
+        }>) => string;
+        type?: import('../index.js').FlagKind;
+        ask?: (opts: import('../index.js').FlagOpts) => Promise<any>;
+        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) => {
+            shouldStop: boolean;
+        } | void) | undefined;
+    } & Omit<import('../index.js').FlagDefinition<string, {
+        exists?: boolean;
+    }>, "parse"> & {
+        parse?: ((input: any, opts: import('../index.js').FlagOpts<any, {
+            exists?: boolean;
+        }>) => string) | undefined;
+    } & O;
+    directory: <const O extends Partial<import('../index.js').FlagDefinition<string, {
+        exists?: boolean;
+    }>>>(overrides?: O | undefined) => {
+        exists?: boolean | undefined;
+    } & {
+        parse: (input: any, opts: import('../index.js').FlagOpts<any, {
+            exists?: boolean;
+        }>) => string;
+        type?: import('../index.js').FlagKind;
+        ask?: (opts: import('../index.js').FlagOpts) => Promise<any>;
+        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) => {
+            shouldStop: boolean;
+        } | void) | undefined;
+    } & Omit<import('../index.js').FlagDefinition<string, {
+        exists?: boolean;
+    }>, "parse"> & {
+        parse?: ((input: any, opts: import('../index.js').FlagOpts<any, {
+            exists?: boolean;
+        }>) => string) | undefined;
+    } & O;
+    url: <const O extends Partial<import('../index.js').FlagDefinition<URL, import('../index.js').CustomOptions>>>(overrides?: O | undefined) => {
+        [x: string]: unknown;
+    } & {
+        parse: (input: any, opts: import('../index.js').FlagOpts<any, import('../index.js').CustomOptions>) => URL;
+        type?: import('../index.js').FlagKind;
+        ask?: (opts: import('../index.js').FlagOpts) => Promise<any>;
+        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) => {
+            shouldStop: boolean;
+        } | void) | undefined;
+    } & Omit<import('../index.js').FlagDefinition<URL, import('../index.js').CustomOptions>, "parse"> & {
+        parse?: ((input: any, opts: import('../index.js').FlagOpts<any, import('../index.js').CustomOptions>) => URL) | undefined;
+    } & O;
+    custom: typeof custom;
+};
+export { Args } from '../args/index.js';

package/dist/esm/flags/number.d.ts

@@ -0,0 +1,32 @@
+/** Numeric flag. Optional `min`/`max` clamp the accepted range and surface as `BadCommandFlag`. */
+export declare const numberFlag: <const O extends Partial<import('../index.js').FlagDefinition<number, {
+    min?: number;
+    max?: number;
+}>>>(overrides?: O | undefined) => {
+    min?: number | undefined;
+    max?: number | undefined;
+} & {
+    parse: (input: any, opts: import('../index.js').FlagOpts<any, {
+        min?: number;
+        max?: number;
+    }>) => number;
+    type?: import('../index.js').FlagKind;
+    ask?: (opts: import('../index.js').FlagOpts) => Promise<any>;
+    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) => {
+        shouldStop: boolean;
+    } | void) | undefined;
+} & Omit<import('../index.js').FlagDefinition<number, {
+    min?: number;
+    max?: number;
+}>, "parse"> & {
+    parse?: ((input: any, opts: import('../index.js').FlagOpts<any, {
+        min?: number;
+        max?: number;
+    }>) => number) | undefined;
+} & O;

package/dist/esm/flags/option.d.ts

@@ -0,0 +1,8 @@
+import { FlagDefinition, InitFlagDefinition } from '../lib/types.js';
+export declare function optionFlag<const T extends readonly string[], const O extends Partial<InitFlagDefinition<T[number], {
+    options: T;
+}>>>(opts: {
+    options: T;
+} & O): FlagDefinition<T[number], {
+    options: T;
+}> & O;

package/dist/esm/flags/string.d.ts

@@ -0,0 +1,19 @@
+/** Text input flag. Pass `secret: true` to mask the prompt as a password. */
+export declare const stringFlag: <const O extends Partial<import('../index.js').FlagDefinition<string, import('../index.js').CustomOptions>>>(overrides?: O | undefined) => {
+    [x: string]: unknown;
+} & {
+    parse: (input: any, opts: import('../index.js').FlagOpts<any, import('../index.js').CustomOptions>) => string;
+    type?: import('../index.js').FlagKind;
+    ask?: (opts: import('../index.js').FlagOpts) => Promise<any>;
+    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) => {
+        shouldStop: boolean;
+    } | void) | undefined;
+} & Omit<import('../index.js').FlagDefinition<string, import('../index.js').CustomOptions>, "parse"> & {
+    parse?: ((input: any, opts: import('../index.js').FlagOpts<any, import('../index.js').CustomOptions>) => string) | undefined;
+} & O;

package/dist/esm/flags/url.d.ts

@@ -0,0 +1,19 @@
+/** URL flag — parses the input with `new URL()` and returns the resulting `URL` object. */
+export declare const urlFlag: <const O extends Partial<import('../index.js').FlagDefinition<URL, import('../index.js').CustomOptions>>>(overrides?: O | undefined) => {
+    [x: string]: unknown;
+} & {
+    parse: (input: any, opts: import('../index.js').FlagOpts<any, import('../index.js').CustomOptions>) => URL;
+    type?: import('../index.js').FlagKind;
+    ask?: (opts: import('../index.js').FlagOpts) => Promise<any>;
+    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) => {
+        shouldStop: boolean;
+    } | void) | undefined;
+} & Omit<import('../index.js').FlagDefinition<URL, import('../index.js').CustomOptions>, "parse"> & {
+    parse?: ((input: any, opts: import('../index.js').FlagOpts<any, import('../index.js').CustomOptions>) => URL) | undefined;
+} & O;