bob-core 3.0.0-beta.3 → 3.0.0-beta.5

package/dist/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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;

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

@@ -12,5 +12,4 @@ export * from './errors/index.js';
 export * from './args/index.js';
 export * from './flags/index.js';
 export * from './lib/types.js';
-export * from './options/index.js';
 export * from './ux/index.js';

package/dist/cjs/{src/lib → lib}/helpers.d.ts

@@ -1,4 +1,4 @@
 import { Command } from '../Command.js';
 import { BobError } from '../errors/index.js';
-export declare function isBobError(err: Error): err is BobError;
+export declare function isBobError(err: unknown): err is BobError;
 export declare function isBobCommandClass(cls: unknown): cls is typeof Command;

package/dist/cjs/lib/types.d.ts

@@ -0,0 +1,99 @@
+import { Command } from '../Command.js';
+import { UX } from '../ux/index.js';
+export type ContextDefinition = any;
+export type CustomOptions = Record<string, unknown>;
+export type FlagKind = 'string' | 'number' | 'boolean' | 'option' | 'file' | 'directory' | 'url' | 'custom';
+/**
+ * Options handed to a flag's `parse`, `ask`, and `handler` callbacks.
+ *
+ * `definition` is typed as the canonical {@link FlagDefinition}. Builder-specific
+ * extras (`options`, `min`, `max`, `exists`, `secret`) live directly on
+ * {@link FlagDefinition}, so handlers can read them without `any` casts while still
+ * being honest that they are optional at the type level.
+ */
+export type FlagOpts<C extends ContextDefinition = ContextDefinition, P extends CustomOptions = CustomOptions> = {
+    name: string;
+    ux: UX;
+    ctx: C;
+    definition: FlagDefinition<C, P>;
+    cmd: typeof Command;
+};
+export type FlagDefinition<T = any, C extends CustomOptions = CustomOptions> = {
+    [key in keyof C]: C[keyof C];
+} & {
+    parse: (input: any, opts: FlagOpts<any, C>) => T;
+    type?: FlagKind;
+    ask?: (opts: FlagOpts) => Promise<any>;
+    description?: string;
+    required?: boolean;
+    default?: T | T[] | null | (() => T | T[] | null) | (() => Promise<T | T[] | null>);
+    multiple?: boolean;
+    help?: string;
+    alias?: string | readonly string[];
+    handler?: (value: T, opts: FlagOpts) => {
+        shouldStop: boolean;
+    } | void;
+};
+export type InitFlagDefinition<T = any, C extends CustomOptions = CustomOptions> = Omit<FlagDefinition<T, C>, 'parse'> & {
+    parse?: (input: any, opts: FlagOpts<any, C>) => T;
+};
+/** Infers the runtime return type of a flag definition, accounting for `multiple`. */
+export type InferFlagReturn<O> = O extends {
+    parse: (...args: any[]) => infer R;
+} ? O extends {
+    multiple: true;
+} ? [R] extends [Array<unknown>] ? R : R[] : R : never;
+/**
+ * `true` when the parsed value cannot be `null`:
+ *  - `required: true`
+ *  - `multiple: true` (always an array)
+ *  - `default` resolves to a value where neither `null` nor `undefined` is in the union
+ *    (covers `T`, `T[]`, `() => T`, `() => Promise<T>`)
+ */
+type IsGuaranteed<O> = O extends {
+    required: true;
+} ? true : O extends {
+    multiple: true;
+} ? true : O extends {
+    default: infer D;
+} ? null extends D ? false : undefined extends D ? false : true : false;
+/**
+ * Final value type seen by the handler — `T` if guaranteed (required, multiple,
+ * or non-null default), otherwise `T | null`.
+ */
+export type FlagReturnType<O> = IsGuaranteed<O> extends true ? InferFlagReturn<O> : InferFlagReturn<O> | null;
+/** Historic alias — kept so `FlagType<O>` keeps working as a value-inference helper. */
+export type FlagType<O> = InferFlagReturn<O>;
+/** Schema mapping flag names to their {@link FlagDefinition}. */
+export type FlagsSchema = {
+    [key: string]: FlagDefinition<any, any>;
+};
+/** Inferred runtime shape of all flags in a schema. */
+export type FlagsObject<Options extends FlagsSchema> = {
+    [Key in keyof Options]: FlagReturnType<Options[Key]>;
+};
+/**
+ * Schema for positional arguments.
+ *
+ * Note on booleans: positional booleans don't really make sense, so the
+ * canonical {@link Args} builder set deliberately omits `Args.boolean`. The
+ * type itself is a structural alias of {@link FlagsSchema} (rather than a
+ * branded subtype) to keep literal-type inference flowing through the builder
+ * generics without surprising errors. If you put `Flags.boolean()` in
+ * `static args`, the runtime parser will accept it but you're outside the
+ * supported design.
+ */
+export type ArgDefinition = FlagDefinition;
+export type ArgsSchema = FlagsSchema;
+export type InferFlags<T> = T extends {
+    flags: infer O extends FlagsSchema;
+} ? O : FlagsSchema;
+export type InferArgs<T> = T extends {
+    args: infer A extends ArgsSchema;
+} ? A : ArgsSchema;
+/** `{ flags, args }` pair for a given Command class — the second handler argument. */
+export type Parsed<T> = {
+    flags: FlagsObject<InferFlags<T>>;
+    args: FlagsObject<InferArgs<T>>;
+};
+export {};

package/dist/cjs/shared/ask-helpers.d.ts

@@ -0,0 +1,7 @@
+import { FlagOpts } from '../lib/types.js';
+export declare function buildStringAsk(builderOpts: FlagOpts): Promise<any>;
+export declare function buildNumberAsk(builderOpts: FlagOpts): Promise<any>;
+export declare function buildOptionAsk(builderOpts: FlagOpts): Promise<any>;
+export declare function buildFileAsk(builderOpts: FlagOpts): Promise<any>;
+export declare function buildDirectoryAsk(builderOpts: FlagOpts): Promise<any>;
+export declare function buildUrlAsk(builderOpts: FlagOpts): Promise<any>;

package/dist/cjs/shared/flagsUtils.d.ts

@@ -0,0 +1,5 @@
+import { numberFlag } from '../flags/number.js';
+import { optionFlag } from '../flags/option.js';
+import { FlagDefinition } from '../lib/types.js';
+export declare function isNumberFlag(flag: FlagDefinition): flag is ReturnType<typeof numberFlag>;
+export declare function isOptionFlag(flag: FlagDefinition<any, any>): flag is ReturnType<typeof optionFlag>;