feat: Display text override for default option value

This PR adds the following two features related to changing default value display for options.

1. `defaultText` option for options

It is either a string or a function that transforms the default value into string. When set, it changes the help text of the default, while the underlying default value is used for processing.

2. `"secret"` input type

This is exactly the same as string type, except it hides its default values on help text.

Testing: new and existing unittests, playing with the build

Fixes: c4spar#774

command/_argument_types.ts

@@ -13,6 +13,7 @@ import type { BooleanType } from "./types/boolean.ts";
 import type { FileType } from "./types/file.ts";
 import type { IntegerType } from "./types/integer.ts";
 import type { NumberType } from "./types/number.ts";
+import type { SecretType } from "./types/secret.ts";
 import type { StringType } from "./types/string.ts";
 
 type DefaultTypes = {
@@ -21,6 +22,7 @@ type DefaultTypes = {
   string: StringType;
   boolean: BooleanType;
   file: FileType;
+  secret: SecretType;
 };
 
 type OptionalOrRequiredValue<TType extends string> =

command/command.ts

@@ -58,6 +58,7 @@ import type {
   CompleteHandler,
   CompleteOptions,
   Completion,
+  DefaultText,
   DefaultValue,
   Description,
   EnvVar,
@@ -80,6 +81,7 @@ import { BooleanType } from "./types/boolean.ts";
 import { FileType } from "./types/file.ts";
 import { IntegerType } from "./types/integer.ts";
 import { NumberType } from "./types/number.ts";
+import { SecretType } from "./types/secret.ts";
 import { StringType } from "./types/string.ts";
 import { checkVersion } from "./upgrade/_check_version.ts";
 
@@ -129,6 +131,7 @@ export class Command<
       string: string;
       boolean: boolean;
       file: string;
+      secret: string;
     },
   TCommandGlobalTypes extends Record<string, unknown> | void =
     TParentCommandGlobals extends number ? any : void,
@@ -1247,12 +1250,14 @@ export class Command<
           TCommandTypes,
           TCommandGlobalTypes,
           TParentCommandTypes,
-          TParentCommand
+          TParentCommand,
+          TDefaultValue
         >,
         "value"
       >
         & {
           default?: DefaultValue<TDefaultValue>;
+          defaultText?: DefaultText<TDefaultValue>;
           required?: TRequired;
           collect?: TCollect;
           value?: OptionValueHandler<
@@ -1324,13 +1329,15 @@ export class Command<
           TCommandTypes,
           TCommandGlobalTypes,
           TParentCommandTypes,
-          TParentCommand
+          TParentCommand,
+          TDefaultValue
         >,
         "value"
       >
         & {
           global: true;
           default?: DefaultValue<TDefaultValue>;
+          defaultText?: DefaultText<TDefaultValue>;
           required?: TRequired;
           collect?: TCollect;
           value?: OptionValueHandler<
@@ -1385,12 +1392,14 @@ export class Command<
           TCommandTypes,
           TCommandGlobalTypes,
           TParentCommandTypes,
-          TParentCommand
+          TParentCommand,
+          TDefaultValue
         >,
         "value"
       >
         & {
           default?: DefaultValue<TDefaultValue>;
+          defaultText?: DefaultText<TDefaultValue>;
           required?: TRequired;
           collect?: TCollect;
           conflicts?: TConflicts;
@@ -1855,6 +1864,8 @@ export class Command<
       this.type("boolean", new BooleanType(), { global: true });
     !this.types.has("file") &&
       this.type("file", new FileType(), { global: true });
+    !this.types.has("secret") &&
+      this.type("secret", new SecretType(), { global: true });
 
     if (!this._help) {
       this.help({});

command/help/_help_generator.ts

@@ -311,14 +311,27 @@ export class HelpGenerator {
 
     option.required && hints.push(yellow(`required`));
 
-    if (typeof option.default !== "undefined") {
+    const type = this.cmd.getType(option.args[0]?.type)?.handler;
+
+    if (
+      typeof option.default !== "undefined" ||
+      typeof option.defaultText !== "undefined"
+    ) {
       const defaultValue = typeof option.default === "function"
         ? option.default()
         : option.default;
 
-      if (typeof defaultValue !== "undefined") {
+      const defaultText = typeof option.defaultText === "function"
+        ? option.defaultText(defaultValue)
+        : (typeof option.defaultText !== "undefined"
+          ? option.defaultText
+          : ((type instanceof Type && type.defaultText)
+            ? type.defaultText()
+            : defaultValue));
+
+      if (typeof defaultText !== "undefined") {
         hints.push(
-          bold(`Default: `) + inspect(defaultValue, this.options.colors),
+          bold(`Default: `) + inspect(defaultText, this.options.colors),
         );
       }
     }
@@ -333,7 +346,6 @@ export class HelpGenerator {
         italic(option.conflicts.map(getFlag).join(", ")),
     );
 
-    const type = this.cmd.getType(option.args[0]?.type)?.handler;
     if (type instanceof Type) {
       const possibleValues = type.values?.(this.cmd, this.cmd.getParent());
       if (possibleValues?.length) {

command/mod.ts

@@ -38,6 +38,7 @@ export { EnumType } from "./types/enum.ts";
 export { FileType } from "./types/file.ts";
 export { IntegerType } from "./types/integer.ts";
 export { NumberType } from "./types/number.ts";
+export { SecretType } from "./types/secret.ts";
 export { StringType } from "./types/string.ts";
 export { Type } from "./type.ts";
 export { ValidationError, type ValidationErrorOptions } from "./_errors.ts";

command/test/command/generic_types_test.ts

@@ -1,6 +1,6 @@
 import { test } from "@cliffy/internal/testing/test";
-import { Command, EnumType } from "../../mod.ts";
 import { assertType, type IsAny, type IsExact } from "@std/testing/types";
+import { Command, EnumType } from "../../mod.ts";
 
 // Not required to execute this code, only type check.
 (() => {
@@ -983,6 +983,8 @@ import { assertType, type IsAny, type IsExact } from "@std/testing/types";
               integer: number;
               string: string;
               boolean: boolean;
+              file: string;
+              secret: string;
             },
             void,
             undefined

command/test/command/help_command_test.ts

@@ -26,6 +26,21 @@ function command(defaultOptions?: boolean, hintOption?: boolean) {
       "I have a default value!",
       { default: "test" },
     )
+    .option(
+      "--default-func [val:string]",
+      "I have a default handler!",
+      { default: () => "test" },
+    )
+    .option(
+      "-T, --default-text [val:string]",
+      "I have a default text!",
+      { defaultText: "test" },
+    )
+    .option(
+      "--default-text-func [val:string]",
+      "I have a default text handler!",
+      { default: "test", defaultText: (value) => value },
+    )
     .option("-r, --required [val:string]", "I am required!", { required: true })
     .option(
       "-H, --hidden [val:string]",
@@ -87,15 +102,18 @@ Description:
 
 Options:
 
-  -h, --help                     - Show this help.                                                                                   
-  -V, --version                  - Show the version number for this program.                                                         
-  -t, --test       [val:string]  - test description                                                                                  
-  -D, --default    [val:string]  - I have a default value!                    (Default: "test")                                      
-  -r, --required   [val:string]  - I am required!                             (required)                                             
-  -d, --depends    [val:string]  - I depend on test!                          (Depends: --test)                                      
-  -c, --conflicts  [val:string]  - I conflict with test!                      (Conflicts: --test)                                    
-  -a, --all        <val:string>  - I have many hints!                         (required, Default: "test", Depends: --test, Conflicts:
-                                                                              --depends)                                             
+  -h, --help                         - Show this help.                                                                                   
+  -V, --version                      - Show the version number for this program.                                                         
+  -t, --test           [val:string]  - test description                                                                                  
+  -D, --default        [val:string]  - I have a default value!                    (Default: "test")                                      
+  --default-func       [val:string]  - I have a default handler!                  (Default: "test")                                      
+  -T, --default-text   [val:string]  - I have a default text!                     (Default: "test")                                      
+  --default-text-func  [val:string]  - I have a default text handler!             (Default: "test")                                      
+  -r, --required       [val:string]  - I am required!                             (required)                                             
+  -d, --depends        [val:string]  - I depend on test!                          (Depends: --test)                                      
+  -c, --conflicts      [val:string]  - I conflict with test!                      (Conflicts: --test)                                    
+  -a, --all            <val:string>  - I have many hints!                         (required, Default: "test", Depends: --test, Conflicts:
+                                                                                  --depends)                                             
 
 Commands:
 
@@ -130,13 +148,16 @@ Description:
 
 Options:
 
-  -t, --test       [val:string]  - test description                                                                
-  -D, --default    [val:string]  - I have a default value!  (Default: "test")                                      
-  -r, --required   [val:string]  - I am required!           (required)                                             
-  -d, --depends    [val:string]  - I depend on test!        (Depends: --test)                                      
-  -c, --conflicts  [val:string]  - I conflict with test!    (Conflicts: --test)                                    
-  -a, --all        <val:string>  - I have many hints!       (required, Default: "test", Depends: --test, Conflicts:
-                                                            --depends)                                             
+  -t, --test           [val:string]  - test description                                                                       
+  -D, --default        [val:string]  - I have a default value!         (Default: "test")                                      
+  --default-func       [val:string]  - I have a default handler!       (Default: "test")                                      
+  -T, --default-text   [val:string]  - I have a default text!          (Default: "test")                                      
+  --default-text-func  [val:string]  - I have a default text handler!  (Default: "test")                                      
+  -r, --required       [val:string]  - I am required!                  (required)                                             
+  -d, --depends        [val:string]  - I depend on test!               (Depends: --test)                                      
+  -c, --conflicts      [val:string]  - I conflict with test!           (Conflicts: --test)                                    
+  -a, --all            <val:string>  - I have many hints!              (required, Default: "test", Depends: --test, Conflicts:
+                                                                       --depends)                                             
 
 Commands:
 

command/test/command/option_test.ts

@@ -39,6 +39,7 @@ test("command - option - option properties", () => {
       standalone: true,
       collect: true,
       default: false,
+      defaultText: "false",
     })
     .getOption("foo-bar", true) as Option;
 
@@ -57,6 +58,7 @@ test("command - option - option properties", () => {
   assertEquals(option.standalone, true);
   assertEquals(option.collect, true);
   assertEquals(option.default, false);
+  assertEquals(option.defaultText, "false");
 
   assertEquals(option.args, [{
     action: "boolean",

command/test/type/secret_test.ts

@@ -0,0 +1,45 @@
+import { test } from "@cliffy/internal/testing/test";
+import {
+  assertEquals,
+  assertMatch,
+  assertNotMatch,
+  assertRejects,
+} from "@std/assert";
+import { Command } from "../../command.ts";
+
+const cmd = new Command()
+  .throwErrors()
+  .option("-f, --flag [value:secret]", "description ...")
+  .option("-d, --default [value:secret]", "description ...", {
+    default: "DEFAULT",
+  })
+  .option("--no-flag", "description ...")
+  .action(() => {});
+
+test("command - type - secret - with no value", async () => {
+  const { options, args } = await cmd.parse(["-f"]);
+
+  assertEquals(options, { flag: true, default: "DEFAULT" });
+  assertEquals(args, []);
+  assertNotMatch(cmd.getHelp(), /"DEFAULT"/g);
+  assertMatch(cmd.getHelp(), /"\*\*\*\*\*\*"/g);
+});
+
+test("command - type - secret - with valid value", async () => {
+  const { options, args } = await cmd.parse(["--flag", "value"]);
+
+  assertEquals(options, { flag: "value", default: "DEFAULT" });
+  assertEquals(args, []);
+  assertNotMatch(cmd.getHelp(), /"DEFAULT"/g);
+  assertMatch(cmd.getHelp(), /"\*\*\*\*\*\*"/g);
+});
+
+test("command - type - secret - no arguments allowed", async () => {
+  await assertRejects(
+    async () => {
+      await cmd.parse(["-f", "value", "unknown"]);
+    },
+    Error,
+    `No arguments allowed for command "COMMAND".`,
+  );
+});

command/test/type/string_test.ts

@@ -1,25 +1,30 @@
 import { test } from "@cliffy/internal/testing/test";
-import { assertEquals, assertRejects } from "@std/assert";
+import { assertEquals, assertMatch, assertRejects } from "@std/assert";
 import { Command } from "../../command.ts";
 
 const cmd = new Command()
   .throwErrors()
   .option("-f, --flag [value:string]", "description ...")
+  .option("-d, --default [value:string]", "description ...", {
+    default: "DEFAULT",
+  })
   .option("--no-flag", "description ...")
   .action(() => {});
 
 test("command - type - string - with no value", async () => {
   const { options, args } = await cmd.parse(["-f"]);
 
-  assertEquals(options, { flag: true });
+  assertEquals(options, { flag: true, default: "DEFAULT" });
   assertEquals(args, []);
+  assertMatch(cmd.getHelp(), /"DEFAULT"/g);
 });
 
 test("command - type - string - with valid value", async () => {
   const { options, args } = await cmd.parse(["--flag", "value"]);
 
-  assertEquals(options, { flag: "value" });
+  assertEquals(options, { flag: "value", default: "DEFAULT" });
   assertEquals(args, []);
+  assertMatch(cmd.getHelp(), /"DEFAULT"/g);
 });
 
 test("command - type - string - no arguments allowed", async () => {

command/type.ts

@@ -1,8 +1,8 @@
 import type { Command } from "./command.ts";
-import type { TypeOrTypeHandler } from "./types.ts";
 import type {
   ArgumentValue,
   CompleteHandlerResult,
+  TypeOrTypeHandler,
   ValuesHandlerResult,
 } from "./types.ts";
 
@@ -34,6 +34,12 @@ import type {
 export abstract class Type<TValue> {
   public abstract parse(type: ArgumentValue): TValue;
 
+  /**
+   * Returns the default display text value for the type. This text will be shown
+   * unless a custom value is provided for option default text.
+   */
+  public defaultText?(): string;
+
   /**
    * Returns values displayed in help text. If no complete method is provided,
    * these values are also used for shell completions.