feat: support env var as default flag value

Signed-off-by: Michael Molisani <[email protected]>

Author: molisani

docs/docs/features/argument-parsing/flags.mdx

@@ -147,6 +147,68 @@ import DefaultFlagCode from "./examples/default-flag.txt";
     {DefaultFlagCode}
 </StricliPlayground>
 
+#### Default from Environment Variables
+
+The default value can be sourced from anywhere, as long as it is a valid string. This includes environment variables, which can be useful for providing default values that are specific to the user's environment.
+
+```ts
+// output-next-line
+/// impl.ts
+export default function(flags: { token: string }) {
+  console.log(flags.token);
+}
+
+// output-next-line
+/// command.ts
+buildCommand({
+  loader: async () => import("./impl"),
+  parameters: {
+    flags: {
+      token: {
+        kind: "parsed",
+        parse: String,
+        brief: "Token used for authentication",
+        // highlight-next-line
+        default: process.env["SOME_TOKEN"],
+      },
+    },
+    ...
+  },
+  ...
+});
+```
+
+However, Stricli has built-in support for loading default values from environment variables. Specifying the default this way enables additional formatting to indicate to the user where this value came from, and the option to "redact" the value from the output. This is done by passing an option with the `env` property in the flag configuration. The value of this property should be a string that represents the name of the environment variable to load. If the user does not pass in a value for the flag and the environment variable is not set, it will throw an `UnsatisfiedFlagError`.
+
+The additional `redact` config is optional, and if enabled will replace the value with `***` in the **Stricli-generated output**. Note that the value is still just a string passed to the flag, so there is nothing preventing the command implementation from displaying the value. There is no way for the command implementation to know where the value was sourced from, so it is up to the developer to ensure that the value is not printed if contains sensitive information.
+
+```ts
+// output-next-line
+/// impl.ts
+export default function(flags: { token: string }) {
+  console.log(flags.token);
+}
+
+// output-next-line
+/// command.ts
+buildCommand({
+  loader: async () => import("./impl"),
+  parameters: {
+    flags: {
+      token: {
+        kind: "parsed",
+        parse: String,
+        brief: "Token used for authentication",
+        // highlight-next-line
+        default: { env: "SOME_TOKEN", redact: true },
+      },
+    },
+    ...
+  },
+  ...
+});
+```
+
 ### Variadic
 
 A flag can be variadic when the type it represents is an array of values. In this case, the flag can be specified multiple times and each value is then parsed individually and added to a single array. If the type of a flag is an array it must be set as variadic.

packages/core/src/context.ts

@@ -27,14 +27,6 @@ interface WritableStreams {
     readonly stderr: Writable;
 }
 
-/**
- * Command-level context that provides necessary process information and is available to all command runs.
- * This type should be extended to include context specific to your command implementations.
- */
-export interface CommandContext {
-    readonly process: WritableStreams;
-}
-
 /**
  * Simple interface that mirrors NodeJS.Process but only requires the minimum API required by Stricli.
  */
@@ -51,6 +43,14 @@ export interface StricliProcess extends WritableStreams {
     exitCode?: number | string;
 }
 
+/**
+ * Command-level context that provides necessary process information and is available to all command runs.
+ * This type should be extended to include context specific to your command implementations.
+ */
+export interface CommandContext {
+    readonly process: StricliProcess;
+}
+
 /**
  * Environment variable names used by Stricli.
  *

packages/core/src/parameter/flag/formatting.ts

@@ -59,7 +59,11 @@ export function formatDocumentationForFlagParameters(
         }
         if (hasDefault(flag)) {
             const defaultKeyword = args.ansiColor ? `\x1B[90m${keywords.default}\x1B[39m` : keywords.default;
-            suffixParts.push(`${defaultKeyword} ${flag.default === "" ? `""` : String(flag.default)}`);
+            if (typeof flag.default === "object") {
+                suffixParts.push(`${defaultKeyword} <from env ${flag.default.env}>`);
+            } else {
+                suffixParts.push(`${defaultKeyword} ${flag.default === "" ? `""` : String(flag.default)}`);
+            }
         }
         const suffix = suffixParts.length > 0 ? `[${suffixParts.join(", ")}]` : void 0;
 

packages/core/src/parameter/flag/types.ts

@@ -3,6 +3,22 @@
 import type { CommandContext } from "../../context";
 import type { ParsedParameter } from "../types";
 
+/**
+ * Default value for flag when one is not provided by the end user.
+ */
+export type DefaultFlagValue<T> =
+    | T
+    | {
+          /**
+           * Default value should be read from the environment variable with this name.
+           */
+          readonly env: string;
+          /**
+           * When enabled, redact the value from the environment variable in all Stricli-generated output.
+           */
+          readonly redact?: boolean;
+      };
+
 interface BaseFlagParameter {
     /**
      * In-line documentation for this flag.
@@ -12,6 +28,10 @@ interface BaseFlagParameter {
      * String that serves as placeholder for the value in the generated usage line. Defaults to "value".
      */
     readonly placeholder?: string;
+    /**
+     * If no value was provided, attempt to read the environment variable with this name for the value.
+     */
+    readonly env?: string;
 }
 
 interface BaseBooleanFlagParameter extends BaseFlagParameter {
@@ -25,7 +45,7 @@ interface BaseBooleanFlagParameter extends BaseFlagParameter {
      *
      * If no value is provided, boolean flags default to `false`.
      */
-    readonly default?: boolean;
+    readonly default?: DefaultFlagValue<boolean>;
 }
 
 type RequiredBooleanFlagParameter = BaseBooleanFlagParameter & {
@@ -44,7 +64,7 @@ type RequiredBooleanFlagParameter = BaseBooleanFlagParameter & {
               /**
                * Default input value if one is not provided at runtime.
                */
-              readonly default: boolean;
+              readonly default: DefaultFlagValue<boolean>;
               /**
                * Parameter should be hidden from all help text and proposed completions.
                * Only available for runtime-optional parameters.
@@ -117,7 +137,7 @@ export interface BaseEnumFlagParameter<T extends string> extends BaseFlagParamet
     /**
      * Default input value if one is not provided at runtime.
      */
-    readonly default?: T;
+    readonly default?: DefaultFlagValue<T>;
     readonly optional?: boolean;
     readonly hidden?: boolean;
     readonly variadic?: boolean;
@@ -203,7 +223,7 @@ export interface BaseParsedFlagParameter<T, CONTEXT extends CommandContext>
     /**
      * Default input value if one is not provided at runtime.
      */
-    readonly default?: string;
+    readonly default?: DefaultFlagValue<string>;
     /**
      * If flag is specified with no corresponding input, infer an empty string `""` as the input.
      */
@@ -233,7 +253,7 @@ type RequiredParsedFlagParameter<T, CONTEXT extends CommandContext> = BaseParsed
               /**
                * Default input value if one is not provided at runtime.
                */
-              readonly default: string;
+              readonly default: DefaultFlagValue<string>;
               /**
                * Parameter should be hidden from all help text and proposed completions.
                * Only available for runtime-optional parameters.
@@ -361,7 +381,7 @@ export type FlagParameters<CONTEXT extends CommandContext = CommandContext> = Re
 
 export function hasDefault<CONTEXT extends CommandContext>(
     flag: FlagParameter<CONTEXT>,
-): flag is FlagParameter<CONTEXT> & { default: string | boolean } {
+): flag is FlagParameter<CONTEXT> & { default: DefaultFlagValue<string | boolean> } {
     return "default" in flag && typeof flag.default !== "undefined";
 }