@noravel/command 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024, Trịnh Trần Phương Nam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,569 @@
+# Noravel Command
+
+# Installation
+
+```bash
+npm install @noravel/command
+```
+
+# Content
+
+- [Create handler](#create-handler)
+- [Create command](#create-command)
+- [Define input expectations](#define-input-expectations)
+  - [Arguments](#arguments)
+  - [Options](#options)
+    - [Options with values](#options-with-values)
+    - [Option shortcuts](#option-shortcuts)
+  - [Input arrays](#input-arrays)
+  - [Option arrays](#option-arrays)
+  - [Input descriptions](#input-descriptions)
+- [Command I/O](#command-io)
+- [Create a maker command](#create-a-maker-command)
+- [Help command](#help-command)
+- [Programmatically executing commands](#programmatically-executing-commands)
+
+## Create handler
+
+Create a handler file in your project.
+
+```bash
+touch noravel
+```
+
+Open a `noravel` file and add the following code:
+
+```js
+#!/usr/bin/env node
+
+import { Kernel } from '@noravel/command';
+
+const kernel = new Kernel(process.argv);
+kernel.run();
+```
+
+## Create command
+
+Create a command file in your project.
+
+```bash
+touch Commands/Greeting.js
+```
+
+Open a `Commands/Greeting.js` file and add the following code:
+
+```js
+import { Command } from '@noravel/command';
+
+class Greeting extends Command {
+    signature = 'greeting';
+    description = 'Sending greetings to someone';
+
+    async handle() {
+        console.log('Hello World');
+    }
+}
+
+export default Greeting;
+```
+
+Make sure your command class exists the `handle` method. Then you can register your command in the `noravel` file.
+
+```js
+#!/usr/bin/env node
+
+import { Kernel } from '@noravel/command';
+import Greeting from './Commands/Greeting.js';
+
+const kernel = new Kernel(process.argv);
+kernel.register([
+    Greeting,
+]).run();
+```
+
+Now, you can run your command like this:
+
+```bash
+./noravel greeting
+```
+
+## Defining input expectations
+
+When writing console commands, it is common to gather input from the user through arguments or options.
+Noravel Command makes it very convenient to define the input you expect from the user using the `signature` property on your commands.
+The signature property allows you to define the name, arguments, and options for the command in a single, expressive.
+
+### Arguments
+
+All user supplied arguments and options are wrapped in curly braces. In the following example, the command defines one required argument: `user:`
+
+```js
+signature = 'greeting {user}';
+```
+
+You may also make arguments optional or define default values for arguments:
+
+```js
+// Optional argument
+signature = 'greeting {user?}';
+
+// Optional argument with default value
+signature = 'greeting {user=Nam}';
+```
+
+### Options
+
+Options, like arguments, are another form of user input.
+Options are prefixed by two hyphens (`--`) when they are provided via the command line.
+There are two types of options: those that receive a value and those that don't.
+Options that don't receive a value serve as a boolean "switch".
+Let's take a look at an example of this type of option:
+
+```js
+signature = 'greeting {--verbose}';
+```
+
+In this example, the `--verbose` switch may be specified when calling your command.
+If the `--verbose` switch is passed, the value of the option will be `true`. Otherwise, the value will be `false`:
+
+```bash
+./noravel greeting --verbose
+```
+
+#### Options with values
+
+Next, let's take a look at an option that expects a value. If the user must specify a value for an option, you should suffix the option name with a `=` sign:
+
+```js
+signature = 'greeting {--verbose=}';
+```
+
+In this example, the user may pass a value for the option like so. If the option is not specified when invoking the command, its value will be `undefined`:
+
+```bash
+./noravel greeting --verbose=Default
+```
+
+You may assign default values to options by specifying the default value after the option name. If no option value is passed by the user, the default value will be used:
+
+```js
+signature = 'greeting {--verbose=Default}';
+```
+
+#### Option shortcuts
+
+To assign a shortcut when defining an option, you may specify it before the option name and use the `|` character as a delimiter to separate the shortcut from the full option name:
+
+```js
+signature = 'greeting {--v|verbose=}';
+```
+
+When invoking the command on your terminal, option shortcuts should be prefixed with a single hyphen and no `=` character should be included when specifying a value for the option:
+
+```bash
+./noravel greeting -vDefault
+```
+
+### Input arrays
+
+If you would like to define arguments or options to expect multiple input values, you may use the `*` character.
+First, let's take a look at an example that specifies such an argument:
+
+```js
+signature = 'greeting {user*}';
+```
+
+When running this command, the user arguments may be passed in order to the command line.
+For example, the following command will set the value of user to an array with 1 and 2 as its values:
+
+```bash
+./noravel greeting user1 user2
+```
+
+This `*` character can be combined with an optional argument definition to allow zero or more instances of an argument:
+
+```js
+signature = 'greeting {user?*}';
+```
+
+### Option arrays
+
+When defining an option that expects multiple input values,
+each option value passed to the command should be prefixed with the option name:
+
+```js
+signature = 'greeting {--tag=*}';
+```
+
+Such a command may be invoked by passing multiple `--tag` arguments:
+
+```bash
+./noravel greeting --tag=tag1 --tag=tag2
+```
+
+### Input descriptions
+
+You may assign descriptions to input arguments and options by separating the argument name from the description using a colon.
+If you need a little extra room to define your command, feel free to spread the definition across multiple lines:
+
+```js
+signature = `greeting {name : The name of the person to greet}
+  {--v|verbose : Increase the verbosity of messages}
+  {--tag=* : Tags to apply to the greeting}`;
+```
+
+**Note**: If your command contains required arguments, the user will receive a thrown error when they are not provided.
+
+## Command I/O
+
+### Retrieving Input
+
+While your command is executing, you will likely need to access the values for the arguments and options accepted by your command. To do so, you may use the `getArgument` and `getOption` methods. If an argument or option does not exist, `undefined` will be returned:
+
+```js
+async handle() {
+  const name = this.getArgument('name');
+  const verbose = this.getOption('verbose');
+}
+```
+
+If you need to retrieve all of the arguments as an `array`, call the `getArgument` method without any parameters:
+
+```js
+async handle() {
+  const arguments = this.getArgument();
+}
+```
+
+Options may be retrieved just as easily as arguments using the option method. To retrieve all of the options as an array, call the `getOption` method without any parameters:
+
+```js
+async handle() {
+  const options = this.getOption();
+}
+```
+
+### Prompting for input
+
+In addition to displaying output, you may also ask the user to provide input during the execution of your command. The `ask` method will prompt the user with the given question, accept their input, and then return the user's input back to your command:
+
+```js
+async handle() {
+  const name = this.prompt.ask('What is your name?');
+}
+```
+
+The `secret` method is similar to `ask`, but the user's input will not be visible to them as they type in the console. This method is useful when asking for sensitive information such as passwords:
+
+```js
+async handle() {
+  const password = this.prompt.secret('What is your password?');
+}
+```
+
+**Multiple choice questions**
+
+If you need to give the user a predefined set of choices when asking a question, you may use the choice method.
+You may set the array index of the default value to be returned if no option is chosen by passing the index as the third argument to the method:
+
+```js
+async handle() {
+  const choice = this.prompt.choice('What is your favorite color?', ['red', 'green', 'blue'], defaultIndex);
+}
+```
+
+In addition, the `choice` method accepts optional fourth argument for determining whether multiple selections are permitted:
+
+```js
+const choices = this.prompt.choice('What is your favorite color?', ['red', 'green', 'blue'], defaultIndex, true);
+```
+
+### Writing Output
+
+To send output to the console, you may use the `line`, `info`, `comment`, `success`, `warning`, and `error` methods. Each of these methods will use appropriate ANSI colors for their purpose. For example, let's display some general information to the user.
+
+```js
+async handle() {
+  this.output.info('This is an info message');
+  this.output.success('This is a success message');
+  this.output.warning('This is a warning message');
+  this.output.error('This is an error message');
+  this.output.comment('This is a comment message');
+}
+```
+
+**Table**
+
+The `table` method makes it easy to correctly format multiple rows / columns of data. All you need to do is provide the column names and the data for the table and Noravel Command will automatically calculate the appropriate width and height of the table for you:
+
+```js
+async handle() {
+  this.output.table(
+    ['id', 'name', 'email', 'date of birth'],
+    [
+      [1, 'John Doe', 'johndoe@example.com', '2000-01-01'],
+      [2, 'Jane Doe', 'janedoe@example.com', '1999-01-01'],
+      [3, 'James Doe', 'jamesdoe@example.com', '2010-01-01'],
+      [4, 'John Smith', 'johnsmith@example.com', '2000-11-01'],
+      [5, 'Jane Smith', 'janesmith@example.com', '2000-01-21'],
+      [6, 'James Smith', 'jamessmith@example.com', '2001-01-01'],
+    ]
+  );
+}
+```
+
+#### Progress Bars
+
+For long running tasks, it can be helpful to show a progress bar that informs users how complete the task is.
+First, define the total number of steps the process will iterate through.
+Then, advance the progress bar after processing each item.
+
+```js
+async handle() {
+  const bar = this.output.createProgressBar(100);
+  bar.start();
+  for (let i = 0; i < units; i++) {
+    // Do some work...
+    bar.advance();
+  }
+  bar.finish();
+}
+```
+
+**Progress Bar Methods**
+
+The progress bar provides several methods to control its behavior:
+
+```js
+async handle() {
+  const bar = this.output.createProgressBar(100);
+  
+  // Start the progress bar with an optional message
+  bar.start('Processing items...');
+  
+  // Advance the progress by one step
+  bar.advance();
+  
+  // Set a different total after creation
+  bar.setTotal(150);
+  
+  // Get the current total
+  const total = bar.getTotal();
+  
+  // Set the progress bar size (in characters)
+  bar.setSize(50);
+  
+  // Get the current size
+  const size = bar.getSize();
+  
+  // Finish the progress bar with an optional message
+  bar.finish('Processing completed!');
+}
+```
+
+**Progress Bar Formats**
+
+The progress bar supports three different display formats:
+
+```js
+async handle() {
+  const bar = this.output.createProgressBar(100);
+  
+  // Normal format (default): [=====>     ] 50.0% 50/100
+  bar.setFormat('normal');
+  
+  // Verbose format: [=====>] 50.0% 50/100 remaining: 25.0s. elapsed: 12.5s.
+  bar.setFormat('verbose');
+  
+  // Minimal format: Progress: 50.0%
+  bar.setFormat('minimal');
+  
+  bar.start();
+  for (let i = 0; i < 100; i++) {
+    bar.advance();
+  }
+  bar.finish();
+}
+```
+
+**Progress Bar Styles**
+
+You can choose between different progress bar styles:
+
+```js
+async handle() {
+  const bar = this.output.createProgressBar(100);
+  
+  // Arrow style (default): [=====>-----]
+  bar.useArrowProgress();
+  
+  // Shape style: [#####_____]
+  bar.useShapeProgress();
+  
+  // Block style: [█████░░░░░]
+  bar.useBlockProgress();
+  
+  bar.start();
+  for (let i = 0; i < 100; i++) {
+    bar.advance();
+  }
+  bar.finish();
+}
+```
+
+**Constructor Options**
+
+When creating a progress bar, you can specify custom options:
+
+```js
+async handle() {
+  // Create progress bar with custom size (in characters)
+  const bar = this.output.createProgressBar(100, 80);
+  
+  // Create progress bar that uses full terminal width
+  const fullBar = this.output.createProgressBar(100, null);
+  
+  bar.start();
+  for (let i = 0; i < 100; i++) {
+    bar.advance();
+  }
+  bar.finish();
+}
+```
+
+
+
+## Create a maker command
+
+Create a command file in your project.
+
+```bash
+touch Commands/ControllerMaker.js
+```
+
+Open a `Commands/ControllerMaker.js` file and add the following code:
+
+```js
+import { MakerCommand } from '@noravel/command';
+
+class ControllerMaker extends MakerCommand {
+    signature = `make:controller
+      {name : The name of the controller}
+      {--m|model= : Generate a resource controller for the given model}
+      {--f|force : Create the class even if the controller already exists}`;
+    description = 'Create a new controller class';
+
+    async handle() {
+        console.log('Creating controller...');
+    }
+}
+
+export default ControllerMaker;
+```
+
+Now let register the command in the `noravel` file:
+
+```js
+#!/usr/bin/env node
+
+import { Kernel } from '@noravel/command';
+import Greeting from './Commands/Greeting.js';
+import ControllerMaker from './Commands/ControllerMaker.js';
+
+const kernel = new Kernel(process.argv);
+kernel.register([
+    Greeting,
+    ControllerMaker,
+]).run();
+```
+
+Let's look at the methods available in the `MakerCommand` class:
+
+```ts
+class MakerCommand {
+    // Returns the base path of the project
+    public basePath(dirPath?: string): string;
+
+    // Returns the filename; if the user hasn't entered it, it will wait for user input
+    public async fileName(question?: string = 'What should the file be named?'): Promise<string>;
+    
+    // Creates a file with the given name and path
+    public makeFile(fileName: string, dirPath: string): void;
+    
+    // Returns the message that the file already exists
+    protected fileAlreadyExists(filePath: string): string;
+    
+    // Returns the message that the file created successfully
+    protected fileCreatedSuccessfully(filePath: string): string;
+    
+    // Returns the contents of a file that will be written to the file being created
+    protected contentFile(fileName: string): string;
+}
+```
+
+## Help command
+
+Check the available commands:
+
+```bash
+./noravel --help
+```
+
+Output:
+
+```
+Usage:
+  command [arguments] [--options]
+
+Available commands:
+  greeting                Sending greetings to someone
+  make:controller         Create a new controller class
+
+Options:
+  -h, --help             Show this help message
+  -v, --version          Display the version of Noravel Command
+```
+
+You can also view a description of a specific command by:
+
+```bash
+./noravel make:controller --help
+```
+
+Output:
+
+```
+Description:
+  Create a new controller class
+
+Usage:
+  make:controller [options] [--] <name>
+
+Arguments:
+  name                    The name of the controller
+
+Options:
+  -m, --model             Generate a resource controller for the given model
+  -f, --force             Create the class even if the controller already exists
+  -h, --help              Display help for the given command
+  -v, --version           Display the version of Noravel Command
+```
+
+## Programmatically executing commands
+
+Sometimes you may wish to execute your command outside of the CLI.
+For example, you may wish to execute your command from a route or controller.
+You may use the `call` method on the `Executor` to accomplish this.
+The `call` method accepts either the command's class name as its first argument, and an array of command parameters as the second argument.
+
+```js
+import Executor from './Executor.js';
+import Greeting from './Commands/Greeting.js';
+
+await Executor.call(Greeting, [
+  'John Doe',
+  '--verbose',
+  '--tag=foo',
+  '--tag=bar',
+]);
+```

package/dist/Command.d.ts

@@ -0,0 +1,27 @@
+import CommandContract from './Contracts/Command';
+import InputDefinition from './Inputs/InputDefinition';
+import Prompt from './Inputs/Prompt';
+import OutputMessage from './Outputs/OutputMessage';
+export default abstract class Command implements CommandContract {
+    argv: string[];
+    protected signature: string;
+    protected name: string;
+    protected description: string;
+    protected definition: InputDefinition;
+    protected inputs: {
+        arguments: Record<string, unknown>;
+        options: Record<string, unknown>;
+    };
+    protected output: OutputMessage;
+    protected prompt: Prompt;
+    constructor(argv: string[]);
+    bootstrap(): this;
+    detect(): this;
+    getName(): string;
+    getDescription(): string;
+    getArgument(name?: string): unknown;
+    getOption(name?: string): unknown;
+    showHelp(): void;
+    exec(command: string): Promise<unknown>;
+    abstract handle(): void;
+}

package/dist/Command.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const Parser_1 = __importDefault(require("./Parser"));
+const Detector_1 = __importDefault(require("./Detector"));
+const InputDefinition_1 = __importDefault(require("./Inputs/InputDefinition"));
+const Prompt_1 = __importDefault(require("./Inputs/Prompt"));
+const OutputMessage_1 = __importDefault(require("./Outputs/OutputMessage"));
+const Helper_1 = __importDefault(require("./Outputs/Helper"));
+class Command {
+    argv;
+    signature = '';
+    name = '';
+    description = '';
+    definition;
+    inputs = {
+        arguments: {},
+        options: {},
+    };
+    output;
+    prompt;
+    constructor(argv) {
+        this.argv = argv;
+        this.definition = new InputDefinition_1.default();
+        this.output = new OutputMessage_1.default();
+        this.prompt = new Prompt_1.default();
+    }
+    bootstrap() {
+        this.signature = this.signature + ' {--h|help : Display help for the given command} {--v|version : Display the version of Noravel Command}';
+        const [name, argumentDefinition, optionDefinition] = Parser_1.default.parse(this.signature);
+        this.name = name;
+        this.definition.setArguments(argumentDefinition);
+        this.definition.setOptions(optionDefinition);
+        return this;
+    }
+    detect() {
+        const [_arguments, _options] = Detector_1.default.detect(this.argv.slice(1), this.definition);
+        this.inputs.arguments = _arguments;
+        this.inputs.options = _options;
+        return this;
+    }
+    getName() {
+        return this.name;
+    }
+    getDescription() {
+        return this.description;
+    }
+    getArgument(name) {
+        if (!name) {
+            return Object.values(this.inputs.arguments);
+        }
+        return this.inputs.arguments[name];
+    }
+    getOption(name) {
+        if (!name) {
+            return Object.values(this.inputs.options);
+        }
+        return this.inputs.options[name];
+    }
+    showHelp() {
+        const helper = new Helper_1.default();
+        helper.showHelp(this.name, this.description, this.definition);
+    }
+    async exec(command) {
+        return new Promise((resolve, reject) => {
+            (0, node_child_process_1.exec)(command, (error, stdout, stderr) => {
+                if (error) {
+                    this.output.error(error.message);
+                    reject(error);
+                    return;
+                }
+                if (stderr) {
+                    this.output.error(stderr);
+                    reject(new Error(stderr));
+                    return;
+                }
+                this.output.info(stdout);
+                resolve(stdout);
+            });
+        });
+    }
+}
+exports.default = Command;

package/dist/Contracts/Command.d.ts

@@ -0,0 +1,10 @@
+export default interface Command {
+    bootstrap(): this;
+    detect(): this;
+    getName(): string;
+    getDescription(): string;
+    getArgument(name?: string): unknown;
+    getOption(name?: string): unknown;
+    showHelp(): void;
+    handle(): void;
+}

package/dist/Contracts/Command.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });