@clerc/core 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Ray <https://github.com/so1ve>
+
+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/dist/index.cjs

@@ -0,0 +1,393 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var liteEmit = require('lite-emit');
+var typeFlag = require('type-flag');
+var utils = require('@clerc/utils');
+var isPlatform = require('is-platform');
+
+class SingleCommandError extends Error {
+  constructor() {
+    super("Single command mode enabled.");
+  }
+}
+class SingleCommandAliasError extends Error {
+  constructor() {
+    super("Single command cannot have alias.");
+  }
+}
+class CommandExistsError extends Error {
+  constructor(name) {
+    super(`Command "${name}" exists.`);
+  }
+}
+class CommonCommandExistsError extends Error {
+  constructor() {
+    super("Common command exists.");
+  }
+}
+class NoSuchCommandError extends Error {
+  constructor(name) {
+    super(`No such command: ${name}`);
+  }
+}
+class ParentCommandExistsError extends Error {
+  constructor(name) {
+    super(`Command "${name}" cannot exist with its parent`);
+  }
+}
+class SubcommandExistsError extends Error {
+  constructor(name) {
+    super(`Command "${name}" cannot exist with its subcommand`);
+  }
+}
+class MultipleCommandsMatchedError extends Error {
+  constructor(name) {
+    super(`Multiple commands matched: ${name}`);
+  }
+}
+class CommandNameConflictError extends Error {
+  constructor(n1, n2) {
+    super(`Command name ${n1} conflicts with ${n2}. Maybe caused by alias.`);
+  }
+}
+
+function resolveFlattenCommands(commands) {
+  const commandsMap = /* @__PURE__ */ new Map();
+  for (const command of Object.values(commands)) {
+    if (command.alias) {
+      const aliases = utils.mustArray(command.alias);
+      for (const alias of aliases) {
+        if (alias in commands) {
+          throw new CommandNameConflictError(commands[alias].name, command.name);
+        }
+        commandsMap.set(alias.split(" "), { ...command, __isAlias: true });
+      }
+    }
+    commandsMap.set(command.name.split(" "), command);
+  }
+  return commandsMap;
+}
+function resolveCommand(commands, name) {
+  if (name === SingleCommand) {
+    return commands[SingleCommand];
+  }
+  const nameArr = utils.mustArray(name);
+  const commandsMap = resolveFlattenCommands(commands);
+  const possibleCommands = [];
+  commandsMap.forEach((v, k) => {
+    if (utils.arrayStartsWith(nameArr, k)) {
+      possibleCommands.push(v);
+    }
+  });
+  if (possibleCommands.length > 1) {
+    const matchedCommandNames = possibleCommands.map((c) => c.name).join(", ");
+    throw new MultipleCommandsMatchedError(matchedCommandNames);
+  }
+  return possibleCommands[0];
+}
+function resolveSubcommandsByParent(commands, parent, depth = Infinity) {
+  const parentArr = parent === "" ? [] : Array.isArray(parent) ? parent : parent.split(" ");
+  return Object.values(commands).filter((c) => {
+    const commandNameArr = c.name.split(" ");
+    return utils.arrayStartsWith(commandNameArr, parentArr) && commandNameArr.length - parentArr.length <= depth;
+  });
+}
+const resolveRootCommands = (commands) => resolveSubcommandsByParent(commands, "", 1);
+function resolveParametersBeforeFlag(argv, isSingleCommand) {
+  if (isSingleCommand) {
+    return [];
+  }
+  const parameters = [];
+  for (const arg of argv) {
+    if (arg.startsWith("-")) {
+      break;
+    }
+    parameters.push(arg);
+  }
+  return parameters;
+}
+const resolveArgv = () => isPlatform.isNode() ? process.argv.slice(2) : isPlatform.isDeno() ? Deno.args : [];
+function compose(inspectors) {
+  return (getCtx) => {
+    return dispatch(0);
+    function dispatch(i) {
+      const inspector = inspectors[i];
+      return inspector(getCtx(), dispatch.bind(null, i + 1));
+    }
+  };
+}
+
+const { stringify } = JSON;
+function parseParameters(parameters) {
+  const parsedParameters = [];
+  let hasOptional;
+  let hasSpread;
+  for (const parameter of parameters) {
+    if (hasSpread) {
+      throw new Error(`Invalid parameter: Spread parameter ${stringify(hasSpread)} must be last`);
+    }
+    const firstCharacter = parameter[0];
+    const lastCharacter = parameter[parameter.length - 1];
+    let required;
+    if (firstCharacter === "<" && lastCharacter === ">") {
+      required = true;
+      if (hasOptional) {
+        throw new Error(`Invalid parameter: Required parameter ${stringify(parameter)} cannot come after optional parameter ${stringify(hasOptional)}`);
+      }
+    }
+    if (firstCharacter === "[" && lastCharacter === "]") {
+      required = false;
+      hasOptional = parameter;
+    }
+    if (required === void 0) {
+      throw new Error(`Invalid parameter: ${stringify(parameter)}. Must be wrapped in <> (required parameter) or [] (optional parameter)`);
+    }
+    let name = parameter.slice(1, -1);
+    const spread = name.slice(-3) === "...";
+    if (spread) {
+      hasSpread = parameter;
+      name = name.slice(0, -3);
+    }
+    parsedParameters.push({
+      name,
+      required,
+      spread
+    });
+  }
+  return parsedParameters;
+}
+function mapParametersToArguments(mapping, parameters, cliArguments) {
+  for (let i = 0; i < parameters.length; i += 1) {
+    const { name, required, spread } = parameters[i];
+    const camelCaseName = utils.camelCase(name);
+    if (camelCaseName in mapping) {
+      throw new Error(`Invalid parameter: ${stringify(name)} is used more than once.`);
+    }
+    const value = spread ? cliArguments.slice(i) : cliArguments[i];
+    if (spread) {
+      i = parameters.length;
+    }
+    if (required && (!value || spread && value.length === 0)) {
+      console.error(`Error: Missing required parameter ${stringify(name)}
+`);
+      return process.exit(1);
+    }
+    mapping[camelCaseName] = value;
+  }
+}
+
+var __accessCheck = (obj, member, msg) => {
+  if (!member.has(obj))
+    throw TypeError("Cannot " + msg);
+};
+var __privateGet = (obj, member, getter) => {
+  __accessCheck(obj, member, "read from private field");
+  return getter ? getter.call(obj) : member.get(obj);
+};
+var __privateAdd = (obj, member, value) => {
+  if (member.has(obj))
+    throw TypeError("Cannot add the same private member more than once");
+  member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+};
+var __privateSet = (obj, member, value, setter) => {
+  __accessCheck(obj, member, "write to private field");
+  setter ? setter.call(obj, value) : member.set(obj, value);
+  return value;
+};
+var _name, _description, _version, _inspectors, _commands, _commandEmitter, _isSingleCommand, isSingleCommand_get, _hasCommands, hasCommands_get;
+const SingleCommand = Symbol("SingleCommand");
+const _Clerc = class {
+  constructor() {
+    __privateAdd(this, _isSingleCommand);
+    __privateAdd(this, _hasCommands);
+    __privateAdd(this, _name, "");
+    __privateAdd(this, _description, "");
+    __privateAdd(this, _version, "");
+    __privateAdd(this, _inspectors, []);
+    __privateAdd(this, _commands, {});
+    __privateAdd(this, _commandEmitter, new liteEmit.LiteEmit());
+  }
+  get _name() {
+    return __privateGet(this, _name);
+  }
+  get _description() {
+    return __privateGet(this, _description);
+  }
+  get _version() {
+    return __privateGet(this, _version);
+  }
+  get _inspectors() {
+    return __privateGet(this, _inspectors);
+  }
+  get _commands() {
+    return __privateGet(this, _commands);
+  }
+  static create() {
+    return new _Clerc();
+  }
+  name(name) {
+    __privateSet(this, _name, name);
+    return this;
+  }
+  description(description) {
+    __privateSet(this, _description, description);
+    return this;
+  }
+  version(version) {
+    __privateSet(this, _version, version);
+    return this;
+  }
+  command(nameOrCommand, description, options) {
+    const checkIsCommandObject = (nameOrCommand2) => !(typeof nameOrCommand2 === "string" || nameOrCommand2 === SingleCommand);
+    const isCommandObject = checkIsCommandObject(nameOrCommand);
+    const name = !isCommandObject ? nameOrCommand : nameOrCommand.name;
+    if (__privateGet(this, _commands)[name]) {
+      if (name === SingleCommand) {
+        throw new CommandExistsError("SingleCommand");
+      }
+    }
+    if (__privateGet(this, _isSingleCommand, isSingleCommand_get)) {
+      throw new SingleCommandError();
+    }
+    if (name === SingleCommand && __privateGet(this, _hasCommands, hasCommands_get)) {
+      throw new CommonCommandExistsError();
+    }
+    if (name === SingleCommand && (isCommandObject ? nameOrCommand : options).alias) {
+      throw new SingleCommandAliasError();
+    }
+    if (name !== SingleCommand) {
+      const splitedName = name.split(" ");
+      const existedCommandNames = Object.keys(__privateGet(this, _commands)).filter((name2) => typeof name2 === "string").map((name2) => name2.split(" "));
+      if (existedCommandNames.some((name2) => utils.arrayStartsWith(splitedName, name2))) {
+        throw new ParentCommandExistsError(splitedName.join(" "));
+      }
+      if (existedCommandNames.some((name2) => utils.arrayStartsWith(name2, splitedName))) {
+        throw new SubcommandExistsError(splitedName.join(" "));
+      }
+    }
+    const { handler = void 0, ...commandToSave } = isCommandObject ? nameOrCommand : { name, description, ...options };
+    __privateGet(this, _commands)[name] = commandToSave;
+    if (isCommandObject && handler) {
+      this.on(nameOrCommand.name, handler);
+    }
+    return this;
+  }
+  on(name, handler) {
+    __privateGet(this, _commandEmitter).on(name, handler);
+    return this;
+  }
+  use(plugin) {
+    return plugin.setup(this);
+  }
+  inspector(inspector) {
+    __privateGet(this, _inspectors).push(inspector);
+    return this;
+  }
+  parse(argv = resolveArgv()) {
+    const name = resolveParametersBeforeFlag(argv, __privateGet(this, _isSingleCommand, isSingleCommand_get));
+    const stringName = name.join(" ");
+    const getCommand = () => __privateGet(this, _isSingleCommand, isSingleCommand_get) ? __privateGet(this, _commands)[SingleCommand] : resolveCommand(__privateGet(this, _commands), name);
+    const getContext = () => {
+      const command = getCommand();
+      const isCommandResolved = !!command;
+      const parsed = typeFlag.typeFlag((command == null ? void 0 : command.flags) || {}, [...argv]);
+      const { _: args, flags } = parsed;
+      let parameters = __privateGet(this, _isSingleCommand, isSingleCommand_get) || !isCommandResolved ? args : args.slice(command.name.split(" ").length);
+      let commandParameters = (command == null ? void 0 : command.parameters) || [];
+      const hasEof = commandParameters.indexOf("--");
+      const eofParameters = commandParameters.slice(hasEof + 1) || [];
+      const mapping = /* @__PURE__ */ Object.create(null);
+      if (hasEof > -1 && eofParameters.length > 0) {
+        commandParameters = commandParameters.slice(0, hasEof);
+        const eofArguments = parsed._["--"];
+        parameters = parameters.slice(0, -eofArguments.length || void 0);
+        mapParametersToArguments(
+          mapping,
+          parseParameters(commandParameters),
+          parameters
+        );
+        mapParametersToArguments(
+          mapping,
+          parseParameters(eofParameters),
+          eofArguments
+        );
+      } else {
+        mapParametersToArguments(
+          mapping,
+          parseParameters(commandParameters),
+          parameters
+        );
+      }
+      const context = {
+        name: command == null ? void 0 : command.name,
+        resolved: isCommandResolved,
+        isSingleCommand: __privateGet(this, _isSingleCommand, isSingleCommand_get),
+        raw: { ...parsed, parameters },
+        parameters: mapping,
+        flags,
+        unknownFlags: parsed.unknownFlags,
+        cli: this
+      };
+      return context;
+    };
+    const emitHandler = () => {
+      const command = getCommand();
+      const handlerContext = getContext();
+      if (!command) {
+        throw new NoSuchCommandError(stringName);
+      }
+      __privateGet(this, _commandEmitter).emit(command.name, handlerContext);
+    };
+    const inspectors = [...__privateGet(this, _inspectors), emitHandler];
+    const callInspector = compose(inspectors);
+    callInspector(getContext);
+    return this;
+  }
+};
+let Clerc = _Clerc;
+_name = new WeakMap();
+_description = new WeakMap();
+_version = new WeakMap();
+_inspectors = new WeakMap();
+_commands = new WeakMap();
+_commandEmitter = new WeakMap();
+_isSingleCommand = new WeakSet();
+isSingleCommand_get = function() {
+  return __privateGet(this, _commands)[SingleCommand] !== void 0;
+};
+_hasCommands = new WeakSet();
+hasCommands_get = function() {
+  return Object.keys(__privateGet(this, _commands)).length > 0;
+};
+
+const definePlugin = (p) => p;
+const defineHandler = (_cli, _key, handler) => handler;
+const defineInspector = (_cli, inspector) => inspector;
+const defineCommand = (c) => c;
+
+exports.Clerc = Clerc;
+exports.CommandExistsError = CommandExistsError;
+exports.CommandNameConflictError = CommandNameConflictError;
+exports.CommonCommandExistsError = CommonCommandExistsError;
+exports.MultipleCommandsMatchedError = MultipleCommandsMatchedError;
+exports.NoSuchCommandError = NoSuchCommandError;
+exports.ParentCommandExistsError = ParentCommandExistsError;
+exports.SingleCommand = SingleCommand;
+exports.SingleCommandAliasError = SingleCommandAliasError;
+exports.SingleCommandError = SingleCommandError;
+exports.SubcommandExistsError = SubcommandExistsError;
+exports.compose = compose;
+exports.defineCommand = defineCommand;
+exports.defineHandler = defineHandler;
+exports.defineInspector = defineInspector;
+exports.definePlugin = definePlugin;
+exports.mapParametersToArguments = mapParametersToArguments;
+exports.parseParameters = parseParameters;
+exports.resolveArgv = resolveArgv;
+exports.resolveCommand = resolveCommand;
+exports.resolveFlattenCommands = resolveFlattenCommands;
+exports.resolveParametersBeforeFlag = resolveParametersBeforeFlag;
+exports.resolveRootCommands = resolveRootCommands;
+exports.resolveSubcommandsByParent = resolveSubcommandsByParent;

package/dist/index.d.ts

@@ -0,0 +1,320 @@
+import * as _clerc_utils from '@clerc/utils';
+import { MaybeArray, Dict, CamelCase, LiteralUnion } from '@clerc/utils';
+
+declare const DOUBLE_DASH = "--";
+type TypeFunction<ReturnType = any> = (value: any) => ReturnType;
+type TypeFunctionArray<ReturnType> = readonly [TypeFunction<ReturnType>];
+type FlagType<ReturnType = any> = TypeFunction<ReturnType> | TypeFunctionArray<ReturnType>;
+type FlagSchemaBase<TF> = {
+    /**
+      Type of the flag as a function that parses the argv string and returns the parsed value.
+  
+      @example
+      ```
+      type: String
+      ```
+  
+      @example Wrap in an array to accept multiple values.
+      ```
+      type: [Boolean]
+      ```
+  
+      @example Custom function type that uses moment.js to parse string as date.
+      ```
+      type: function CustomDate(value: string) {
+          return moment(value).toDate();
+      }
+      ```
+      */
+    type: TF;
+    /**
+      A single-character alias for the flag.
+  
+      @example
+      ```
+      alias: 's'
+      ```
+      */
+    alias?: string;
+} & Record<PropertyKey, unknown>;
+type FlagSchemaDefault<TF, DefaultType = any> = FlagSchemaBase<TF> & {
+    /**
+      Default value of the flag. Also accepts a function that returns the default value.
+      [Default: undefined]
+  
+      @example
+      ```
+      default: 'hello'
+      ```
+  
+      @example
+      ```
+      default: () => [1, 2, 3]
+      ```
+      */
+    default: DefaultType | (() => DefaultType);
+};
+type FlagSchema<TF = FlagType> = (FlagSchemaBase<TF> | FlagSchemaDefault<TF>);
+type FlagTypeOrSchema<ExtraOptions = Record<string, unknown>> = FlagType | (FlagSchema & ExtraOptions);
+type Flags<ExtraOptions = Record<string, unknown>> = Record<string, FlagTypeOrSchema<ExtraOptions>>;
+type InferFlagType<Flag extends FlagTypeOrSchema> = (Flag extends (TypeFunctionArray<infer T> | FlagSchema<TypeFunctionArray<infer T>>) ? (Flag extends FlagSchemaDefault<TypeFunctionArray<T>, infer D> ? T[] | D : T[]) : (Flag extends TypeFunction<infer T> | FlagSchema<TypeFunction<infer T>> ? (Flag extends FlagSchemaDefault<TypeFunction<T>, infer D> ? T | D : T | undefined) : never));
+interface ParsedFlags<Schemas = Record<string, unknown>> {
+    flags: Schemas;
+    unknownFlags: Record<string, (string | boolean)[]>;
+    _: string[] & {
+        [DOUBLE_DASH]: string[];
+    };
+}
+type TypeFlag<Schemas extends Flags> = ParsedFlags<{
+    [flag in keyof Schemas]: InferFlagType<Schemas[flag]>;
+}>;
+
+type FlagOptions = FlagSchema & {
+    description?: string;
+};
+type Flag = FlagOptions & {
+    name: string;
+};
+declare interface CommandCustomProperties {
+}
+interface CommandOptions<P extends string[] = string[], A extends MaybeArray<string> = MaybeArray<string>, F extends Dict<FlagOptions> = Dict<FlagOptions>> extends CommandCustomProperties {
+    alias?: A;
+    parameters?: P;
+    flags?: F;
+    examples?: [string, string][];
+    notes?: string[];
+}
+type Command<N extends string | SingleCommandType = string, O extends CommandOptions = CommandOptions> = O & {
+    name: N;
+    description: string;
+};
+type CommandAlias<N extends string | SingleCommandType = string, O extends CommandOptions = CommandOptions> = Command<N, O> & {
+    __isAlias?: true;
+};
+type CommandWithHandler<N extends string | SingleCommandType = string, O extends CommandOptions = CommandOptions> = Command<N, O> & {
+    handler?: HandlerInCommand<Record<N, Command<N, O>>, N>;
+};
+type StripBrackets<Parameter extends string> = (Parameter extends `<${infer ParameterName}>` | `[${infer ParameterName}]` ? (ParameterName extends `${infer SpreadName}...` ? SpreadName : ParameterName) : never);
+type ParameterType<Parameter extends string> = (Parameter extends `<${infer _ParameterName}...>` | `[${infer _ParameterName}...]` ? string[] : Parameter extends `<${infer _ParameterName}>` ? string : Parameter extends `[${infer _ParameterName}]` ? string | undefined : never);
+type CommandRecord = Dict<Command> & {
+    [SingleCommand]?: Command;
+};
+type MakeEventMap<T extends CommandRecord> = {
+    [K in keyof T]: [InspectorContext];
+};
+type PossibleInputKind = string | number | boolean | Dict<any>;
+type NonNullableParameters<T extends string[] | undefined> = T extends undefined ? [] : NonNullable<T>;
+interface HandlerContext<C extends CommandRecord = CommandRecord, N extends keyof C = keyof C> {
+    name?: N;
+    resolved: boolean;
+    isSingleCommand: boolean;
+    raw: TypeFlag<NonNullable<C[N]["flags"]>> & {
+        parameters: string[];
+    };
+    parameters: {
+        [Parameter in [...NonNullableParameters<C[N]["parameters"]>][number] as CamelCase<StripBrackets<Parameter>>]: ParameterType<Parameter>;
+    };
+    unknownFlags: ParsedFlags["unknownFlags"];
+    flags: TypeFlag<NonNullable<C[N]["flags"]>>["flags"];
+    cli: Clerc<C>;
+}
+type Handler<C extends CommandRecord = CommandRecord, K extends keyof C = keyof C> = (ctx: HandlerContext<C, K>) => void;
+type HandlerInCommand<C extends CommandRecord = CommandRecord, K extends keyof C = keyof C> = (ctx: HandlerContext<C, K> & {
+    name: K;
+}) => void;
+type FallbackType<T, U> = {} extends T ? U : T;
+type InspectorContext<C extends CommandRecord = CommandRecord> = HandlerContext<C> & {
+    flags: FallbackType<TypeFlag<NonNullable<C[keyof C]["flags"]>>["flags"], Dict<any>>;
+};
+type Inspector<C extends CommandRecord = CommandRecord> = (ctx: InspectorContext<C>, next: () => void) => void;
+interface Plugin<T extends Clerc = Clerc, U extends Clerc = Clerc> {
+    setup: (cli: T) => U;
+}
+
+declare const SingleCommand: unique symbol;
+type SingleCommandType = typeof SingleCommand;
+declare class Clerc<C extends CommandRecord = {}> {
+    #private;
+    private constructor();
+    get _name(): string;
+    get _description(): string;
+    get _version(): string;
+    get _inspectors(): Inspector<CommandRecord>[];
+    get _commands(): C;
+    /**
+     * Create a new cli
+     * @returns
+     * @example
+     * ```ts
+     * const cli = Clerc.create()
+     * ```
+     */
+    static create(): Clerc<{}>;
+    /**
+     * Set the name of the cli
+     * @param name
+     * @returns
+     * @example
+     * ```ts
+     * Clerc.create()
+     *   .name("test")
+     * ```
+     */
+    name(name: string): this;
+    /**
+     * Set the description of the cli
+     * @param description
+     * @returns
+     * @example
+     * ```ts
+     * Clerc.create()
+     *  .description("test cli")
+     */
+    description(description: string): this;
+    /**
+     * Set the version of the cli
+     * @param version
+     * @returns
+     * @example
+     * ```ts
+     * Clerc.create()
+     *  .version("1.0.0")
+     */
+    version(version: string): this;
+    /**
+     * Register a command
+     * @param name
+     * @param description
+     * @param options
+     * @returns
+     * @example
+     * ```ts
+     * Clerc.create()
+     *   .command("test", "test command", {
+     *     alias: "t",
+     *     flags: {
+     *       foo: {
+     *         alias: "f",
+     *         description: "foo flag",
+     *       }
+     *     }
+     *   })
+     * ```
+     * @example
+     * ```ts
+     * Clerc.create()
+     *   .command("", "single command", {
+     *     flags: {
+     *       foo: {
+     *         alias: "f",
+     *         description: "foo flag",
+     *       }
+     *     }
+     *   })
+     * ```
+     */
+    command<N extends string | SingleCommandType, O extends CommandOptions<[...P], A, F>, P extends string[] = string[], A extends MaybeArray<string> = MaybeArray<string>, F extends Dict<FlagOptions> = Dict<FlagOptions>>(c: CommandWithHandler<N, O & CommandOptions<[...P], A, F>>): this & Clerc<C & Record<N, Command<N, O>>>;
+    command<N extends string | SingleCommandType, P extends string[], O extends CommandOptions<[...P]>>(name: N, description: string, options?: O & CommandOptions<[...P]>): this & Clerc<C & Record<N, Command<N, O>>>;
+    /**
+     * Register a handler
+     * @param name
+     * @param handler
+     * @returns
+     * @example
+     * ```ts
+     * Clerc.create()
+     *   .command("test", "test command")
+     *   .on("test", (ctx) => {
+     *     console.log(ctx);
+     *   })
+     * ```
+     */
+    on<K extends keyof CM, CM extends this["_commands"] = this["_commands"]>(name: LiteralUnion<K, string>, handler: Handler<CM, K>): this;
+    /**
+     * Use a plugin
+     * @param plugin
+     * @returns
+     * @example
+     * ```ts
+     * Clerc.create()
+     *   .use(plugin)
+     * ```
+     */
+    use<T extends Clerc, U extends Clerc>(plugin: Plugin<T, U>): U;
+    /**
+     * Register a inspector
+     * @param inspector
+     * @returns
+     * @example
+     * ```ts
+     * Clerc.create()
+     *   .inspector((ctx, next) => {
+     *     console.log(ctx);
+     *     next();
+     *   })
+     * ```
+     */
+    inspector(inspector: Inspector): this;
+    /**
+     * Parse the command line arguments
+     * @param args
+     * @returns
+     * @example
+     * ```ts
+     * Clerc.create()
+     *   .parse(process.argv.slice(2)) // Optional
+     * ```
+     */
+    parse(argv?: string[]): this;
+}
+
+declare const definePlugin: <T extends Clerc<{}>, U extends Clerc<{}>>(p: Plugin<T, U>) => Plugin<T, U>;
+declare const defineHandler: <C extends Clerc<{}>, K extends keyof C["_commands"]>(_cli: C, _key: K, handler: Handler<C["_commands"], K>) => Handler<C["_commands"], K>;
+declare const defineInspector: <C extends Clerc<{}>>(_cli: C, inspector: Inspector<C["_commands"]>) => Inspector<C["_commands"]>;
+declare const defineCommand: <N extends string | typeof SingleCommand, O extends CommandOptions<[...P], A, F>, P extends string[] = string[], A extends MaybeArray<string> = MaybeArray<string>, F extends Dict<FlagOptions> = Dict<FlagOptions>>(c: CommandWithHandler<N, O & CommandOptions<[...P], A, F>>) => CommandWithHandler<N, O & CommandOptions<[...P], A, F>>;
+
+declare class SingleCommandError extends Error {
+    constructor();
+}
+declare class SingleCommandAliasError extends Error {
+    constructor();
+}
+declare class CommandExistsError extends Error {
+    constructor(name: string);
+}
+declare class CommonCommandExistsError extends Error {
+    constructor();
+}
+declare class NoSuchCommandError extends Error {
+    constructor(name: string);
+}
+declare class ParentCommandExistsError extends Error {
+    constructor(name: string);
+}
+declare class SubcommandExistsError extends Error {
+    constructor(name: string);
+}
+declare class MultipleCommandsMatchedError extends Error {
+    constructor(name: string);
+}
+declare class CommandNameConflictError extends Error {
+    constructor(n1: string, n2: string);
+}
+
+declare function resolveFlattenCommands(commands: CommandRecord): Map<string[], CommandAlias<string, CommandOptions<string[], _clerc_utils.MaybeArray<string>, _clerc_utils.Dict<FlagOptions>>>>;
+declare function resolveCommand(commands: CommandRecord, name: string | string[] | SingleCommandType): Command | undefined;
+declare function resolveSubcommandsByParent(commands: CommandRecord, parent: string | string[], depth?: number): Command<string, CommandOptions<string[], _clerc_utils.MaybeArray<string>, _clerc_utils.Dict<FlagOptions>>>[];
+declare const resolveRootCommands: (commands: CommandRecord) => Command<string, CommandOptions<string[], _clerc_utils.MaybeArray<string>, _clerc_utils.Dict<FlagOptions>>>[];
+declare function resolveParametersBeforeFlag(argv: string[], isSingleCommand: boolean): string[];
+declare const resolveArgv: () => string[];
+declare function compose(inspectors: Inspector[]): (getCtx: () => InspectorContext) => void;
+
+interface ParsedParameter {
+    name: string;
+    required: boolean;
+    spread: boolean;
+}
+declare function parseParameters(parameters: string[]): ParsedParameter[];
+declare function mapParametersToArguments(mapping: Record<string, string | string[]>, parameters: ParsedParameter[], cliArguments: string[]): undefined;
+
+export { Clerc, Command, CommandAlias, CommandCustomProperties, CommandExistsError, CommandNameConflictError, CommandOptions, CommandRecord, CommandWithHandler, CommonCommandExistsError, FallbackType, Flag, FlagOptions, Handler, HandlerContext, HandlerInCommand, Inspector, InspectorContext, MakeEventMap, MultipleCommandsMatchedError, NoSuchCommandError, ParentCommandExistsError, Plugin, PossibleInputKind, SingleCommand, SingleCommandAliasError, SingleCommandError, SingleCommandType, SubcommandExistsError, compose, defineCommand, defineHandler, defineInspector, definePlugin, mapParametersToArguments, parseParameters, resolveArgv, resolveCommand, resolveFlattenCommands, resolveParametersBeforeFlag, resolveRootCommands, resolveSubcommandsByParent };

package/dist/index.mjs

@@ -0,0 +1,366 @@
+import { LiteEmit } from 'lite-emit';
+import { typeFlag } from 'type-flag';
+import { mustArray, arrayStartsWith, camelCase } from '@clerc/utils';
+import { isNode, isDeno } from 'is-platform';
+
+class SingleCommandError extends Error {
+  constructor() {
+    super("Single command mode enabled.");
+  }
+}
+class SingleCommandAliasError extends Error {
+  constructor() {
+    super("Single command cannot have alias.");
+  }
+}
+class CommandExistsError extends Error {
+  constructor(name) {
+    super(`Command "${name}" exists.`);
+  }
+}
+class CommonCommandExistsError extends Error {
+  constructor() {
+    super("Common command exists.");
+  }
+}
+class NoSuchCommandError extends Error {
+  constructor(name) {
+    super(`No such command: ${name}`);
+  }
+}
+class ParentCommandExistsError extends Error {
+  constructor(name) {
+    super(`Command "${name}" cannot exist with its parent`);
+  }
+}
+class SubcommandExistsError extends Error {
+  constructor(name) {
+    super(`Command "${name}" cannot exist with its subcommand`);
+  }
+}
+class MultipleCommandsMatchedError extends Error {
+  constructor(name) {
+    super(`Multiple commands matched: ${name}`);
+  }
+}
+class CommandNameConflictError extends Error {
+  constructor(n1, n2) {
+    super(`Command name ${n1} conflicts with ${n2}. Maybe caused by alias.`);
+  }
+}
+
+function resolveFlattenCommands(commands) {
+  const commandsMap = /* @__PURE__ */ new Map();
+  for (const command of Object.values(commands)) {
+    if (command.alias) {
+      const aliases = mustArray(command.alias);
+      for (const alias of aliases) {
+        if (alias in commands) {
+          throw new CommandNameConflictError(commands[alias].name, command.name);
+        }
+        commandsMap.set(alias.split(" "), { ...command, __isAlias: true });
+      }
+    }
+    commandsMap.set(command.name.split(" "), command);
+  }
+  return commandsMap;
+}
+function resolveCommand(commands, name) {
+  if (name === SingleCommand) {
+    return commands[SingleCommand];
+  }
+  const nameArr = mustArray(name);
+  const commandsMap = resolveFlattenCommands(commands);
+  const possibleCommands = [];
+  commandsMap.forEach((v, k) => {
+    if (arrayStartsWith(nameArr, k)) {
+      possibleCommands.push(v);
+    }
+  });
+  if (possibleCommands.length > 1) {
+    const matchedCommandNames = possibleCommands.map((c) => c.name).join(", ");
+    throw new MultipleCommandsMatchedError(matchedCommandNames);
+  }
+  return possibleCommands[0];
+}
+function resolveSubcommandsByParent(commands, parent, depth = Infinity) {
+  const parentArr = parent === "" ? [] : Array.isArray(parent) ? parent : parent.split(" ");
+  return Object.values(commands).filter((c) => {
+    const commandNameArr = c.name.split(" ");
+    return arrayStartsWith(commandNameArr, parentArr) && commandNameArr.length - parentArr.length <= depth;
+  });
+}
+const resolveRootCommands = (commands) => resolveSubcommandsByParent(commands, "", 1);
+function resolveParametersBeforeFlag(argv, isSingleCommand) {
+  if (isSingleCommand) {
+    return [];
+  }
+  const parameters = [];
+  for (const arg of argv) {
+    if (arg.startsWith("-")) {
+      break;
+    }
+    parameters.push(arg);
+  }
+  return parameters;
+}
+const resolveArgv = () => isNode() ? process.argv.slice(2) : isDeno() ? Deno.args : [];
+function compose(inspectors) {
+  return (getCtx) => {
+    return dispatch(0);
+    function dispatch(i) {
+      const inspector = inspectors[i];
+      return inspector(getCtx(), dispatch.bind(null, i + 1));
+    }
+  };
+}
+
+const { stringify } = JSON;
+function parseParameters(parameters) {
+  const parsedParameters = [];
+  let hasOptional;
+  let hasSpread;
+  for (const parameter of parameters) {
+    if (hasSpread) {
+      throw new Error(`Invalid parameter: Spread parameter ${stringify(hasSpread)} must be last`);
+    }
+    const firstCharacter = parameter[0];
+    const lastCharacter = parameter[parameter.length - 1];
+    let required;
+    if (firstCharacter === "<" && lastCharacter === ">") {
+      required = true;
+      if (hasOptional) {
+        throw new Error(`Invalid parameter: Required parameter ${stringify(parameter)} cannot come after optional parameter ${stringify(hasOptional)}`);
+      }
+    }
+    if (firstCharacter === "[" && lastCharacter === "]") {
+      required = false;
+      hasOptional = parameter;
+    }
+    if (required === void 0) {
+      throw new Error(`Invalid parameter: ${stringify(parameter)}. Must be wrapped in <> (required parameter) or [] (optional parameter)`);
+    }
+    let name = parameter.slice(1, -1);
+    const spread = name.slice(-3) === "...";
+    if (spread) {
+      hasSpread = parameter;
+      name = name.slice(0, -3);
+    }
+    parsedParameters.push({
+      name,
+      required,
+      spread
+    });
+  }
+  return parsedParameters;
+}
+function mapParametersToArguments(mapping, parameters, cliArguments) {
+  for (let i = 0; i < parameters.length; i += 1) {
+    const { name, required, spread } = parameters[i];
+    const camelCaseName = camelCase(name);
+    if (camelCaseName in mapping) {
+      throw new Error(`Invalid parameter: ${stringify(name)} is used more than once.`);
+    }
+    const value = spread ? cliArguments.slice(i) : cliArguments[i];
+    if (spread) {
+      i = parameters.length;
+    }
+    if (required && (!value || spread && value.length === 0)) {
+      console.error(`Error: Missing required parameter ${stringify(name)}
+`);
+      return process.exit(1);
+    }
+    mapping[camelCaseName] = value;
+  }
+}
+
+var __accessCheck = (obj, member, msg) => {
+  if (!member.has(obj))
+    throw TypeError("Cannot " + msg);
+};
+var __privateGet = (obj, member, getter) => {
+  __accessCheck(obj, member, "read from private field");
+  return getter ? getter.call(obj) : member.get(obj);
+};
+var __privateAdd = (obj, member, value) => {
+  if (member.has(obj))
+    throw TypeError("Cannot add the same private member more than once");
+  member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+};
+var __privateSet = (obj, member, value, setter) => {
+  __accessCheck(obj, member, "write to private field");
+  setter ? setter.call(obj, value) : member.set(obj, value);
+  return value;
+};
+var _name, _description, _version, _inspectors, _commands, _commandEmitter, _isSingleCommand, isSingleCommand_get, _hasCommands, hasCommands_get;
+const SingleCommand = Symbol("SingleCommand");
+const _Clerc = class {
+  constructor() {
+    __privateAdd(this, _isSingleCommand);
+    __privateAdd(this, _hasCommands);
+    __privateAdd(this, _name, "");
+    __privateAdd(this, _description, "");
+    __privateAdd(this, _version, "");
+    __privateAdd(this, _inspectors, []);
+    __privateAdd(this, _commands, {});
+    __privateAdd(this, _commandEmitter, new LiteEmit());
+  }
+  get _name() {
+    return __privateGet(this, _name);
+  }
+  get _description() {
+    return __privateGet(this, _description);
+  }
+  get _version() {
+    return __privateGet(this, _version);
+  }
+  get _inspectors() {
+    return __privateGet(this, _inspectors);
+  }
+  get _commands() {
+    return __privateGet(this, _commands);
+  }
+  static create() {
+    return new _Clerc();
+  }
+  name(name) {
+    __privateSet(this, _name, name);
+    return this;
+  }
+  description(description) {
+    __privateSet(this, _description, description);
+    return this;
+  }
+  version(version) {
+    __privateSet(this, _version, version);
+    return this;
+  }
+  command(nameOrCommand, description, options) {
+    const checkIsCommandObject = (nameOrCommand2) => !(typeof nameOrCommand2 === "string" || nameOrCommand2 === SingleCommand);
+    const isCommandObject = checkIsCommandObject(nameOrCommand);
+    const name = !isCommandObject ? nameOrCommand : nameOrCommand.name;
+    if (__privateGet(this, _commands)[name]) {
+      if (name === SingleCommand) {
+        throw new CommandExistsError("SingleCommand");
+      }
+    }
+    if (__privateGet(this, _isSingleCommand, isSingleCommand_get)) {
+      throw new SingleCommandError();
+    }
+    if (name === SingleCommand && __privateGet(this, _hasCommands, hasCommands_get)) {
+      throw new CommonCommandExistsError();
+    }
+    if (name === SingleCommand && (isCommandObject ? nameOrCommand : options).alias) {
+      throw new SingleCommandAliasError();
+    }
+    if (name !== SingleCommand) {
+      const splitedName = name.split(" ");
+      const existedCommandNames = Object.keys(__privateGet(this, _commands)).filter((name2) => typeof name2 === "string").map((name2) => name2.split(" "));
+      if (existedCommandNames.some((name2) => arrayStartsWith(splitedName, name2))) {
+        throw new ParentCommandExistsError(splitedName.join(" "));
+      }
+      if (existedCommandNames.some((name2) => arrayStartsWith(name2, splitedName))) {
+        throw new SubcommandExistsError(splitedName.join(" "));
+      }
+    }
+    const { handler = void 0, ...commandToSave } = isCommandObject ? nameOrCommand : { name, description, ...options };
+    __privateGet(this, _commands)[name] = commandToSave;
+    if (isCommandObject && handler) {
+      this.on(nameOrCommand.name, handler);
+    }
+    return this;
+  }
+  on(name, handler) {
+    __privateGet(this, _commandEmitter).on(name, handler);
+    return this;
+  }
+  use(plugin) {
+    return plugin.setup(this);
+  }
+  inspector(inspector) {
+    __privateGet(this, _inspectors).push(inspector);
+    return this;
+  }
+  parse(argv = resolveArgv()) {
+    const name = resolveParametersBeforeFlag(argv, __privateGet(this, _isSingleCommand, isSingleCommand_get));
+    const stringName = name.join(" ");
+    const getCommand = () => __privateGet(this, _isSingleCommand, isSingleCommand_get) ? __privateGet(this, _commands)[SingleCommand] : resolveCommand(__privateGet(this, _commands), name);
+    const getContext = () => {
+      const command = getCommand();
+      const isCommandResolved = !!command;
+      const parsed = typeFlag((command == null ? void 0 : command.flags) || {}, [...argv]);
+      const { _: args, flags } = parsed;
+      let parameters = __privateGet(this, _isSingleCommand, isSingleCommand_get) || !isCommandResolved ? args : args.slice(command.name.split(" ").length);
+      let commandParameters = (command == null ? void 0 : command.parameters) || [];
+      const hasEof = commandParameters.indexOf("--");
+      const eofParameters = commandParameters.slice(hasEof + 1) || [];
+      const mapping = /* @__PURE__ */ Object.create(null);
+      if (hasEof > -1 && eofParameters.length > 0) {
+        commandParameters = commandParameters.slice(0, hasEof);
+        const eofArguments = parsed._["--"];
+        parameters = parameters.slice(0, -eofArguments.length || void 0);
+        mapParametersToArguments(
+          mapping,
+          parseParameters(commandParameters),
+          parameters
+        );
+        mapParametersToArguments(
+          mapping,
+          parseParameters(eofParameters),
+          eofArguments
+        );
+      } else {
+        mapParametersToArguments(
+          mapping,
+          parseParameters(commandParameters),
+          parameters
+        );
+      }
+      const context = {
+        name: command == null ? void 0 : command.name,
+        resolved: isCommandResolved,
+        isSingleCommand: __privateGet(this, _isSingleCommand, isSingleCommand_get),
+        raw: { ...parsed, parameters },
+        parameters: mapping,
+        flags,
+        unknownFlags: parsed.unknownFlags,
+        cli: this
+      };
+      return context;
+    };
+    const emitHandler = () => {
+      const command = getCommand();
+      const handlerContext = getContext();
+      if (!command) {
+        throw new NoSuchCommandError(stringName);
+      }
+      __privateGet(this, _commandEmitter).emit(command.name, handlerContext);
+    };
+    const inspectors = [...__privateGet(this, _inspectors), emitHandler];
+    const callInspector = compose(inspectors);
+    callInspector(getContext);
+    return this;
+  }
+};
+let Clerc = _Clerc;
+_name = new WeakMap();
+_description = new WeakMap();
+_version = new WeakMap();
+_inspectors = new WeakMap();
+_commands = new WeakMap();
+_commandEmitter = new WeakMap();
+_isSingleCommand = new WeakSet();
+isSingleCommand_get = function() {
+  return __privateGet(this, _commands)[SingleCommand] !== void 0;
+};
+_hasCommands = new WeakSet();
+hasCommands_get = function() {
+  return Object.keys(__privateGet(this, _commands)).length > 0;
+};
+
+const definePlugin = (p) => p;
+const defineHandler = (_cli, _key, handler) => handler;
+const defineInspector = (_cli, inspector) => inspector;
+const defineCommand = (c) => c;
+
+export { Clerc, CommandExistsError, CommandNameConflictError, CommonCommandExistsError, MultipleCommandsMatchedError, NoSuchCommandError, ParentCommandExistsError, SingleCommand, SingleCommandAliasError, SingleCommandError, SubcommandExistsError, compose, defineCommand, defineHandler, defineInspector, definePlugin, mapParametersToArguments, parseParameters, resolveArgv, resolveCommand, resolveFlattenCommands, resolveParametersBeforeFlag, resolveRootCommands, resolveSubcommandsByParent };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@clerc/core",
+  "version": "0.10.0",
+  "author": "Ray <nn_201312@163.com> (https://github.com/so1ve)",
+  "description": "Clerc core",
+  "keywords": [
+    "cli",
+    "clerc",
+    "arguments",
+    "argv",
+    "args",
+    "terminal"
+  ],
+  "homepage": "https://github.com/so1ve/clerc/tree/main/packages/core#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/so1ve/clerc.git",
+    "directory": "/"
+  },
+  "bugs": {
+    "url": "https://github.com/so1ve/clerc/issues"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "is-platform": "^0.2.0",
+    "lite-emit": "^1.4.0",
+    "type-flag": "^3.0.0",
+    "@clerc/utils": "0.10.0"
+  },
+  "scripts": {
+    "build": "puild",
+    "watch": "puild --watch"
+  }
+}