feat: global flags (#28)

* refactor

* tsdoc

* make description required.

* refactor

* fix test

* remov no description

* move to utils

* global flags

* refactor

* use global flag

Author: so1ve

packages/core/src/cli.ts

@@ -22,7 +22,9 @@ import type {
   CommandType,
   CommandWithHandler,
   Commands,
+  FlagWithoutDescription,
   Flags,
+  FlagsWithoutDescription,
   Handler,
   HandlerContext,
   I18N,
@@ -48,13 +50,14 @@ import { locales } from "./locales";
 export const Root = Symbol.for("Clerc.Root");
 export type RootType = typeof Root;
 
-export class Clerc<C extends Commands = {}> {
+export class Clerc<C extends Commands = {}, GF extends FlagsWithoutDescription = {}> {
   #name = "";
   #description = "";
   #version = "";
   #inspectors: Inspector[] = [];
   #commands = {} as C;
   #commandEmitter = new LiteEmit<MakeEventMap<C>>();
+  #flags = {} as GF;
   #usedNames = new Set<string | RootType>();
   #argv: string[] | undefined;
   #errorHandlers = [] as ((err: any) => void)[];
@@ -97,6 +100,7 @@ export class Clerc<C extends Commands = {}> {
   get _version () { return this.#version; }
   get _inspectors () { return this.#inspectors; }
   get _commands () { return this.#commands; }
+  get _flags () { return this.#flags; }
 
   #addCoreLocales () { this.i18n.add(locales); }
   #otherMethodCaled () { this.#isOtherMethodCalled = true; }
@@ -244,8 +248,8 @@ export class Clerc<C extends Commands = {}> {
    *   })
    * ```
    */
-  command<N extends string | RootType, O extends CommandOptions<[...P], A, F>, P extends string[] = string[], A extends MaybeArray<string | RootType> = MaybeArray<string | RootType>, F extends Flags = Flags>(c: CommandWithHandler<N, O & CommandOptions<[...P], A, F>>): this & Clerc<C & Record<N, Command<N, O>>>;
-  command<N extends string | RootType, O extends CommandOptions<[...P], A, F>, P extends string[] = string[], A extends MaybeArray<string | RootType> = MaybeArray<string | RootType>, F extends Flags = Flags>(name: N, description: string, options?: O & CommandOptions<[...P], A, F>): this & Clerc<C & Record<N, Command<N, O>>>;
+  command<N extends string | RootType, O extends CommandOptions<[...P], A, F>, P extends string[] = string[], A extends MaybeArray<string | RootType> = MaybeArray<string | RootType>, F extends Flags = Flags>(c: CommandWithHandler<N, O & CommandOptions<[...P], A, F>>): this & Clerc<C & Record<N, Command<N, O>>, GF>;
+  command<N extends string | RootType, O extends CommandOptions<[...P], A, F>, P extends string[] = string[], A extends MaybeArray<string | RootType> = MaybeArray<string | RootType>, F extends Flags = Flags>(name: N, description: string, options?: O & CommandOptions<[...P], A, F>): this & Clerc<C & Record<N, Command<N, O>>, GF>;
   command (nameOrCommand: any, description?: any, options: any = {}) {
     this.#callWithErrorHandling(() => this.#command(nameOrCommand, description, options));
     return this;
@@ -282,6 +286,28 @@ export class Clerc<C extends Commands = {}> {
     return this as any;
   }
 
+  /**
+   * Register a global flag
+   * @param name
+   * @param options
+   * @returns
+   * @example
+   * ```ts
+   * Clerc.create()
+   *   .flag("help", {
+   *     alias: "h",
+   *     description: "help",
+   *   })
+   * ```
+   */
+  flag<N extends string, O extends FlagWithoutDescription>(name: N, description: string, options: O): this & Clerc<C, GF & Record<N, O>> {
+    this.#flags[name] = {
+      description,
+      ...options,
+    } as any;
+    return this as any;
+  }
+
   /**
    * Register a handler
    * @param name
@@ -296,7 +322,7 @@ export class Clerc<C extends Commands = {}> {
    *   })
    * ```
    */
-  on<K extends LiteralUnion<keyof CM, string | RootType>, CM extends this["_commands"] = this["_commands"]>(name: K, handler: Handler<CM, K>) {
+  on<K extends LiteralUnion<keyof CM, string | RootType>, CM extends this["_commands"] = this["_commands"]>(name: K, handler: Handler<CM, K, this["_flags"]>) {
     this.#commandEmitter.on(name as any, handler as any);
     return this;
   }
@@ -433,7 +459,7 @@ export class Clerc<C extends Commands = {}> {
     return context;
   }
 
-  #callWithErrorHandling (fn: () => void) {
+  #callWithErrorHandling (fn: (...args: any[]) => any) {
     try {
       fn();
     } catch (e) {

packages/core/src/types/index.ts

@@ -7,12 +7,14 @@ import type { ParseFlag, ParseParameters, ParseRaw } from "./utils";
 export type CommandType = RootType | string;
 
 export type FlagOptions = FlagSchema & {
-  description?: string
+  description: string
 };
 export type Flag = FlagOptions & {
   name: string
 };
+export type FlagWithoutDescription = Omit<Flag, "description">;
 export type Flags = Dict<FlagOptions>;
+export type FlagsWithoutDescription = Dict<FlagWithoutDescription>;
 
 export declare interface CommandCustomProperties {}
 export interface CommandOptions<P extends string[] = string[], A extends MaybeArray<string | RootType> = MaybeArray<string | RootType>, F extends Flags = Flags> extends CommandCustomProperties {
@@ -37,19 +39,19 @@ export interface ParseOptions {
   run?: boolean
 }
 
-export interface HandlerContext<C extends Commands = Commands, N extends keyof C = keyof C> {
+export interface HandlerContext<C extends Commands = Commands, N extends keyof C = keyof C, GF extends FlagsWithoutDescription = {}> {
   name?: LiteralUnion<N, string>
   called?: string | RootType
   resolved: boolean
   hasRootOrAlias: boolean
   hasRoot: boolean
-  raw: Simplify<ParseRaw<C[N]>>
+  raw: Simplify<ParseRaw<C[N], GF>>
   parameters: Simplify<ParseParameters<C, N>>
   unknownFlags: ParsedFlags["unknownFlags"]
-  flags: Simplify<ParseFlag<C, N> & Record<string, any>>
-  cli: Clerc<C>
+  flags: Simplify<ParseFlag<C, N, GF> & Record<string, any>>
+  cli: Clerc<C, GF>
 }
-export type Handler<C extends Commands = Commands, K extends keyof C = keyof C> = (ctx: HandlerContext<C, K>) => void;
+export type Handler<C extends Commands = Commands, K extends keyof C = keyof C, GF extends FlagsWithoutDescription = {}> = (ctx: HandlerContext<C, K, GF>) => void;
 export type HandlerInCommand<C extends HandlerContext> = (ctx: { [K in keyof C]: C[K] }) => void;
 export type FallbackType<T, U> = {} extends T ? U : T;
 export type InspectorContext<C extends Commands = Commands> = HandlerContext<C> & {

packages/core/src/types/utils.ts

@@ -1,7 +1,7 @@
 import type { CamelCase, Dict, Equals } from "@clerc/utils";
 import type { OmitIndexSignature } from "type-fest";
 import type { TypeFlag } from "./type-flag";
-import type { Command, Commands, InspectorContext } from ".";
+import type { Command, Commands, Flags, FlagsWithoutDescription, InspectorContext } from ".";
 
 type StripBrackets<Parameter extends string> = (
   Parameter extends `<${infer ParameterName}>` | `[${infer ParameterName}]`
@@ -30,13 +30,13 @@ export type TransformParameters<C extends Command> = {
 
 export type MakeEventMap<T extends Commands> = { [K in keyof T]: [InspectorContext] };
 
-type FallbackFlags<C extends Command> = Equals<NonNullableFlag<C>["flags"], {}> extends true ? Dict<any> : NonNullableFlag<C>["flags"];
-type NonNullableFlag<C extends Command> = TypeFlag<NonNullable<C["flags"]>>;
-export type ParseFlag<C extends Commands, N extends keyof C> = N extends keyof C ? OmitIndexSignature<NonNullableFlag<C[N]>["flags"]> : FallbackFlags<C[N]>["flags"];
-export type ParseRaw<C extends Command> = NonNullableFlag<C> & {
-  flags: FallbackFlags<C>
+type FallbackFlags<F extends Flags | undefined> = Equals<NonNullableFlag<F>["flags"], {}> extends true ? Dict<any> : NonNullableFlag<F>["flags"];
+type NonNullableFlag<F extends Flags | undefined> = TypeFlag<NonNullable<F>>;
+export type ParseFlag<C extends Commands, N extends keyof C, GF extends FlagsWithoutDescription = {}> = N extends keyof C ? OmitIndexSignature<NonNullableFlag<C[N]["flags"] & GF>["flags"]> : FallbackFlags<C[N]["flags"] & GF>["flags"];
+export type ParseRaw<C extends Command, GF extends FlagsWithoutDescription = {}> = NonNullableFlag<C["flags"] & GF> & {
+  flags: FallbackFlags<C["flags"] & GF>
   parameters: string[]
-  mergedFlags: FallbackFlags<C> & NonNullableFlag<C>["unknownFlags"]
+  mergedFlags: FallbackFlags<C["flags"] & GF> & NonNullableFlag<C["flags"] & GF>["unknownFlags"]
 };
 export type ParseParameters<C extends Commands = Commands, N extends keyof C = keyof C> =
   Equals<TransformParameters<C[N]>, {}> extends true

packages/plugin-help/src/index.ts

@@ -1,12 +1,11 @@
-import type { Clerc, Command, HandlerContext, RootType, TranslateFn } from "@clerc/core";
+import type { HandlerContext, RootType } from "@clerc/core";
 import { NoSuchCommandError, Root, definePlugin, formatCommandName, resolveCommandStrict, withBrackets } from "@clerc/core";
-
-import { gracefulFlagName, toArray } from "@clerc/utils";
+import { toArray } from "@clerc/utils";
 import pc from "picocolors";
 
 import type { Render, Renderers, Section } from "./renderer";
 import { defaultRenderers, render } from "./renderer";
-import { splitTable } from "./utils";
+import { DELIMITER, formatFlags, generateCliDetail, generateExamples, print, sortName, splitTable } from "./utils";
 import { locales } from "./locales";
 
 declare module "@clerc/core" {
@@ -15,46 +14,6 @@ declare module "@clerc/core" {
   }
 }
 
-const DELIMITER = pc.yellow("-");
-
-const print = (s: string) => { process.stdout.write(s); };
-
-const generateCliDetail = (sections: Section[], cli: Clerc, subcommand?: Command<string | RootType>) => {
-  const { t } = cli.i18n;
-  const items = [
-    {
-      title: t("help.name")!,
-      body: pc.red(cli._name),
-    },
-    {
-      title: t("help.version")!,
-      body: pc.yellow(cli._version),
-    },
-  ];
-  if (subcommand) {
-    items.push({
-      title: t("help.subcommand")!,
-      body: pc.green(`${cli._name} ${formatCommandName(subcommand.name)}`),
-    });
-  }
-  sections.push({
-    type: "inline",
-    items,
-  });
-  sections.push({
-    title: t("help.description")!,
-    body: [subcommand?.description || cli._description],
-  });
-};
-
-const generateExamples = (sections: Section[], examples: [string, string][], t: TranslateFn) => {
-  const examplesFormatted = examples.map(([command, description]) => [command, DELIMITER, description]);
-  sections.push({
-    title: t("help.examples")!,
-    body: splitTable(examplesFormatted),
-  });
-};
-
 const generateHelp = (render: Render, ctx: HandlerContext, notes: string[] | undefined, examples: [string, string][] | undefined) => {
   const { cli } = ctx;
   const { t } = cli.i18n;
@@ -64,23 +23,31 @@ const generateHelp = (render: Render, ctx: HandlerContext, notes: string[] | und
     title: t("help.usage")!,
     body: [pc.magenta(`$ ${cli._name} ${withBrackets("command", ctx.hasRootOrAlias)} [flags]`)],
   });
-  const commands = [...(ctx.hasRoot ? [cli._commands[Root]!] : []), ...Object.values(cli._commands)].map((command) => {
+  const commands = [
+    ...(ctx.hasRoot ? [cli._commands[Root]!] : []),
+    ...Object.values(cli._commands),
+  ].map((command) => {
     const commandNameWithAlias = [typeof command.name === "symbol" ? "" : command.name, ...toArray(command.alias || [])]
-      .sort((a, b) => {
-        if (a === Root) { return -1; }
-        if (b === Root) { return 1; }
-        return a.length - b.length;
-      })
+      .sort(sortName)
       .map((n) => {
         return (n === "" || typeof n === "symbol") ? `${cli._name}` : `${cli._name} ${n}`;
       })
       .join(", ");
     return [pc.cyan(commandNameWithAlias), DELIMITER, command.description];
   });
-  sections.push({
-    title: t("help.commands")!,
-    body: splitTable(commands),
-  });
+  if (commands.length) {
+    sections.push({
+      title: t("help.commands")!,
+      body: splitTable(commands),
+    });
+  }
+  const globalFlags = formatFlags(cli._flags);
+  if (globalFlags.length) {
+    sections.push({
+      title: t("help.globalFlags")!,
+      body: splitTable(globalFlags),
+    });
+  }
   if (notes) {
     sections.push({
       title: t("help.notes")!,
@@ -118,25 +85,17 @@ const generateSubcommandHelp = (render: Render, ctx: HandlerContext, command: st
     title: t("help.usage")!,
     body: [pc.magenta(`$ ${cli._name}${commandName}${parametersString}${flagsString}`)],
   });
+  const globalFlags = formatFlags(cli._flags);
+  if (globalFlags.length) {
+    sections.push({
+      title: t("help.globalFlags")!,
+      body: splitTable(globalFlags),
+    });
+  }
   if (subcommand.flags) {
     sections.push({
       title: t("help.flags")!,
-      body: splitTable(
-        Object.entries(subcommand.flags).map(([name, flag]) => {
-          const hasDefault = flag.default !== undefined;
-          let flagNameWithAlias: string[] = [gracefulFlagName(name)];
-          if (flag.alias) {
-            flagNameWithAlias.push(gracefulFlagName(flag.alias));
-          }
-          flagNameWithAlias = flagNameWithAlias.map(renderers.renderFlagName);
-          const items = [pc.blue(flagNameWithAlias.join(", ")), renderers.renderType(flag.type, hasDefault)];
-          items.push(DELIMITER, flag.description || t("help.noDescription")!);
-          if (hasDefault) {
-            items.push(`(${t("help.default", renderers.renderDefault(flag.default))})`);
-          }
-          return items;
-        }),
-      ),
+      body: splitTable(formatFlags(subcommand.flags)),
     });
   }
   if (subcommand.notes) {
@@ -154,10 +113,15 @@ const generateSubcommandHelp = (render: Render, ctx: HandlerContext, command: st
 
 export interface HelpPluginOptions {
   /**
-   * Whether to registr the help command.
+   * Whether to register the help command.
    * @default true
    */
   command?: boolean
+  /**
+   * Whether to register the global help flag.
+   * @default true
+   */
+  flag?: boolean
   /**
    * Whether to show help when no command is specified.
    * @default true
@@ -172,12 +136,13 @@ export interface HelpPluginOptions {
    */
   examples?: [string, string][]
   /**
-   * Banner
+   * Banner.
    */
   banner?: string
 }
 export const helpPlugin = ({
   command = true,
+  flag = true,
   showHelpWhenNoCommand = true,
   notes,
   examples,
@@ -192,7 +157,7 @@ export const helpPlugin = ({
     };
 
     if (command) {
-      cli = cli.command("help", t("help.commandDescription")!, {
+      cli = cli.command("help", t("help.helpDdescription")!, {
         parameters: [
           "[command...]",
         ],
@@ -216,15 +181,23 @@ export const helpPlugin = ({
         });
     }
 
+    if (flag) {
+      cli = cli.flag("help", t("help.helpDdescription")!, {
+        alias: "h",
+        type: Boolean,
+        default: false,
+      });
+    }
+
     cli.inspector((ctx, next) => {
-      const helpFlag = ctx.raw.mergedFlags.h || ctx.raw.mergedFlags.help;
-      if (!ctx.hasRootOrAlias && !ctx.raw._.length && showHelpWhenNoCommand && !helpFlag) {
+      const shouldShowHelp = ctx.flags.help;
+      if (!ctx.hasRootOrAlias && !ctx.raw._.length && showHelpWhenNoCommand && !shouldShowHelp) {
         let str = `${t("core.noCommandGiven")}\n\n`;
         str += generateHelp(render, ctx, notes, examples);
         str += "\n";
         printHelp(str);
         process.exit(1);
-      } else if (helpFlag) {
+      } else if (shouldShowHelp) {
         if (ctx.raw._.length) {
           if (ctx.called !== Root) {
             if (ctx.name === Root) {

packages/plugin-help/src/locales.ts

@@ -6,12 +6,12 @@ export const locales: Locales = {
     "help.version": "Version",
     "help.subcommand": "Subcommand",
     "help.commands": "Commands",
+    "help.globalFlags": "Global Flags",
     "help.flags": "Flags",
     "help.description": "Description",
     "help.usage": "Usage",
     "help.examples": "Examples",
     "help.notes": "Notes",
-    "help.noDescription": "(No description)",
     "help.notes.1": "If no command is specified, show help for the CLI.",
     "help.notes.2": "If a command is specified, show help for the command.",
     "help.notes.3": "-h is an alias for --help.",
@@ -25,12 +25,12 @@ export const locales: Locales = {
     "help.version": "版本",
     "help.subcommand": "子命令",
     "help.commands": "命令",
+    "help.globalFlags": "全局标志",
     "help.flags": "标志",
     "help.description": "描述",
     "help.usage": "使用",
     "help.examples": "示例",
     "help.notes": "备注",
-    "help.noDescription": "(无描述)",
     "help.notes.1": "如果没有指定展示哪个命令的帮助信息，默认展示CLI的。",
     "help.notes.2": "如果指定了则展示该命令帮助信息。",
     "help.notes.3": "-h 是 --help 的一个别名。",