cli-api 0.1.1 → 0.2.0

package/dist/types/constants.d.ts

@@ -1,4 +0,0 @@
-export declare const EMPTY_ARRAY: ReadonlyArray<any>;
-export declare const EMPTY_OBJECT: Record<string, any>;
-export declare const TRUE_VALUES: Set<string>;
-export declare const FALSE_VALUES: Set<string>;

package/dist/types/index.d.ts

@@ -1,3 +0,0 @@
-export type { App, Command, Option } from "./interfaces";
-export { OptType } from './interfaces';
-export { default as default } from './run';

package/dist/types/interfaces.d.ts

@@ -1,79 +0,0 @@
-export interface Command {
-    name: string;
-    alias?: string | string[];
-    description?: string;
-    longDescription?: string;
-    flags?: Flag[];
-    options?: Option[];
-    arguments?: Argument[];
-    /**
-     * Executed when the command matches.
-     *
-     * @param options Named arguments, options, and flags.
-     * @param args Positional arguments.
-     * @param app Entire app config.
-     */
-    execute(options: Record<string, any>, args: string[], app: App): Promise<number | void>;
-}
-export declare enum OptType {
-    STRING = 0,
-    BOOL = 1,
-    INT = 2,
-    FLOAT = 3,
-    /** A string, truncated and converted to lowercase. */
-    ENUM = 4,
-    /** File must be readable. Single dash will be converted to STDIN. */
-    INPUT_FILE = 5,
-    /** Directory must be readable. */
-    INPUT_DIRECTORY = 6,
-    /** File's directory must exist and be writeable. Single dash will be converted to STDOUT. */
-    OUTPUT_FILE = 7,
-    OUTPUT_DIRECTORY = 8,
-    /** An empty or non-existent directory. */
-    EMPTY_DIRECTORY = 9
-}
-interface ArgumentOrOptionOrFlag {
-    /** Name of the option to display in help. */
-    name: string;
-    /** Alternative name for this option. */
-    alias?: string | string[];
-    /** Description of the option. */
-    description?: string;
-    /** Default value if not provided. */
-    defaultValue?: any | ((value: string) => any);
-    /** Default value to display in help. */
-    defaultValueText?: string;
-    /** Property name to use in `execute()` options. */
-    key?: string;
-}
-export declare type AnyOptType = OptType | string[];
-export interface ArgumentOrOption extends ArgumentOrOptionOrFlag {
-    /** Type to coerce the option value to. */
-    type?: AnyOptType;
-    /** Option is repeatable by specifying the flag again. Value will be an array. */
-    repeatable?: boolean;
-    /** Option is required. */
-    required?: boolean;
-}
-/** Boolean flag. */
-export interface Flag extends ArgumentOrOptionOrFlag, OptionOrFlag {
-}
-/** Positional argument. */
-export interface Argument extends ArgumentOrOption {
-}
-interface OptionOrFlag {
-    valueNotRequired?: boolean;
-}
-/** Option with value. */
-export interface Option extends ArgumentOrOption, OptionOrFlag {
-    /** Placeholder value to use in help. */
-    valuePlaceholder?: string;
-}
-export interface App {
-    name: string;
-    argv0?: string;
-    version?: string;
-    commands: Command[];
-    globalOptions?: Option[];
-}
-export {};

package/dist/types/options.d.ts

@@ -1,7 +0,0 @@
-import { App, Command, Option } from './interfaces';
-export declare function formatOption(opt: Option): [string, string];
-export declare function getValuePlaceholder(opt: Option): string;
-export declare function getOptions(cmd: Command): Option[];
-export declare function parseArgs(cmd: Command, argv: string[]): [any[], Record<string, any>];
-export declare function getOptName(opt: Option): string;
-export declare function getCommand(name: string, app: App): Command;

package/dist/types/print-command-help.d.ts

@@ -1,2 +0,0 @@
-import { App, Command } from './interfaces';
-export declare function printCommandHelp(app: App, cmd: Command): void;

package/dist/types/run.d.ts

@@ -1,2 +0,0 @@
-import { App } from './interfaces';
-export default function run(app: App): void;

package/dist/types/utils.d.ts

@@ -1,17 +0,0 @@
-/// <reference types="node" />
-import { App } from './interfaces';
-import FileSys from 'fs';
-export declare const print: {
-    (buffer: string | Uint8Array, cb?: ((err?: Error | undefined) => void) | undefined): boolean;
-    (str: string | Uint8Array, encoding?: string | undefined, cb?: ((err?: Error | undefined) => void) | undefined): boolean;
-};
-export declare const printLn: (message?: any, ...optionalParams: any[]) => void;
-export declare function abort(message: string, code?: number): never;
-export declare function toArray<T>(x: T | T[]): readonly T[];
-export declare function resolve<T>(x: any): T;
-export declare function toBool(str: string | boolean): boolean;
-export declare function space(len: number, str?: string): string;
-export declare function getProcName(app: App): string;
-export declare function includes(needle: string, haystack: string | string[] | undefined): boolean;
-export declare function statSync(path: string): FileSys.Stats | null;
-export declare function sortBy<T>(arr: T[], cmp: (x: T) => string): T[];

package/rollup.config.js

@@ -1,44 +0,0 @@
-import babel from '@rollup/plugin-babel';
-import nodeResolve from '@rollup/plugin-node-resolve';
-import nodeExternals from 'rollup-plugin-node-externals'
-import * as tsconfig from './tsconfig.json';
-import * as pkg from './package.json'
-import json from '@rollup/plugin-json';
-const extensions = ['.ts'];
-
-export default {
-    input: tsconfig.files,
-    plugins: [
-        nodeResolve({
-            extensions,
-        }),
-        nodeExternals({
-            builtins: true,
-            deps: true,
-            devDeps: false,
-            peerDeps: true,
-            optDeps: true,
-        }),
-        json(),
-        // TODO: change to typescript2 like node-mysql3c
-        babel({
-            exclude: 'node_modules/**',
-            extensions,
-            comments: false,
-            babelHelpers: 'bundled',
-        }),
-    ],
-    output: [
-        {
-            file: pkg.main,
-            format: 'cjs',
-            sourcemap: true,
-            exports: 'named',
-        },
-        {
-            file: pkg.module,
-            format: 'es',
-            sourcemap: true,
-        },
-    ],
-}

package/src/app-help.ts

@@ -1,34 +0,0 @@
-import {App} from './interfaces'
-import {getProcName, print, printLn, space} from './utils'
-import Chalk from 'chalk'
-import stringWidth from 'string-width'
-
-export function printHelp(app: App) {
-    print(Chalk.green(app.name))
-    if (app.version) {
-        print(` version ${Chalk.yellow(app.version)}`)
-    }
-    print('\n\n')
-    printLn(Chalk.yellow("Usage:"))
-    printLn(`  ${Chalk.cyan(getProcName(app))} ${Chalk.gray('<')}command${Chalk.gray('>')} ${Chalk.gray(`[options] [arguments]`)}\n`)
-
-    if (app.globalOptions) {
-        printLn("TODO")
-    }
-
-    printAvailableCommands(app)
-}
-
-export function printAvailableCommands(app: App) {
-    printLn(Chalk.yellow("Available commands:"))
-    const width = Math.max(...app.commands.map(c => stringWidth(c.name))) + 2
-    for (const cmd of app.commands) {
-        print(`  ${Chalk.green(cmd.name)}`)
-        if (cmd.description) {
-            print(`${space(width, cmd.name)}${cmd.description}`)
-        }
-        printLn()
-    }
-
-    // printLn()
-}

package/src/commands/command-help.ts

@@ -1,28 +0,0 @@
-import {App, Command} from '../interfaces'
-import {getCommand} from '../options'
-import {printCommandHelp} from '../print-command-help'
-import {printAvailableCommands} from '../app-help'
-import {printLn} from '../utils'
-
-export const helpCommand: Command = {
-    name: 'help',
-    // alias: '--help',
-    description: "Displays help for a command",
-    arguments: [
-        {
-            name: "command",
-            description: "The command name.",
-            required: false,
-        }
-    ],
-    async execute(options: Record<string, string>, [commandName]: string[], app: App) {
-        if(commandName) {
-            printCommandHelp(app, getCommand(commandName, app))
-        } else {
-            printCommandHelp(app, getCommand('help', app))
-            printLn()
-            printAvailableCommands(app)
-        }
-    }
-}
-

package/src/commands/version.ts

@@ -1,11 +0,0 @@
-import {Command} from '../interfaces'
-import {printLn} from '../utils'
-
-export const versionCommand: Command = {
-    name: 'version',
-    // alias: '--version',
-    description: "Displays current version",
-    async execute(opts, args, app) {
-        printLn(app.version)
-    }
-}

package/src/constants.ts

@@ -1,4 +0,0 @@
-export const EMPTY_ARRAY: ReadonlyArray<any> = Object.freeze([])
-export const EMPTY_OBJECT: Record<string,any> = Object.freeze(Object.create({__proto__:null}))
-export const TRUE_VALUES = new Set(['y', 'yes', 't', 'true', '1', 'on'])
-export const FALSE_VALUES = new Set(['n', 'no', 'f', 'false', '0', 'off'])

package/src/index.ts

@@ -1,3 +0,0 @@
-export type {App, Command, Option} from "./interfaces"
-export {OptType} from './interfaces'
-export {default as default} from './run'

package/src/interfaces.ts

@@ -1,89 +0,0 @@
-export interface Command {
-    name: string
-    alias?: string|string[]
-    description?: string
-    longDescription?: string
-    flags?: Flag[]
-    options?: Option[]
-    arguments?: Argument[]
-    /**
-     * Executed when the command matches.
-     *
-     * @param options Named arguments, options, and flags.
-     * @param args Positional arguments.
-     * @param app Entire app config.
-     */
-    execute(options: Record<string,any>, args: string[], app: App): Promise<number|void>
-}
-
-export enum OptType {
-    STRING,
-    BOOL,
-    INT,
-    FLOAT,
-    /** A string, truncated and converted to lowercase. */
-    ENUM,
-    /** File must be readable. Single dash will be converted to STDIN. */
-    INPUT_FILE,
-    /** Directory must be readable. */
-    INPUT_DIRECTORY,
-    /** File's directory must exist and be writeable. Single dash will be converted to STDOUT. */
-    OUTPUT_FILE,
-    OUTPUT_DIRECTORY,
-    /** An empty or non-existent directory. */
-    EMPTY_DIRECTORY,
-}
-
-interface ArgumentOrOptionOrFlag {
-    /** Name of the option to display in help. */
-    name: string
-    /** Alternative name for this option. */
-    alias?: string|string[]
-    /** Description of the option. */
-    description?: string
-    /** Default value if not provided. */
-    defaultValue?: any|((value:string)=>any)
-    /** Default value to display in help. */
-    defaultValueText?: string
-    /** Property name to use in `execute()` options. */
-    key?: string
-}
-
-export type AnyOptType = OptType | string[] // | ((value:string)=>any)
-
-export interface ArgumentOrOption extends ArgumentOrOptionOrFlag {
-    /** Type to coerce the option value to. */
-    type?: AnyOptType
-    /** Option is repeatable by specifying the flag again. Value will be an array. */
-    repeatable?: boolean
-    /** Option is required. */
-    required?: boolean
-}
-
-/** Boolean flag. */
-export interface Flag extends ArgumentOrOptionOrFlag,OptionOrFlag {
-
-}
-
-/** Positional argument. */
-export interface Argument extends ArgumentOrOption {
-
-}
-
-interface OptionOrFlag {
-    valueNotRequired?: boolean
-}
-
-/** Option with value. */
-export interface Option extends ArgumentOrOption,OptionOrFlag {
-    /** Placeholder value to use in help. */
-    valuePlaceholder?: string
-}
-
-export interface App {
-    name: string
-    argv0?: string
-    version?: string
-    commands: Command[]
-    globalOptions?: Option[]
-}

package/src/options.ts

@@ -1,266 +0,0 @@
-import {AnyOptType, App, Command, Option, OptType} from './interfaces'
-import {abort, includes, resolve, statSync, toArray, toBool} from './utils'
-import Chalk from 'chalk'
-import Path from 'path'
-import FileSys from 'fs'
-
-export function formatOption(opt: Option): [string, string] {
-    const aliases: string[] = []
-    if (opt.alias) {
-        if (Array.isArray(opt.alias)) {
-            aliases.push(...opt.alias)
-        } else {
-            aliases.push(opt.alias)
-        }
-    }
-    aliases.push(opt.name)
-    let flags = aliases.map(a => Chalk.green(a.length === 1 ? `-${a}` : `--${a}`)).join(', ')
-    let valuePlaceholder = getValuePlaceholder(opt)
-    if (opt.type !== OptType.BOOL) {
-        flags += `=${valuePlaceholder}`
-    }
-    let desc = opt.description ?? ''
-    let defaultValueText = opt.defaultValueText
-    if (defaultValueText === undefined && opt.defaultValue !== undefined) {
-        defaultValueText = JSON.stringify(resolve(opt.defaultValue))
-    }
-    if (defaultValueText !== undefined) {
-        desc += Chalk.yellow(` [default: ${defaultValueText}]`)
-    }
-    return [flags, desc]
-}
-
-export function getValuePlaceholder(opt: Option): string {
-    if (opt.valuePlaceholder !== undefined) {
-        return opt.valuePlaceholder
-    }
-    if (Array.isArray(opt.type)) {
-        return opt.type.join('|')
-    } else if (opt.type == OptType.BOOL) {
-        return JSON.stringify(!resolve(opt.defaultValue))
-    } else if (opt.type === OptType.INT || opt.type === OptType.FLOAT) {
-        return '#'
-    } else if (opt.type === OptType.INPUT_FILE || opt.type === OptType.OUTPUT_FILE) {
-        return 'FILE'
-    } else if (opt.type === OptType.INPUT_DIRECTORY || opt.type === OptType.OUTPUT_DIRECTORY || opt.type === OptType.EMPTY_DIRECTORY) {
-        return 'DIR'
-    } else {
-        return opt.name
-    }
-}
-
-export function getOptions(cmd: Command): Option[] {
-    return [
-        ...toArray(cmd.options),
-        ...toArray(cmd.flags).map(f => ({
-            ...f,
-            valueNotRequired: true,
-            type: OptType.BOOL,
-
-        })),
-        // {
-        //     name: 'help',
-        //     description: "Print help for this command",
-        //     valueNotRequired: true,
-        //     type: OptType.BOOL,
-        // }
-    ] as Option[]
-}
-
-export function parseArgs(cmd: Command, argv: string[]): [any[], Record<string, any>] {
-    const args: any[] = []
-    const opts: Record<string, any> = Object.create(null)
-    let parseFlags = true
-    // TODO: initialize all repeatables to empty arrays
-
-    const allOptions = getOptions(cmd)
-
-    let argIdx = 0
-    for (let i = 0; i < argv.length; ++i) {
-        let arg = argv[i]
-
-        if (parseFlags && arg === '--') {
-            parseFlags = false
-            continue
-        }
-
-        if (parseFlags && arg.length >= 2 && arg.startsWith('-')) {
-            let name: string
-            let value: any
-            if (arg.includes('=')) {
-                [arg, value] = arg.split('=', 2)
-            } /*else if(i < argv.length - 2 && argv[i+1] === '=') {
-                value = argv[i+2]
-                i += 2
-            }*/
-            if (arg.startsWith('--')) {
-                name = arg.slice(2)
-            } else {
-                if (arg.length > 2) {
-                    if (value !== undefined) {
-                        abort(`Malformed option "${arg}"`)
-                    }
-                    value = arg.slice(2)
-                    arg = arg.slice(0, 2)
-                }
-                name = arg.slice(1)
-                // TODO: parse multiple single-char flags
-            }
-
-            const opt = allOptions.find(opt => opt.name === name || includes(name, opt.alias))
-            if (!opt) {
-                abort(`"${cmd.name}" command does not have option "${name}".`)
-            }
-            if (value === undefined) {
-                if (opt.valueNotRequired) {
-                    value = !resolve(opt.defaultValue)
-                } else if (i < argv.length - 1) {
-                    value = argv[++i]
-                } else {
-                    abort(`Missing required value for option "${arg}"`)
-                }
-            }
-            if (opt.type != null) {
-                value = coerceType(value, opt.type)
-            }
-            opts[opt.key ?? opt.name] = value
-        } else {
-            // TODO: examine cmd.arguments
-            let value: any = arg
-
-            if (cmd.arguments && cmd.arguments.length > argIdx) {
-                const cmdArg = cmd.arguments[argIdx]
-                if (cmdArg.type != null) {
-                    value = coerceType(value, cmdArg.type)
-                }
-                if (cmdArg.key) {
-                    opts[cmdArg.key] = value
-                }
-            }
-            args.push(value)
-            ++argIdx
-        }
-    }
-
-    if (allOptions.length) {
-        for (const opt of allOptions) {
-            const k = opt.key ?? opt.name
-            if (opts[k] === undefined) {
-                if (opt.defaultValue !== undefined) {
-                    opts[k] = resolve(opt.defaultValue)
-                } else if (opt.required) {
-                    throw new Error(`"${getOptName(opt)}" option is required`)
-                } else {
-                    // TODO: should we fill in undefined options? with `null` or `undefined`?
-                }
-            }
-        }
-    }
-
-    if (cmd.arguments?.length) {
-        for (let i = 0; i < cmd.arguments.length; ++i) {
-            if (cmd.arguments[i].required && argIdx <= i) {
-                throw new Error(`"${cmd.arguments[i].name}" argument is required`)
-            }
-        }
-    }
-
-    // TODO: fill global options into opts
-    // TODO: copy named arguments into opts too
-    return [args, opts]
-}
-
-function coerceType(value: string, type: AnyOptType) {
-    if (Array.isArray(type)) {
-        // TODO: search for closest match of value in type or throw error
-        return String(value).trim().toLowerCase()
-    }
-    switch (type) {
-        case OptType.BOOL:
-            return toBool(value)
-        case OptType.INT:
-            return Math.trunc(Number(value))
-        case OptType.FLOAT:
-            return Number(value)
-        case OptType.ENUM:
-            return String(value).trim().toLowerCase()
-        case OptType.STRING:
-            return String(value)
-        case OptType.INPUT_FILE: {
-            if (value === '-') return '/dev/stdin'    // TODO: support windows
-            const file = Path.normalize(value)
-            const fullPath = Path.resolve(file)
-            const stat = statSync(file)
-            if (!stat) {
-                throw new Error(`File ${Chalk.underline(fullPath)} does not exist`)
-            }
-            if (!stat.isFile()) {
-                throw new Error(`${Chalk.underline(fullPath)} is not a file`)
-            }
-            try {
-                FileSys.accessSync(file, FileSys.constants.R_OK)
-            } catch (err) {
-                throw new Error(`${Chalk.underline(fullPath)} is not readable`)
-            }
-            return file
-        }
-        case OptType.INPUT_DIRECTORY:
-            const dir = Path.normalize(value)
-            FileSys.accessSync(dir, FileSys.constants.X_OK)
-            return dir
-        case OptType.OUTPUT_FILE: {
-            if (value === '-') return '/dev/stdout'  // TODO: support windows
-            const file = Path.normalize(value)
-            const stat = statSync(file)
-            if (stat) {
-                if (!stat.isFile()) {
-                    throw new Error(`'${file}' is not a file`)
-                }
-                // if((stat.mode & 0x222) === 0) { // TODO: does this work?
-                //     throw new Error(`'${value}' is not writeable`);
-                // }
-                FileSys.accessSync(file, FileSys.constants.W_OK)
-            } else {
-                FileSys.accessSync(Path.dirname(file), FileSys.constants.W_OK)
-            }
-            return file
-        }
-        case OptType.OUTPUT_DIRECTORY: {
-            FileSys.accessSync(value, FileSys.constants.W_OK)
-            return Path.normalize(value)
-        }
-        case OptType.EMPTY_DIRECTORY: {
-            const dir = Path.normalize(value)
-            let files = []
-            try {
-                files = FileSys.readdirSync(dir)
-            } catch (err) {
-                if (err.code === 'ENOENT') {
-                    FileSys.accessSync(Path.dirname(dir), FileSys.constants.W_OK)
-                } else {
-                    throw err
-                }
-            }
-            if (files.length) {
-                throw new Error(`${Chalk.underline(dir)} is not empty`)
-            }
-            return dir
-        }
-    }
-    return value
-}
-
-
-export function getOptName(opt: Option) {
-    return (opt.name.length > 1 ? '--' : '-') + opt.name
-}
-
-export function getCommand(name: string, app: App): Command {
-    const cmdName = String(name).trim().replace(/^-{1,2}/,'').toLowerCase()
-    const cmd = app.commands.find(c => c.name === cmdName || includes(cmdName, c.alias))
-    if (cmd === undefined) {
-        // TODO: levenshtein search for closest match? "Did you mean...?"
-        throw new Error(`Command "${name}" does not exist.`)
-    }
-    return cmd
-}

package/src/print-command-help.ts

@@ -1,78 +0,0 @@
-import {App, Command, OptType} from './interfaces'
-import {getProcName, print, printLn, space, toArray} from './utils'
-import Chalk from 'chalk'
-import {formatOption, getOptions, getOptName, getValuePlaceholder} from './options'
-import stringWidth from 'string-width'
-
-
-export function printCommandHelp(app: App, cmd: Command) {
-    if (cmd.description) {
-        printLn(cmd.description)
-        printLn()
-    }
-
-    printLn(Chalk.yellow("Usage:"))
-    print(`  ${Chalk.cyan(getProcName(app))} ${cmd.name}`)
-
-    const allOptions = getOptions(cmd)
-
-    if (allOptions.length) {
-        let otherOptions = 0
-        for (let opt of allOptions) {
-            if (opt.required) {
-                print(` ${getOptName(opt)}`)
-                if (opt.type !== OptType.BOOL) {
-                    print(`=${getValuePlaceholder(opt)}`)
-                }
-            } else {
-                ++otherOptions
-            }
-        }
-        if (otherOptions) {
-            print(` ${Chalk.gray('[')}options${Chalk.gray(']')}`)
-        }
-    }
-    if (cmd.arguments?.length) {
-        print(` ${Chalk.grey('[')}--${Chalk.grey(']')}`)
-        for (const arg of cmd.arguments) {
-            print(' ')
-            print(Chalk.grey(arg.required ? '<' : '['))
-            if (arg.repeatable) {
-                print(Chalk.grey('...'))
-            }
-            print(arg.name)
-            print(Chalk.grey(arg.required ? '>' : ']'))
-        }
-    }
-    printLn()
-
-    if (allOptions.length) {
-        printLn(Chalk.yellow("\nOptions:"))
-        const lines = allOptions.map(formatOption)
-        const width = Math.max(...lines.map(l => stringWidth(l[0])))
-        for (const line of lines) {
-            printLn('  ' + line[0] + space(width + 2, line[0]) + line[1])
-        }
-    }
-
-    if (cmd.arguments?.length) {
-        printLn(Chalk.yellow("\nArguments:"))
-        const width = Math.max(...cmd.arguments.map(a => stringWidth(a.name)))
-        for (const arg of cmd.arguments) {
-            print('  ' + Chalk.green(arg.name))
-            if (arg.description) {
-                print(space(width + 2, arg.name) + arg.description)
-            }
-            printLn()
-        }
-    }
-
-    if (cmd.alias) {
-        const alaises = toArray(cmd.alias)
-        printLn(Chalk.yellow(`\nAlias${alaises.length !== 1 ? 'es' : ''}: `) + toArray(cmd.alias).join(Chalk.gray(', ')))
-    }
-    if (cmd.longDescription) {
-        printLn(Chalk.yellow("\nDescription:"))
-        printLn('  ' + cmd.longDescription)
-    }
-}