cleye 1.0.0

package/README.md

@@ -0,0 +1,536 @@
+
+<p align="center">
+	<img width="110" src=".github/logo.png">
+</p>
+<h1 align="center">cleye</h1>
+
+The intuitive command-line interface (CLI) development tool.
+
+### Features
+- Minimal API surface
+- Powerful flag parsing
+- Strongly typed parameters and flags
+- Command support
+- Help documentation generation (customizable too!)
+
+→ Try it out online
+
+<sub>Support this project by starring and sharing it. [Follow me](https://github.com/privatenumber) to see what other cool projects I'm working on.</sub>
+
+## Install
+
+```bash
+npm i cleye
+```
+
+## About
+_Cleye_ makes it very easy to develop command-line scripts in Node.js. It handles argv parsing to give you strongly typed parameters + flags and generates `--help` documentation based on the provided information.
+
+Here's an example script that simply logs: `Good morning/evening <name>!`:
+
+_greet.js:_
+```ts
+import { cli } from 'cleye'
+
+// Parse argv
+const argv = cli({
+    name: 'greet.js',
+
+    // Define parameters
+    parameters: [
+        '<first name>', // First name is required
+        '[last name]' // Last name is optional
+    ],
+
+    // Define flags/options
+    flags: {
+
+        // Parses `--time` as a string
+        time: {
+            type: String,
+            description: 'Time of day to greet (morning or evening)',
+            default: 'morning'
+        }
+    }
+})
+
+const name = [argv._.firstName, argv._.lastName].filter(Boolean).join(' ')
+
+if (argv.flags.time === 'morning') {
+    console.log(`Good morning ${name}!`)
+} else {
+    console.log(`Good evening ${name}!`)
+}
+```
+
+🛠 In development, type hints are provided on parsed flags and parameters:
+<p align="center">
+    <img src=".github/typed-flags.png" width="600">
+</p>
+
+📖 Generated help documentation can be viewed with the `--help` flag:
+
+```sh
+$ node greet.js --help
+
+greet.js
+
+Usage:
+  greet.js [flags...] <first name> [last name]
+
+Flags:
+  -h, --help                 Show help
+      --time <string>        Time of day to greet (morning or evening) (default: "morning")
+```
+
+✅ Run the script to see it in action:
+
+```sh
+$ node greet.js John Doe --time evening
+
+Good evening John Doe!
+```
+
+## Examples
+Want to dive right into some code? Check out some of these examples:
+
+- [**greet.js**](/examples/greet/index.ts): Working example from above
+- [**npm install**](/examples/npm/index.ts): Reimplementation of [`npm install`](https://docs.npmjs.com/cli/install/)'s CLI
+- [**tsc**](/examples/tsc/index.ts): Reimplementation of TypeScript [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html)'s CLI
+- [**snap-tweet**](/examples/snap-tweet/index.ts): Reimplementation of [`snap-tweet`](https://github.com/privatenumber/snap-tweet)'s CLI
+- [**pkg-size**](/examples/pkg-size/index.ts): Reimplementation of [`pkg-size`](https://github.com/pkg-size/pkg-size)'s CLI
+
+## Usage
+
+### Arguments
+Arguments are values passed into the script that are not associated with any flags/options.
+
+For example, in the following command, the first argument is `file-a.txt` and the second is `file-b.txt`:
+
+```
+$ my-script file-a.txt file-b.txt
+```
+
+Arguments can be accessed from the `_` array-property of the returned object.
+
+Example:
+
+```ts
+const argv = cli({ /* ... */ })
+
+// $ my-script file-a.txt file-b.txt
+
+argv._ // => ["file-a.txt", "file-b.txt"] (string[])
+```
+
+#### Parameters
+Parameters (aka _positional arguments_) are the names that map against argument values. Think of parameters as variable names and arguments as values associated with the variables.
+
+Parameters can be defined in the `parameters` array-property to make specific arguments accessible by name. This is useful for writing more readable code, enforcing validation, and generating help documentation.
+
+Parameters are defined in the following formats:
+- **Required parameters** are indicated by angle brackets (eg. `<parameter name>`).
+- **Optional parameters** are indicated by square brackets (eg. `[parameter name]`).
+- **Spread parameters** are indicated by `...` suffix (eg. `<parameter name...>` or `[parameter name...]`).
+
+Note, required parameters cannot come after optional parameters, and spread parameters must be last.
+
+Parameters can be accessed in camelCase on the `_` property of the returned object.
+
+Example:
+
+```ts
+const argv = cli({
+    parameters: [
+        '<required parameter>',
+        '[optional parameter]',
+        '[optional spread...]'
+    ]
+})
+
+// $ my-script a b c d
+
+argv._.requiredParameter // => "a" (string)
+argv._.optionalParameter // => "b" (string | undefined)
+argv._.optionalSpread // => ["c", "d"] (string[])
+```
+
+### Flags
+Flags (aka Options) are key-value pairs passed into the script in the format `--flag-name <value>`.
+
+For example, in the following command, `--file-a` has value `data.json` and `--file-b` has value `file.txt`:
+
+```
+$ my-script --file-a data.json --file-b=file.txt
+```
+
+#### Parsing features
+_Cleye_'s flag parsing is powered by [`type-flag`](https://github.com/privatenumber/type-flag) and comes with many features:
+
+- Array & Custom types
+- Flag delimiters: `--flag value`, `--flag=value`, `--flag:value`, and `--flag.value`
+- Combined aliases: `-abcd 2` → `-a -b -c -d 2`
+- Early termination: Pass in `--` to end flag parsing
+- Unknown flags: Unexpected flags stored in `unknownFlags`
+
+
+Read the [_type-flag_ docs](https://github.com/privatenumber/type-flag) to learn more.
+
+#### Defining flags
+Flags can be specified in the `flag` object-property, where the key is the flag name, and the value is a flag type function or an object that describes the flag.
+
+The flag name is recommended to be in camelCase as it will be interpreted to parse kebab-case equivalents.
+
+The flag type function can be any function that accepts a string and returns the parsed value. Default JavaScript constructors should cover most use-cases: [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String), [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/Number), [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean/Boolean), etc.
+
+The flag description object can be used to store additional information about the flag, such as `alias`, `default`, and `description`. To accept multiple values for a flag, wrap the type function in an array.
+
+All of the provided information will be used to generate better help documentation.
+
+Example:
+
+```ts
+const argv = cli({
+    flags: {
+        someBoolean: Boolean,
+
+        someString: {
+            type: String,
+            description: 'Some string flag',
+            default: 'n/a'
+        },
+
+        someNumber: {
+            // Wrap the type function in an array to allow multiple values
+            type: [Number],
+            alias: 'n',
+            description: 'Array of numbers. (eg. -n 1 -n 2 -n 3)'
+        }
+    }
+})
+
+// $ my-script --some-boolean --some-string hello --some-number 1 -n 2
+
+argv.flags.someBoolean // => true (boolean | undefined)
+argv.flags.someString // => "hello" (string)
+argv.flags.someNumber // => [1, 2] (number[])
+```
+
+#### Custom flag types & validation
+Custom flag types can be created to validate flags and narrow types. Simply create a new function that accepts a string and returns the parsed value.
+
+Here's an example with a custom `Size` type that narrows the flag type to `"small" | "medium" | "large"`:
+
+```ts
+const possibleSizes = ['small', 'medium', 'large'] as const
+
+type Sizes = typeof possibleSizes[number] // => "small" | "medium" | "large"
+
+// Custom type function
+function Size(size: Sizes) {
+    if (!possibleSizes.includes(size)) {
+        throw new Error(`Invalid size: "${size}"`)
+    }
+
+    return size
+}
+
+const argv = cli({
+    flags: {
+        size: {
+            type: Size,
+            description: 'Size of the pizza (small, medium, large)'
+        }
+    }
+})
+
+// $ my-script --size large
+
+argv.flags.size // => "large" ("small" | "medium" | "large")
+```
+
+#### Default flags
+By default, _Cleye_ will try to handle the `--help, -h` and `--version` flags.
+
+##### Help flag
+Handling `--help, -h` is enabled by default.
+
+To disable it, set `help` to `false`. The help documentation can still be manually displayed by calling `.showHelp(helpOptions)` on the returned object.
+
+##### Version flag
+To enable handling `--version`, specify the `version` property.
+
+```ts
+cli({
+    version: '1.2.3'
+})
+```
+
+```sh
+$ my-script --version
+1.2.3
+```
+
+The version is also shown in the help documentation. To opt out of handling `--version` while still showing the version in `--help`, pass the version into `help.version`.
+
+### Commands
+Commands allow organizing multiple "scripts" into a single script. An example of this is the [`npm install`](https://docs.npmjs.com/cli/install/) command, which is essentially an "install" script inside the "npm" script, adjacent to other commands like [`npm run`](https://docs.npmjs.com/cli/run-script/).
+
+#### Defining commands
+A command can be created by importing the `command` function and initializing it with a name. The rest of the options are the same as the `cli` function.
+
+Pass the created command into `cli` option's `commands` array-property to register it:
+
+_npm.js_
+```ts
+import { cli, command } from 'cleye'
+
+const argv = cli({
+    name: 'npm',
+
+    version: '1.2.3',
+
+    commands: [
+        command({
+            // Command name
+            name: 'install',
+
+            parameters: ['<package name>'],
+
+            flags: {
+                noSave: Boolean,
+                saveDev: Boolean
+            }
+        })
+    ]
+})
+
+// $ npm install lodash
+
+argv.command // => "install" (string)
+argv._.packageName // => "lodash" (string)
+```
+
+Depending on the command given, the resulting type can be narrowed:
+<p align="center">
+    <img src=".github/command-type-narrowing.png" width="420">
+</p>
+
+#### Command callback
+
+When a CLI app has many commands, it's recommended to organize each command in its own file. With this structure, parsed output handling for each command is better placed where they are respectively defined rather than the single `cli` output point. This can be done by passing a callback function into the `command` function (callbacks are supported in the `cli` function too).
+
+Example:
+
+_install-command.js_ (`install` command using callback)
+```ts
+import { command } from 'cleye'
+
+export const installCommand = command({
+    // Command name
+    name: 'install',
+
+    parameters: ['<package name>'],
+
+    flags: {
+        noSave: Boolean,
+        saveDev: Boolean
+    }
+}, (argv) => {
+    // $ npm install lodash
+
+    argv._.packageName // => "lodash" (string)
+})
+```
+
+_npm.js_ (CLI entry file)
+```ts
+import { installCommand } from './install-command.js'
+
+cli({
+    name: 'npm',
+
+    commands: [
+        installCommand
+    ]
+})
+```
+
+### Help documentation
+_Cleye_ uses all information provided to generate rich help documentation. The more information you give, the better the docs!
+
+#### Help customization
+The help document can be customized by passing a `render(nodes, renderers) => string` function to `help.render`.
+
+The `nodes` parameter contains an array of nodes that will be used to render the document. The `renderers` parameter is an object of functions used to render the document. Each node has properties `type` and `data`, where `type` corresponds to a property in `renderers` and `data` is passed into the render function.
+
+Default renderers can be found in [`/src/render-help/renderers.ts`](/src/render-help/renderers.ts).
+
+Here's an example that adds an extra sentence at the end and also updates the flags table to use the `=` operator (`--flag <value>` → `--flag=<value>`):
+
+```ts
+cli({
+    // ...,
+
+    help: {
+        render(nodes, renderers) {
+            /* Modify nodes... */
+
+            // Add some text at end of document
+            nodes.push('\nCheckout Cleye: https://github.com/privatenumber/cleye')
+
+            /* Extend renderers... */
+
+            // Make all flag examples use `=` as the separator
+            renderers.flagOperator = () => '='
+
+            /* Render nodes and return help */
+            return renderers.render(nodes)
+        }
+    }
+})
+```
+
+#### Responsive tables
+_Cleye_'s "Flags" table in the help document is responsive and wraps cell text content based on the column & terminal width. It also has [breakpoints to display more vertically-optimized tables](/src/render-help/render-flags.ts#L4) for narrower viewports.
+
+This feature is powered by [terminal-columns](https://github.com/privatenumber/terminal-columns) and can be configured via the `renderers.table` renderer.
+
+<table>
+	<tr>
+		<th>Normal width</th>
+		<th>Narrow width</th>
+	</tr>
+	<tr>
+		<th><img src=".github/responsive-normal.png" width="420"></th>
+		<th><img src=".github/responsive-narrow.png" width="300"></th>
+	</tr>
+</table>
+
+## API
+
+### cli(options, callback?, argvs?)
+
+Return type:
+```ts
+type ParsedArgv = {
+    // Parsed arguments
+    _: string[] & Parameters
+
+    // Parsed flags
+    flags: {
+        [flagName: string]: InferredType
+    }
+
+    // Unexpected flags
+    unknownFlags: {
+        [flagName: string]: (string | boolean)[]
+    }
+
+    // Method to print version
+    showVersion: () => void
+
+    // Method to print help
+    showHelp: (options: HelpOptions) => void
+}
+```
+
+Function to parse argvs by declaring parameters and flags.
+
+#### options
+
+Options object to configure `cli`.
+##### name
+
+Type: `string`
+
+Name of the script used in the help documentation.
+
+##### version
+
+Type: `string`
+
+Version of the script used in the help documentation.
+
+Passing this in enables auto-handling `--version`. To provide a version for the documentation without auto-handling `--version`, pass it into [`help.version`](#version-1).
+
+##### parameters
+
+Type: `string[]`
+
+Parameter names to map onto arguments. Also used for validation and help documentation.
+
+Parameters must be defined in the following formats:
+| Format | Description |
+| - | - |
+| `<parameter name>` | Required parameter |
+| `[parameter name]` | Optional parameter |
+| `<parameter name...>` | Required spread parameter (1 or more) |
+| `[parameter name...]` | Optional spread parameter (0 or more) |
+
+Required parameters must be defined before optional parameters, and spread parameters must be defined at the end.
+
+##### flags
+
+Type: An object that maps the flag name (in camelCase) to a flag type function or an object describing the flag:
+
+| Property | Type | Description |
+| - | - | - |
+| `type` | `Function` | Flag value parsing function. |
+| `alias` | `string` | Single character alias for the flag. |
+| `default` | `any` | Default value for the flag. |
+| `description` | `string` | Description of the flag shown in `--help`. |
+| `placeholder` | `string` | Placeholder for the flag value shown in `--help`. |
+
+##### help
+
+Type: `false` or an object with the following properties.
+
+| Property | Type | Description |
+| - | - | - |
+| `version` | `string` | Version shown in `--help`. |
+| `description` | `string` | Description shown in `--help`. |
+| `usage` | `string \| string[]` | Usage code examples shown in `--help`. |
+| `examples` | `string \| string[]` | Example code snippets shown in `--help`. |
+| `render` | `(nodes, renderers) => string` | Function to customize the help document. |
+
+Handling `--help, -h` is enabled by default. To disable it, pass in `false`.
+
+##### commands
+
+Type: `Command[]`
+
+Array of [commands](#commandoptions-callback) to register.
+
+
+#### callback(parsed)
+
+Type: 
+
+Optional callback function that is called when the script is invoked without a command.
+
+#### argvs
+
+Type: `string[]`
+
+Default: `process.argv.slice(2)`
+
+The raw parameters array to parse.
+
+### command(options, callback?)
+
+#### options
+
+| Property | Type | Description |
+| - | - | - |
+| `name` | `string` | Required name used to invoke the command. |
+| `alias` | `string \| string[]` | Aliases used to invoke the command. |
+| `parameters` | `string[]` | Parameters for the command. Same as [`parameters`](#parameters-1). |
+| `flags` | `Flags` | Flags for the command. Same as [`flags`](#flags-1). |
+| `help` | `false \| HelpOptions` | Help options for the command. Same as [`help`](#help-1). |
+
+#### callback(parsed)
+
+Type: 
+
+Optional callback function that is called when the command is invoked.

package/dist/index.d.ts

@@ -0,0 +1,203 @@
+import { Flags as Flags$1, TypeFlag } from 'type-flag';
+import { Options } from 'terminal-columns';
+
+declare type CommandOptions<Parameters = string[]> = {
+    /**
+    Name of the command used to invoke it. Also displayed in `--help` output.
+    */
+    name: string;
+    /**
+    Aliases for the command used to invoke it. Also displayed in `--help` output.
+    */
+    alias?: string | string[];
+    /**
+    Parameters accepted by the command. Parameters must be in the following formats:
+
+    - Required parameter: `<parameter name>`
+    - Optional parameter: `[parameter name]`
+    - Required spread parameter: `<parameter name...>`
+    - Optional spread parameter: `[parameter name...]`
+    */
+    parameters?: Parameters;
+    /**
+    Flags accepted by the command
+    */
+    flags?: Flags;
+    /**
+    Options to configure the help documentation. Pass in `false` to disable handling `--help, -h`.
+    */
+    help?: false | HelpOptions;
+};
+declare function command<Options extends CommandOptions<[...Parameters]>, Parameters extends string[]>(options: Readonly<Options> & CommandOptions<[...Parameters]>, callback?: CallbackFunction<ParseArgv<Options, Parameters>>): Command<Options, ParseArgv<Options, Parameters, Options['name']>>;
+declare type Command<Options extends CommandOptions = CommandOptions, ParsedType = any> = {
+    readonly options: Options;
+    readonly callback?: CallbackFunction<any>;
+    [parsedType]: ParsedType;
+};
+
+declare type FlagData = {
+    name: string;
+    flag: Flags[string];
+    flagFormatted: string;
+    aliasesEnabled: boolean;
+    aliasFormatted: string | undefined;
+};
+
+declare type TypeFunction = (value: any) => any;
+declare type HelpDocumentNodeOrString<Type extends PropertyKey> = string | HelpDocumentNode<Type>;
+declare class Renderers {
+    text(text: string): string;
+    bold(text: string): string;
+    indentText({ text, spaces }: {
+        text: string;
+        spaces: number;
+    }): string;
+    heading(text: string): string;
+    section({ title, body, indentBody, }: {
+        title?: string;
+        body?: string;
+        indentBody?: number;
+    }): string;
+    table({ tableData, tableOptions, tableBreakpoints, }: {
+        tableData: string[][];
+        tableOptions?: Options;
+        tableBreakpoints?: Record<string, Options>;
+    }): string;
+    flagParameter(typeFunction: TypeFunction | readonly [TypeFunction]): string;
+    flagOperator(): string;
+    flagName({ flag, flagFormatted, aliasesEnabled, aliasFormatted, }: FlagData): string;
+    flagDefault(value: any): string;
+    flagDescription({ flag }: FlagData): string;
+    render(nodes: (HelpDocumentNodeOrString<keyof this> | HelpDocumentNodeOrString<keyof this>[])): string;
+}
+
+declare const parsedType: unique symbol;
+declare type Flags = Flags$1<{
+    /**
+    Description to be used in help output
+
+    @example
+    ```
+    description: 'Unit of output (metric, imperial)',
+    ```
+    */
+    description?: string;
+    /**
+    Placeholder label to be used in help output
+
+    @example Required value
+    ```
+    placeholder: '<locale>'
+    ```
+    */
+    placeholder?: string;
+}>;
+declare type CallbackFunction<Parsed> = (parsed: {
+    [Key in keyof Parsed]: Parsed[Key];
+}) => void;
+declare type HasVersion<Options extends {
+    flags?: Flags;
+}> = (Options extends {
+    version: string;
+} ? Options['flags'] & {
+    version: BooleanConstructor;
+} : Options['flags']);
+declare type HasHelp<Options extends {
+    flags?: Flags;
+}> = (Options extends {
+    help: false;
+} ? Options['flags'] : Options['flags'] & {
+    help: BooleanConstructor;
+});
+declare type HasHelpOrVersion<Options> = HasVersion<Options> & HasHelp<Options>;
+declare type HelpDocumentNode<Types extends PropertyKey = keyof Renderers> = {
+    id?: string;
+    type: Types;
+    data: any;
+};
+declare type HelpOptions = {
+    /**
+    Version of the script displayed in `--help` output. Use to avoid enabling `--version` flag.
+    */
+    version?: string;
+    /**
+    Description of the script or command to display in `--help` output.
+    */
+    description?: string;
+    /**
+    Usage code examples to display in `--help` output.
+    */
+    usage?: false | string | string[];
+    /**
+    Example code snippets to display in `--help` output.
+    */
+    examples?: string | string[];
+    /**
+    Function to customize the help document before it is logged.
+    */
+    render?: (nodes: HelpDocumentNode<keyof Renderers>[], renderers: Renderers) => string;
+};
+declare type CliOptions<Commands = Command[], Parameters extends string[] = string[]> = {
+    /**
+    Name of the script displayed in `--help` output.
+    */
+    name?: string;
+    /**
+    Version of the script displayed in `--version` and `--help` outputs.
+    */
+    version?: string;
+    /**
+    Parameters accepted by the script. Parameters must be in the following formats:
+
+    - Required parameter: `<parameter name>`
+    - Optional parameter: `[parameter name]`
+    - Required spread parameter: `<parameter name...>`
+    - Optional spread parameter: `[parameter name...]`
+    */
+    parameters?: Parameters;
+    /**
+    Commands to register to the script.
+    */
+    commands?: Commands;
+    /**
+    Flags accepted by the script
+    */
+    flags?: Flags;
+    /**
+    Options to configure the help documentation. Pass in `false` to disable handling `--help, -h`.
+    */
+    help?: false | HelpOptions;
+};
+declare type kebabToCamel<Word extends string> = (Word extends `${infer Prefix}-${infer Suffix}` | `${infer Prefix} ${infer Suffix}` ? `${Prefix}${Capitalize<kebabToCamel<Suffix>>}` : Word);
+declare type StripBrackets<Parameter extends string> = (Parameter extends `<${infer ParameterName}>` | `[${infer ParameterName}]` ? (ParameterName extends `${infer SpreadName}...` ? SpreadName : ParameterName) : never);
+declare type ParameterType<Parameter extends string> = (Parameter extends `<${infer _ParameterName}...>` | `[${infer _ParameterName}...]` ? string[] : Parameter extends `<${infer _ParameterName}>` ? string : Parameter extends `[${infer _ParameterName}]` ? string | undefined : never);
+declare type WithCommand<Options extends {
+    flags?: Flags;
+}, Command extends string | undefined = undefined> = {
+    command: Command;
+} & Options;
+declare type TypeFlagWrapper<Options extends {
+    flags?: Flags;
+}, Parameters extends string[]> = TypeFlag<HasHelpOrVersion<Options>> & {
+    _: {
+        [Parameter in Parameters[number] as kebabToCamel<StripBrackets<Parameter>>]: ParameterType<Parameter>;
+    };
+    showHelp: (options?: HelpOptions) => void;
+    showVersion: () => void;
+};
+declare type ParseArgv<Options extends {
+    flags?: Flags;
+}, Parameters extends string[], Command extends string | undefined = ''> = (Command extends '' ? TypeFlagWrapper<Options, Parameters> : WithCommand<TypeFlagWrapper<Options, Parameters>, Command>);
+
+declare function cli<Options extends CliOptions<undefined, [...Parameters]>, Parameters extends string[]>(options: Options & CliOptions<undefined, [...Parameters]>, callback?: CallbackFunction<ParseArgv<Options, Parameters>>, argv?: string[]): {
+    [Key in keyof ParseArgv<Options, Parameters, undefined>]: ParseArgv<Options, Parameters, undefined>[Key];
+};
+declare function cli<Options extends CliOptions<[...Commands], [...Parameters]>, Commands extends Command[], Parameters extends string[]>(options: Options & CliOptions<[...Commands], [...Parameters]>, callback?: CallbackFunction<ParseArgv<Options, Parameters>>, argv?: string[]): ({
+    [Key in keyof ParseArgv<Options, Parameters, undefined>]: ParseArgv<Options, Parameters, undefined>[Key];
+} | {
+    [KeyA in keyof Commands]: (Commands[KeyA] extends Command ? ({
+        [KeyB in keyof Commands[KeyA][typeof parsedType]]: Commands[KeyA][typeof parsedType][KeyB];
+    }) : never);
+}[number]);
+
+export { cli, command };

package/dist/index.js

@@ -0,0 +1,10 @@
+var M=Object.create;var y=Object.defineProperty,W=Object.defineProperties,Z=Object.getOwnPropertyDescriptor,z=Object.getOwnPropertyDescriptors,G=Object.getOwnPropertyNames,F=Object.getOwnPropertySymbols,Q=Object.getPrototypeOf,k=Object.prototype.hasOwnProperty,X=Object.prototype.propertyIsEnumerable;var D=(t,e,n)=>e in t?y(t,e,{enumerable:!0,configurable:!0,writable:!0,value:n}):t[e]=n,c=(t,e)=>{for(var n in e||(e={}))k.call(e,n)&&D(t,n,e[n]);if(F)for(var n of F(e))X.call(e,n)&&D(t,n,e[n]);return t},O=(t,e)=>W(t,z(e)),T=t=>y(t,"__esModule",{value:!0});var Y=(t,e)=>{for(var n in e)y(t,n,{get:e[n],enumerable:!0})},E=(t,e,n,a)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of G(e))!k.call(t,r)&&(n||r!=="default")&&y(t,r,{get:()=>e[r],enumerable:!(a=Z(e,r))||a.enumerable});return t},A=(t,e)=>E(T(y(t!=null?M(Q(t)):{},"default",!e&&t&&t.__esModule?{get:()=>t.default,enumerable:!0}:{value:t,enumerable:!0})),t),ee=(t=>(e,n)=>t&&t.get(e)||(n=E(T({}),e,1),t&&t.set(e,n),n))(typeof WeakMap!="undefined"?new WeakMap:0);var ue={};Y(ue,{cli:()=>V,command:()=>_});var q=A(require("type-flag"));var S=t=>t.replace(/[-_ ](\w)/g,(e,n)=>n.toUpperCase()),B=t=>t.replace(/\B([A-Z])/g,"-$1").toLowerCase();var te={"> 80":[{width:"content-width",paddingLeft:2,paddingRight:8},{width:"auto"}],"> 40":[{width:"auto",paddingLeft:2,paddingRight:8,preprocess:t=>t.trim()},{width:"100%",paddingLeft:2,paddingBottom:1}],"> 0":{stdoutColumns:1e3,columns:[{width:"content-width",paddingLeft:2,paddingRight:8},{width:"content-width"}]}};function I(t){let e=!1,a=Object.keys(t).sort((r,s)=>r.localeCompare(s)).map(r=>{let s=t[r],i="alias"in s;return i&&(e=!0),{name:r,flag:s,flagFormatted:`--${B(r)}`,aliasesEnabled:e,aliasFormatted:i?`-${s.alias}`:void 0}}).map(r=>(r.aliasesEnabled=e,[{type:"flagName",data:r},{type:"flagDescription",data:r}]));return{type:"table",data:{tableData:a,tableBreakpoints:te}}}var R=t=>{var e;return!t||((e=t.version)!=null?e:t.help?t.help.version:void 0)},j=t=>{var n;let e="parent"in t&&((n=t.parent)==null?void 0:n.name);return(e?`${e} `:"")+t.name};function ne(t){var a;let e=[];t.name&&e.push(j(t));let n=(a=R(t))!=null?a:"parent"in t&&R(t.parent);if(n&&e.push(`v${n}`),e.length!==0)return{id:"name",type:"text",data:`${e.join(" ")}
+`}}function re(t){let{help:e}=t;if(!(!e||!e.description))return{id:"description",type:"text",data:`${e.description}
+`}}function ae(t){var n;let e=t.help||{};if("usage"in e)return e.usage?{id:"usage",type:"section",data:{title:"Usage:",body:Array.isArray(e.usage)?e.usage.join(`
+`):e.usage}}:void 0;if(t.name){let a=[],r=[j(t)];if(t.flags&&Object.keys(t.flags).length>0&&r.push("[flags...]"),t.parameters&&t.parameters.length>0&&r.push(t.parameters.join(" ")),r.length>1&&a.push(r.join(" ")),"commands"in t&&((n=t.commands)==null?void 0:n.length)&&a.push(`${t.name} <command>`),a.length>0)return{id:"usage",type:"section",data:{title:"Usage:",body:a.join(`
+`)}}}}function se(t){var a;if(!("commands"in t)||!((a=t.commands)==null?void 0:a.length))return;let e=t.commands.map(r=>[r.options.name,r.options.help?r.options.help.description:""]);return{id:"commands",type:"section",data:{title:"Commands:",body:{type:"table",data:{tableData:e,tableOptions:[{width:"content-width",paddingLeft:2,paddingRight:8}]}},indentBody:0}}}function ie(t){if(!(!t.flags||Object.keys(t.flags).length===0))return{id:"flags",type:"section",data:{title:"Flags:",body:I(t.flags),indentBody:0}}}function oe(t){let{help:e}=t;if(!e||!e.examples||e.examples.length===0)return;let{examples:n}=e;if(Array.isArray(n)&&(n=n.join(`
+`)),n)return{id:"examples",type:"section",data:{title:"Examples:",body:n}}}function me(t){if(!("alias"in t)||!t.alias)return;let{alias:e}=t,n=Array.isArray(e)?e.join(", "):e;return{id:"aliases",type:"section",data:{title:"Aliases:",body:n}}}var $=t=>[ne,re,ae,se,ie,oe,me].map(e=>e(t)).filter(e=>Boolean(e));var K=A(require("tty")),C=A(require("terminal-columns")),pe=K.default.WriteStream.prototype.hasColors(),b=class{text(e){return e}bold(e){return`${e}`}indentText({text:e,spaces:n}){return e.replace(/^/gm," ".repeat(n))}heading(e){return pe?this.bold(e):e.toLocaleUpperCase()}section({title:e,body:n,indentBody:a=2}){return`${(e?`${this.heading(e)}
+`:"")+(n?this.indentText({text:this.render(n),spaces:a}):"")}
+`}table({tableData:e,tableOptions:n,tableBreakpoints:a}){return(0,C.default)(e.map(r=>r.map(s=>this.render(s))),a?(0,C.breakpoints)(a):n)}flagParameter(e){return e===Boolean?"":e===String?"<string>":e===Number?"<number>":Array.isArray(e)?this.flagParameter(e[0]):"<value>"}flagOperator(){return" "}flagName({flag:e,flagFormatted:n,aliasesEnabled:a,aliasFormatted:r}){let s="";if(r?s+=`${r}, `:a&&(s+="    "),s+=n,"placeholder"in e&&typeof e.placeholder=="string")s+=`${this.flagOperator()}${e.placeholder}`;else{let i=this.flagParameter("type"in e?e.type:e);i&&(s+=`${this.flagOperator()}${i}`)}return s}flagDefault(e){return JSON.stringify(e)}flagDescription({flag:e}){var a;let n="description"in e&&(a=e.description)!=null?a:"";if("default"in e){let{default:r}=e;typeof r=="function"&&(r=r()),r&&(n+=` (default: ${this.flagDefault(r)})`)}return n}render(e){if(typeof e=="string")return e;if(Array.isArray(e))return e.map(n=>this.render(n)).join(`
+`);if("type"in e&&this[e.type]){let n=this[e.type];if(typeof n=="function")return n.call(this,e.data)}throw new Error(`Invalid node type: ${JSON.stringify(e)}`)}};var h=/^[\w-]+$/;var{stringify:m}=JSON,le=/[|\\{}()[\]^$+*?.]/;function de(t){let e=[],n,a;for(let r of t){if(a)throw new Error(`Invalid parameter: Spread parameter ${m(a)} must be last`);let s=r[0],i=r[r.length-1],p;if(s==="<"&&i===">"&&(p=!0,n))throw new Error(`Invalid parameter: Required parameter ${m(r)} cannot come after optional parameter ${m(n)}`);if(s==="["&&i==="]"&&(p=!1,n=r),p===void 0)throw new Error(`Invalid parameter: ${m(r)}. Must be wrapped in <> (required parameter) or [] (optional parameter)`);let o=r.slice(1,-1),u=o.slice(-3)==="...";u&&(a=r,o=o.slice(0,-3));let g=o.match(le);if(g)throw new Error(`Invalid parameter: ${m(r)}. Invalid character found ${m(g[0])}`);e.push({name:o,required:p,spread:u})}return e}function ce(t){return t===void 0||t!==!1}function L(t,e,n,a){let r=c({},e.flags),s=e.version;s&&(r.version={type:Boolean,description:"Show version"});let{help:i}=e,p=ce(i);p&&!("help"in r)&&(r.help={type:Boolean,alias:"h",description:"Show help"});let o=(0,q.default)(r,a),u=()=>{console.log(e.version)};if(s&&o.flags.version===!0)return u(),process.exit(0);let g=new b,U=p&&(i==null?void 0:i.render)?i.render:l=>g.render(l),P=l=>{let x=$(O(c(c({},e),l?{help:l}:{}),{flags:r}));console.log(U(x,g))};if(p&&o.flags.help===!0)return P(),process.exit(0);if(e.parameters){let l=de(e.parameters),x=o._;for(let f=0;f<l.length;f+=1){let{name:N,required:J,spread:w}=l[f],v=w?o._.slice(f):o._[f];if(w&&(f=l.length),J&&(!v||w&&v.length===0))return console.error(`Error: Missing required parameter ${m(N)}
+`),P(),process.exit(1);x[S(N)]=v}}let H=O(c({},o),{showVersion:u,showHelp:P});return typeof n=="function"&&n(H),c({command:t},H)}function fe(t,e){let n=new Map;for(let a of e){let r=[a.options.name],{alias:s}=a.options;s&&(Array.isArray(s)?r.push(...s):r.push(s));for(let i of r){if(n.has(i))throw new Error(`Duplicate command name found: ${m(i)}`);n.set(i,a)}}return n.get(t)}function V(t,e,n=process.argv.slice(2)){if(!t)throw new Error("Options is required");if("name"in t&&(!t.name||!h.test(t.name)))throw new Error(`Invalid script name: ${m(t.name)}`);let a=n[0];if(t.commands&&h.test(a)){let r=fe(a,t.commands);if(r)return L(r.options.name,O(c({},r.options),{parent:t}),r.callback,n.slice(1))}return L(void 0,t,e,n)}function _(t,e){if(!t)throw new Error("Command options are required");let{name:n}=t;if(t.name===void 0)throw new Error("Command name is required");if(!h.test(n))throw new Error(`Invalid command name ${JSON.stringify(n)}. Command names must be one word.`);return{options:t,callback:e}}module.exports=ee(ue);0&&(module.exports={cli,command});

package/dist/index.mjs

@@ -0,0 +1,10 @@
+var R=Object.defineProperty,j=Object.defineProperties;var K=Object.getOwnPropertyDescriptors;var H=Object.getOwnPropertySymbols;var q=Object.prototype.hasOwnProperty,L=Object.prototype.propertyIsEnumerable;var N=(t,e,n)=>e in t?R(t,e,{enumerable:!0,configurable:!0,writable:!0,value:n}):t[e]=n,f=(t,e)=>{for(var n in e||(e={}))q.call(e,n)&&N(t,n,e[n]);if(H)for(var n of H(e))L.call(e,n)&&N(t,n,e[n]);return t},O=(t,e)=>j(t,K(e));import ee from"type-flag";var F=t=>t.replace(/[-_ ](\w)/g,(e,n)=>n.toUpperCase()),k=t=>t.replace(/\B([A-Z])/g,"-$1").toLowerCase();var V={"> 80":[{width:"content-width",paddingLeft:2,paddingRight:8},{width:"auto"}],"> 40":[{width:"auto",paddingLeft:2,paddingRight:8,preprocess:t=>t.trim()},{width:"100%",paddingLeft:2,paddingBottom:1}],"> 0":{stdoutColumns:1e3,columns:[{width:"content-width",paddingLeft:2,paddingRight:8},{width:"content-width"}]}};function D(t){let e=!1,a=Object.keys(t).sort((r,s)=>r.localeCompare(s)).map(r=>{let s=t[r],i="alias"in s;return i&&(e=!0),{name:r,flag:s,flagFormatted:`--${k(r)}`,aliasesEnabled:e,aliasFormatted:i?`-${s.alias}`:void 0}}).map(r=>(r.aliasesEnabled=e,[{type:"flagName",data:r},{type:"flagDescription",data:r}]));return{type:"table",data:{tableData:a,tableBreakpoints:V}}}var T=t=>{var e;return!t||((e=t.version)!=null?e:t.help?t.help.version:void 0)},E=t=>{var n;let e="parent"in t&&((n=t.parent)==null?void 0:n.name);return(e?`${e} `:"")+t.name};function _(t){var a;let e=[];t.name&&e.push(E(t));let n=(a=T(t))!=null?a:"parent"in t&&T(t.parent);if(n&&e.push(`v${n}`),e.length!==0)return{id:"name",type:"text",data:`${e.join(" ")}
+`}}function U(t){let{help:e}=t;if(!(!e||!e.description))return{id:"description",type:"text",data:`${e.description}
+`}}function J(t){var n;let e=t.help||{};if("usage"in e)return e.usage?{id:"usage",type:"section",data:{title:"Usage:",body:Array.isArray(e.usage)?e.usage.join(`
+`):e.usage}}:void 0;if(t.name){let a=[],r=[E(t)];if(t.flags&&Object.keys(t.flags).length>0&&r.push("[flags...]"),t.parameters&&t.parameters.length>0&&r.push(t.parameters.join(" ")),r.length>1&&a.push(r.join(" ")),"commands"in t&&((n=t.commands)==null?void 0:n.length)&&a.push(`${t.name} <command>`),a.length>0)return{id:"usage",type:"section",data:{title:"Usage:",body:a.join(`
+`)}}}}function M(t){var a;if(!("commands"in t)||!((a=t.commands)==null?void 0:a.length))return;let e=t.commands.map(r=>[r.options.name,r.options.help?r.options.help.description:""]);return{id:"commands",type:"section",data:{title:"Commands:",body:{type:"table",data:{tableData:e,tableOptions:[{width:"content-width",paddingLeft:2,paddingRight:8}]}},indentBody:0}}}function W(t){if(!(!t.flags||Object.keys(t.flags).length===0))return{id:"flags",type:"section",data:{title:"Flags:",body:D(t.flags),indentBody:0}}}function Z(t){let{help:e}=t;if(!e||!e.examples||e.examples.length===0)return;let{examples:n}=e;if(Array.isArray(n)&&(n=n.join(`
+`)),n)return{id:"examples",type:"section",data:{title:"Examples:",body:n}}}function z(t){if(!("alias"in t)||!t.alias)return;let{alias:e}=t,n=Array.isArray(e)?e.join(", "):e;return{id:"aliases",type:"section",data:{title:"Aliases:",body:n}}}var v=t=>[_,U,J,M,W,Z,z].map(e=>e(t)).filter(e=>Boolean(e));import G from"tty";import Q,{breakpoints as X}from"terminal-columns";var Y=G.WriteStream.prototype.hasColors(),C=class{text(e){return e}bold(e){return`${e}`}indentText({text:e,spaces:n}){return e.replace(/^/gm," ".repeat(n))}heading(e){return Y?this.bold(e):e.toLocaleUpperCase()}section({title:e,body:n,indentBody:a=2}){return`${(e?`${this.heading(e)}
+`:"")+(n?this.indentText({text:this.render(n),spaces:a}):"")}
+`}table({tableData:e,tableOptions:n,tableBreakpoints:a}){return Q(e.map(r=>r.map(s=>this.render(s))),a?X(a):n)}flagParameter(e){return e===Boolean?"":e===String?"<string>":e===Number?"<number>":Array.isArray(e)?this.flagParameter(e[0]):"<value>"}flagOperator(){return" "}flagName({flag:e,flagFormatted:n,aliasesEnabled:a,aliasFormatted:r}){let s="";if(r?s+=`${r}, `:a&&(s+="    "),s+=n,"placeholder"in e&&typeof e.placeholder=="string")s+=`${this.flagOperator()}${e.placeholder}`;else{let i=this.flagParameter("type"in e?e.type:e);i&&(s+=`${this.flagOperator()}${i}`)}return s}flagDefault(e){return JSON.stringify(e)}flagDescription({flag:e}){var a;let n="description"in e&&(a=e.description)!=null?a:"";if("default"in e){let{default:r}=e;typeof r=="function"&&(r=r()),r&&(n+=` (default: ${this.flagDefault(r)})`)}return n}render(e){if(typeof e=="string")return e;if(Array.isArray(e))return e.map(n=>this.render(n)).join(`
+`);if("type"in e&&this[e.type]){let n=this[e.type];if(typeof n=="function")return n.call(this,e.data)}throw new Error(`Invalid node type: ${JSON.stringify(e)}`)}};var h=/^[\w-]+$/;var{stringify:m}=JSON,te=/[|\\{}()[\]^$+*?.]/;function ne(t){let e=[],n,a;for(let r of t){if(a)throw new Error(`Invalid parameter: Spread parameter ${m(a)} must be last`);let s=r[0],i=r[r.length-1],p;if(s==="<"&&i===">"&&(p=!0,n))throw new Error(`Invalid parameter: Required parameter ${m(r)} cannot come after optional parameter ${m(n)}`);if(s==="["&&i==="]"&&(p=!1,n=r),p===void 0)throw new Error(`Invalid parameter: ${m(r)}. Must be wrapped in <> (required parameter) or [] (optional parameter)`);let o=r.slice(1,-1),g=o.slice(-3)==="...";g&&(a=r,o=o.slice(0,-3));let y=o.match(te);if(y)throw new Error(`Invalid parameter: ${m(r)}. Invalid character found ${m(y[0])}`);e.push({name:o,required:p,spread:g})}return e}function re(t){return t===void 0||t!==!1}function S(t,e,n,a){let r=f({},e.flags),s=e.version;s&&(r.version={type:Boolean,description:"Show version"});let{help:i}=e,p=re(i);p&&!("help"in r)&&(r.help={type:Boolean,alias:"h",description:"Show help"});let o=ee(r,a),g=()=>{console.log(e.version)};if(s&&o.flags.version===!0)return g(),process.exit(0);let y=new C,B=p&&(i==null?void 0:i.render)?i.render:l=>y.render(l),b=l=>{let P=v(O(f(f({},e),l?{help:l}:{}),{flags:r}));console.log(B(P,y))};if(p&&o.flags.help===!0)return b(),process.exit(0);if(e.parameters){let l=ne(e.parameters),P=o._;for(let u=0;u<l.length;u+=1){let{name:$,required:I,spread:x}=l[u],w=x?o._.slice(u):o._[u];if(x&&(u=l.length),I&&(!w||x&&w.length===0))return console.error(`Error: Missing required parameter ${m($)}
+`),b(),process.exit(1);P[F($)]=w}}let A=O(f({},o),{showVersion:g,showHelp:b});return typeof n=="function"&&n(A),f({command:t},A)}function ae(t,e){let n=new Map;for(let a of e){let r=[a.options.name],{alias:s}=a.options;s&&(Array.isArray(s)?r.push(...s):r.push(s));for(let i of r){if(n.has(i))throw new Error(`Duplicate command name found: ${m(i)}`);n.set(i,a)}}return n.get(t)}function se(t,e,n=process.argv.slice(2)){if(!t)throw new Error("Options is required");if("name"in t&&(!t.name||!h.test(t.name)))throw new Error(`Invalid script name: ${m(t.name)}`);let a=n[0];if(t.commands&&h.test(a)){let r=ae(a,t.commands);if(r)return S(r.options.name,O(f({},r.options),{parent:t}),r.callback,n.slice(1))}return S(void 0,t,e,n)}function ie(t,e){if(!t)throw new Error("Command options are required");let{name:n}=t;if(t.name===void 0)throw new Error("Command name is required");if(!h.test(n))throw new Error(`Invalid command name ${JSON.stringify(n)}. Command names must be one word.`);return{options:t,callback:e}}export{se as cli,ie as command};

package/package.json

@@ -0,0 +1,73 @@
+{
+	"name": "cleye",
+	"version": "1.0.0",
+	"description": "The intuitive CLI development tool",
+	"keywords": [
+		"cli",
+		"command line",
+		"argv",
+		"parameters",
+		"flags",
+		"node",
+		"typescript"
+	],
+	"license": "MIT",
+	"repository": "privatenumber/cleye",
+	"funding": "https://github.com/privatenumber/cleye?sponsor=1",
+	"author": {
+		"name": "Hiroki Osame",
+		"email": "hiroki.osame@gmail.com"
+	},
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"require": "./dist/index.js",
+			"import": "./dist/index.mjs",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"scripts": {
+		"build": "tsup src/index.ts --dts --format esm,cjs --minify",
+		"lint": "eslint .",
+		"test": "CI=true jest"
+	},
+	"husky": {
+		"hooks": {
+			"pre-commit": "lint-staged && npm test"
+		}
+	},
+	"lint-staged": {
+		"*.ts": [
+			"eslint"
+		]
+	},
+	"dependencies": {
+		"terminal-columns": "^1.4.0",
+		"type-flag": "^2.0.0"
+	},
+	"devDependencies": {
+		"@pvtnbr/eslint-config": "^0.11.0",
+		"@types/jest": "^27.4.0",
+		"@types/node": "^17.0.8",
+		"colorette": "^2.0.16",
+		"es-jest": "^1.5.0",
+		"eslint": "^8.6.0",
+		"esno": "^0.13.0",
+		"husky": "^4.3.8",
+		"jest": "^27.4.7",
+		"lint-staged": "^12.1.2",
+		"tsup": "^5.11.10",
+		"typescript": "^4.5.4"
+	},
+	"eslintConfig": {
+		"extends": "@pvtnbr",
+		"rules": {
+			"unicorn/no-process-exit": "off"
+		}
+	}
+}