cli-api 0.1.0 → 0.1.2

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)
-    }
-}

package/src/run.ts

@@ -1,45 +0,0 @@
-import {App} from './interfaces'
-import {helpCommand} from './commands/command-help'
-import {versionCommand} from './commands/version'
-import {printHelp} from './app-help'
-import {getCommand, parseArgs} from './options'
-import {abort, sortBy} from './utils'
-import {printCommandHelp} from './print-command-help'
-
-export default function run(app: App) {
-    app = {
-        ...app,
-        commands: [...sortBy(app.commands, c => c.name), versionCommand,helpCommand],
-        // commands: sortBy([...app.commands,versionCommand,helpCommand], c => c.name),
-    }
-    if (process.argv.length <= 2) {
-        printHelp(app)
-        process.exit(0)
-    }
-
-    const cmd = getCommand(process.argv[2], app)
-    const rawArgs = process.argv.slice(3)
-    if (rawArgs.includes('--help')) {
-        printCommandHelp(app, cmd)
-        process.exit(0)
-    }
-    let args, opts
-    try {
-        [args, opts] = parseArgs(cmd, rawArgs)
-    } catch (err) {
-        abort(String(err.message))
-        process.exit(2)
-    }
-    Promise.resolve(cmd.execute(opts, args, app))
-        .then(code => {
-            if (code != null) {
-                process.exit(code)
-            }
-            process.exit(0)
-        }, err => {
-            // console.error(err)
-            abort(String(err.stack))
-            process.exit(1)
-        })
-
-}

package/src/utils.ts

@@ -1,86 +0,0 @@
-import {App} from './interfaces'
-import Path from 'path'
-import stringWidth from 'string-width'
-import Chalk from 'chalk'
-import {EMPTY_ARRAY, FALSE_VALUES, TRUE_VALUES} from './constants'
-import FileSys from 'fs'
-
-export const print = process.stdout.write.bind(process.stdout)
-export const printLn = console.log.bind(console)
-
-function blockError(str: string) {
-    const lines = str.split('\n')
-    const width = Math.max(...lines.map(l => stringWidth(l))) + 4
-    printLn(Chalk.bgRed(space(width)))
-    for (const line of lines) {
-        const txt = `  ${line}`
-        printLn(Chalk.bgRed(txt + space(width, txt)))
-    }
-    printLn(Chalk.bgRed(space(width)))
-}
-
-export function abort(message: string, code: number = 1): never {
-    blockError(message)
-    process.exit(code)
-}
-
-export function toArray<T>(x: T | T[]): readonly T[] {
-    if (!x) return EMPTY_ARRAY
-    return Array.isArray(x) ? x : [x]
-}
-
-export function resolve<T>(x: any): T {
-    return typeof x === 'function' ? x() : x
-}
-
-export function toBool(str: string | boolean): boolean {
-    if (typeof str === 'boolean') return str
-    str = String(str).trim().toLowerCase()
-    if (TRUE_VALUES.has(str)) {
-        return true
-    }
-    if (FALSE_VALUES.has(str)) {
-        return false
-    }
-    throw new Error(`Could not cast "${str}" to boolean`)
-}
-
-export function space(len: number, str?: string) {
-    if (str) {
-        len -= stringWidth(str)
-    }
-
-    return len > 0 ? ' '.repeat(len) : ''
-}
-
-export function getProcName(app: App) {
-    if (app.argv0 != null) {
-        return app.argv0
-    }
-    const relPath = Path.relative(process.cwd(), process.argv[1])
-    // console.log(relPath, process.argv[1])
-    // console.log(process.argv0,process.argv[0])
-    return `${Path.basename(process.argv[0])} ${relPath.length < process.argv[1].length ? relPath : process.argv[1]}`
-}
-
-export function includes(needle: string, haystack: string | string[] | undefined) {
-    if (!haystack) return false
-    if (Array.isArray(haystack)) return haystack.includes(needle)
-    return needle === haystack
-}
-
-export function statSync(path: string): FileSys.Stats | null {
-    try {
-        return FileSys.lstatSync(path)
-    } catch {
-        return null
-    }
-}
-
-export function sortBy<T>(arr: T[], cmp: (x: T) => string): T[] {
-    const collator = new Intl.Collator() // 'en',{usage: 'sort',sensitivity:'base'}
-    const values = arr.map(cmp)
-    const keys = Array.from(arr.keys())
-    keys.sort((a, b) => collator.compare(values[a], values[b]))
-    return keys.map(i => arr[i])
-}