bob-core 0.2.0 → 0.3.0

package/dist/Cli.d.ts

@@ -1,10 +1,13 @@
 import { CommandRegistry } from "./CommandRegistry";
 import { Command } from "./Command";
 import HelpCommand from "./commands/HelpCommand";
+import { ExceptionHandler } from "./ExceptionHandler";
 export declare class Cli {
     readonly commandRegistry: CommandRegistry;
+    private readonly exceptionHandler;
     get CommandRegistryClass(): typeof CommandRegistry;
     get HelpCommandClass(): typeof HelpCommand;
+    get ExceptionHandlerClass(): typeof ExceptionHandler;
     constructor();
     loadCommandsPath(commandsPath: string): Promise<void>;
     registerCommand(command: Command): void;

package/dist/Cli.js

@@ -6,16 +6,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Cli = void 0;
 const CommandRegistry_1 = require("./CommandRegistry");
 const HelpCommand_1 = __importDefault(require("./commands/HelpCommand"));
+const ExceptionHandler_1 = require("./ExceptionHandler");
 class Cli {
     commandRegistry;
+    exceptionHandler;
     get CommandRegistryClass() {
         return CommandRegistry_1.CommandRegistry;
     }
     get HelpCommandClass() {
         return HelpCommand_1.default;
     }
+    get ExceptionHandlerClass() {
+        return ExceptionHandler_1.ExceptionHandler;
+    }
     constructor() {
         this.commandRegistry = new this.CommandRegistryClass();
+        this.exceptionHandler = new this.ExceptionHandlerClass();
         this.registerCommand(new this.HelpCommandClass(this.commandRegistry));
     }
     async loadCommandsPath(commandsPath) {
@@ -25,7 +31,8 @@ class Cli {
         this.commandRegistry.registerCommand(command);
     }
     async runCommand(command, ...args) {
-        return await this.commandRegistry.runCommand(command, ...args);
+        return await this.commandRegistry.runCommand(command, ...args)
+            .catch(this.exceptionHandler.handle);
     }
 }
 exports.Cli = Cli;

package/dist/Command.d.ts

@@ -1,14 +1,20 @@
 import { CommandHelper } from "./CommandHelper";
+import { Parser } from "./Parser";
+export type CommandExample = {
+    description: string;
+    command: string;
+};
 export declare abstract class Command extends CommandHelper {
     abstract signature: string;
     abstract description: string;
-    private parser;
+    protected helperDefinitions: {
+        [key: string]: string;
+    };
+    protected commandsExamples: CommandExample[];
+    protected parser: Parser;
     get command(): string;
     protected abstract handle(): Promise<void | number>;
     run(...args: any[]): Promise<number>;
     protected option(key: string, defaultValue?: any): string | null;
     protected argument(key: string, defaultValue?: any): string | null;
-    signatures(): {
-        [argument: string]: import("./Parser").ParamSignature;
-    };
 }

package/dist/Command.js

@@ -4,14 +4,16 @@ exports.Command = void 0;
 const CommandHelper_1 = require("./CommandHelper");
 const Parser_1 = require("./Parser");
 class Command extends CommandHelper_1.CommandHelper {
+    helperDefinitions = {};
+    commandsExamples = [];
     parser;
     get command() {
         return this.signature.split(' ')[0];
     }
     async run(...args) {
-        this.parser = new Parser_1.Parser(this.signature, ...args);
+        this.parser = new Parser_1.Parser(this.signature, this.helperDefinitions, ...args);
         if (args.includes('--help') || args.includes('-h')) {
-            return this.help();
+            return this.help.bind(this)();
         }
         this.parser.validate();
         return (await this.handle()) ?? 0;
@@ -22,8 +24,5 @@ class Command extends CommandHelper_1.CommandHelper {
     argument(key, defaultValue) {
         return this.parser.argument(key) ?? defaultValue;
     }
-    signatures() {
-        return this.parser.signatures();
-    }
 }
 exports.Command = Command;

package/dist/CommandHelper.d.ts

@@ -1,3 +1,6 @@
+import { Command } from "./Command";
+import { ArgSignature } from "./Parser";
 export declare class CommandHelper {
-    help(): number;
+    get defaultOptions(): ArgSignature[];
+    help(this: Command): number;
 }

package/dist/CommandHelper.js

@@ -8,33 +8,59 @@ const chalk_1 = __importDefault(require("chalk"));
 const lodash_1 = require("lodash");
 const string_1 = require("./lib/string");
 class CommandHelper {
+    get defaultOptions() {
+        return [
+            {
+                name: 'help',
+                optional: true,
+                help: (0, chalk_1.default) `Display help for the given command. When no command is given display help for the {green list} command`,
+                alias: ['h']
+            }
+        ];
+    }
     help() {
-        const command = this;
         const log = console.log;
-        const signatures = command.signatures();
-        const availableArguments = Object.entries(signatures).filter(([_, signature]) => !signature.isOption);
-        const availableOptions = Object.entries(signatures).filter(([_, signature]) => signature.isOption);
-        const requiredArguments = availableArguments.filter(([_, signature]) => !signature.optional);
+        const availableArguments = Object.values(this.parser.argumentsSignatures());
+        const availableOptions = [...Object.values(this.parser.optionsSignatures()), ...this.defaultOptions]
+            .map((signature) => ({
+            ...signature,
+            optionWithAlias: `--${signature.name}${signature.alias?.map(a => `, -${a}`).join('') ?? ''}`
+        }));
+        const requiredArguments = availableArguments.filter((signature) => !signature.optional);
         log((0, chalk_1.default) `{yellow Description}:`);
-        log((0, chalk_1.default) `  ${command.description}\n`);
+        log((0, chalk_1.default) `  ${this.description}\n`);
         log((0, chalk_1.default) `{yellow Usage}:`);
-        log((0, chalk_1.default) `  ${command.command} ${requiredArguments.length > 0 ? requiredArguments.map(([arg]) => `<${arg}>`).join(' ') : '\b'} [options]`);
-        const maxOptionLength = (0, lodash_1.max)(availableOptions.map(([option]) => option.length)) ?? 0;
-        const maxArgumentLength = (0, lodash_1.max)(availableArguments.map(([arg]) => arg.length)) ?? 0;
+        log((0, chalk_1.default) `  ${this.command} ${requiredArguments.length > 0 ? requiredArguments.map((signature) => `<${signature.name}>`).join(' ') : '\b'} [options]`);
+        const maxOptionLength = (0, lodash_1.max)(availableOptions.map((signature) => signature.optionWithAlias.length)) ?? 0;
+        const maxArgumentLength = (0, lodash_1.max)(availableArguments.map((arg) => arg.name.length)) ?? 0;
         const maxLength = maxArgumentLength > maxOptionLength ? maxArgumentLength : maxOptionLength;
         if (availableArguments.length > 0) {
             log((0, chalk_1.default) `{yellow Arguments}:`);
-            for (const [argument, signature] of availableArguments) {
-                const spaces = (0, string_1.generateSpace)(maxLength - argument.length);
-                log((0, chalk_1.default) `  {green ${argument}} ${spaces} ${signature.help ?? '\b'} ${signature.optional ? (0, chalk_1.default) `{gray (optional)}` : ''}`);
+            for (const signature of availableArguments) {
+                const spaces = (0, string_1.generateSpace)(maxLength - signature.name.length);
+                log((0, chalk_1.default) `  {green ${signature.name}} ${spaces} ${signature.help ?? '\b'} ${signature.optional ? (0, chalk_1.default) `{gray (optional)}` : ''}`);
             }
             log((0, chalk_1.default) ``);
         }
         if (availableOptions.length > 0) {
             log((0, chalk_1.default) `{yellow Options}:`);
-            for (const [option, signature] of availableOptions) {
-                const spaces = (0, string_1.generateSpace)(maxLength - option.length);
-                log((0, chalk_1.default) `  {green ${option}} ${spaces} ${signature.help ?? '\b'} `);
+            for (const signature of availableOptions) {
+                const spaces = (0, string_1.generateSpace)(maxLength - signature.optionWithAlias.length);
+                log((0, chalk_1.default) `  {green ${signature.optionWithAlias}} ${spaces} ${signature.help ?? '\b'} `);
+            }
+        }
+        if (this.commandsExamples.length > 0) {
+            log((0, chalk_1.default) `\n{yellow Examples}:`);
+            let binaryName = process.argv[0].split('/').pop();
+            if (binaryName === 'node') {
+                binaryName += ' ' + process.argv[1].split('/').pop();
+            }
+            for (const [index, example] of this.commandsExamples.entries()) {
+                if (index > 0) {
+                    log('');
+                }
+                log(`  ${example.description}\n`);
+                log((0, chalk_1.default) `    {green ${binaryName} ${example.command}}`);
             }
         }
         return -1;

package/dist/CommandRegistry.d.ts

@@ -9,5 +9,4 @@ export declare class CommandRegistry {
     loadCommandsPath(commandsPath: string): Promise<void>;
     runCommand(command: string, ...args: any[]): Promise<number>;
     private listCommandsFiles;
-    private commandNotFound;
 }

package/dist/CommandRegistry.js

@@ -29,8 +29,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommandRegistry = void 0;
 const path_1 = __importDefault(require("path"));
 const fs = __importStar(require("node:fs"));
-const SS = __importStar(require("string-similarity"));
-const chalk_1 = __importDefault(require("chalk"));
+const CommandNotFoundError_1 = require("./errors/CommandNotFoundError");
 class CommandRegistry {
     commands = {};
     get commandSuffix() {
@@ -75,7 +74,7 @@ class CommandRegistry {
     async runCommand(command, ...args) {
         const commandToRun = this.commands[command];
         if (!this.commands[command]) {
-            return this.commandNotFound(command);
+            throw new CommandNotFoundError_1.CommandNotFoundError(command, this.getAvailableCommands());
         }
         return await commandToRun.run(...args);
     }
@@ -94,21 +93,5 @@ class CommandRegistry {
             }
         }
     }
-    commandNotFound(command) {
-        const log = console.log;
-        const similarCommands = this.getCommands().filter(cmd => cmd.command //
-            .split(':')
-            .filter(part => SS.compareTwoStrings(part, command) > 0.3).length);
-        if (similarCommands.length) {
-            log((0, chalk_1.default) `  {white.bgRed  ERROR } Command "${command}" is not defined, Did you mean one of these?`);
-            for (const cmd of similarCommands) {
-                log((0, chalk_1.default) `  {gray ⇂ ${cmd.command}}`);
-            }
-        }
-        else {
-            log((0, chalk_1.default) `  {white.bgRed  ERROR } Command "${command}" is not defined.`);
-        }
-        return 1;
-    }
 }
 exports.CommandRegistry = CommandRegistry;

package/dist/ExceptionHandler.d.ts

@@ -0,0 +1,4 @@
+import { BobError } from "./errors/BobError";
+export declare class ExceptionHandler {
+    handle(err: Error | BobError): number;
+}

package/dist/ExceptionHandler.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExceptionHandler = void 0;
+const BobError_1 = require("./errors/BobError");
+class ExceptionHandler {
+    handle(err) {
+        if (err instanceof BobError_1.BobError) {
+            err.pretty();
+            return -1;
+        }
+        throw err;
+    }
+}
+exports.ExceptionHandler = ExceptionHandler;

package/dist/Parser.d.ts

@@ -1,22 +1,32 @@
-export type ParamSignature = {
+export type ArgSignature = {
     name: string;
     optional: boolean;
-    alias?: string;
+    alias?: string[];
     help?: string;
     defaultValue?: string | boolean | null;
-    isOption: boolean;
+    isOption?: boolean;
 };
 export declare class Parser {
+    protected readonly signature: string;
+    protected readonly helperDefinitions: {
+        [key: string]: string;
+    };
     command: string;
     private arguments;
     private options;
     private argumentsSignature;
+    private optionsSignature;
     option(name: string): any;
     argument(name: string): any;
-    signatures(): {
-        [argument: string]: ParamSignature;
+    argumentsSignatures(): {
+        [argument: string]: ArgSignature;
+    };
+    optionsSignatures(): {
+        [option: string]: ArgSignature;
     };
-    constructor(signature: string, ...args: any[]);
+    constructor(signature: string, helperDefinitions: {
+        [key: string]: string;
+    }, ...args: any[]);
     private parseSignature;
     private parseParamSignature;
     validate(): void;

package/dist/Parser.js

@@ -5,21 +5,30 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Parser = void 0;
 const minimist_1 = __importDefault(require("minimist"));
+const MissingRequiredArgumentValue_1 = require("./errors/MissingRequiredArgumentValue");
 class Parser {
+    signature;
+    helperDefinitions;
     command;
     arguments = {};
     options = {};
     argumentsSignature = {};
+    optionsSignature = {};
     option(name) {
         return this.options[name];
     }
     argument(name) {
         return this.arguments[name];
     }
-    signatures() {
+    argumentsSignatures() {
         return this.argumentsSignature;
     }
-    constructor(signature, ...args) {
+    optionsSignatures() {
+        return this.optionsSignature;
+    }
+    constructor(signature, helperDefinitions, ...args) {
+        this.signature = signature;
+        this.helperDefinitions = helperDefinitions;
         const [command, ...params] = signature.split(/\{(.*?)\}/g).map(param => param.trim()).filter(Boolean);
         const { _: paramValues, ...optionValues } = (0, minimist_1.default)(args);
         this.command = command;
@@ -31,12 +40,19 @@ class Parser {
             if (param.isOption) {
                 const optionValue = optionValues[param.name];
                 this.options[param.name] = optionValue ?? param.defaultValue ?? null;
+                this.optionsSignature[param.name] = param;
+                for (const alias of param.alias ?? []) {
+                    if (optionValues[alias]) {
+                        this.options[param.name] = optionValues[alias];
+                        this.optionsSignature[param.name] = param;
+                    }
+                }
             }
             else {
                 const paramValue = paramValues.shift();
                 this.arguments[param.name] = paramValue ?? param.defaultValue ?? null;
+                this.argumentsSignature[param.name] = param;
             }
-            this.argumentsSignature[param.name] = param;
         }
     }
     parseParamSignature(argument) {
@@ -78,19 +94,26 @@ class Parser {
                 arg.defaultValue = false;
             }
         }
+        if (arg.name.includes('|')) {
+            const [name, ...alias] = arg.name.split('|');
+            arg.name = name.trim();
+            arg.alias = alias.map(a => a.trim());
+        }
         if (arg.name.startsWith('--')) {
             arg.isOption = true;
             arg.name = arg.name.slice(2);
         }
+        if (this.helperDefinitions[arg.name]) {
+            arg.help = this.helperDefinitions[arg.name];
+        }
         return arg;
     }
     validate() {
         // validate arguments
         for (const [argument, value] of Object.entries(this.arguments)) {
-            const signature = this.argumentsSignature[argument];
-            if (!value && !signature.optional) {
-                const argumentHelp = signature.help ?? 'no help available';
-                throw new Error(`Argument ${argument} is required. (help: ${argumentHelp})`);
+            const argSignature = this.argumentsSignature[argument];
+            if (!value && !argSignature.optional) {
+                throw new MissingRequiredArgumentValue_1.MissingRequiredArgumentValue(argSignature);
             }
         }
     }

package/dist/errors/BadParameter.d.ts

@@ -0,0 +1,11 @@
+import { BobError } from "./BobError";
+export type BadParameterProps = {
+    param: string;
+    value?: string;
+    reason?: string;
+};
+export declare class BadParameter extends BobError {
+    readonly param: BadParameterProps;
+    constructor(param: BadParameterProps);
+    pretty(): void;
+}

package/dist/errors/BadParameter.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BadParameter = void 0;
+const BobError_1 = require("./BobError");
+const chalk_1 = __importDefault(require("chalk"));
+class BadParameter extends BobError_1.BobError {
+    param;
+    constructor(param) {
+        let message = `Argument "${param.param}" value is invalid.`;
+        if (param.reason) {
+            message += ` Reason: ${param.reason}`;
+        }
+        else {
+            message += ` Value: "${param.value}"`;
+        }
+        super(message);
+        this.param = param;
+    }
+    pretty() {
+        const log = console.log;
+        log((0, chalk_1.default) `  {white.bgRed  ERROR } Argument "${this.param.param}" value is invalid. `);
+        if (this.param.value || this.param.reason) {
+            log('');
+        }
+        if (this.param.value) {
+            log((0, chalk_1.default) `  {blue Value}: ${this.param.value}`);
+        }
+        if (this.param.reason) {
+            log((0, chalk_1.default) `  {yellow Reason}: ${this.param.reason}`);
+        }
+    }
+}
+exports.BadParameter = BadParameter;

package/dist/errors/BobError.d.ts

@@ -0,0 +1,3 @@
+export declare abstract class BobError extends Error {
+    abstract pretty(): void;
+}

package/dist/errors/BobError.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BobError = void 0;
+class BobError extends Error {
+}
+exports.BobError = BobError;

package/dist/errors/CommandNotFoundError.d.ts

@@ -0,0 +1,7 @@
+import { BobError } from "./BobError";
+export declare class CommandNotFoundError extends BobError {
+    readonly command: string;
+    readonly availableCommands: string[];
+    constructor(command: string, availableCommands: string[]);
+    pretty(): void;
+}

package/dist/errors/CommandNotFoundError.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandNotFoundError = void 0;
+const BobError_1 = require("./BobError");
+const SS = __importStar(require("string-similarity"));
+const chalk_1 = __importDefault(require("chalk"));
+class CommandNotFoundError extends BobError_1.BobError {
+    command;
+    availableCommands;
+    constructor(command, availableCommands) {
+        super(`Command "${command}" not found.`);
+        this.command = command;
+        this.availableCommands = availableCommands;
+    }
+    pretty() {
+        const log = console.log;
+        const similarCommands = this.availableCommands.filter(cmd => cmd //
+            .split(':')
+            .filter(part => SS.compareTwoStrings(part, this.command) > 0.3).length);
+        if (similarCommands.length) {
+            log((0, chalk_1.default) `  {white.bgRed  ERROR } Command "${this.command}" is not defined, Did you mean one of these?`);
+            for (const cmd of similarCommands) {
+                log((0, chalk_1.default) `  {gray ⇂ ${this.command}}`);
+            }
+        }
+        else {
+            log((0, chalk_1.default) `  {white.bgRed  ERROR } Command "${this.command}" is not defined.`);
+        }
+    }
+}
+exports.CommandNotFoundError = CommandNotFoundError;

package/dist/errors/MissingRequiredArgumentValue.d.ts

@@ -0,0 +1,7 @@
+import { BobError } from "./BobError";
+import { ArgSignature } from "../Parser";
+export declare class MissingRequiredArgumentValue extends BobError {
+    readonly paramSignature: ArgSignature;
+    constructor(paramSignature: ArgSignature);
+    pretty(): void;
+}

package/dist/errors/MissingRequiredArgumentValue.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingRequiredArgumentValue = void 0;
+const BobError_1 = require("./BobError");
+const chalk_1 = __importDefault(require("chalk"));
+class MissingRequiredArgumentValue extends BobError_1.BobError {
+    paramSignature;
+    constructor(paramSignature) {
+        super(`Argument "${paramSignature.name}" is required.`);
+        this.paramSignature = paramSignature;
+    }
+    pretty() {
+        const log = console.log;
+        log((0, chalk_1.default) `  {white.bgRed  ERROR } Argument "${this.paramSignature.name}" is required.`);
+        if (this.paramSignature.help) {
+            log((0, chalk_1.default) `\n  {yellow Help}: ${this.paramSignature.help}`);
+        }
+    }
+}
+exports.MissingRequiredArgumentValue = MissingRequiredArgumentValue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bob-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "BOB Core",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",