bob-core 2.1.0 → 3.0.0-alpha.0

package/dist/esm/src/CommandRegistry.d.ts

@@ -2,8 +2,8 @@ import { Command } from './Command.js';
 import { CommandIO, CommandIOOptions } from './CommandIO.js';
 import { Logger } from './Logger.js';
 import { StringSimilarity } from './StringSimilarity.js';
-import { ArgumentsSchema, ContextDefinition, OptionsSchema } from './lib/types.js';
-export type CommandResolver = (path: string) => Promise<Command | null>;
+import { ContextDefinition } from './lib/types.js';
+export type CommandResolver = (path: string) => Promise<typeof Command | null>;
 export type FileImporter = (filePath: string) => Promise<unknown>;
 export type CommandRegistryOptions = {
     logger?: Logger;
@@ -17,14 +17,14 @@ export declare class CommandRegistry {
     protected newCommandIO(opts: CommandIOOptions): CommandIO;
     constructor(opts?: CommandRegistryOptions);
     getAvailableCommands(): string[];
-    getCommands(): Array<Command>;
+    getCommands(): Array<typeof Command>;
     private importFile;
     private commandResolver;
     withCommandResolver(resolver: CommandResolver): this;
     withFileImporter(importer: FileImporter): this;
-    registerCommand<C extends ContextDefinition = ContextDefinition, Opts extends OptionsSchema = OptionsSchema, Args extends ArgumentsSchema = ArgumentsSchema>(command: Command<C, Opts, Args>, force?: boolean): void;
+    registerCommand(command: typeof Command<any>, force?: boolean): void;
     loadCommandsPath(commandsPath: string): Promise<void>;
-    runCommand(ctx: ContextDefinition, command: string | Command, ...args: string[]): Promise<number>;
+    runCommand(ctx: ContextDefinition, command: string | typeof Command | Command, ...args: string[]): Promise<number>;
     private suggestCommand;
     private askRunSimilarCommand;
     private listCommandsFiles;

package/dist/esm/src/CommandSignatureParser.d.ts

@@ -1,30 +1,24 @@
-import { Command } from './Command.js';
-import { CommandIO } from './CommandIO.js';
-import { CommandParser } from './CommandParser.js';
-import { CommandOption } from './contracts/index.js';
-import { OptionsSchema } from './lib/types.js';
+import { ArgumentsSchema, FlagsSchema } from './lib/types.js';
 /**
- * Extends CommandParser to parse command signatures like "command {arg} {--option}"
- * Handles interactive prompting for missing required arguments via CommandIO
+ * @deprecated This class is deprecated and will be removed in future versions. Use CommandParser with explicit schema definitions instead.
+ * Parses command signature strings like "command {arg} {--option}" into
+ * FlagsSchema and ArgumentsSchema using Flags/Args factories.
  */
-export declare class CommandSignatureParser<Opts extends OptionsSchema = OptionsSchema, Args extends OptionsSchema = OptionsSchema> extends CommandParser<Opts, Args> {
-    readonly command: string;
-    constructor(opts: {
-        io: CommandIO;
-        signature: string;
-        helperDefinitions: {
-            [key: string]: string;
-        };
-        defaultOptions: CommandOption<Command>[];
-    });
+export declare class CommandSignatureParser {
     /**
-     * Parses command signature string into command name and parameter schemas
-     * Example: "migrate {name} {--force}" -> { command: "migrate", arguments: {name: ...}, options: {force: ...} }
+     * Parses a command signature string into command name, flags, and args schemas.
+     *
+     * @example
+     * CommandSignatureParser.parse('migrate {name} {--force}')
+     * // => { command: 'migrate', flags: { force: Flags.boolean() }, args: { name: Args.string({ required: true }) } }
      */
-    private static parseSignature;
+    static parse(signature: string, helperDefinitions?: Record<string, string>): {
+        command: string;
+        flags: FlagsSchema;
+        args: ArgumentsSchema;
+    };
     /**
-     * Parses a single parameter signature like "{name}" or "{--force}" or "{files*}"
-     * Extracts name, type, default value, aliases, description, etc.
+     * Parses a single parameter signature into a FlagDefinition.
      *
      * Signature syntax:
      * - {arg}          -> required string argument
@@ -32,9 +26,12 @@ export declare class CommandSignatureParser<Opts extends OptionsSchema = Options
      * - {arg=default}  -> argument with default value
      * - {arg*}         -> variadic argument (array)
      * - {arg:desc}     -> argument with description
-     * - {--opt}        -> boolean option
-     * - {--opt=}       -> string option
-     * - {--opt|o}      -> option with alias
+     * - {--opt}        -> boolean flag
+     * - {--opt=}       -> string flag
+     * - {--opt=default} -> string flag with default
+     * - {--opt=*}      -> array flag
+     * - {--opt|o}      -> flag with alias
+     * - {--opt=true}   -> boolean flag with default true
      */
     private static parseParamSignature;
 }

package/dist/esm/src/CommandWithSignature.d.ts

@@ -1,28 +1,24 @@
-import { Command, CommandHandlerOptions } from './Command.js';
-import { CommandIO } from './CommandIO.js';
-import { CommandSignatureParser } from './CommandSignatureParser.js';
-import { ContextDefinition, OptionsSchema } from './lib/types.js';
-export declare abstract class CommandWithSignature<C extends ContextDefinition = ContextDefinition, Opts extends OptionsSchema = OptionsSchema, Args extends OptionsSchema = OptionsSchema> extends Command<C, Opts, Args> {
-    abstract signature: string;
-    abstract description: string;
-    protected helperDefinitions: {
-        [key: string]: string;
-    };
-    protected parser: CommandSignatureParser<Opts, Args>;
-    get command(): string;
-    protected newCommandParser(opts: {
-        io: CommandIO;
-        options: Opts;
-        arguments: Args;
-    }): CommandSignatureParser<Opts, Args>;
-    constructor();
-    protected abstract handle(ctx: C, opts: CommandHandlerOptions<Opts, Args>): Promise<number | void>;
-    protected option<T = string>(key: string): T | null;
-    protected option<T = string>(key: string, defaultValue: T): NoInfer<T>;
+import { Command, CommandRunOption } from './Command.js';
+import { ContextDefinition } from './lib/types.js';
+/**
+ * @deprecated Use `Command` with explicit `flags` and `args` instead. This class will be removed in a future major release.
+ *
+ * CommandWithSignature allows defining a command using a concise signature string, which is parsed to generate flags and arguments.
+ * The signature is parsed lazily on first run to avoid unnecessary overhead if the command is never executed.
+ */
+export declare abstract class CommandWithSignature<C extends ContextDefinition = ContextDefinition> extends Command<C> {
+    static signature: string;
+    static helperDefinitions: Record<string, string>;
+    static get command(): string;
+    run(runOpts: CommandRunOption<C>): Promise<number | void>;
+    /**
+     * Convenience accessor for a parsed flag value.
+     */
+    protected flag<T = string>(key: string): T | null;
+    protected flag<T = string>(key: string, defaultValue: T): NoInfer<T>;
+    /**
+     * Convenience accessor for a parsed argument value.
+     */
     protected argument<T = string>(key: string): T | null;
     protected argument<T = string>(key: string, defaultValue: T): NoInfer<T>;
-    askForConfirmation(...opts: Parameters<typeof this.io.askForConfirmation>): ReturnType<typeof this.io.askForConfirmation>;
-    askForInput(...opts: Parameters<typeof this.io.askForInput>): ReturnType<typeof this.io.askForInput>;
-    askForSelect(...opts: Parameters<typeof this.io.askForSelect>): ReturnType<typeof this.io.askForSelect>;
-    newLoader(...opts: Parameters<typeof this.io.newLoader>): ReturnType<typeof this.io.newLoader>;
 }

package/dist/esm/src/Flags.d.ts

@@ -0,0 +1,25 @@
+import { BooleanFlagDef, CustomFlagDef, DirectoryFlagDef, EnumFlagDef, FileFlagDef, FlagInput, NumberFlagDef, StringFlagDef, UrlFlagDef } from './lib/types.js';
+export declare const Flags: {
+    string<const T extends FlagInput<StringFlagDef>>(opts?: T): StringFlagDef & T;
+    number<const T extends FlagInput<NumberFlagDef>>(opts?: T): NumberFlagDef & T;
+    boolean<const T extends FlagInput<BooleanFlagDef>>(opts?: T): BooleanFlagDef & T;
+    enum<const T extends readonly string[], const U extends FlagInput<EnumFlagDef<T>, "options">>(opts: {
+        options: T;
+    } & U): EnumFlagDef<T> & U;
+    file<const T extends FlagInput<FileFlagDef>>(opts?: T): FileFlagDef & T;
+    directory<const T extends FlagInput<DirectoryFlagDef>>(opts?: T): DirectoryFlagDef & T;
+    url<const T extends FlagInput<UrlFlagDef>>(opts?: T): UrlFlagDef & T;
+    custom<T>(defaults?: FlagInput<CustomFlagDef<T>>): <const U extends FlagInput<CustomFlagDef<T>>>(overrides?: U) => CustomFlagDef<T> & U;
+};
+export declare const Args: {
+    string<const T extends FlagInput<StringFlagDef>>(opts?: T): StringFlagDef & T;
+    number<const T extends FlagInput<NumberFlagDef>>(opts?: T): NumberFlagDef & T;
+    boolean<const T extends FlagInput<BooleanFlagDef>>(opts?: T): BooleanFlagDef & T;
+    enum<const T extends readonly string[], const U extends FlagInput<EnumFlagDef<T>, "options">>(opts: {
+        options: T;
+    } & U): EnumFlagDef<T> & U;
+    file<const T extends FlagInput<FileFlagDef>>(opts?: T): FileFlagDef & T;
+    directory<const T extends FlagInput<DirectoryFlagDef>>(opts?: T): DirectoryFlagDef & T;
+    url<const T extends FlagInput<UrlFlagDef>>(opts?: T): UrlFlagDef & T;
+    custom<T>(defaults?: FlagInput<CustomFlagDef<T>>): <const U extends FlagInput<CustomFlagDef<T>>>(overrides?: U) => CustomFlagDef<T> & U;
+};

package/dist/esm/src/commands/HelpCommand.d.ts

@@ -7,6 +7,8 @@ export type HelpCommandOptions = {
 };
 export default class HelpCommand extends Command {
     private opts;
+    static command: string;
+    static description: string;
     constructor(opts: HelpCommandOptions);
     handle(): Promise<void>;
 }

package/dist/esm/src/contracts/index.d.ts

@@ -1,2 +1 @@
-export * from './CommandOption.js';
 export * from './LoggerContract.js';

package/dist/esm/src/errors/BadCommandArgument.d.ts

@@ -0,0 +1,14 @@
+import { Logger } from '../Logger.js';
+import { BobError } from './BobError.js';
+import { FlagDefinition } from '../lib/types.js';
+export type ArgumentProps = {
+    arg: string;
+    value?: any;
+    reason?: string;
+};
+export declare class BadCommandArgument extends BobError {
+    readonly detail: ArgumentProps;
+    readonly argDefinition?: FlagDefinition | undefined;
+    constructor(detail: ArgumentProps, argDefinition?: FlagDefinition | undefined);
+    pretty(logger: Logger): void;
+}

package/dist/esm/src/errors/BadCommandFlag.d.ts

@@ -0,0 +1,14 @@
+import { Logger } from '../Logger.js';
+import { BobError } from './BobError.js';
+import { FlagDefinition } from '../lib/types.js';
+export type FlagProps = {
+    flag: string;
+    value?: any;
+    reason?: string;
+};
+export declare class BadCommandFlag extends BobError {
+    readonly param: FlagProps;
+    readonly flagDefinition?: FlagDefinition | undefined;
+    constructor(param: FlagProps, flagDefinition?: FlagDefinition | undefined);
+    pretty(logger: Logger): void;
+}

package/dist/esm/src/errors/InvalidFlag.d.ts

@@ -0,0 +1,9 @@
+import { Logger } from '../Logger.js';
+import { BobError } from './BobError.js';
+import { FlagsSchema } from '../lib/types.js';
+export declare class InvalidFlag extends BobError {
+    private flag;
+    private flagsSchema;
+    constructor(flag: string, flagsSchema?: FlagsSchema);
+    pretty(logger: Logger): void;
+}

package/dist/esm/src/errors/MissingRequiredFlagValue.d.ts

@@ -0,0 +1,7 @@
+import { Logger } from '../Logger.js';
+import { BobError } from './BobError.js';
+export declare class MissingRequiredFlagValue extends BobError {
+    readonly flag: string;
+    constructor(flag: string);
+    pretty(logger: Logger): void;
+}

package/dist/esm/src/errors/index.d.ts

@@ -1,8 +1,8 @@
 export * from './BobError.js';
-export * from './BadCommandParameter.js';
-export * from './BadCommandOption.js';
-export * from './InvalidOption.js';
+export * from './BadCommandArgument.js';
+export * from './BadCommandFlag.js';
+export * from './InvalidFlag.js';
 export * from './CommandNotFoundError.js';
 export * from './MissingRequiredArgumentValue.js';
-export * from './MissingRequiredOptionValue.js';
+export * from './MissingRequiredFlagValue.js';
 export * from './TooManyArguments.js';

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

@@ -1,14 +1,15 @@
 export * from './Command.js';
-export * from './CommandWithSignature.js';
 export * from './CommandIO.js';
 export * from './CommandParser.js';
-export * from './CommandSignatureParser.js';
 export * from './CommandRegistry.js';
+export * from './CommandSignatureParser.js';
+export * from './CommandWithSignature.js';
 export * from './Cli.js';
 export * from './Logger.js';
 export * from './ExceptionHandler.js';
 export * from './StringSimilarity.js';
 export * from './lib/types.js';
+export * from './Flags.js';
 export * from './errors/index.js';
 export * from './options/index.js';
 export * from './contracts/index.js';